Commandes

Cycle de vie

fichier → devis → commande (brouillon) → confirmée → offerte à une ferme
→ acceptée → en impression → imprimée (photo QC) → expédiée → livrée

Chaque transition émet un événement webhook : order.created, order.confirmed, order.in_production, order.printed, order.shipped, order.delivered — et côté fabrication job.offered, job.accepted, job.declined, job.printing, job.printed.

Créer une commande

Une commande consomme un ou plusieurs devis (items[].quote_id) — un devis validé fixe le prix, la couleur et la quantité d'une ligne. Ajoutez l'adresse de livraison et, si vous en avez une, votre référence (external_ref, ex. le numéro de commande Etsy).

• Brouillon : sans confirm, la commande reste en draft — rien n'est fabriqué, rien n'est offert aux fermes. Confirmez-la avec POST /v1/orders/{id}/confirm.
• Immédiat : "confirm": true à la création envoie directement en fabrication.
• Annulation : POST /v1/orders/{id}/cancel tant que la production n'a pas commencé ; ensuite l'API répond 409 order_in_production.

Idempotence

Passez un en-tête Idempotency-Key sur POST /v1/quotes et POST /v1/orders : si la même requête (même clé, même corps) est rejouée — retry réseau, worker relancé — l'API renvoie la réponse d'origine au lieu de créer un doublon.

-H "Idempotency-Key: etsy-1042"

Suivre une commande

• GET /v1/orders — liste paginée (limit, starting_after), filtrable par status et external_ref.
• GET /v1/orders/{id} — détail : lignes, jobs de fabrication, expéditions (transporteur, numéro de suivi), historique d'événements.
• Les webhooks vous poussent chaque changement — c'est la méthode recommandée, plutôt que d'interroger l'API en boucle.

Expédition

L'étiquette est achetée par FRED à l'acceptation du job (Sendcloud). Le colis part au nom de votre marque, avec bon de livraison conforme. Les événements shipment.created, shipment.updated et shipment.delivered suivent le transporteur jusqu'à la remise.