Für den Zugriff auf die Integration API authentifizieren Sie Requests mit einem Application Access Token und einer Application Key:

Autorisierungsheader

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Anwendungsschlüssel-Header

X-Application-Key: APPLICATION_KEY

Beispiel für einen cURL-Befehl

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'

Ersetzen Sie APPLICATION_ACCESS_TOKEN durch Ihr tatsächliches Zugriffstoken und APPLICATION_KEY durch Ihren tatsächlichen Anwendungsschlüssel.

Die Endpoints der Integration API sind nach Resource Type organisiert und folgen der REST-Architektur. Jeder Endpoint repräsentiert eine Resource; Aktionen werden mit Standard-HTTP-Methods ausgeführt.

Alle Requests und Responses der Integration API verwenden JSON und bieten damit eine konsistente Schnittstelle.

Ausführliche Informationen zu jedem Endpunkt, einschließlich Anforderungs- und Antwortbeispielen, finden Sie in unserem Swagger documentation.

Antwortformat

Alle Endpunkte geben Daten in einem standardisierten Format mit diesen Objekten zurück:

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

Beschreibung der Antwortobjekte

Alle API-Anfragen geben HTTP-Statuscodes zurück, die Einblick in die Antwort geben.

Fehlerantworttext

Ein Beispiel für einen Fehlerantworttext:

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

errors enthält Details darüber, was fehlgeschlagen ist. Das Array messages listet Fehlerbeschreibungen auf. Bei einer fehlerhaften Anfrage erhalten Sie die Namen der Felder, deren Validierung fehlgeschlagen ist.

Die Integrations-API unterstützt ein Limit von 30 Anfragen pro Anwendung und Minute.

Wenn Sie dieses Limit überschreiten, erhalten Sie eine 429 Too Many Requests-Antwort.

Alle Antworten der Integrations-API enthalten den X-RateLimit-Remaining-Header, der angibt, wie viele Anfragen der Client noch stellen kann, und den X-RateLimit-Limit-Header, die insgesamt zulässige Anzahl pro Minute.

Erstellen Sie Orders in Fabrixa aus Ihrem eigenen Storefront oder Ihrer Plattform, hängen Sie die erforderlichen Druckdateien an und verfolgen Sie jedes Item durch das Fulfilment.

Um eine Order über die Fabrixa Integration API zu erstellen, senden Sie einen POST Request an https://api.fabrixa.com/v2/integration/orders. Der Request Body muss enthalten:

Körperstruktur anfordern

Musteranfrage

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

Um den Fulfilment-Status einer bestimmten Order abzurufen, senden Sie einen GET Request an https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Die Response enthält Fulfilments zur Order, inklusive Item-Status, Produktdetails und Fortschritt der Produktionsschritte.

Beispielantwort

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

Die Antwort enthält eine Liste der Erfüllungen, die jeweils Folgendes enthalten:

Jeder Erfüllungsdatensatz entspricht einem bestimmten Produkt oder einer bestimmten Produktvariante innerhalb der Bestellung, und jedes Exemplar des Produkts in der Bestellung verfügt über einen eigenen Erfüllungsdatensatz – jeder Artikel wird während der gesamten Produktion einzeln verfolgt.

Wenn für eine Bestellung keine Erfüllung zurückgegeben wird, befindet sich die Bestellung noch nicht in der Bearbeitungsphase.

Wenn Sie source files in Ihrer Order verwenden, müssen diese die folgenden Anforderungen erfüllen:

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

PDF-Anforderungen und Seitenreihenfolge

Die Reihenfolge der Seiten im PDF ist wichtig. Die Seiten werden nach Position den Produktebenen zugeordnet und die erwartete Seitenreihenfolge hängt vom Produkttyp ab. Stellen Sie sicher, dass die Seiten in Ihrer PDF-Datei der richtigen Ebenenreihenfolge für das Produkt entsprechen, das Sie einreichen.

Wichtig: Jede PDF-Seite muss den erforderlichen Abmessungen für ihre Produktebene entsprechen und korrekt ausgerichtet sein. Platzieren Sie das Bildmaterial so, dass der obere Rand des Designs mit dem oberen Rand der Seite übereinstimmt. Eine falsche Seitengröße oder -ausrichtung kann zu Skalierungs-, Rotations- oder Ausrichtungsproblemen in der Produktion führen.

