Conventions

Les formes que partagent tous les endpoints — URL de base et gestion des versions, identifiants, horodatages, pagination et enveloppe d'erreur.

URL de base et gestion des versions

Toutes les requêtes sont adressées à https://api.veeton.com/v1.

La gestion des versions se fait sur un seul axe et se trouve dans le chemin. Ciblez explicitement /v1. Au sein d’une version majeure, seuls des changements additifs sont livrés : nouveaux champs, nouveaux paramètres optionnels, nouvelles valeurs d’énumération lorsque la documentation indique qu’un ensemble est ouvert. Les clients doivent ignorer les champs qu’ils ne connaissent pas.

Identifiants

Chaque ressource est désignée par un id : un ULID de 26 caractères en base32 Crockford, tel que 01HX5K2MZ7A3Q4FBNDC0EVDXY1. Les identifiants sont opaques et non énumérables. La seule exception concerne les identifiants de mannequins : les mannequins système sélectionnés par Veeton portent des identifiants hérités plus courts ("19274"), traitez donc model_id comme une chaîne opaque plutôt que de valider sa forme.

Les identifiants d’événements webhook sont préfixés : evt_….

Horodatages

Tous les horodatages sont au format RFC 3339 en UTC, 2026-09-03T14:30:09Z. Les paramètres de requête qui prennent un horodatage (since= sur les exports) acceptent également un décalage horaire.

Pagination

Chaque endpoint de liste renvoie la même enveloppe et prend les mêmes paramètres.

{
  "data": [ … ],
  "next_cursor": "eyJpZCI6MTIzNDV9",
  "has_more": true
}

limit : de 1 à 100, 25 par défaut.
cursor : le next_cursor de la page précédente. Opaque ; ne le construisez pas vous-même.

La pagination repose sur un jeu de clés (keyset) : ajouter ou supprimer des lignes pendant que vous paginez ne saute ni ne répète jamais un élément. Un cursor inutilisable est refusé avec 400 invalid_cursor.

Erreurs

Chaque erreur, quel que soit l’endpoint, utilise la même enveloppe.

{
  "error": {
    "type": "not_found",
    "code": "product_not_found",
    "message": "Product 01HX5K2MZ7A3Q4FBNDC0EVDXY1 was not found.",
    "param": "inputs.product_id"
  }
}

Champ	Signification
`type`	La classe d’échec : `invalid_request`, `not_found`, `unauthorized`, `forbidden`, `payment_required`, `conflict`, `rate_limited`, `internal`. Aiguillez votre comportement sur ce champ.
`code`	Un identifiant stable et précis, tel que `reference_already_exists`. Aiguillez vos messages sur ce champ.
`message`	Lisible par un humain, peut être affiché à un opérateur sans risque. Non stable ; ne l’analysez pas.
`param`	Lorsqu’il est présent, le champ de la requête concerné par l’erreur.

Deux endpoints valident de nombreux éléments à la fois et renvoient une liste plutôt qu’une erreur unique, afin que vous n’ayez jamais à réessayer par dichotomie : POST /v1/imports renvoie { "errors": [{ "line", "code", "message", "param?" }] } et POST /v1/tasks/tryon renvoie { "errors": [{ "input_index", "type", "code", "message", "param?" }] }.

Une 5xx ne renvoie jamais de détail interne. La réponse porte un message générique et le X-Request-Id à citer au support ; le détail est de notre côté, indexé par cet identifiant.

Identifiants de requête

Chaque réponse porte X-Request-Id. Envoyez votre propre valeur dans le même en-tête et elle vous est renvoyée telle quelle (jusqu’à 128 caractères parmi les lettres, les chiffres, ., _, : et -), afin que vous puissiez corréler un appel entre vos logs et les nôtres.

Images

Le type des images est déterminé par leurs octets, jamais par un Content-Type déclaré. Les formats JPEG, PNG et WebP sont acceptés, jusqu’à 10 Mo chacun. Les URL signées vers les octets d’une image sont valables une heure ; l’id de l’image est permanent et GET /v1/images/{id} renvoie une nouvelle URL.

CORS

L’API répond aux requêtes preflight CORS de manière permissive afin de pouvoir être appelée depuis n’importe quel backend. Elle est conçue pour un usage serveur à serveur : une clé machine dans un navigateur est une clé machine rendue publique.