Référence de l’API Fabrixa Integration

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.

Le mode bac à sable vous permet de tester votre intégration de bout en bout avant qu’une commande réelle ne soit produite ou facturée. Il s’applique à l’ensemble de votre compte : les commandes de tous les canaux de vente, y compris l’Integration API et les boutiques Shopify et WooCommerce connectées, ne sont ni produites ni débitées de votre solde. Votre compte est en mode bac à sable tant que son statut est en attente d’activation.

En mode bac à sable, vous pouvez :

• connecter votre boutique Shopify ou WooCommerce, ou créer un canal Integration API ;
• ajouter des produits et vérifier les prix et les estimations de livraison ;
• importer, créer, modifier et annuler des commandes ;
• constater qu’aucune de ces commandes n’est produite ni débitée de votre solde ;
• vérifier la remise des webhooks et les signatures.

Pour tester des commandes, ajoutez des produits du catalogue Fabrixa : ouvrez un produit, cliquez sur Vendre ce produit et choisissez des variantes et des designs. Ils apparaissent ensuite sous Mes produits.

Pour passer votre compte en mode bac à sable, ouvrez Platform, allez dans Paramètres → Entreprise → Mode bac à sable et cliquez sur Passer en mode bac à sable. Vous pouvez aussi l’activer lors de l’ajout d’un nouveau canal de vente, y compris un canal Integration API, ou écrire à support@fabrixa.com et nous passerons votre compte en mode bac à sable pour vous. Le mode bac à sable est réservé aux comptes actifs.

Lorsque vous êtes prêt, activez vous-même votre compte dans Platform sous Paramètres → Entreprise → Mode bac à sable. Vous pouvez aussi écrire à support@fabrixa.com et nous l’activerons pour vous. Vos boutiques connectées et vos identifiants API continuent de fonctionner : rien n’est à reconfigurer.

Une fois le compte activé, toutes les nouvelles commandes partent en production et sont débitées de votre solde. Les commandes créées avant l’activation restent des commandes de test : elles ne sont jamais produites ni facturées, même après l’activation.

Le catalogue est tout ce que Fabrixa produit. Vos produits sont les produits du catalogue que vous avez ajoutés à votre compte Fabrixa, avec vos propres noms, descriptions, images et SKU. Une ligne de commande nomme une variante de produit - une taille ou une version d'un produit - par son sku ou son variant_id : une variante de l'un de vos produits, ou une variante du catalogue commandée directement.

Pour lister les produits que Fabrixa produit, envoyez une requête GET à https://api.fabrixa.com/v2/integration/catalog/products avec vos identifiants. Il liste les produits actifs qui ont une variante qu'un partenaire d'impression produit actuellement, et seulement ces variantes, chacune avec son SKU, son prix de vente, ses dimensions et ses valeurs d'option.

Paramètres de requête

