Créer et suivre les commandes avec l’API FRED

Créer la commande

POST /v1/storefront/orders accepte soit quote_id, soit product_id. L’adresse complète du destinataire est obligatoire. L’adresse de départ est celle de l’atelier fabricant ; aucune adresse d’expédition de marque n’est à configurer. Ajoutez external_ref pour retrouver votre numéro de commande dans FRED et metadata pour vos références applicatives.

Par défaut, FRED retient le fabricant recommandé. Un option_id vous permet de conserver un choix explicite fait à partir d’un devis. max_total_cents est un plafond facultatif pour un devis et obligatoire pour un produit commandé directement. Les montants sont exprimés en centimes d’euro.

Chaque option du devis expose shipping_options (code, transporteur, service, prix et délai quand il est connu). Pour recalculer avec l’adresse complète et choisir un service, appelez POST /v1/storefront/quotes/{quote_id}/shipping avec shipping_address, supplier_id et shipping_service_code. Vous pouvez ensuite transmettre shipping_service_code dans la commande. FRED revérifie le tarif pour l’adresse finale et refuse tout dépassement de max_total_cents.

Dans Réglages → Validation des commandes, la marque choisit le traitement de ses prochaines commandes : automatique sans pause, pause de 1 heure, pause de 2 heures, ou attente de validation manuelle sans limite de temps. Indiquez brand_id dans la commande (ou utilisez un produit rattaché à cette marque).

`approval_mode`	Comportement
Omis ou `null`	Suit les réglages de la marque ; sans marque, ceux du compte
`auto`	Suit le délai de la marque et respecte une éventuelle validation manuelle configurée pour elle
`manual`	Ajoute une attente de validation manuelle pour cette commande

Pendant la pause, aucun paiement ni envoi au fabricant n’a lieu. Le prix accepté reste valable pendant la revue programmée. À l’échéance, FRED vérifie la disponibilité et le paiement avant de lancer la fabrication. Un problème de disponibilité ou de paiement laisse la commande à traiter dans le dashboard. Une pause manuelle prolongée peut nécessiter une actualisation du prix.

Vous pouvez aussi choisir Approuver maintenant dans la fiche d’une commande. Modifier les réglages de la marque ne change pas les commandes déjà reçues.

Une clé API n’active pas automatiquement le paiement de votre compte. Les plafonds, la carte et les éventuelles validations du modèle doivent être prêts. Tant que ordering_enabled est faux, le devis sert à préparer l’intégration ; la création renvoie 503 ordering_unavailable.

Lire le résultat

201 signifie commande créée, pas encore imprimée ni forcément payée. La réponse fournit id, status, payment_status, total_cents, shipments et dashboard_url. Si une vérification ou une authentification bancaire est nécessaire, ouvrez cette commande dans le dashboard.

Un 202 avec object: "order_request" signifie que le devis est encore en calcul, sans commande créée. Attendez poll_url, puis répétez exactement la même requête avec la même clé d’idempotence.

Suivre depuis votre site

curl https://api.fredpod.com/v1/storefront/orders/ord_abc123 \
  -H "X-API-Key: $FRED_API_KEY"

Statut courant	Sens pour votre boutique
`pending_review`	Une validation reste nécessaire
`payment_required`	Aucune carte enregistrée : ajouter une carte dans Facturation puis payer la commande. Aucun débit tenté.
`payment_failed`	Paiement à résoudre dans le dashboard
`confirmed`	Commande confirmée, en attente de prise en charge
`in_production`	Fabrication prise en charge ou en cours
`printed`	Fabrication terminée, avant expédition
`shipped`	Colis remis au transporteur
`delivered`	Livraison signalée par le transporteur
`failed`	Fabrication à reprendre ; consultez FRED
`cancelled`	Commande annulée

Les événements peuvent arriver en retard ou plusieurs fois. Utilisez les webhooks pour déclencher une mise à jour, puis ce GET pour relire l’état courant. Les numéros et liens de suivi sont dans shipments.

Prix expiré, disponibilité ou adresse modifiée

Une offre peut devenir indisponible entre son affichage et le paiement. FRED recontrôle la disponibilité et le financement ; aucune demande n’est envoyée au fabricant avant confirmation du débit.

destination_changed : demandez un nouveau prix de livraison.
option_unavailable : rechargez le devis, vérifiez le motif ou recalculez-le.
price_limit_exceeded : faites accepter un nouveau plafond avant de recommander.
preview_approval_required : affichez et faites valider le modèle concerné.

Après une erreur réseau, répétez la requête avec la même Idempotency-Key et les mêmes paramètres. Après un changement volontaire de prix, modèle ou adresse, utilisez un nouveau devis et une nouvelle clé. Une création rejouée conserve son résultat initial ; le GET de la commande donne son statut le plus récent.

Votre marque

Configurez l’identité, les documents et les inserts dans le dashboard. Utilisez X-Brand-Id pour le contexte de la boutique et, si nécessaire, brand_id sur la commande. Les API boutique gèrent la vente ; la préparation de votre compte reste dans le dashboard.