Fabrixa Integration API Referentie

Om de Integration API te gebruiken, authenticeer je requests met zowel een Application Access Token als een Application Key:

Authorization header

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Application Key header

X-Application-Key: APPLICATION_KEY

Voorbeeld cURL command

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'

Vervang APPLICATION_ACCESS_TOKEN door je eigen access token en APPLICATION_KEY door je eigen application key.

De endpoints van de Integration API zijn georganiseerd per resource type en volgen de REST-architectuur. Elk endpoint vertegenwoordigt een resource; acties op resources worden uitgevoerd met standaard HTTP methods.

Alle requests en responses van de Integration API gebruiken JSON, zodat de interactie met de API consistent en eenvoudig blijft.

Zie onze Swagger-documentatie voor alle endpointdetails, inclusief request- en responsevoorbeelden.

Responseformaat

Alle endpoints geven data terug in een gestandaardiseerd formaat met deze objecten:

{
  "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"
    }
  ]
}

Beschrijving van responseobjecten

Alle API requests geven HTTP status codes terug die inzicht geven in de response.

Error response body

Voorbeeld van een error response body:

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

errors bevat details over wat is mislukt. De array messages bevat foutbeschrijvingen. Bij een Bad Request ontvang je de veldnamen die validatie niet hebben gehaald.

De Integration API ondersteunt een limiet van 30 requests per application per minuut.

Als je deze limiet overschrijdt, ontvang je een 429 Too Many Requests response.

Alle Integration API responses bevatten de header X-RateLimit-Remaining, het aantal requests dat de client nog kan doen, en X-RateLimit-Limit, het totaal toegestane aantal per minuut.

Met de sandboxmodus test je je integratie van begin tot eind, voordat een echte bestelling wordt geproduceerd of in rekening gebracht. De modus geldt voor je hele account: bestellingen uit alle verkoopkanalen, waaronder de Integration API en gekoppelde Shopify- en WooCommerce-winkels, worden niet geproduceerd en niet van je saldo afgeschreven. Je account staat in de sandboxmodus zolang de status wacht op activering is.

In de sandboxmodus kun je:

• je Shopify- of WooCommerce-winkel koppelen of een Integration API-kanaal aanmaken;
• producten toevoegen en prijzen en verzendkosten controleren;
• bestellingen importeren, aanmaken, bijwerken en annuleren;
• zien dat geen van deze bestellingen wordt geproduceerd of van je saldo wordt afgeschreven;
• de aflevering van webhooks en handtekeningen controleren.

Voeg om bestellingen te testen producten uit de Fabrixa-catalogus toe: open een product, klik op Verkoop dit en kies varianten en ontwerpen. Ze verschijnen daarna onder Mijn producten.

Om je account naar de sandboxmodus te schakelen, open je Platform, ga je naar Instellingen → Bedrijf → Sandboxmodus en klik je op Naar sandboxmodus. Je kunt de modus ook inschakelen wanneer je een nieuw verkoopkanaal toevoegt, waaronder een Integration API-kanaal, of mailen naar support@fabrixa.com, dan schakelen wij je account voor je om. De sandboxmodus is alleen beschikbaar voor actieve accounts.

Wanneer je klaar bent, activeer je je account zelf in Platform onder Instellingen → Bedrijf → Sandboxmodus. Je kunt ook mailen naar support@fabrixa.com, dan activeren wij het voor je. Je gekoppelde winkels en API-inloggegevens blijven werken, dus er hoeft niets opnieuw te worden ingesteld.

Na activering gaan alle nieuwe bestellingen naar productie en worden ze van je saldo afgeschreven. Bestellingen die vóór de activering zijn aangemaakt, blijven testbestellingen: ze worden nooit geproduceerd of in rekening gebracht, ook niet na activering.

De catalogus is alles wat Fabrixa produceert. Je producten zijn de catalogusproducten die je aan je Fabrixa-account hebt toegevoegd, met je eigen namen, beschrijvingen, afbeeldingen en SKU's. Een orderregel noemt een productvariant - één maat of uitvoering van een product - via de sku of variant_id: een variant van een van je producten, of een rechtstreeks bestelde catalogusvariant.