Demande d'échantillon

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/catalog/products?category_id=19&limit=10' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemple de réponse

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/catalog/products",
        "first_page": "https://api.fabrixa.com/v2/integration/catalog/products?page=1",
        "last_page": "https://api.fabrixa.com/v2/integration/catalog/products?page=1",
        "next_page": null,
        "prev_page": null
    },
    "meta": {
        "total": 1,
        "current_page": 1,
        "per_page": 10
    },
    "data": [
        {
            "id": 1305,
            "name": "Duvet Cover",
            "subtitle": "Duvet Cover with a pillow",
            "description": "
Soft personalized duvet cover.
",
            "slug": "duvet-cover",
            "code": "DUVET-001",
            "HS_code": "63023100",
            "created_at": "2024-08-16T09:32:07.000000Z",
            "updated_at": "2024-08-16T09:38:50.000000Z",
            "is_sellable": true,
            "variants_min_selling_price": "29.95",
            "variants_max_selling_price": "49.95",
            "type": {
                "id": 5,
                "name": "Duvet cover"
            },
            "status": {
                "id": 2,
                "name": "Active"
            },
            "categories": [
                {
                    "id": 19,
                    "name": "Duvet covers",
                    "description": "Personalized duvet covers",
                    "parent_category": {
                        "id": 8,
                        "name": "Bedroom",
                        "description": "Bedroom products"
                    }
                }
            ],
            "images": [
                {
                    "id": 5566,
                    "url": "https://storage.googleapis.com/example/catalog/duvet-cover.jpg",
                    "is_main": true,
                    "created_at": "2024-08-16T09:32:07.000000Z",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ],
            "variants": [
                {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "description": null,
                    "SKU": "COT864311",
                    "selling_price": "29.95",
                    "width": "140.00",
                    "height": "200.00",
                    "length": "2.00",
                    "weight": "1.20",
                    "created_at": "2024-08-06T11:23:44.000000Z",
                    "updated_at": "2024-08-16T09:36:37.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 471,
                                    "value": "140x200"
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": 2708,
                    "name": "Duvet Cover",
                    "subtitle": "200x220",
                    "description": null,
                    "SKU": "COT864314",
                    "selling_price": "49.95",
                    "width": "200.00",
                    "height": "220.00",
                    "length": "2.00",
                    "weight": "1.80",
                    "created_at": "2024-08-06T11:23:44.000000Z",
                    "updated_at": "2024-08-16T09:37:11.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 474,
                                    "value": "200x220"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Champs de la réponse

Pour lister les catégories dans lesquelles le catalogue est organisé, envoyez une requête GET à https://api.fabrixa.com/v2/integration/catalog/categories avec vos identifiants. La réponse contient les catégories de premier niveau, chacune avec ses sous-catégories imbriquées dans sub_categories et le nombre de produits du catalogue qu'elle contient dans products_count. Passez l'id d'une catégorie comme category_id en parcourant le catalogue, ou l'id d'une catégorie de premier niveau comme parent_category_id pour obtenir d'un coup les produits de toutes ses sous-catégories.

Paramètres de requête

Demande d'échantillon

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/catalog/categories?with_products_only=true' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemple de réponse

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/catalog/categories"
    },
    "meta": {
        "total": 1
    },
    "data": [
        {
            "id": 8,
            "name": "Bedroom",
            "description": "Bedroom products",
            "sort_number": 1,
            "slug": "bedroom",
            "products_count": 12,
            "sub_categories": [
                {
                    "id": 19,
                    "name": "Duvet covers",
                    "description": "Personalized duvet covers",
                    "sort_number": 1,
                    "slug": "duvet-covers",
                    "products_count": 7,
                    "images": [],
                    "sub_categories": []
                },
                {
                    "id": 20,
                    "name": "Pillows",
                    "description": "Personalized pillows and pillowcases",
                    "sort_number": 2,
                    "slug": "pillows",
                    "products_count": 4,
                    "images": [],
                    "sub_categories": []
                }
            ],
            "parent_category": null,
            "images": [
                {
                    "id": 781,
                    "url": "https://storage.googleapis.com/example/catalog/bedroom.jpg",
                    "is_main": true,
                    "created_at": "2024-08-16T09:32:07.000000Z",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ]
        }
    ]
}

Pour lister les produits de votre compte, envoyez une requête GET à https://api.fabrixa.com/v2/integration/products avec vos identifiants. Vos produits sont les produits du catalogue que vous avez ajoutés à votre compte Fabrixa : ils portent les noms, descriptions et images que vous leur avez donnés là-bas, et leurs variantes les valeurs de SKU que vous avez choisies. Seuls les produits actifs sont listés, dix par page sauf si vous passez limit.

Paramètres de requête

Demande d'échantillon

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

Exemple de réponse

{
    "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=1",
        "next_page": null,
        "prev_page": null
    },
    "meta": {
        "total": 1,
        "current_page": 1,
        "per_page": 10
    },
    "data": [
        {
            "id": 5321,
            "name": "Dreamy Duvet Cover",
            "subtitle": "Duvet cover with a matching pillowcase",
            "description": "
Our personalized duvet cover, printed on soft cotton sateen.
",
            "slug": "dreamy-duvet-cover",
            "width": "50.00",
            "height": "50.00",
            "length": "20.00",
            "weight": "100.00",
            "created_at": "2025-03-04T10:12:40.000000Z",
            "updated_at": "2025-03-04T10:15:02.000000Z",
            "type": {
                "id": 5,
                "name": "Duvet cover",
                "description": "Duvet cover with pillow"
            },
            "available_options": [
                {
                    "id": 151,
                    "name": "Duvet Size",
                    "values": [
                        {
                            "id": 471,
                            "value": "140x200"
                        },
                        {
                            "id": 474,
                            "value": "200x220"
                        }
                    ]
                }
            ],
            "categories": [
                {
                    "id": 912,
                    "name": "Bedding"
                }
            ],
            "collections": [
                {
                    "id": 77,
                    "name": "Spring 2025"
                }
            ],
            "images": [
                {
                    "id": 48120,
                    "is_main": true,
                    "image_size": "1200x1200",
                    "url": "https://storage.googleapis.com/example/shop/dreamy-duvet-cover.jpg",
                    "screen_type_size": "large",
                    "sort_number": 1
                }
            ],
            "variants": [
                {
                    "id": 32323,
                    "name": "Dreamy Duvet Cover",
                    "subtitle": "140x200",
                    "description": null,
                    "SKU": "DDC-140200",
                    "created_at": "2025-03-04T10:12:41.000000Z",
                    "updated_at": "2025-03-04T10:12:41.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 471,
                                    "value": "140x200"
                                }
                            ]
                        }
                    ],
                    "images": [],
                    "available_source_types": ["duvet", "pillow", "pillow-back"],
                    "required_source_types": ["duvet", "pillow"]
                },
                {
                    "id": 32326,
                    "name": "Dreamy Duvet Cover",
                    "subtitle": "200x220",
                    "description": null,
                    "SKU": "DDC-200220",
                    "created_at": "2025-03-04T10:12:41.000000Z",
                    "updated_at": "2025-03-04T10:12:41.000000Z",
                    "options": [
                        {
                            "id": 151,
                            "name": "Duvet Size",
                            "values": [
                                {
                                    "id": 474,
                                    "value": "200x220"
                                }
                            ]
                        }
                    ],
                    "images": [],
                    "available_source_types": ["duvet", "pillow", "pillow-back"],
                    "required_source_types": ["duvet", "pillow"]
                }
            ]
        }
    ]
}

