Appel API
Cette solution permet d'envoyer des commandes de manière unitaire ou en lot, soit en "temps réel", soit de manière groupée avec une fréquence minimum de 1 lot par jour.
Une fois votre compte créé, Hipli vous remettra deux informations : votre identifiant et votre token (la création de compte se fait via demande auprès d'Hipli).
Gardez ces informations secrètes, ce sont elles qui permettent d'identifier vos différents appels.
Pour chaque appel, le serveur vous répondra un code HTTP 202 (Accepted) avec un corps vide.
En cas d'erreur, le serveur vous retourna un code HTTP 400 ou 500.
Si vous voulez de l'aide pour comprendre l'erreur, contactez l'équipe technique d'Hipli
L'URL d'accès au service est le suivant :
https://hipli.pro
(Il est possible de vérifier que le service est opérationnel en faisant un GET sur l'URL https://hipli.pro/status retournant OK
)
L'appel à ce service peut se faire commande par commande (appel unitaire) ou en lot :
- Appel unitaire
- Appel en lot
Chaque appel se fait ainsi :
POST /shop/order
avec en headers :
Content-Type: application/json
X-Hipli-ShopToken: {TOKEN}
(Le token est celui qui vous été transmis lors de la création de votre compte)
Le corps de la requête doit contenir l'objet suivant en JSON (respecter la casse et envoyer en UTF-8) :
Nom | Type | Obligatoire | Description | Taille | Exemple |
---|---|---|---|---|---|
sourceId | Chaine de caractères | Obligatoire | Représente un identifiant unique de votre système (utile pour les regroupements pour une même commande). D'usage, il est recommandé d'utiliser votre numéro de commande. | Max 50 caractères | ORD-1234 |
sourceShop | Chaine de caractères | Obligatoire | Représente votre identifiant transmis lors de la création de votre compte. | Max 50 caractères | SHOP-HIPLI |
orderDate | Chaine de caractères - date ISO-8601 | Obligatoire | Représente la date de votre commande au format ISO-8601. | 23 caractères | 2023-01-13T10:15:30.00Z |
destinationCountry | Chaine de caractères | Obligatoire | Code pays au format ISO 3166-Alpha 3 (voir liste ici https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements) | 3 caractères | FRA |
numberOfProduct | Numérique | Obligatoire | Représente le nombre d'articles (Hors colis Hipli) dans la commande de l'utilisateur. Attention si vous ajoutez le colis Hipli comme un article supplémentaire à votre commande, pensez à le retirer lors du comptage. | Nombre inférieur à 50 | 4 |
hipliSku | Chaine de caractère | Facultatif | Représente le numéro de série du colis Hipli utilisé pour l'expédition. Ce champ peut être le contenu du code barre générique représentant le format, ou l'identifiant unique (code barre ou QRCode) ou une chaine de caractère parmi les valeurs (MINUS, HIPLUS, MAGNUS, MAXIMUS, RIGIDE) | Max 50 caractères | MAGNUS |
mailLang | Chaine de caractère | Facultatif | Langue de l'email envoyé au client (défaut : FR) - Valeurs autorisées : FR, EN | Max 5 caractères | FR |
client | Objet JSON | Obligatoire | Objet "Client" (voir après) | Représente les informations du client |
Objet Client :
Nom | Type | Obligatoire | Description | Taille | Exemple |
---|---|---|---|---|---|
firstName | Chaine de caractères | Obligatoire | Prénom de l'utilisateur | Max 50 caractères | Pierre |
lastName | Chaine de caractères | Obligatoire | Nom de famille de l'utilisateur | Max 50 caractères | Leresteux |
Chaine de caractères | Obligatoire | Adresse mail de l'utilisateur (sera utilisée pour le mail envoyé par Hipli) | Max 50 caractères | pierre.leresteux@hipli.fr | |
addr1 | Chaine de caractères | Facultatif | Première partie de l'adresse postale de l'utilisateur | Max 100 caractères | 52 quai frissard |
addr2 | Chaine de caractères | Facultatif | Seconde partie de l'adresse postale de l'utilisateur | Max 100 caractères | Immeuble Le Bassin |
city | Chaine de caractères | Facultatif | Représente la ville de l'utilisateur | Max 100 caractères | Le Havre |
zipCode | Chaine de caractères | Facultatif | Représente le code postal de l'utilisateur | Max 10 caractères | 76600 |
country | Chaine de caractères | Facultatif | Représente le pays de l'utilisateur | Max 50 caractères | FRANCE |
phone | Chaine de caractères | Facultatif | Représente le numéro de téléphone de l'utilisateur | Max 30 caractères | 0607080910 |
Voici des exemples de contenu de la requête :
JSON minimal (uniquement les champs obligatoires) :
{
"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"
}
}
JSON complet (tous les champs) :
{
"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"
}
}
L'appel en lot diffère de l'appel unitaire car il permet d'envoyer en 1 seul appel plusieurs commandes.
Chaque appel se fait ainsi :
POST /shop/orders
avec en headers :
Content-Type: application/json
X-Hipli-ShopToken: {TOKEN}
(Le token est celui qui vous été transmis lors de la création de votre compte)
Le corps de la requête doit contenir un tableau composé des objets suivants en JSON (respecter la casse et envoyer en UTF-8) :
Nom | Type | Obligatoire | Description | Taille | Exemple |
---|---|---|---|---|---|
sourceId | Chaine de caractères | Obligatoire | Représente un identifiant unique de votre système (utile pour les regroupements pour une même commande). D'usage, il est recommandé d'utiliser votre numéro de commande. | Max 50 caractères | ORD-1234 |
sourceShop | Chaine de caractères | Obligatoire | Représente votre identifiant transmis lors de la création de votre compte. | Max 50 caractères | SHOP-HIPLI |
orderDate | Chaine de caractères - date ISO-8601 | Obligatoire | Représente la date de votre commande au format ISO-8601. | 23 caractères | 2023-01-13T10:15:30.00Z |
destinationCountry | Chaine de caractères | Obligatoire | Code pays au format ISO 3166-Alpha 3 (voir liste ici https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements) | 3 caractères | FRA |
numberOfProduct | Numérique | Obligatoire | Représente le nombre d'articles (Hors colis Hipli) dans la commande de l'utilisateur. Attention si vous ajoutez le colis Hipli comme un article supplémentaire à votre commande, pensez à le retirer lors du comptage. | Nombre inférieur à 50 | 4 |
hipliSku | Chaine de caractère | Facultatif | Représente le numéro de série du colis Hipli utilisé pour l'expédition. Ce champ peut être le contenu du code barre générique représentant le format, ou l'identifiant unique (code barre ou QRCode) ou une chaine de caractère parmi les valeurs (MINUS, HIPLUS, MAGNUS, MAXIMUS, RIGIDE) | Max 50 caractères | MAGNUS |
mailLang | Chaine de caractère | Facultatif | Langue de l'email envoyé au client (défaut : FR) - Valeurs autorisées : FR, EN | Max 5 caractères | FR |
client | Objet JSON | Obligatoire | Objet "Client" (voir après) | Représente les informations du client |
Objet Client :
Nom | Type | Obligatoire | Description | Taille | Exemple |
---|---|---|---|---|---|
firstName | Chaine de caractères | Obligatoire | Prénom de l'utilisateur | Max 50 caractères | Pierre |
lastName | Chaine de caractères | Obligatoire | Nom de famille de l'utilisateur | Max 50 caractères | Leresteux |
Chaine de caractères | Obligatoire | Adresse mail de l'utilisateur (sera utilisée pour le mail envoyé par Hipli) | Max 50 caractères | pierre.leresteux@hipli.fr | |
addr1 | Chaine de caractères | Facultatif | Première partie de l'adresse postale de l'utilisateur | Max 100 caractères | 52 quai frissard |
addr2 | Chaine de caractères | Facultatif | Seconde partie de l'adresse postale de l'utilisateur | Max 100 caractères | Immeuble Le Bassin |
city | Chaine de caractères | Facultatif | Représente la ville de l'utilisateur | Max 100 caractères | Le Havre |
zipCode | Chaine de caractères | Facultatif | Représente le code postal de l'utilisateur | Max 10 caractères | 76600 |
country | Chaine de caractères | Facultatif | Représente le pays de l'utilisateur | Max 50 caractères | FRANCE |
phone | Chaine de caractères | Facultatif | Représente le numéro de téléphone de l'utilisateur | Max 30 caractères | 0607080910 |
Voici des exemples de contenu de la requête :
JSON minimal (uniquement les champs obligatoires) :
[{
"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"
}
}]
JSON complet (tous les champs) :
[{
"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
En cas de question ou de soucis, contactez votre référent Hipli ou l'équipe technique