Fabrixa Studio ist ein Tool, mit dem Benutzer Produkte nahtlos in Echtzeit anpassen und personalisieren können, mit einer intuitiven Benutzeroberfläche, über die Benutzer ihre eigenen Designs erstellen oder hochladen können.

Fabrixa Studio ist ideal für Unternehmen, die kundenspezifische Produkte anbieten – so können Kunden ihre Designs visualisieren, bevor sie Bestellungen abschließen.

Sie können Fabrixa Studio per iframe in Ihre Website einbetten. Dadurch können Kunden Produkte direkt auf Ihrer Seite während des Checkouts personalisieren.

Beispiel-Iframe zum Einbetten von 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>

Ersetzen Sie die Werte für product_sku, cart_item_key und application_key durch Ihre dynamischen Werte.

• application_key – eindeutiger Schlüssel zur Authentifizierung bei der Integrations-API.
• product_sku – die SKU der Produktvariante, abgerufen von der Integrations-API.
• cart_item_key – ein eindeutiger Wert von der Einbettungsplattform, der den mit dem Produkt verknüpften Warenkorbartikel identifiziert. Wird zum Speichern der Benutzeranpassungen verwendet; Bei der Auftragserstellung identifiziert es die gespeicherten Anpassungen und ordnet sie der Bestellung zu. Siehe Beispiel unten.

Anfrage zum Erstellen einer Bestellung mit 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": {
    "...": "..."
  }
}

Wenn im Iframe auf die Schaltfläche Zum Warenkorb hinzufügen geklickt wird, wird der folgende Befehl ausgeführt:

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

Ähnlich verhält es sich, wenn auf die Schaltfläche Zurück geklickt wird:

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

Die postMessage-Methode erleichtert die ursprungsübergreifende Kommunikation zwischen dem Iframe und seinem übergeordneten Fenster und ermöglicht es ihr, das übergeordnete Fenster über bestimmte Benutzeraktionen zu benachrichtigen.

Das erste Argument von postMessage sind die Daten, die Sie senden möchten. Die Zeichenfolge 'customizationFinished' gibt an, dass der Benutzer die Anpassung abgeschlossen hat und das Produkt in den Warenkorb legt. 'closeButtonClicked' zeigt an, dass der Benutzer sich für die Rückkehr entschieden hat.

Warten Sie im übergeordneten Fenster mit dem message-Ereignis-Listener auf diese Nachrichten:

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

Überprüfen Sie immer den origin eingehender Nachrichten, um sicherzustellen, dass sie von einer vertrauenswürdigen Quelle stammen. Führen Sie abhängig von der empfangenen Nachricht die erforderlichen Aktionen aus – aktualisieren Sie die Benutzeroberfläche, verarbeiten Sie den Warenkorb usw. Die Validierung von origin ist für die Sicherheit von entscheidender Bedeutung – sie verhindert, dass nicht autorisierte Skripte mit Ihrer Anwendung interagieren.

Nachdem die Anpassung abgeschlossen ist, zeigen Sie das endgültige Design über die unten stehende Vorschau-URL an. Diese URL gibt ein Bild des angepassten Produkts zurück, das als src-Wert in einem <img>-Tag geeignet ist. Ideal, um das personalisierte Produkt in Ihrem Warenkorb, in der Bestellübersicht oder an einer beliebigen Stelle in Ihrer Shop-Oberfläche anzuzeigen.

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

Ersetzen Sie {CART_ITEM_KEY} durch den tatsächlichen Warenkorbartikelschlüssel und {APPLICATION_KEY} durch Ihren gültigen Anwendungsschlüssel.

Beispielverwendung in einem Bild-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 werden von Fabrixa verwendet, um Ihr System über Echtzeitereignisse zu benachrichtigen – Bestellaktualisierungen oder -kreationen. Wenn ein Ereignis eintritt, sendet Fabrixa einen Webhook mit den relevanten Informationen an Ihren Server. Ihr Server muss einen öffentlichen POST-Endpunkt bereitstellen, um eingehende Webhooks zu verarbeiten.

Der Webhook Request enthält die folgenden Headers, damit Sie die eingehende Anfrage identifizieren und validieren können:

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