Pour lire un seul produit, envoyez une requête GET à https://api.fabrixa.com/v2/integration/products/{product_id}, où {product_id} est son id. La réponse contient les mêmes champs que la liste. Un produit qui n'est pas dans votre compte, même un produit du catalogue, répond 404 Not Found avec le message Product not found.

Champs de la réponse

Une variante est une version commandable d'un produit - une taille, une couleur - et ce que nomme une ligne de commande, par sku ou par variant_id. Pour lire une variante de l'un de vos produits, envoyez une requête GET à https://api.fabrixa.com/v2/integration/variants/{variant_id}, où {variant_id} est son id. Une variante d'un produit qui n'est pas dans votre compte répond 404 Not Found avec le message Variant not found.

Demande d'échantillon

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

Exemple de réponse

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/variants/32323"
    },
    "meta": [],
    "data": {
        "id": 32323,
        "name": "Dreamy Duvet Cover",
        "subtitle": "140x200",
        "description": null,
        "SKU": "DDC-140200",
        "created_at": "2025-03-04T10:12:41.000000Z",
        "updated_at": "2025-03-04T10:12:41.000000Z",
        "width": "140.00",
        "height": "200.00",
        "length": "2.00",
        "weight": "1.20",
        "options": [
            {
                "id": 151,
                "name": "Duvet Size",
                "values": [
                    {
                        "id": 471,
                        "value": "140x200"
                    }
                ]
            }
        ],
        "images": [],
        "product": {
            "id": 5321,
            "name": "Dreamy Duvet Cover",
            "subtitle": "Duvet cover with a matching pillowcase",
            "description": "
Our personalized duvet cover, printed on soft cotton sateen.
",
            "description2": null,
            "slug": "dreamy-duvet-cover",
            "created_at": "2025-03-04T10:12:40.000000Z",
            "updated_at": "2025-03-04T10:15:02.000000Z"
        },
        "available_source_types": ["duvet", "pillow", "pillow-back"],
        "required_source_types": ["duvet", "pillow"]
    }
}

