Vue d'ensemble de l'API

L'API E-commerce permet à vos propres outils de remplir votre boutique et de la relire : un script de migration, une synchronisation avec votre ERP ou un flux fournisseur envoie des éléments par lots, et relit n'importe quel élément pour vérifier ce qui a été enregistré. Ses routes logistiques permettent à vos propres logiciels d'ajouter les colis à suivre, de tenir votre carnet d'adresses à jour et de lire le catalogue des transporteurs. C'est une API JSON sur HTTPS. Cette page donne les règles communes à tous les appels, puis la liste des articles de référence.

Adresse de base

Toutes les requêtes sont envoyées à :

https://api.ultineo.com/v1/

Seul HTTPS est servi. Un point d'accès ne demande aucune clé ; vous pouvez l'utiliser pour vérifier que l'hôte est joignable :

curl https://api.ultineo.com/health

{
  "code": 200,
  "title": "OK",
  "response": "api gateway"
}

Authentification

Envoyez la clé API de votre boutique comme jeton Bearer dans l'en-tête Authorization de chaque appel. Une clé commence par sk-project-, appartient à une seule boutique et détient des droits : chaque ressource a un droit de lecture et un droit d'écriture, et un appel auquel il manque son droit est refusé avec 403. Vous créez une clé dans votre espace de travail, depuis l'onglet Accès API de votre projet ; l'article API keys de ce centre d'aide en détaille les étapes. L'en-tête et le tableau des droits se trouvent dans Votre premier appel.

L'enveloppe de réponse

Chaque point d'accès répond avec les trois mêmes clés, en cas de succès comme en cas d'échec. Lisez d'abord le code de statut HTTP, puis lisez response.

Erreurs

Un appel en échec utilise la même enveloppe qu'un appel réussi : lisez le code de statut HTTP, puis lisez response pour obtenir un message décrivant le problème. Codes d'erreur liste chaque statut renvoyé par l'API, ses messages et la conduite à tenir.

Limites

• Requêtes — Trop de requêtes en peu de temps reçoivent un 429. Attendez le nombre de secondes indiqué dans l'en-tête Retry-After, puis réessayez.
• Corps — Le corps d'une requête ne dépasse pas 200 000 octets. Un corps plus grand reçoit un 413 : envoyez des lots plus petits.
• Lot — Chaque ressource a sa propre limite de lot, de 25 à 500 éléments, indiquée dans son tableau de points d'accès. Un lot qui dépasse la limite reçoit un 422 : divisez-le.
• Listes — Les ressources importées se relisent un élément à la fois, sans liste, ni recherche, ni pagination. Les listes de Colis, adresses et transporteurs acceptent limit (50 par défaut, 100 au plus) et offset.

Version

La version de l'API est dans le chemin : les routes de cette référence sont sous /v1/.

Tester avec le mode essai

Avec "dry_run": true dans le corps d'un import, vous obtenez le rapport complet — ce qui serait créé, mis à jour, laissé inchangé ou refusé — et rien n'est écrit. Vérifiez toujours le champ dry_run de la réponse avant de vous fier à un rapport. Voir Votre premier appel.

Les articles de référence