Header-Aufschlüsselung

• content-type – für Webhooks immer auf application/json eingestellt.
• x-webhook-signature – die HMAC-SHA256-Signatur zur Anforderungsüberprüfung.
• x-webhook-topic – der Ereignistyp oder das Thema des Webhooks. Zum Beispiel:
  • order.created – wird ausgelöst, wenn eine neue Bestellung erstellt wird.
  • order.updated – wird ausgelöst, wenn eine bestehende Bestellung aktualisiert wird.

Fabrixa Webhooks informieren Ihr System über Änderungen am Order-Status oder an Aktivitäten. Jeder Webhook wird durch einen bestimmten x-webhook-topic Wert ausgelöst. Aktuell unterstützte Topics:

Bestellstatus

• Abgeschlossen – die Bestellung wurde versendet oder abgeholt und der Empfang wurde bestätigt. Für digitale Produkte hat der Kunde bezahlt und die Dateien stehen zum Download zur Verfügung.
• Storniert – der Kunde hat die Zahlung storniert; Die Transaktion wurde nicht abgeschlossen.
• In der Warteschleife – die Bestellung ist vorübergehend gesperrt.
• Importiert – die Bestellung wurde in die Plattform importiert.

Erfüllungsstatus

• Unerfüllt – die Bestellung wurde noch nicht vorbereitet oder versendet.
• Teilweise erfüllt – einige Artikel wurden bearbeitet oder versendet, andere stehen noch aus.
• Geplant – die Bestellung ist geplant und zur Bearbeitung eingeplant.
• Abgelehnt – die Erfüllungsanfrage wurde abgelehnt, häufig aufgrund ungültiger Bestelldetails oder Nichtverfügbarkeit.
• Erfüllt – die Bestellung wurde vollständig bearbeitet und geliefert oder dem Kunden zur Verfügung gestellt.

Ein Beispiel für die mit dem Webhook gesendete Nutzlast. Diese Nutzlast stellt eine Bestellaktualisierung dar:

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

Um sicherzustellen, dass der Webhook Request authentisch und unverändert ist, prüfen Sie den x-webhook-signature Header. Berechnen Sie die HMAC-SHA256 Signature mit dem raw request payload und Ihrer secret key neu und vergleichen Sie sie mit der empfangenen Signature.

Rohes PHP-Beispiel

$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-Beispiel

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

Ersetzen Sie $yourSecret durch Ihren gemeinsamen geheimen Schlüssel. Verwenden Sie immer hash_equals zum Vergleichen von Signaturen, um Timing-Angriffe abzuwehren.

Webhooks werden standardmäßig nach 10 erfolglosen Zustellungsversuchen deaktiviert. Wenn Ihr Endpunkt einen fehlgeschlagenen Status wie 404 oder einen 5xx-Fehler zurückgibt, wird der Webhook insgesamt zehnmal erneut versuchen. Wenn weiterhin ein Nicht-2xx- oder Nicht-3xx-Antwortcode zurückgegeben wird, wird es deaktiviert. Zu den erfolgreichen Antworten gehören:

• 2xx – zeigt erfolgreiche Verarbeitung an, z.B. 200 OK.
• 301 und 302 – Umleitungsantworten, die angeben, dass der Webhook erfolgreich verarbeitet oder weitergeleitet wurde.

Wir empfehlen dringend, dass Ihr Endpunkt so schnell wie möglich einen 200 OK-Statuscode zurückgibt, um den erfolgreichen Empfang des Webhooks zu bestätigen. Während jede 2xx- oder 3xx-Antwort als erfolgreich gilt, ist 200 die am häufigsten verwendete und zuverlässigste.

Um Übermittlungszeitüberschreitungen oder Wiederholungsversuche zu vermeiden, geben Sie 200 OK sofort zurück und verarbeiten Sie die Webhook-Nutzlast asynchron, beispielsweise über einen Hintergrundjob oder eine Warteschlange. Wenn die Antwort Ihres Endpunkts zu lange dauert, kann dies als Fehler betrachtet werden, auch wenn die Antwort letztendlich erfolgreich ist.

Antworten mit Statuscodes im Bereich 4xx oder 5xx oder Zeitüberschreitungen lösen Wiederholungsversuche gemäß dem Wiederholungsmechanismus aus.