Retenez les règles communes à toutes les routes de l’API
L’API d’Ultineo E-commerce est une API JSON sur HTTPS dont les routes suivent les mêmes règles. Cette page les rassemble : l’enveloppe de réponse, la façon de désigner un élément, les dates, les montants, les listes et la version.
Ce que toutes les routes ont en commun
- JSON sur HTTPS
Toutes les routes ne sont servies qu’en HTTPS. Un corps est en JSON, envoyé avec l’en-tête Content-Type application/json.
- La version dans le chemin
La version de l’API est dans le chemin : les routes de la documentation de référence sont sous /v1/. Toutes les requêtes sont donc envoyées à https://api.ultineo.com/v1/.
- Deux façons de désigner un élément
Un élément a deux désignations : la clé que vous lui avez donnée, c’est-à-dire external_id, ou le SKU ou le nom pour un élément du catalogue, et son identifiant dans votre boutique. Une lecture accepte l’une ou l’autre.
Comment lire n’importe quelle réponse
-
1
Lisez le statut HTTP Le code de statut HTTP est la première chose à lire, en cas de succès comme en cas d’échec. Le guide « Gérer les erreurs et les limites » indique ce que chaque statut demande à votre client.
-
2
Ouvrez l’enveloppe Chaque point d’accès répond avec les trois mêmes clés : code, title et response. Un appel en échec utilise la même enveloppe qu’un appel réussi.
-
3
Repérez code et title La clé code répète le code de statut HTTP dans le corps. La clé title porte le libellé court du statut, par exemple OK ou Not Found.
-
4
Lisez response En cas de succès, response contient l’élément ou le rapport d’import. En cas d’échec, response contient un message décrivant le problème.
La même enveloppe, en cas de succès comme d’échec
Les deux réponses sont des exemples distincts de la documentation de référence : une catégorie relue, réduite à quelques champs, et un autre appel, refusé pour un droit manquant. Elles portent les trois mêmes clés.
Appel réussi
{
"code": 200,
"title": "OK",
"response": {
"object": "category",
"id": "cate_4be1a07f93c2d58e6a10",
...
"created_at": 1789143990,
"updated_at": 1789143990
}
} La clé response contient l’élément, et ses deux dates sont des nombres de secondes.
Appel en échec
{
"code": 403,
"title": "Forbidden",
"response": "The API key is missing the required scope: order:write"
} La clé response contient un message à la place d’un élément.
Dates, montants et listes : les points à surveiller
- Une date dans un autre format
Les horodatages, comme created_at, sont envoyés et renvoyés sous forme de nombres entiers de secondes depuis l’epoch Unix, en UTC, et 0 dans une réponse signifie que la date n’est pas renseignée. Une date dans un autre format est refusée, pas convertie.
- Des montants lus comme des nombres
Les montants sont renvoyés sous forme de chaînes contenant un nombre décimal, par exemple "129.90". Cette forme est retenue afin qu’aucune précision ne soit perdue.
- Lister une ressource importée
Une ressource importée n’a pas de liste : une lecture renvoie un seul élément. Les listes n’existent que dans l’API d’Ultineo Logistics (colis, adresses et transporteurs) : elles acceptent limit, 50 par défaut et 100 au plus, et offset.
Les articles derrière cette page
Cette page reprend les articles suivants du centre d’aide. Ils détaillent chaque champ, chaque valeur et chaque réponse.
Centre d’aide Ultineo Logistics : colis, adresses et transporteurs
Les pages produit à lire ensuite
- Accès API
Reliez vos systèmes avec des accès adaptés à la boutique
- Produits
Fiches produits, images et catégories
- Commandes
Articles, paiements et expéditions liés
- Expéditions
Colis, transporteurs et suivi
Poursuivre dans cette rubrique
- Référence de l’API E-commerce
Tous les articles de l’API E-commerce, dans le centre d’aide.
- Sécurité
Comment les clés, les connexions chiffrées et les accès de l’équipe protègent ce qu’atteint votre intégration.
- État des services
L'état actuel de nos services
- Nouveautés
Ce qui a changé dans les produits
- Aide aux développeurs
Où un développeur ou un intégrateur trouve une réponse, quoi vérifier d’abord et quoi nous envoyer.
Appliquez ces règles à votre propre boutique
Une clé se crée dans une boutique ouverte, et les comptes Ultineo E-commerce sont ouverts après étude de votre demande.
Questions
Une liste répond total, limit, offset et data. Dans l’API d’Ultineo Logistics, la liste des colis peut aussi être synchronisée, pour suivre les changements sans tout relire : son centre d’aide donne les appels.
Sur les routes colis, adresses et transporteurs de l’API d’Ultineo Logistics, un identifiant porte un préfixe : carr_ pour un transporteur, parc_ pour un colis, addr_ pour une adresse et ship_ pour une expédition. Un transporteur, un colis et une adresse nomment aussi leur type dans leur champ object, qui vaut toujours carrier, parcel ou address.
Oui. Dans un import, les champs de montant, comme le total d’une commande ou le montant d’un paiement, acceptent un nombre ou une chaîne. L’article de référence « Commandes & logistique » liste ces champs ; le montant d’un paiement, par exemple, accepte jusqu’à 2 décimales.
Dans l’historique des ventes, un lien vers un autre élément utilise l’external_id de cet élément : customer_external_id, order_external_id, shipment_external_id, etc. L’élément ainsi désigné doit déjà être importé : le guide « Importer par lots » donne l’ordre recommandé.