Aby uzyskać dostęp do interfejsu API integracji, uwierzytelnij swoje żądania przy użyciu zarówno tokenu dostępu do aplikacji, jak i klucza aplikacji:

Nagłówek autoryzacji

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Nagłówek klucza aplikacji

X-Application-Key: APPLICATION_KEY

Przykładowe polecenie 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'

Zastąp APPLICATION_ACCESS_TOKEN rzeczywistym tokenem dostępu i APPLICATION_KEY rzeczywistym kluczem aplikacji.

Punkty końcowe interfejsu API integracji są zorganizowane według typu zasobu i są zgodne ze stylem architektonicznym RESTful. Każdy punkt końcowy reprezentuje zasób, a akcje na tych zasobach są wykonywane przy użyciu standardowych metod HTTP.

Wszystkie żądania i odpowiedzi Integration API są w formacie JSON, co zapewnia spójny i łatwy w użyciu interfejs do interakcji z API.

Pełne informacje o każdym endpoincie, w tym przykłady żądań i odpowiedzi, znajdziesz w naszej dokumentacji Swagger.

Forma odpowiedzi

Wszystkie punkty końcowe zwracają dane w ustandaryzowanym formacie z następującymi obiektami:

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

Opis obiektów odpowiedzi

Wszystkie żądania API zwracają kody stanu HTTP, które zapewniają wgląd w odpowiedź.

Treść odpowiedzi na błąd

Przykład treści odpowiedzi na błąd:

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

errors zawiera szczegółowe informacje o tym, co się nie udało. Tablica messages zawiera opisy błędów. W przypadku nieprawidłowego żądania otrzymasz nazwy pól, które nie zostały zweryfikowane.

Interfejs API integracji obsługuje limit 30 żądań na aplikację na minutę.

Jeśli przekroczysz ten limit, otrzymasz odpowiedź 429 Too Many Requests.

Wszystkie odpowiedzi interfejsu API integracji zawierają nagłówek X-RateLimit-Remaining określający liczbę żądań, które klient może jeszcze wykonać, oraz nagłówek X-RateLimit-Limit oznaczający całkowitą dozwoloną liczbę żądań na minutę.

Twórz zamówienia w Fabrixa z własnego sklepu lub platformy, dołącz wymagane pliki do druku i śledź każdy przedmiot podczas realizacji.

Aby utworzyć zamówienie za pośrednictwem API integracji Fabrixa, wyślij żądanie POST do https://api.fabrixa.com/v2/integration/orders. Treść wniosku musi zawierać:

Zapytaj o strukturę ciała

Przykładowe żądanie

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

Aby uzyskać status realizacji konkretnego zamówienia, wyślij żądanie GET do https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Odpowiedź zawiera listę realizacji powiązanych z zamówieniem, w tym status każdego artykułu, szczegóły produktu i postęp na etapie produkcji.

Przykładowa odpowiedź

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

Odpowiedź zawiera listę spełnień, z których każde zawiera:

Każdy zapis realizacji odpowiada konkretnemu produktowi lub wariantowi produktu w ramach zamówienia, a każdy egzemplarz produktu w zamówieniu ma swój własny zapis realizacji - każdy artykuł jest śledzony indywidualnie przez całą produkcję.

Jeżeli za zamówienie nie zwrócono żadnych realizacji, oznacza to, że zamówienie nie weszło jeszcze w fazę realizacji.

Dołączając do zamówienia pliki źródłowe, upewnij się, że spełniają one następujące wymagania:

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

Wymagania dotyczące plików PDF i kolejność stron

Kolejność stron w pliku PDF jest istotna. Strony dopasowywane są do warstw produktów według pozycji, a oczekiwana kolejność stron zależy od rodzaju produktu. Upewnij się, że strony w pliku PDF mają prawidłową kolejność warstw dla przesyłanego produktu.

