Pour accéder à l’API Integration, authentifiez vos requêtes avec un Application Access Token et une Application Key :

En-tête d'autorisation

Authorization: Bearer APPLICATION_ACCESS_TOKEN

En-tête de clé d'application

X-Application-Key: APPLICATION_KEY

Exemple de commande cURL

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/ping' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Remplacez APPLICATION_ACCESS_TOKEN par votre jeton d'accès réel et APPLICATION_KEY par votre clé d'application réelle.

Les endpoints de l’API Integration sont organisés par type de ressource et suivent l’architecture REST. Chaque endpoint représente une ressource, et les actions sont effectuées avec des méthodes HTTP standard.

Toutes les requêtes et réponses de l’API Integration utilisent JSON, ce qui fournit une interface cohérente et simple.

Pour plus de détails sur chaque point de terminaison, y compris des exemples de requêtes et de réponses, consultez notre Swagger documentation.

Format de réponse

Tous les points de terminaison renvoient des données dans un format standardisé avec ces objets :

{
  "links": {
    "self": "https://api.fabrixa.com/v2/integration/products",
    "first_page": "https://api.fabrixa.com/v2/integration/products?page=1",
    "last_page": "https://api.fabrixa.com/v2/integration/products?page=2",
    "next_page": "https://api.fabrixa.com/v2/integration/products?page=2",
    "prev_page": null
  },
  "meta": {
    "total": 2,
    "current_page": 1,
    "per_page": 10
  },
  "data": [
    {
      "id": 1,
      "name": "Product 1",
      "description": "Description of Product 1"
    },
    {
      "id": 2,
      "name": "Product 2",
      "description": "Description of Product 2"
    }
  ]
}

Description des objets de réponse

Toutes les requêtes API renvoient des codes d'état HTTP qui fournissent un aperçu de la réponse.

Corps de la réponse d'erreur

Un exemple de corps de réponse d'erreur :

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/ping"
    },
    "meta": [],
    "errors": {
        "messages": [
            "Application Key is not specified."
        ]
    }
}

errors contient des détails sur ce qui a échoué. Le tableau messages répertorie les descriptions d'erreurs. Pour une mauvaise demande, vous recevrez les noms des champs dont la validation a échoué.

L'API d'intégration prend en charge une limite de 30 requêtes par application et par minute.

Si vous dépassez cette limite, vous recevrez une réponse 429 Too Many Requests.

Toutes les réponses de l'API d'intégration incluent l'en-tête X-RateLimit-Remaining, le nombre de requêtes que le client peut encore effectuer, et l'en-tête X-RateLimit-Limit, le total autorisé par minute.

Créez des commandes dans Fabrixa depuis votre boutique ou plateforme, joignez les fichiers d’impression requis et suivez chaque article pendant le fulfilment.

Pour créer une commande via l’API Fabrixa Integration, envoyez une requête POST vers https://api.fabrixa.com/v2/integration/orders. Le body de la requête doit contenir :

Structure du corps de la demande

Demande d'échantillon

{
  "number": "NL2024010201",
  "comments": "Customer agrees with a low resolution file.",
  "purchased_at": "2024-06-26 21:12:22",
  "client_ip": "127.0.0.1",
  "client_user_agent": "Mozilla",
  "rows": [
    {
      "variant_id": 2705,
      "quantity": 1,
      "client_barcode": "1234567890",
      "sources": [
        {
          "type": "file",
          "url": "https://samples-files.com/samples/sample.pdf"
        }
      ]
    }
  ],
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "3VJtP@example.com",
    "phone": "0647185332"
  },
  "shipping_address": {
    "address": "Pierre cuypershof",
    "address2": "17",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "state": "North Holland",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0647185332"
  },
  "shipping_label": {
    "method_name": "Post NL",
    "tracking_number": "3SYZXG1585577",
    "tracking_url": "https://postnl.nl/tracktrace/3SYZXG1585577",
    "label_pdf_url": "https://api.fabrixa.com/storage/8966630826422f36d822f91680012141.pdf",
    "date_created": "2024-01-01 00:00:00"
  }
}

Pour obtenir le statut de fulfilment d’une commande spécifique, envoyez une requête GET vers https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. La réponse fournit les fulfilments liés à la commande, avec le statut de chaque article, les détails produit et la progression des étapes de production.