Om de producten op te halen die Fabrixa produceert, stuur je een GET-request naar https://api.fabrixa.com/v2/integration/catalog/products met je inloggegevens. Hij toont de actieve producten met een variant die een printpartner op dit moment produceert, en alleen die varianten, elk met SKU, verkoopprijs, afmetingen en optiewaarden.

Queryparameters

Voorbeeldrequest

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'

Voorbeeldresponse

{
    "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"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Velden in de respons

Om de categorieën op te halen waarin de catalogus is ingedeeld, stuur je een GET-request naar https://api.fabrixa.com/v2/integration/catalog/categories met je inloggegevens. De respons bevat de hoofdcategorieën, elk met de subcategorieën genest in sub_categories en het aantal catalogusproducten erin in products_count. Geef de id van een categorie mee als category_id bij het bekijken van de catalogus, of de id van een hoofdcategorie als parent_category_id om de producten van al haar subcategorieën in één keer op te halen.

Queryparameters

Voorbeeldrequest

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'

Voorbeeldresponse

{
    "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
                }
            ]
        }
    ]
}

Om de producten in je account op te halen, stuur je een GET-request naar https://api.fabrixa.com/v2/integration/products met je inloggegevens. Je producten zijn de catalogusproducten die je aan je Fabrixa-account hebt toegevoegd: ze dragen de namen, beschrijvingen en afbeeldingen die je ze daar hebt gegeven, en hun varianten de SKU-waarden die je hebt gekozen. Alleen actieve producten worden getoond, tien per pagina tenzij je limit meegeeft.

Queryparameters

Voorbeeldrequest

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'

Voorbeeldresponse

{
    "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"]
                }
            ]
        }
    ]
}

Om één product te lezen, stuur je een GET-request naar https://api.fabrixa.com/v2/integration/products/{product_id}, waarbij {product_id} de id ervan is. De respons bevat dezelfde velden als de lijst. Een product dat niet in je account staat, ook een catalogusproduct, antwoordt met 404 Not Found en de melding Product not found.

Velden in de respons

Een variant is één bestelbare uitvoering van een product - één maat, één kleur - en wat een orderregel noemt, via sku of variant_id. Om een variant van een van je producten te lezen, stuur je een GET-request naar https://api.fabrixa.com/v2/integration/variants/{variant_id}, waarbij {variant_id} de id ervan is. Een variant van een product dat niet in je account staat, antwoordt met 404 Not Found en de melding Variant not found.

Voorbeeldrequest

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'

Voorbeeldresponse

{
    "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"]
    }
}

Velden in de respons

Een orderregel voor deze variant, met een PDF waarvan de pagina's de lagen zijn:

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

Welke varianten kunnen worden besteld

Maak orders in Fabrixa vanuit je eigen storefront of platform, voeg de vereiste printbestanden toe en volg elk item terwijl het door fulfilment gaat.

Om een order aan te maken via de Fabrixa Integration API, stuur je een POST request naar https://api.fabrixa.com/v2/integration/orders. De request body moet bevatten:

Structuur van de request body

Voorbeeldrequest

{
  "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"
  }
}

Voorbeeldresponse

{
    "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"
        }
    }
}

Om een order bij te werken, stuur je een PATCH request naar https://api.fabrixa.com/v2/integration/orders/{order_id}, waarbij {order_id} het Fabrixa-order-id is. Alleen de velden die je meestuurt worden gewijzigd, en de status van de order blijft gelijk. Het antwoord bevat de bijgewerkte order. Je kunt wijzigen:

Voorbeeldrequest

{
  "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"
  }
}

Voorbeeldresponse

{
    "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."
        ]
    }
}

Om een order te annuleren, stuur je een POST request zonder body naar https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, waarbij {order_id} het Fabrixa-order-id is (het numerieke veld id van de order), niet je ordernummer. Het antwoord bevat de order met de status canceled, en er wordt een order.updated webhook verstuurd.

Voorbeeldresponse

{
    "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"
        }
    }
}

Als de order niet kan worden geannuleerd, antwoordt de API met 412 Precondition Failed en een melding met de reden: de huidige status staat het niet toe (de status staat in de melding), of de productie is al gestart.