Ważne: każda strona PDF musi odpowiadać wymaganym wymiarom dla warstwy produktu i być prawidłowo zorientowana. Umieść grafikę tak, aby góra projektu była wyrównana z górą strony. Nieprawidłowy rozmiar strony lub orientacja może powodować problemy ze skalowaniem, rotacją lub wyrównaniem w produkcji.

Fabrixa Studio to narzędzie, które pozwala użytkownikom bezproblemowo dostosowywać i personalizować produkty w czasie rzeczywistym za pomocą intuicyjnego interfejsu, w którym użytkownicy mogą tworzyć lub przesyłać własne projekty.

Fabrixa Studio jest idealne dla firm oferujących produkty niestandardowe – umożliwiając klientom wizualizację swoich projektów przed sfinalizowaniem zamówienia.

Możesz osadzić Fabrixa Studio na swojej stronie internetowej za pomocą iframe. Dzięki temu Twoi klienci mogą personalizować produkty bezpośrednio na Twojej stronie podczas realizacji transakcji.

Przykładowy element iframe do osadzenia 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>

Zastąp wartości product_sku, cart_item_key i application_key swoimi wartościami dynamicznymi.

• application_key - unikalny klucz do uwierzytelnienia w Integration API.
• product_sku - SKU wariantu produktu pobrany z Integration API.
• cart_item_key - unikalna wartość z platformy embedingowej identyfikująca pozycję koszyka powiązaną z produktem. Służy do zapisywania dostosowań użytkownika; podczas tworzenia zamówienia identyfikuje zapisane dostosowania i przypisuje je do zamówienia. Zobacz przykład poniżej.

Prośba o utworzenie zamówienia za pomocą 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": {
    "...": "..."
  }
}

Po kliknięciu przycisku Dodaj do koszyka wewnątrz elementu iframe wykonywane jest następujące polecenie:

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

Podobnie po kliknięciu przycisku Back:

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

Metoda postMessage ułatwia komunikację między źródłami między ramką iframe a jej oknem nadrzędnym, umożliwiając powiadamianie elementu nadrzędnego o określonych działaniach użytkownika.

Pierwszym argumentem postMessage są dane, które chcesz wysłać. Ciąg 'customizationFinished' wskazuje, że użytkownik zakończył dostosowywanie i dodaje produkt do koszyka. 'closeButtonClicked' wskazuje, że użytkownik zdecydował się wrócić.

W oknie nadrzędnym nasłuchuj tych komunikatów za pomocą detektora zdarzeń 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.');
        }
    }
});

Zawsze sprawdzaj origin przychodzących wiadomości, aby upewnić się, że pochodzą z zaufanego źródła. W zależności od otrzymanej wiadomości wykonaj niezbędne działania - zaktualizuj interfejs użytkownika, przetwórz koszyk itp. Walidacja origin jest kluczowa dla bezpieczeństwa - zapobiega interakcji nieautoryzowanych skryptów z Twoją aplikacją.

Po zakończeniu dostosowywania wyświetl ostateczny projekt, korzystając z poniższego adresu URL podglądu. Ten adres URL zwraca obraz spersonalizowanego produktu, odpowiedni jako wartość src w tagu <img>. Idealny do pokazania spersonalizowanego produktu w koszyku, podsumowaniu zamówienia lub w dowolnym miejscu interfejsu sklepu.

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

Zastąp {CART_ITEM_KEY} rzeczywistym kluczem pozycji koszyka i {APPLICATION_KEY} prawidłowym kluczem aplikacji.

Przykładowe użycie w tagu obrazu:

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

Webhooki są używane przez firmę Fabrixa do powiadamiania Twojego systemu o zdarzeniach w czasie rzeczywistym - aktualizacjach zamówień lub kreacjach. Kiedy nastąpi zdarzenie, Fabrixa wysyła webhook na Twój serwer zawierający odpowiednie informacje. Twój serwer musi udostępniać publiczny punkt końcowy POST, aby obsługiwać przychodzące webhooki.

Żądanie webhooka zawiera następujące nagłówki, które pomogą Ci zidentyfikować i zweryfikować przychodzące żądanie:

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

Podział nagłówka