Exemple de réponse

{
    "data": [
        {
            "id": 1499,
            "barcode": "1200004169200",
            "status": "unfulfilled",
            "created_at": "2024-08-19T12:38:59.000000Z",
            "updated_at": "2024-08-19T12:39:00.000000Z",
            "variant": {
                "id": 32327,
                "name": "Test iAPI blanket product",
                "subtitle": "100 x 150 cm",
                "SKU": "COF099191"
            },
            "product": {
                "id": 1306,
                "name": "Test iAPI blanket product",
                "subtitle": "Test iAPI blanket product"
            },
            "production_steps": [
                {
                    "id": 5,
                    "name": "Print duvet",
                    "description": "Printing the duvet according to the specified design and dimensions.",
                    "status": {
                        "value": "pending",
                        "notes": null,
                        "updated_at": null
                    }
                },
                {
                    "id": 6,
                    "name": "Print pillow",
                    "description": "Printing the pillow cover with the assigned design.",
                    "status": {
                        "value": "pending",
                        "notes": null,
                        "updated_at": null
                    }
                }
            ]
        }
    ]
}

La réponse comprend une liste de réponses, chacune fournissant :

Chaque enregistrement d'exécution correspond à un produit ou à une variante de produit spécifique dans la commande, et chaque copie du produit dans la commande possède son propre enregistrement d'exécution - chaque article est suivi individuellement tout au long de la production.

Si aucune exécution n'est retournée pour une commande, celle-ci n'est pas encore entrée en phase de traitement.

Lorsque vous ajoutez des source files à une commande, assurez-vous qu’ils respectent les exigences suivantes :

"sources": [
    {
        "type": "file",
        "url": "https://samples-files.com/samples/source.pdf"
    }
]

Exigences PDF et ordre des pages

L’ordre des pages dans le PDF est important. Les pages sont associées aux couches de produits par position et l'ordre des pages attendu dépend du type de produit. Assurez-vous que les pages de votre PDF suivent la séquence de couches correcte pour le produit que vous soumettez.

Important : chaque page PDF doit correspondre aux dimensions requises pour sa couche de produit et être orientée correctement. Placez l'illustration de manière à ce que le haut du motif soit aligné avec le haut de la page. Une taille ou une orientation de page incorrecte peut entraîner des problèmes de mise à l'échelle, de rotation ou d'alignement en production.

Fabrixa Studio est un outil qui permet aux utilisateurs de personnaliser et de personnaliser de manière transparente les produits en temps réel avec une interface intuitive où les utilisateurs peuvent créer ou télécharger leurs propres créations.

Fabrixa Studio est idéal pour les entreprises proposant des produits personnalisés, permettant aux clients de visualiser leurs créations avant de finaliser les commandes.

Vous pouvez intégrer Fabrixa Studio dans votre site web avec un iframe. Vos clients peuvent ainsi personnaliser les produits directement sur votre site pendant le checkout.

Exemple d'iframe pour l'intégration de Fabrixa Studio :

<iframe id="fabrixa-studio"
    src="https://studio.fabrixa.com?application_key={application_key}&sku={product_sku}&cart_item_key={cart_item_key}"
    name="FabrixaStudio"
    scrolling="no"
    frameborder="1"
    width="100%"
    height="100%"
    allowfullscreen="">
</iframe>

Remplacez les valeurs de product_sku, cart_item_key et application_key par vos valeurs dynamiques.

• application_key - clé unique pour l'authentification auprès de l'API d'intégration.
• product_sku - le SKU de la variante du produit, récupéré de l'API d'intégration.
• cart_item_key - une valeur unique de la plateforme d'intégration identifiant l'article du panier associé au produit. Utilisé pour enregistrer les personnalisations de l'utilisateur ; lors de la création de la commande, il identifie les personnalisations enregistrées et les affecte à la commande. Voir l'exemple ci-dessous.

Demande de création d'une commande avec cart_item_key

{
  "number": "NL2024010201",
  "purchased_at": "2024-06-26 21:12:22",
  "client_ip": "127.0.0.1",
  "client_user_agent": "Mozilla",
  "rows": [
    {
      "sku": "SB796162",
      "quantity": 1,
      "cart_item_key": "0cb76770-de2d-4524-aa48-47b6e5f0d8a5"
    }
  ],
  "customer": {
    "...": "..."
  },
  "shipping_address": {
    "...": "..."
  },
  "shipping_label": {
    "...": "..."
  }
}