{
    "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)."
        ]
    }
}

Een order wordt gevolgd met drie statussen: de status van de order, de productiestatus fulfillment_status en de status van elke zending in shipments. Elke wijziging wordt verstuurd in de webhook order.updated en teruggegeven door GET /orders/{order_id}.

Orderstatussen

De status van een order, in de volgorde waarin die wordt bereikt:

• imported - de order is via de API ontvangen. Elke order begint hier.
• on hold - het saldo dekt de kosten van de order niet. Zodra het is aangevuld, keert de order terug naar imported en gaat verder.
• accepted - de order is geaccepteerd en gaat naar productie.
• completed (definitief) - alle artikelen zijn geproduceerd.
• canceled (definitief) - de order is geannuleerd. Dat kan zolang de order imported, accepted of on hold is en de productie nog niet is gestart.

Fulfilmentstatussen

De fulfillment_status van een order en van elke orderregel, in de volgorde waarin die wordt bereikt. Die gaat alleen vooruit, nooit terug:

• unfulfilled - de productie is nog niet gestart.
• scheduled - de order is ingepland in een productiebatch. Vanaf dit moment kan de order niet meer worden geannuleerd.
• processing - de productie is bezig.
• partially fulfilled - een deel van de artikelen is klaar, de rest is nog in productie.
• fulfilled (definitief) - alle artikelen zijn klaar. De status van de order wordt dan completed.

Een order als geheel wordt nooit afgekeurd. Een afzonderlijk artikel kan tijdens de productie bij de kwaliteitscontrole worden afgekeurd. Het wordt dan opnieuw geprint: het keert terug naar unfulfilled en doorloopt de productie nog een keer, terwijl de order zijn status behoudt en verdergaat zodra het artikel klaar is.

Zendingstatussen

De status van elke zending in shipments, in de volgorde waarin die wordt bereikt:

• pending - de zending wordt voorbereid.
• registered - het label is aangemaakt bij de vervoerder.
• collected - de vervoerder heeft het pakket opgehaald.
• in transit - het pakket is onderweg.
• delivered (definitief) - het pakket is bezorgd.

Uitzonderingen:

• failed - de vervoerder heeft een probleem gemeld.
• returned (definitief) - het pakket is naar ons teruggestuurd.
• canceled (definitief) - de zending is geannuleerd.

Om de fulfilment status van een specifieke order op te halen, stuur je een GET request naar https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. De response bevat de fulfilments van de order, inclusief status per item, productdetails en voortgang van productiestappen.

Voorbeeldresponse

{
    "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
                    }
                }
            ]
        }
    ]
}

De response bevat een lijst met fulfilments, elk met:

Elke fulfilment hoort bij een specifiek product of productvariant binnen de order, en elk exemplaar van het product in de order heeft een eigen fulfilment record. Zo wordt elk item afzonderlijk gevolgd tijdens productie.

Als er geen fulfilments worden teruggegeven, is de order nog niet in de verwerkingsfase.

Wanneer je source files aan een order toevoegt, moeten ze aan de volgende vereisten voldoen:

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

PDF-vereisten en paginavolgorde

De volgorde van pagina’s in de PDF is belangrijk. Pagina’s worden op basis van hun positie gekoppeld aan productlagen, en de verwachte paginavolgorde hangt af van het producttype. Zorg dat de pagina’s in je PDF de juiste laagvolgorde volgen.

Belangrijk: elke PDF-pagina moet de juiste afmetingen hebben voor de productlaag en correct georiënteerd zijn. Plaats het artwork zo dat de bovenkant van het ontwerp aan de bovenkant van de pagina staat. Een verkeerde pagina-afmeting of oriëntatie kan schaal-, rotatie- of uitlijnproblemen veroorzaken in productie.

Weet wat de verzending van een order kost en hoe lang die onderweg is voordat je hem plaatst, berekend met dezelfde regels die Fabrixa op de order zelf toepast.

