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.

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

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.

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.

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",
  "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.

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:

Orderstatussen

• Completed - order is verzonden of opgehaald en ontvangst is bevestigd. Voor digitale producten heeft de klant betaald en zijn bestanden beschikbaar voor download.
• Canceled - klant heeft de betaling geannuleerd; de transactie is niet voltooid.
• On hold - de order is tijdelijk geblokkeerd.
• Imported - de order is geïmporteerd in het platform.

Fulfilmentstatussen

• Unfulfilled - de order is nog niet voorbereid of verzonden.
• Partially fulfilled - sommige items zijn verwerkt of verzonden, andere wachten nog.
• Scheduled - de order is gepland voor verwerking.
• Rejected - de fulfilment request is afgewezen, vaak door ongeldige orderdetails of onbeschikbaarheid.
• Fulfilled - de order is volledig verwerkt en geleverd of beschikbaar gesteld aan de klant.

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

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.