• content-type - zawsze ustawione na application/json dla webhooków.
• x-webhook-signature - podpis HMAC-SHA256 do weryfikacji żądania.
• x-webhook-topic - typ zdarzenia lub temat webhooka. Na przykład:
  • order.created - wyzwalane w momencie utworzenia nowego zamówienia.
  • order.updated - wyzwalane w przypadku aktualizacji istniejącego zamówienia.

Webhooki Fabrixa powiadamiają Twój system o zmianach w statusie zamówienia lub aktywności. Każdy webhook jest wyzwalany przez określoną wartość x-webhook-topic. Aktualnie obsługiwane tematy:

Statusy zamówień

• Completed - zamówienie zostało wysłane lub odebrane, a odbiór został potwierdzony. W przypadku produktów cyfrowych klient zapłacił i pliki są dostępne do pobrania.
• Anulowane - płatność anulowana przez klienta; transakcja nie została zrealizowana.
• Wstrzymane - zlecenie tymczasowo zablokowane.
• Importowane - zamówienie zostało zaimportowane na platformę.

Statusy realizacji

• Niezrealizowane - zamówienie nie zostało jeszcze przygotowane ani wysłane.
• Częściowo zrealizowane - niektóre pozycje zostały przetworzone lub wysłane, inne nadal oczekują.
• Scheduled - zamówienie jest planowane i zaplanowane do realizacji.
• Odrzucone - żądanie realizacji zostało odrzucone, często z powodu nieprawidłowych szczegółów zamówienia lub niedostępności.
• Spełnione - zamówienie zostało w całości przetworzone i dostarczone lub udostępnione klient.

Przykład ładunku wysłanego za pomocą webhooka. Ten ładunek reprezentuje aktualizację zamówienia:

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

Aby upewnić się, że żądanie elementu webhook jest autentyczne i niezmienione, sprawdź nagłówek x-webhook-signature. Obejmuje to ponowne obliczenie podpisu HMAC-SHA256 przy użyciu nieprzetworzonego ładunku żądania i tajnego klucza, a następnie porównanie go z otrzymanym podpisem.

Przykład surowego PHP

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

Przykład Laravela

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

Zastąp $yourSecret swoim wspólnym tajnym kluczem. Zawsze używaj hash_equals do porównywania podpisów, aby złagodzić ataki czasowe.

Domyślnie webhooki są wyłączone po 10 nieudanych próbach dostarczenia. Jeśli punkt końcowy zwróci status niepowodzenia, taki jak 404 lub dowolny błąd 5xx, element webhook spróbuje ponownie w sumie 10 razy. Jeśli w dalszym ciągu będzie zwracał kod odpowiedzi inny niż 2xx lub inny niż 3xx, zostanie dezaktywowany. Pomyślne odpowiedzi obejmują:

• 2xx - oznacza pomyślne przetwarzanie, np.: 200 OK.
• 301 i 302 - odpowiedzi przekierowań wskazujące, że webhook został pomyślnie obsłużony lub przesłany dalej.

Zdecydowanie zalecamy, aby punkt końcowy zwrócił kod stanu 200 OK tak szybko, jak to możliwe, aby potwierdzić pomyślne otrzymanie elementu webhook. Chociaż każdą odpowiedź 2xx lub 3xx uważa się za pomyślną, najczęściej używaną i niezawodną jest odpowiedź 200.

Aby uniknąć przekroczenia limitu czasu dostarczania lub ponownych prób, zwróć natychmiast 200 OK i obsłuż asynchroniczne przetwarzanie ładunku elementu webhook, na przykład za pośrednictwem zadania lub kolejki w tle. Jeśli odpowiedź punktu końcowego trwa zbyt długo, może to zostać uznane za awarię, nawet jeśli odpowiedź ostatecznie zakończy się sukcesem.

Odpowiedzi z kodami stanu z zakresu 4xx lub 5xx lub przekroczenia limitu czasu będą wyzwalać ponowne próby zgodnie z mechanizmem ponawiania.