Lorsque vous cliquez sur le bouton Ajouter au panier à l'intérieur de l'iframe, la commande suivante est exécutée :

window.parent.postMessage('customizationFinished', '*');

De même, lorsque l'on clique sur le bouton Retour :

window.parent.postMessage('closeButtonClicked', '*');

La méthode postMessage facilite la communication d'origine croisée entre l'iframe et sa fenêtre parent, lui permettant d'informer le parent des actions spécifiques de l'utilisateur.

Le premier argument de postMessage correspond aux données que vous souhaitez envoyer. La chaîne 'customizationFinished' indique que l'utilisateur a finalisé la personnalisation et ajoute le produit au panier. 'closeButtonClicked' indique que l'utilisateur a choisi de revenir en arrière.

Dans la fenêtre parent, écoutez ces messages à l'aide de l'écouteur d'événements message :

window.addEventListener('message', function(event) {
    if (event.origin === 'https://studio.fabrixa.com') {
        if (event.data === 'customizationFinished') {
            // Handle the Add to Cart event
            console.log('Customization finished and item can be added to cart.');
        } else if (event.data === 'closeButtonClicked') {
            // Handle the Back button event
            console.log('Back button clicked.');
        }
    }
});

Vérifiez toujours le origin des messages entrants pour vous assurer qu’ils proviennent d’une source fiable. En fonction du message reçu, effectuez les actions nécessaires - mettre à jour l'interface utilisateur, traiter le panier, etc. La validation de origin est cruciale pour la sécurité - elle empêche les scripts non autorisés d'interagir avec votre application.

Une fois la personnalisation terminée, affichez la conception finale à l'aide de l'URL d'aperçu ci-dessous. Cette URL renvoie une image du produit personnalisé, adaptée à la valeur src dans une balise <img>. Idéal pour afficher le produit personnalisé dans votre panier, le récapitulatif de votre commande ou n'importe où dans l'interface de votre boutique.

https://api.fabrixa.com/v2/studio/customizations/{CART_ITEM_KEY}/preview?Application-Key={APPLICATION_KEY}

Remplacez {CART_ITEM_KEY} par la clé réelle de l'article du panier et {APPLICATION_KEY} par votre clé d'application valide.

Exemple d'utilisation dans une balise d'image :

<img
    src="https://api.fabrixa.com/v2/studio/customizations/{CART_ITEM_KEY}/preview?Application-Key={APPLICATION_KEY}"
    alt="Customized Product Preview"
    style="max-width: 100%; height: auto;" />

Les webhooks sont utilisés par Fabrixa pour informer votre système des événements en temps réel : commandes de mises à jour ou de créations. Lorsqu'un événement se produit, Fabrixa envoie un webhook à votre serveur contenant les informations pertinentes. Votre serveur doit exposer un point de terminaison POST public pour gérer les webhooks entrants.

La requête webhook inclut les headers suivants pour vous aider à identifier et valider la requête entrante :

{
  "content-type": "application/json",
  "x-webhook-signature": "YmEwNjBhMGMyMzE3ZWQ5NGQ5NDYwOGVhNzNhMjQ4M2MyODZkZmI3NTQ1YzYxYjdkMzNhZjgzYzBmMTkxYTAxMw==",
  "x-webhook-topic": "order.updated"
}

Répartition de l'en-tête

• content-type - toujours défini sur application/json pour les webhooks.
• x-webhook-signature - la signature HMAC-SHA256 pour la vérification des demandes.
• x-webhook-topic - le type d'événement ou le sujet du webhook. Par exemple :
  • order.created - déclenché lorsqu'une nouvelle commande est créée.
  • order.updated - déclenché lorsqu'une commande existante est mise à jour.

Les webhooks Fabrixa notifient votre système des changements de statut ou d’activité des commandes. Chaque webhook est déclenché par une valeur x-webhook-topic spécifique. Topics actuellement pris en charge :

Statuts des commandes

• Terminé : la commande a été expédiée ou récupérée et la réception est confirmée. Pour les produits numériques, le client a payé et les fichiers sont disponibles en téléchargement.
• Annulé - le client a annulé le paiement ; la transaction n'a pas été complétée.
• En attente - la commande est temporairement bloquée.
• Importée - la commande a été importée dans la plateforme.