Om te zien naar welke landen een productvariant kan worden verzonden, stuur je een GET-request naar https://api.fabrixa.com/v2/integration/shipping/countries met je inloggegevens. De lijst bevat, gesorteerd op naam, de landen waarnaar de locatie die de variant produceert een verzendtarief heeft voor een verzendpakket waarin de variant kan worden verpakt. Een land dat niet in de lijst staat, heeft geen verzendtarief voor de variant.

Queryparameters

Voorbeeldrequest

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'

Voorbeeldresponse

{
    "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
        }
    ]
}

Velden in de respons

Om te zien wat de verzending van een productvariant zou kosten en hoe lang die onderweg zou zijn, stuur je een GET-request naar https://api.fabrixa.com/v2/integration/shipping/estimate met je inloggegevens. De schatting volgt dezelfde regels als de prijsberekening van een order: de stuks worden verpakt in de verzendpakketten van de locatie die de variant produceert, en voor elk pakket wordt de prijs bepaald over de route van die locatie naar het land van bestemming. Er wordt niets besteld of gereserveerd, en de prijs van een order wordt bepaald wanneer die wordt geplaatst; de verzendkosten kunnen dus afwijken als de tarieven in de tussentijd veranderen.

Queryparameters

Voorbeeldrequest

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'

Voorbeeldresponse

{
    "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
    }
}

Velden in de respons

Een request die niet door de validatie komt, wordt beantwoord met 400 Bad Request en de reden per veld, met dezelfde meldingen als bij een orderregel, bijvoorbeeld The variant not found. Als geen enkel verzendpakket de stuks kan bevatten, is het antwoord 400 Bad Request met de melding No shipping package can carry the variant.

Fabrixa Studio is een tool waarmee gebruikers producten realtime kunnen personaliseren via een intuïtieve interface waarin zij eigen ontwerpen kunnen maken of uploaden.

Fabrixa Studio is ideaal voor bedrijven die custom producten aanbieden, zodat klanten hun ontwerp kunnen bekijken voordat zij de order afronden.

Je kunt Fabrixa Studio in je website insluiten met een iframe. Zo kunnen klanten producten direct op je site personaliseren tijdens checkout.

Voorbeeld iframe voor het insluiten van 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>

Vervang de waarden voor product_sku, cart_item_key en application_key door je dynamische waarden.

• application_key - unieke key voor authenticatie bij de Integration API.
• product_sku - de SKU van de productvariant, opgehaald uit de Integration API.
• cart_item_key - unieke waarde van het embedding platform die het cart item identificeert. Wordt gebruikt om personalisaties op te slaan; bij orderaanmaak koppelt deze waarde de opgeslagen personalisaties aan de order. Zie voorbeeld hieronder.
• locale (optioneel) - de taal van de Studio-interface en van de foutmeldingen, bijv. de_DE of de. Zonder deze parameter opent Studio in de browsertaal van de koper als die wordt ondersteund, anders in het Engels.

De kop van Studio toont de productnaam zoals die in je winkel staat - dezelfde titel die je klanten zien - met daaronder de opties van de gekozen variant. Het is de eigen kopie van het product in je winkel, dus een naam die je in Fabrixa aanpast, verschijnt ook in Studio; locale vertaalt hem niet.

Request om een order aan te maken met 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": {
    "...": "..."
  }
}

Wanneer binnen het iframe op de knop Add to Cart wordt geklikt, wordt het volgende command uitgevoerd:

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

Wanneer op de knop Back wordt geklikt:

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

De methode postMessage maakt cross-origin communicatie mogelijk tussen het iframe en het parent window, zodat specifieke gebruikersacties kunnen worden doorgegeven.

Het eerste argument van postMessage is de data die je wilt sturen. De string 'customizationFinished' betekent dat de gebruiker de personalisatie heeft afgerond en het product aan de cart toevoegt. 'closeButtonClicked' betekent dat de gebruiker terug wil gaan.

Luister in het parent window naar deze berichten via de message event listener:

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.');
        }
    }
});

Controleer altijd de origin van inkomende berichten om zeker te weten dat ze van een vertrouwde bron komen. Voer op basis van het bericht de juiste acties uit, zoals de interface bijwerken of de cart verwerken. Validatie van origin is belangrijk voor security en voorkomt dat ongeautoriseerde scripts met je applicatie communiceren.

