API
esc

Saisissez votre recherche.

Référence API

Introduction

L'API Veeton Studio est une API REST sur HTTPS avec des corps JSON, des clés machine limitées à une organisation, une pagination par cursor et une seule enveloppe d'erreur partout.

Les ressources sont organisées autour de ce que vous détenez et de ce que vous générez. Commencez par Products et Imports pour importer un catalogue, Tasks pour générer des rendus, Exports pour tout relire, et Webhooks pour être prévenu quand un traitement se termine.

Au sein d'une version majeure, seuls des changements additifs sont livrés : nouveaux champs, nouveaux paramètres optionnels, nouvelles valeurs là où un ensemble est documenté comme ouvert. Les clients doivent ignorer les champs qu'ils ne connaissent pas.

URL de base

https://api.veeton.com/v1

Ressources

Authentification

Chaque requête porte une clé machine limitée à une organisation, sous forme de bearer token. Si l'équipe Veeton vous a donné accès à l'API, générez-en une dans le tableau de bord, sous Organisation → Clés API. Les clés commencent par ak_ ; les tokens de session du tableau de bord ne sont pas acceptés.

Les clés portent des périmètres (products:read, tasks:write, …) et une requête hors de ces périmètres est refusée avec 403 insufficient_scope. La vérification est mise en cache environ une minute ; une révocation met donc ce délai à s'appliquer. Voir le guide Authentification.

Requête authentifiée

curl https://api.veeton.com/v1/products \
  -H "Authorization: Bearer $VEETON_KEY"

Erreurs

Les codes de statut HTTP conventionnels indiquent la classe du résultat ; le corps indique ce qui s'est passé. Chaque erreur suit la même enveloppe, { error: { type, code, message, param? } }. Aiguillez votre comportement sur type et vos messages sur code ; message s'adresse aux humains et n'est pas stable.

Attributs

  • typeenum
    Valeurs possibles (8)
    • invalid_request
    • not_found
    • unauthorized
    • forbidden
    • payment_required
    • conflict
    • rate_limited
    • internal
  • codestring
  • messagestring
  • paramstring

Codes de statut HTTP

  • 200, 201, 202, 204
    La requête a abouti. 202 signifie qu'un job asynchrone a été accepté.
  • 400
    La requête est malformée ou a échoué à la validation. Les imports et les shootings photo (tryon) listent tous les problèmes d'un coup.
  • 401
    Pas de clé, ou une clé inconnue, révoquée ou expirée.
  • 402
    Pas d'abonnement actif ou crédits insuffisants. Rien n'a été mis en file.
  • 403
    La clé n'a pas le périmètre requis, est liée à un utilisateur plutôt qu'à une organisation, ou l'organisation n'a pas reçu l'accès à l'API.
  • 404
    La ressource n'existe pas dans votre organisation.
  • 409
    Un conflit d'unicité, par exemple une reference déjà utilisée.
  • 413, 415
    Le corps est trop volumineux, ou son type de contenu n'est pas accepté.
  • 422
    La requête est bien formée mais ne peut pas être appliquée : une clé d'idempotence réutilisée avec un autre corps, un subtype et des inputs qui ne correspondent pas.
  • 429
    Limite de débit atteinte. Attendez Retry-After secondes puis réessayez.
  • 5xx
    Une erreur de notre côté. Communiquez le X-Request-Id au support.

Enveloppe d'erreur

{
  "error": {
    "type": "invalid_request",
    "code": "product_not_found",
    "message": "Product 01HX...XY1 was not found.",
    "param": "inputs.product_id"
  }
}

Pagination

Chaque endpoint de liste accepte limit (de 1 à 100, 25 par défaut) et cursor, et retourne la même enveloppe. Renvoyez next_cursor dans cursor jusqu'à ce que has_more soit false. Les cursors sont opaques et reposent sur un jeu de clés (keyset) : les lignes ajoutées ou supprimées pendant que vous paginez ne sont jamais sautées ni répétées.

Enveloppe de liste

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

Requêtes idempotentes

Envoyez Idempotency-Key (toute chaîne jusqu'à 255 caractères, un UUID par convention) sur POST, PATCH et DELETE. La même clé avec la même requête rejoue la réponse stockée avec Idempotent-Replayed: true ; la même clé avec une requête différente donne 422 idempotency_key_reused ; une clé encore en cours donne409 request_in_progress. Les clés expirent après 24 heures. Une 5xx n'est jamais stockée : la réessayer relance donc la requête. Voir Idempotence.

Requête idempotente

curl https://api.veeton.com/v1/tasks/beautifier \
  -H "Authorization: Bearer $VEETON_KEY" \
  -H "Idempotency-Key: 4d1b9f6e-6c2a-4c1e-9c3f-2a7e8b0d1f22" \
  -H "Content-Type: application/json" \
  -d @task.json

Limites de débit

Par organisation et par minute : 600 lectures (GET) et 60 écritures (POST, PATCH, DELETE). Chaque réponse porte l'état du compartiment dans les en-têtes X-RateLimit-*. Au-delà de la limite vous recevez 429 rate_limited avec Retry-After ; rien n'a été créé et aucune clé d'idempotence n'a été consommée, réessayer est donc toujours sans risque.

En-têtes de réponse

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1756910040

Identifiants de requête

Chaque réponse porte X-Request-Id. Envoyez votre propre valeur dans cet en-tête (jusqu'à 128 caractères parmi lettres, chiffres, ., _, : et-) et elle vous est renvoyée telle quelle : un même identifiant suit un appel dans vos logs et dans les nôtres. Communiquez-le quand vous contactez le support.

En-têtes de réponse

X-Request-Id: req_7f3c2a1b9e4d4c0f8a6b