Développeurs · Ressources

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.

Vue d’ensemble de l’API

Votre premier appel

Centre d’aide Ultineo Logistics : colis, adresses et transporteurs

Codes d’erreur

Commandes & logistique

Commandes

Articles, paiements et expéditions liés

Ouvrir la page

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.

Ouvrir la page

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.

Ouvrir la page

État des services

L'état actuel de nos services

Ouvrir la page

Nouveautés

Ce qui a changé dans les produits

Ouvrir la page

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.

Ouvrir la page

Vue d’ensemble développeurs

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é.