Skip to main content

Guide d'intégration

Guide d'intégration Fabrixa API - authentification, première commande, gestion des webhooks, récupération des erreurs
DÉVELOPPEURS - GUIDE D'INTÉGRATION

Auth à l'exécution en quinze minutes.

Copier-coller du Fabrixa REST API : s'authentifier, lister les produits disponibles, passer une commande, enregistrer un webhook, gérer les événements du cycle de vie, passer une commande, enregistrer un webhook, gérer les événements du cycle de vie. JSON sur HTTPS, authentification par bearer-token, requêtes idempotentes, webhooks sécurisés. Pas de surprises.

REST + JSON - BEARER AUTH - IDEMPOTENT - WEBHOOK-DRIVEN

CONDITIONS PRÉALABLES

Ce dont vous avez besoin avant de commencer.

01
API KEY

Délivrée à partir du tableau de bord de votre compte Fabrixa. Clé Sandbox pour le développement, clé de production pour les commandes en cours. Les deux sont des jetons au porteur.

02
POINT DE TERMINAISON DU WEBHOOK

Un point de terminaison HTTPS accessible au public de votre côté qui peut accepter des requêtes POST JSON. Localhost fonctionne en dev via des outils de tunnellisation.

03
FILES D'ARTISANAT

Maquette prête à être imprimée, accessible via une URL HTTPS. Adobe Illustrator, Photoshop, matriciel ou vectoriel. Nous récupérons le fichier lors du rendu du travail d'impression.

ÉTAPE 1 - AUTHENTIFICATION

Testez la clé API avec un appel de bienvenue.

Authentification par jeton. L'URL de base du bac à sable est https://sandbox.api.fabrixa.com/v1; la production échange le sous-domaine.

GET /v1/compte
# Vérifier l'authentification et l'accès au compte
boucler https://sandbox.api.fabrixa.com/v1/account \N ---------------
  -H "Authorization : Bearer $FABRIXA_API_KEY" \
  -H "Accept : application/json"

# 200 OK
{
  "account_id": "acct_4fK8B2qZ",
  "environnement": "bac à sable",
  "niveau": "production",
  "url_rappel": nul
}

Un 401 signifie que la clé est erronée ou révoquée. Générez-en une nouvelle à partir du tableau de bord. Un 403 signifie que la clé est valide mais que vous n'avez pas l'autorisation d'accéder à la ressource (rare dans les cas de /compte).

ÉTAPE 2 - LISTE DES PRODUITS

Découvrez les SKU disponibles pour votre compte.

Renvoie le catalogue avec les identifiants des produits, les matériaux de base, les tailles et les niveaux de prix. Mise en cache locale ; le rafraîchissement du catalogue ne se fait pas par demande.

GET /v1/produits
GET /v1/produits?catégorie=vêtements&page=1&limite=20

# Réponse (tronquée)
{
  "données": [
    {
      "product_id": "prod_tee_unisex_aop",
      "catégorie": "habillement.tees-tops",
      "nom": "T-shirt unisexe AOP",
      "base": "organic-cotton-160gsm",
      "tailles": ["XS","S","M","L","XL","XXL"],
      "print" (impression)": "reactive-aop",
      "production_hub": "PT",
      "lead_time_days": { "min": 6, "max": 9 }
    }
  ],
  "page": 1,
  "a_plus": vrai
}
ÉTAPE 3 - PASSER UNE COMMANDE

Création d'ordre idempotent.

Set (jeu de mots) Clé d'idempotence à chaque demande d'ordre - ce qui permet de relancer le même appel sans créer d'ordres en double. Utilisez un UUID par ordre logique de votre côté.

POST /v1/commandes
PUBLIER /v1/ordres
Clé d'idempotence: 8e6f4b2a-7c1d-4f3e-9a8b-1e2d3c4b5a6f

{
  "order_ref": "shopify-1042",
  "éléments": [
    {
      "product_id": "prod_tee_unisex_aop",
      "taille": "L",
      "quantité": 2,
      "url_de_l'œuvre_d'art": "https://cdn.yourbrand.com/art/drop-001.png"
    }
  ],
  "destinataire": {
    "nom": "Lena Costa",
    "adresse_ligne1": "Rua das Flores 12",
    "ville": "Porto",
    "pays": "PT",
    "code_postal": "4050-262"
  },
  "emballage": "marque blanche"
}

# 201 Créé
{
  "order_id": "ord_8e6f4b2a",
  "statut": "reçu",
  "estimated_dispatch" (répartition estimée)": "2026-05-15",
  "webhook_events": ["order.printed","order.dispatched"]
}
ÉTAPE 4 - POINT D'ARRIVÉE DU WEBHOOK

S'abonner au cycle de vie de la commande.

Définissez l'URL du webhook une fois au niveau du compte. Chaque événement du cycle de vie de la commande POST à cette URL. Vérifier la signature HMAC avant le traitement.

PUT /v1/compte/webhook
PUT /v1/compte/webhook

{
  "url": "https://api.yourbrand.com/fabrixa/webhook",
  "événements": [
    "order.received",
    "order.printed",
    "order.dispatched",
    "order.failed"
  ]
}

# Webhook payload (POST vers votre point de terminaison)
{
  "événement": "order.dispatched",
  "order_id": "ord_8e6f4b2a",
  "order_ref": "shopify-1042",
  "horodatage": "2026-05-15T11:32:08Z",
  "suivi": {
    "transporteur": "DHL",
    "Numéro de suivi": "JJD0123456789",
    "tracking_url": "https://dhl.com/track/JJD0123456789"
  }
}

Référence complète de l'événement et vérification de la signature sur le page webhooks.

TRAITEMENT DES ERREURS ET LIMITES DE TAUX

Ce à quoi il faut s'attendre lorsque les choses tournent mal.

FORME DE LA RÉPONSE À L'ERREUR

Les erreurs sont au format JSON, jamais au format HTML.

Réponse d'erreur
{
  "erreur": {
    "code": "artwork_unreachable" (œuvre d'art inaccessible)",
    "message": "GET on artwork_url failed (timeout 30s)",
    "request_id": "req_94kQ7r2L",
    "réessayable": vrai
  }
}

Les codes sont des chaînes stables - ils peuvent être allumés en toute sécurité. réessayable : true signifie qu'il est sûr de réessayer avec la même clé d'idempotence.

LIMITES DE TAUX

Fenêtre coulissante, les en-têtes indiquent le budget.

  • Bac à sable : 60 req / minute par clé
  • Production : 600 req / minute par clé (augmentation sur demande)
  • En-têtes : X-RateLimit-Remaining, X-RateLimit-Reset
  • 429 réponse sur le dépassement avec Réessayer après secondes
  • Les livraisons de webhooks ne sont pas prises en compte dans votre budget d'appels entrants.
COINCÉ ?

Adressez-vous à un ingénieur en solutions.

Pour l'assistance à l'intégration, les problèmes de clés de bac à sable, les exigences personnalisées ou la planification de la capacité, il est préférable de s'adresser au canal technique SE plutôt qu'au service commercial. canal technique SE plutôt que ligne de vente. Réponse moyenne en un jour ouvrable.

Chariot (0 article)

Créez votre compte