Champs de la réponse

Une ligne de commande pour cette variante, avec un PDF dont les pages sont ses couches :

"rows": [
    {
        "sku": "DDC-140200",
        "quantity": 1,
        "sources": [
            {
                "type": "file",
                "url": "https://samples-files.com/samples/duvet-cover.pdf"
            }
        ]
    }
]

Quelles variantes peuvent être commandées

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": "0612345678"
  },
  "shipping_address": {
    "address": "Voorbeeldstraat",
    "address2": "17",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "state": "North Holland",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0612345678"
  },
  "shipping_label": {
    "method_name": "Post NL",
    "tracking_number": "3SABCD1234567",
    "tracking_url": "https://postnl.nl/tracktrace/3SABCD1234567",
    "label_pdf_url": "https://api.fabrixa.com/storage/8966630826422f36d822f91680012141.pdf",
    "date_created": "2024-01-01 00:00:00"
  }
}

Exemple de réponse

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Customer agrees with a low resolution file.",
        "is_archived": false,
        "status": "imported",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-26T21:15:04.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "17",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

Pour mettre à jour une commande, envoyez une requête PATCH vers https://api.fabrixa.com/v2/integration/orders/{order_id}, où {order_id} est l’identifiant Fabrixa de la commande. Seuls les champs envoyés sont modifiés, et le statut de la commande reste inchangé. La réponse contient la commande mise à jour. Vous pouvez modifier :

Demande d'échantillon

{
  "comments": "Deliver to the neighbours if nobody is home.",
  "shipping_address": {
    "address": "Voorbeeldstraat",
    "address2": "19",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0612345678"
  }
}

Exemple de réponse

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Deliver to the neighbours if nobody is home.",
        "is_archived": false,
        "status": "imported",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-27T09:41:18.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "19",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338"
    },
    "meta": [],
    "errors": {
        "rows": [
            "Order rows cannot be changed. Cancel the order and create a new one."
        ]
    }
}

Pour annuler une commande, envoyez une requête POST sans body vers https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, où {order_id} est l’identifiant Fabrixa de la commande (le champ numérique id de la commande), et non votre numéro de commande. La réponse contient la commande avec le statut canceled, et un webhook order.updated est envoyé.

Exemple de réponse

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338/cancel"
    },
    "meta": [],
    "data": {
        "id": 20338,
        "number": "NL2024010201",
        "comments": "Customer agrees with a low resolution file.",
        "is_archived": false,
        "status": "canceled",
        "fulfillment_status": "unfulfilled",
        "purchased_at": "2024-06-26T21:12:22.000000Z",
        "created_at": "2024-06-26T21:15:03.000000Z",
        "updated_at": "2024-06-27T10:02:45.000000Z",
        "rows": [
            {
                "id": 41600,
                "quantity": 1,
                "client_barcode": "1234567890",
                "fulfillment_status": "unfulfilled",
                "variant": {
                    "id": 2705,
                    "name": "Duvet Cover",
                    "subtitle": "140x200",
                    "SKU": "COT864311",
                    "product": {
                        "id": 1305,
                        "name": "Duvet Cover",
                        "subtitle": "Duvet Cover with a pillow"
                    }
                },
                "sources": [
                    {
                        "type": "file",
                        "url": "https://samples-files.com/samples/sample.pdf",
                        "properties": null
                    }
                ]
            }
        ],
        "shipments": [],
        "customer": {
            "email": "3VJtP@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678"
        },
        "shipping_address": {
            "address": "Voorbeeldstraat",
            "address2": "17",
            "address3": null,
            "city": "Amsterdam",
            "country": "Netherlands",
            "country_code": "NL",
            "company": null,
            "first_name": "John",
            "last_name": "Doe",
            "phone": "0612345678",
            "state": "North Holland",
            "postal_code": "1012 AB"
        }
    }
}