Statuts d'exécution

• Non exécutée : la commande n'a pas encore été préparée ni envoyée.
• Partiellement exécutée : certains articles ont été traités ou expédiés, d'autres sont toujours en attente.
• Planifiée : la commande est planifiée et planifiée pour son traitement.
• Rejetée : la demande d'exécution a été refusée, souvent en raison de détails de commande non valides ou indisponibilité.
• Exécutée - la commande a été entièrement traitée et livrée ou mise à la disposition du client.

Un exemple de charge utile envoyée avec le webhook. Cette charge utile représente une mise à jour de commande :

{
  "id": 23069,
  "number": "1250211835",
  "comments": null,
  "is_archived": false,
  "status": "imported",
  "fulfillment_status": "unfulfilled",
  "purchased_at": "2025-04-17T16:17:21.000000Z",
  "created_at": "2025-04-17T16:17:23.000000Z",
  "updated_at": "2025-04-18T07:43:52.000000Z",
  "rows": [
    {
      "id": 27954,
      "quantity": 1,
      "client_barcode": "1250211835",
      "fulfillment_status": "unfulfilled",
      "variant": {
        "id": 293457,
        "name": "Sherpa fleece deken",
        "subtitle": "100x150",
        "SKU": "SFD787231",
        "product": {
          "id": 5319,
          "name": "Sherpa fleece deken",
          "subtitle": "Sherpa fleece deken"
        }
      },
      "sources": [
        {
          "type": "print",
          "url": "https://storage.googleapis.com/fabrixa-api/storage/99b10aaa-df4d-47e4-9bc9-b1d6a785df4c/orders/merchandise-sources/120002795400.pdf",
          "properties": {
            "fill_style": "contain"
          }
        }
      ]
    }
  ]
}

Pour garantir que la requête webhook est authentique et non modifiée, vérifiez le header x-webhook-signature. Recalculez la signature HMAC-SHA256 avec le raw request payload et votre secret key, puis comparez-la à la signature reçue.

Exemple PHP brut

$payload = file_get_contents('php://input');
$yourSecret = 'your-secret-key';
$expectedSignature = base64_encode(hash_hmac('sha256', $payload, $yourSecret, true));
$receivedSignature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(403);
    exit('Invalid signature');
}

Exemple Laravel

public function handle(Request $request)
{
    $yourSecret = 'your-secret-key';
    $payload = $request->getContent();
    $expectedSignature = base64_encode(hash_hmac('sha256', $payload, $yourSecret, true));
    $receivedSignature = $request->header('x-webhook-signature');

    if (!hash_equals($expectedSignature, $receivedSignature)) {
        abort(403, 'Invalid signature');
    }

    // Continue processing...
}

Remplacez $yourSecret par votre clé secrète partagée. Utilisez toujours hash_equals pour comparer les signatures afin d’atténuer les attaques temporelles.

Les webhooks sont désactivés par défaut après 10 tentatives de livraison infructueuses. Si votre point de terminaison renvoie un statut d'échec tel que 404 ou toute erreur 5xx, le webhook réessayera 10 fois au total. S'il continue à renvoyer un code de réponse non-2xx ou non-3xx, il sera désactivé. Les réponses réussies comprennent :

• 2xx - indique un traitement réussi, par ex. 200 OK.
• 301 et 302 - réponses de redirection indiquant que le webhook a été géré ou transféré avec succès.

Nous recommandons fortement que votre point de terminaison renvoie un code d'état 200 OK le plus rapidement possible pour accuser réception réussie du webhook. Bien que toute réponse 2xx ou 3xx soit considérée comme réussie, 200 est la plus couramment utilisée et la plus fiable.

Pour éviter les délais d'attente ou les tentatives de livraison, renvoyez immédiatement 200 OK et gérez le traitement de la charge utile du webhook de manière asynchrone, par exemple via une tâche en arrière-plan ou une file d'attente. Si votre point de terminaison met trop de temps à répondre, cela peut être considéré comme un échec même si la réponse aboutit finalement.

Les réponses avec des codes d'état dans la plage 4xx ou 5xx, ou des délais d'attente, déclencheront de nouvelles tentatives selon le mécanisme de nouvelle tentative.