API call

This solution allows you to send single or batch orders, either in "real time" or in a grouped way with a minimum frequency of 1 batch per day.

Once your account is created, Hipli will give you two pieces of information: your identifier and your token (account creation is done via request to Hipli).

To remember

Keep these information secret, they are the ones that identify your different calls.

For each call, the server will answer you a HTTP code 202 (Accepted) with an empty body.

In case of error, the server will return an HTTP code 400 or 500.

If you need help to understand the error, please contact the Hipli technical team

The URL to access the service is the following: https://hooks.hipli.fr

(It is possible to check that the service is operational by doing a GET on the URL https://hooks.hipli.fr/status returning the time in UTC)

The call to this service can be made order by order (unit call) or in batch:

Unit call
Batch call

Each call is made as follows:

POST /order

with headers :

Content-Type: application/json
X-Hipli-ShopToken: {TOKEN}

(The token is the one that was given to you when you created your account)

The request body must contain the following object in JSON (case-sensitive and send in UTF-8):

Field	Type	Mandatory	Description	Size	Example
sourceId	String	Mandatory	Represents a unique identifier for your system (useful for grouping for the same order). Usually, it is recommended to use your order number.	Max 50 char	ORD-1234
sourceShop	String	Mandatory	Represents your identifier given to you when your account was created.	Max 50 char	SHOP-HIPLI
orderDate	String - date ISO-8601	Mandatory	Represents the date of your order in ISO-8601 format.	23 char	2023-01-13T10:15:30.00Z
destinationCountry	String	Mandatory	Country code in ISO 3166-Alpha 3 (see list here https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements)	3 char	FRA
numberOfProduct	Integer	Mandatory	Represents the number of items (excluding Hipli parcel) in the user's order. Be careful if you add the Hipli package as an additional item to your order, remember to remove it when counting.	under 50	4
hipliSku	String	Optional	Represents the serial number of the Hipli package used for shipping. This field can be the content of the generic barcode representing the format, or the unique identifier (barcode or QRCode) or a character string among the values (MINUS, HIPLUS, MAGNUS, MAXIMUS, BOX,...)	Max 50 char	MAGNUS
mailLang	String	Optional	Language of the email sent to the customer (default: FR) - Allowed values: FR, EN	Max 5 char	FR
client	JSON object	Mandatory	"Client" object (see after)	Represents client information

Client object :

Field	Type	Mandatory	Description	Size	Example
firstName	String	Mandatory	Client first name	Max 50 char	Pierre
lastName	String	Mandatory	Client last name	Max 50 char	Leresteux
mail	String	Mandatory	Client mail (will be used for the mail sent by Hipli)	Max 50 char	pierre.leresteux@hipli.fr
addr1	String	Optional	First part of the client's postal address	Max 100 char	52 quai frissard
addr2	String	Optional	Second part of the client's postal address	Max 100 char	Immeuble Le Bassin
city	String	Optional	Client city	Max 100 char	Le Havre
zipCode	String	Optional	Client zipcode	Max 10 char	76600
country	String	Optional	Client country	Max 50 char	FRANCE
phone	String	Optional	Client phone number	Max 30 char	0607080910

The following are examples of query content:

Minimal JSON (Only with mandatory fields) :

{
  "sourceId": "ORD-1234",
  "sourceShop": "SHOP-HIPLI",
  "orderDate": "2023-01-13T10:15:30.00Z",
  "destinationCountry": "FRA",
  "numberOfProduct": 4,
  "client": {
    "firstName": "Pierre",
    "lastName": "Leresteux",
    "mail": "pierre.leresteux@hipli.fr"
  }
}

Full JSON (all fields) :

{
  "sourceId": "ORD-1234",
  "sourceShop": "SHOP-HIPLI",
  "orderDate": "2023-01-13T10:15:30.00Z",
  "destinationCountry": "FRA",
  "numberOfProduct": 4,
  "hipliSku": "MINUS",
  "mailLang": "FR",
  "client": {
    "firstName": "Pierre",
    "lastName": "Leresteux",
    "mail": "pierre.leresteux@hipli.fr",
    "addr1": "52 quai frissard",
    "addr2": "Immeuble Le Bassin",
    "city": "Le Havre",
    "zipCode": "76600",
    "country": "FRANCE",
    "phone": "0607080910"
  }
}

The batch call differs from the unit call because it allows you to send several orders in one call.

Each call is made as follows:

POST /orders

with headers :

Content-Type: application/json
X-Hipli-ShopToken: {TOKEN}

(The token is the one that was given to you when you created your account)

The request body must contain an array containing the following object in JSON (case-sensitive and send in UTF-8):

Field	Type	Mandatory	Description	Size	Example
sourceId	String	Mandatory	Represents a unique identifier for your system (useful for grouping for the same order). Usually, it is recommended to use your order number.	Max 50 char	ORD-1234
sourceShop	String	Mandatory	Represents your identifier given to you when your account was created.	Max 50 char	SHOP-HIPLI
orderDate	String - date ISO-8601	Mandatory	Represents the date of your order in ISO-8601 format.	23 char	2023-01-13T10:15:30.00Z
destinationCountry	String	Mandatory	Country code in ISO 3166-Alpha 3 (see list here https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements)	3 char	FRA
numberOfProduct	Integer	Mandatory	Represents the number of items (excluding Hipli parcel) in the user's order. Be careful if you add the Hipli package as an additional item to your order, remember to remove it when counting.	under 50	4
hipliSku	String	Optional	Represents the serial number of the Hipli package used for shipping. This field can be the content of the generic barcode representing the format, or the unique identifier (barcode or QRCode) or a character string among the values (MINUS, HIPLUS, MAGNUS, MAXIMUS, BOX,...)	Max 50 char	MAGNUS
mailLang	String	Optional	Language of the email sent to the customer (default: FR) - Allowed values: FR, EN	Max 5 char	FR
client	JSON object	Mandatory	"Client" object (see after)	Represents client information

Client object :

Field	Type	Mandatory	Description	Size	Example
firstName	String	Mandatory	Client first name	Max 50 char	Pierre
lastName	String	Mandatory	Client last name	Max 50 char	Leresteux
mail	String	Mandatory	Client mail (will be used for the mail sent by Hipli)	Max 50 char	pierre.leresteux@hipli.fr
addr1	String	Optional	First part of the client's postal address	Max 100 char	52 quai frissard
addr2	String	Optional	Second part of the client's postal address	Max 100 char	Immeuble Le Bassin
city	String	Optional	Client city	Max 100 char	Le Havre
zipCode	String	Optional	Client zipcode	Max 10 char	76600
country	String	Optional	Client country	Max 50 char	FRANCE
phone	String	Optional	Client phone number	Max 30 char	0607080910

The following are examples of query content:

Minimal JSON (Only with mandatory fields) :

[{
  "sourceId": "ORD-1234",
  "sourceShop": "SHOP-HIPLI",
  "orderDate": "2023-01-13T10:15:30.00Z",
  "destinationCountry": "FRA",
  "numberOfProduct": 4,
  "client": {
    "firstName": "Pierre",
    "lastName": "Leresteux",
    "mail": "pierre.leresteux@hipli.fr"
  }
},
{
  "sourceId": "ORD-1235",
  "sourceShop": "SHOP-HIPLI",
  "orderDate": "2023-01-13T11:18:21.00Z",
  "destinationCountry": "FRA",
  "numberOfProduct": 1,
  "client": {
    "firstName": "John",
    "lastName": "Doe",
    "mail": "john.doe@hipli.fr"
  }
}]

Full JSON (all fields) :

[{
  "sourceId": "ORD-1234",
  "sourceShop": "SHOP-HIPLI",
  "orderDate": "2023-01-13T10:15:30.00Z",
  "destinationCountry": "FRA",
  "numberOfProduct": 4,
  "hipliSku": "MINUS",
  "mailLang": "FR",
  "client": {
    "firstName": "Pierre",
    "lastName": "Leresteux",
    "mail": "pierre.leresteux@hipli.fr",
    "addr1": "52 quai frissard",
    "addr2": "Immeuble Le Bassin",
    "city": "Le Havre",
    "zipCode": "76600",
    "country": "FRANCE",
    "phone": "0607080910"
  }
},
{
  "sourceId": "ORD-1235",
  "sourceShop": "SHOP-HIPLI",
  "orderDate": "2023-01-13T11:18:21.00Z",
  "destinationCountry": "FRA",
  "numberOfProduct": 2,
  "hipliSku": "ABC00000000000A000102571",
  "mailLang": "EN",
  "client": {
    "firstName": "John",
    "lastName": "Doe",
    "mail": "john.doe@hipli.fr",
    "addr1": "Place du Général-de-Gaulle",
    "addr2": "CS 31402",
    "city": "Rouen",
    "zipCode": "76000",
    "country": "FRANCE",
    "phone": "021122334455"
  }
}]

Contact / Questions

If you have any questions or concerns, please contact your Hipli contact or the technical team: contact

API call

Contact / Questions​

Contact / Questions