Si la commande ne peut pas être annulée, l’API répond 412 Precondition Failed avec un message qui en donne la raison : son statut actuel ne le permet pas (le statut figure dans le message), ou la production a déjà commencé.

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/orders/20338/cancel"
    },
    "meta": [],
    "errors": {
        "messages": [
            "This order cannot be canceled in its current status (ready for shipping)."
        ]
    }
}

Une commande est suivie à l'aide de trois statuts : le status de la commande, son statut de production fulfillment_status et le status de chaque expédition dans shipments. Chaque changement est envoyé dans le webhook order.updated et renvoyé par GET /orders/{order_id}.

Statuts des commandes

Le status d'une commande, dans l'ordre où il est atteint :

• imported - la commande a été reçue via l'API. Toute commande commence ici.
• on hold - le solde ne couvre pas le coût de la commande. Une fois rechargé, la commande revient à imported et se poursuit.
• accepted - la commande a été acceptée et part en production.
• completed (définitif) - tous les articles ont été produits.
• canceled (définitif) - la commande a été annulée. C'est possible tant qu'elle est imported, accepted ou on hold et que la production n'a pas encore commencé.

Statuts d'exécution

Le fulfillment_status d'une commande et de chaque ligne de commande, dans l'ordre où il est atteint. Il ne fait qu'avancer, jamais reculer :

• unfulfilled - la production n'a pas commencé.
• scheduled - la commande est planifiée dans un lot de production. À partir de ce moment, elle ne peut plus être annulée.
• processing - la production est en cours.
• partially fulfilled - certains articles sont terminés, les autres sont encore en production.
• fulfilled (définitif) - tous les articles sont terminés. Le status de la commande devient alors completed.

Une commande dans son ensemble n'est jamais rejetée. Un article peut être rejeté lors du contrôle qualité en production. Il est alors réimprimé : il revient à unfulfilled et repasse en production, tandis que la commande garde son statut et se poursuit une fois l'article terminé.

Statuts d'expédition

Le status de chaque expédition dans shipments, dans l'ordre où il est atteint :

• pending - l'expédition est en préparation.
• registered - l'étiquette a été créée auprès du transporteur.
• collected - le transporteur a récupéré le colis.
• in transit - le colis est en route.
• delivered (définitif) - le colis a été livré.

Exceptions :

• failed - le transporteur a signalé un problème.
• returned (définitif) - le colis nous a été retourné.
• canceled (définitif) - l'expédition a été annulée.

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.

Sachez ce que coûtera l'expédition d'une commande et combien de temps elle sera en route avant de la passer, selon les mêmes règles que celles appliquées par Fabrixa à la commande elle-même.

Pour savoir vers quels pays une variante de produit peut être expédiée, envoyez une requête GET à https://api.fabrixa.com/v2/integration/shipping/countries avec vos identifiants. La liste, triée par nom, contient les pays vers lesquels le site qui produit la variante dispose d'un tarif d'expédition pour un colis d'expédition dans lequel la variante peut être emballée. Un pays absent de la liste n'a pas de tarif d'expédition pour la variante.

Paramètres de requête

Demande d'échantillon

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/shipping/countries?sku=DDC-140200' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemple de réponse

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/shipping/countries"
    },
    "meta": {
        "total": 2
    },
    "data": [
        {
            "code": "BE",
            "name": "Belgium",
            "min_shipping_price": "7.75",
            "max_shipping_price": "9.85",
            "currency": "EUR",
            "min_eta_days": 1,
            "max_eta_days": 2
        },
        {
            "code": "NL",
            "name": "Netherlands",
            "min_shipping_price": "6.70",
            "max_shipping_price": "8.40",
            "currency": "EUR",
            "min_eta_days": 1,
            "max_eta_days": 1
        }
    ]
}

Champs de la réponse