Nadat de personalisatie is voltooid, toon je het eindontwerp met de preview-URL hieronder. Deze URL geeft een afbeelding van het gepersonaliseerde product terug, geschikt als src waarde in een <img> tag. Ideaal voor weergave in cart, orderoverzicht of shopinterface.

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

Vervang {CART_ITEM_KEY} door de echte cart item key en {APPLICATION_KEY} door je geldige application key.

Voorbeeldgebruik in een image tag:

<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;" />

Webhooks worden door Fabrixa gebruikt om je systeem te informeren over realtime events, zoals orderupdates of nieuwe orders. Wanneer een event plaatsvindt, stuurt Fabrixa een webhook naar je server met de relevante informatie. Je server moet een publieke POST endpoint beschikbaar stellen om inkomende webhooks te verwerken.

De webhook request bevat de volgende headers om de inkomende request te identificeren en valideren:

{
  "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"
}

Headeroverzicht

• content-type - altijd application/json voor webhooks.
• x-webhook-signature - de HMAC-SHA256 signature voor requestverificatie.
• x-webhook-topic - het event type of topic van de webhook. Bijvoorbeeld:
  • order.created - getriggerd wanneer een nieuwe order wordt aangemaakt.
  • order.updated - getriggerd wanneer een bestaande order wordt bijgewerkt.

Webhooks worden verstuurd met de User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); als je endpoint automatisch verkeer filtert, sta die dan toe. Om zeker te weten dat een request van Fabrixa komt, controleer je x-webhook-signature.

Fabrixa webhooks informeren je systeem over wijzigingen in orderstatus of activiteit. Elke webhook wordt getriggerd door een specifieke x-webhook-topic waarde. Momenteel ondersteunde topics:

Voorbeeld van de payload die met de webhook wordt verzonden. Deze payload toont een orderupdate:

{
  "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"
    }
  ]
}

Zodra de order is verzonden, toont shipments elke zending met de vervoerder (carrier), verzendmethode (method), status (status: pending, registered, collected, in transit, delivered, failed, returned of canceled) en tracking: tracking_number en tracking_url, en hetzelfde per pakket in packages als een zending er meerdere heeft. Er wordt een order.updated webhook verstuurd telkens wanneer de status of tracking van een zending verandert, en GET /orders/{order_id} geeft hetzelfde veld terug.

Om zeker te weten dat de webhook request authentiek en ongewijzigd is, verifieer je de x-webhook-signature header. Bereken de HMAC-SHA256 signature opnieuw met de raw request payload en je secret key, en vergelijk deze met de ontvangen signature.

Raw PHP voorbeeld

$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');
}

Laravel voorbeeld

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...
}

Vervang $yourSecret door je gedeelde secret key. Gebruik altijd hash_equals om signatures te vergelijken en timing attacks te beperken.

Webhooks worden standaard uitgeschakeld na 10 mislukte afleverpogingen. Als je endpoint een onsuccesvolle status teruggeeft, zoals 404 of een 5xx error, probeert de webhook het maximaal 10 keer opnieuw. Blijft de response non-2xx of non-3xx, dan wordt de webhook gedeactiveerd. Succesvolle responses zijn:

• 2xx - geeft succesvolle verwerking aan, bijv. 200 OK.
• 301 en 302 - redirect responses die aangeven dat de webhook succesvol is verwerkt of doorgestuurd.

We raden sterk aan dat je endpoint zo snel mogelijk een 200 OK status code teruggeeft om succesvolle ontvangst van de webhook te bevestigen. Hoewel elke 2xx of 3xx response als succesvol geldt, is 200 het meest gebruikelijk en betrouwbaar.

Om delivery timeouts of retries te voorkomen, geef je direct 200 OK terug en verwerk je de webhook payload asynchroon, bijvoorbeeld via een background job of queue. Als je endpoint te lang doet over de response, kan dit als failure worden gezien, zelfs als de response uiteindelijk succesvol is.

Responses met status codes in de 4xx of 5xx range, of timeouts, starten retries volgens het retrymechanisme.