Pour savoir combien coûterait l'expédition d'une variante de produit et combien de temps elle serait en route, envoyez une requête GET à https://api.fabrixa.com/v2/integration/shipping/estimate avec vos identifiants. L'estimation suit les règles selon lesquelles une commande est tarifée : les unités sont réparties dans les colis d'expédition du site qui produit la variante, et chaque colis est tarifé selon le trajet de ce site jusqu'au pays de destination. Rien n'est commandé ni réservé, et une commande est tarifée au moment où elle est passée : ses frais d'expédition peuvent donc différer si les tarifs changent entre-temps.

Paramètres de requête

Demande d'échantillon

curl -X 'GET' \
  'https://api.fabrixa.com/v2/integration/shipping/estimate?sku=DDC-140200&country_code=NL&quantity=2' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer APPLICATION_ACCESS_TOKEN' \
  -H 'X-Application-Key: APPLICATION_KEY'

Exemple de réponse

{
    "links": {
        "self": "https://api.fabrixa.com/v2/integration/shipping/estimate"
    },
    "meta": [],
    "data": {
        "variant_id": 32323,
        "sku": "DDC-140200",
        "quantity": 2,
        "country_code": "NL",
        "origin_country": {
            "code": "PT",
            "name": "Portugal"
        },
        "packages_count": 1,
        "packages": [
            {
                "package_type": "Small Box",
                "length": 30,
                "width": 20,
                "height": 10,
                "quantity": 1,
                "price": "7.45",
                "eta_days": 3
            }
        ],
        "shipping_price": "7.45",
        "currency": "EUR",
        "eta_days": 3
    }
}

Champs de la réponse

Une requête qui ne passe pas la validation reçoit une réponse 400 Bad Request indiquant la raison pour chaque champ, avec les mêmes messages que pour une ligne de commande, par exemple The variant not found. Lorsqu'aucun colis d'expédition ne peut contenir les unités, la réponse est 400 Bad Request avec le message No shipping package can carry the variant.

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.
• locale (facultatif) - la langue de l'interface de Studio et de ses messages d'erreur, par ex. de_DE ou de. Sans lui, Studio s'ouvre dans la langue du navigateur de l'acheteur si elle est prise en charge, sinon en anglais.

L'en-tête de Studio affiche le nom du produit tel qu'il figure dans votre boutique - le même titre que voient vos clients -, avec en dessous les options de la variante choisie. C'est la copie du produit propre à votre boutique : un nom que vous modifiez dans Fabrixa s'affiche aussi dans Studio ; locale ne le traduit pas.

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",
  "user-agent": "Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook)",
  "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 sont envoyés avec le User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook) ; si votre endpoint filtre le trafic automatisé, autorisez-le. Pour être sûr qu’une requête provient de Fabrixa, vérifiez x-webhook-signature.

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 :

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": "accepted",
  "fulfillment_status": "fulfilled",
  "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": "fulfilled",
      "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"
          }
        }
      ]
    }
  ],
  "shipments": [
    {
      "id": 4182,
      "carrier": "PostNL",
      "method": "Standard",
      "status": "registered",
      "tracking_number": "3SABCD1234567",
      "tracking_url": "https://jouw.postnl.nl/track-and-trace/3SABCD1234567-NL-1012AB",
      "packages": [
        {
          "tracking_number": "3SABCD1234567",
          "tracking_url": "https://jouw.postnl.nl/track-and-trace/3SABCD1234567-NL-1012AB"
        }
      ],
      "expected_delivery_date": "2025-04-22",
      "created_at": "2025-04-18T07:43:50.000000Z"
    }
  ]
}

Une fois la commande expédiée, shipments liste chaque envoi avec son transporteur (carrier), son mode d’expédition (method), son statut (status : pending, registered, collected, in transit, delivered, failed, returned ou canceled) et son suivi : tracking_number et tracking_url, ainsi que les mêmes informations pour chaque colis dans packages lorsqu’un envoi en comporte plusieurs. Un webhook order.updated est envoyé à chaque changement du statut ou du suivi d’un envoi, et GET /orders/{order_id} renvoie le même champ.

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.