Referenční dokumentace Fabrixa Integration API

Pro přístup k Integration API autentizujte své požadavky pomocí přístupového tokenu aplikace a klíče aplikace:

Hlavička Authorization

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Hlavička s klíčem aplikace

X-Application-Key: APPLICATION_KEY

Ukázkový příkaz 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'

Nahraďte APPLICATION_ACCESS_TOKEN svým skutečným přístupovým tokenem a APPLICATION_KEY svým skutečným klíčem aplikace.

Endpointy Integration API jsou organizovány podle typu zdroje a dodržují architektonický styl REST. Každý endpoint představuje zdroj a akce nad těmito zdroji se provádějí standardními metodami HTTP.

Všechny požadavky a odpovědi Integration API jsou ve formátu JSON, což poskytuje konzistentní a snadno použitelné rozhraní pro práci s API.

Úplné podrobnosti o všech endpointech včetně ukázek požadavků a odpovědí najdete v naší dokumentaci Swagger.

Formát odpovědi

Všechny endpointy vracejí data ve standardizovaném formátu s těmito objekty:

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

Popis objektů odpovědi

Všechny požadavky na API vracejí stavové kódy HTTP, které poskytují informaci o odpovědi.

Tělo chybové odpovědi

Ukázka těla chybové odpovědi:

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

errors obsahuje podrobnosti o tom, co selhalo. Pole messages uvádí popisy chyb. U chyby Bad Request obdržíte názvy polí, která neprošla validací.

Integration API podporuje limit 30 požadavků na aplikaci za minutu.

Pokud tento limit překročíte, obdržíte odpověď 429 Too Many Requests.

Všechny odpovědi Integration API obsahují hlavičku X-RateLimit-Remaining, tedy kolik požadavků může klient ještě provést, a hlavičku X-RateLimit-Limit, tedy celkový povolený počet za minutu.

Vytvářejte objednávky ve Fabrixe ze svého vlastního obchodu nebo platformy, přiložte potřebné tiskové soubory a sledujte každou položku, jak postupuje plněním.

Chcete-li vytvořit objednávku přes Fabrixa Integration API, odešlete požadavek POST na https://api.fabrixa.com/v2/integration/orders. Tělo požadavku musí obsahovat:

Struktura těla požadavku

Ukázkový požadavek

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

Chcete-li získat stav plnění konkrétní objednávky, odešlete požadavek GET na https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Odpověď obsahuje seznam plnění spojených s objednávkou včetně stavu každé položky, podrobností o produktu a průběhu výrobních kroků.

Ukázková odpověď

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

Odpověď obsahuje seznam plnění, každé z nich poskytuje:

Každý záznam plnění odpovídá konkrétnímu produktu nebo jeho variantě v objednávce a každý kus produktu v objednávce má svůj vlastní záznam plnění - každá položka je během výroby sledována samostatně.

Pokud pro objednávku nejsou vrácena žádná plnění, objednávka dosud nevstoupila do fáze zpracování.

Pokud k objednávce přikládáte zdrojové soubory, ujistěte se, že splňují následující požadavky:

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

Požadavky na PDF a pořadí stránek

Pořadí stránek v PDF je důležité. Stránky se k produktovým vrstvám přiřazují podle pozice a očekávané pořadí stránek závisí na typu produktu. Ujistěte se, že stránky ve vašem PDF odpovídají správné posloupnosti vrstev pro produkt, který odesíláte.

Důležité: každá stránka PDF musí odpovídat požadovaným rozměrům pro svou produktovou vrstvu a mít správnou orientaci. Umístěte grafiku tak, aby horní část designu byla zarovnána s horním okrajem stránky. Nesprávná velikost nebo orientace stránky může ve výrobě způsobit problémy se škálováním, otočením nebo zarovnáním.

Fabrixa Studio je nástroj, který uživatelům umožňuje plynule personalizovat produkty v reálném čase díky intuitivnímu rozhraní, ve kterém mohou vytvářet nebo nahrávat vlastní designy.

Fabrixa Studio je ideální pro firmy nabízející produkty na míru - zákazníci si mohou svůj design zobrazit ještě před dokončením objednávky.

Fabrixa Studio můžete vložit do svého webu pomocí iframe. To vašim zákazníkům umožní personalizovat produkty přímo na vašem webu během nákupu.

Ukázka iframe pro vložení Fabrixa Studia:

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

Nahraďte hodnoty product_sku, cart_item_key a application_key svými dynamickými hodnotami.

• application_key - unikátní klíč pro autentizaci k Integration API.
• product_sku - SKU varianty produktu získané z Integration API.
• cart_item_key - unikátní hodnota z vkládající platformy, která identifikuje položku košíku spojenou s produktem. Slouží k uložení personalizací uživatele; při vytváření objednávky identifikuje uložené personalizace a přiřadí je k objednávce. Viz ukázku níže.

Požadavek na vytvoření objednávky s 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": {
    "...": "..."
  }
}

Když se uvnitř iframe klikne na tlačítko Přidat do košíku, provede se následující příkaz:

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

Obdobně při kliknutí na tlačítko Zpět:

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

Metoda postMessage umožňuje komunikaci mezi iframe a jeho nadřazeným oknem přes různé domény, takže může nadřazené okno informovat o konkrétních akcích uživatele.

Prvním argumentem postMessage jsou data, která chcete odeslat. Řetězec 'customizationFinished' znamená, že uživatel dokončil personalizaci a přidává produkt do košíku. 'closeButtonClicked' znamená, že se uživatel rozhodl vrátit zpět.

V nadřazeném okně tyto zprávy odchytávejte pomocí posluchače události message:

window.addEventListener('message', function(event) {
    if (event.origin === 'https://studio.fabrixa.com') {
        if (event.data === 'customizationFinished') {
            // Handle the Add to Cart event
            console.log('Customization finished and item can be added to cart.');
        } else if (event.data === 'closeButtonClicked') {
            // Handle the Back button event
            console.log('Back button clicked.');
        }
    }
});

Vždy kontrolujte origin příchozích zpráv, abyste se ujistili, že přicházejí z důvěryhodného zdroje. Podle přijaté zprávy provádějte potřebné akce - aktualizaci uživatelského rozhraní, zpracování košíku a podobně. Validace origin je pro bezpečnost klíčová - zabraňuje neoprávněným skriptům v interakci s vaší aplikací.

Po dokončení personalizace zobrazte finální design pomocí níže uvedené URL náhledu. Tato URL vrací obrázek personalizovaného produktu vhodný jako hodnota src ve značce <img>. Je ideální pro zobrazení personalizovaného produktu v košíku, v souhrnu objednávky nebo kdekoli v rozhraní vašeho obchodu.

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

Nahraďte {CART_ITEM_KEY} skutečným klíčem položky košíku a {APPLICATION_KEY} svým platným klíčem aplikace.

Ukázka použití ve značce obrázku:

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

Fabrixa používá webhooky k tomu, aby váš systém informovala o událostech v reálném čase - aktualizacích nebo vytvoření objednávek. Když událost nastane, Fabrixa odešle na váš server webhook s příslušnými informacemi. Váš server musí vystavit veřejný POST endpoint, který příchozí webhooky zpracuje.

Požadavek webhooku obsahuje následující hlavičky, které vám pomohou příchozí požadavek identifikovat a ověřit:

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

Rozpis hlaviček

• content-type - u webhooků vždy nastaveno na application/json.
• x-webhook-signature - podpis HMAC-SHA256 pro ověření požadavku.
• x-webhook-topic - typ události nebo téma webhooku. Například:
  • order.created - spuštěno při vytvoření nové objednávky.
  • order.updated - spuštěno při aktualizaci existující objednávky.

Webhooky Fabrixa informují váš systém o změnách stavu objednávky nebo o aktivitě. Každý webhook je spuštěn konkrétní hodnotou x-webhook-topic. Aktuálně podporovaná témata:

Stavy objednávky

• Completed - objednávka byla odeslána nebo vyzvednuta a převzetí je potvrzeno. U digitálních produktů zákazník zaplatil a soubory jsou dostupné ke stažení.
• Canceled - zákazník zrušil platbu; transakce nebyla dokončena.
• On hold - objednávka je dočasně zablokována.
• Imported - objednávka byla do platformy importována.

Stavy plnění

• Unfulfilled - objednávka dosud nebyla připravena ani odeslána.
• Partially fulfilled - některé položky byly zpracovány nebo odeslány, ostatní stále čekají.
• Scheduled - objednávka je naplánována ke zpracování.
• Rejected - požadavek na plnění byl zamítnut, často kvůli neplatným údajům objednávky nebo nedostupnosti.
• Fulfilled - objednávka byla plně zpracována a doručena nebo předána zákazníkovi.

Ukázka payloadu odesílaného s webhookem. Tento payload představuje aktualizaci objednávky:

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

Chcete-li se ujistit, že je požadavek webhooku pravý a nezměněný, ověřte hlavičku x-webhook-signature. Znamená to znovu vypočítat podpis HMAC-SHA256 z nezpracovaného payloadu požadavku a vašeho tajného klíče a poté jej porovnat s přijatým podpisem.

Ukázka v čistém 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');
}

Ukázka v Laravelu

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

Nahraďte $yourSecret svým společným tajným klíčem. Pro porovnávání podpisů vždy používejte hash_equals, abyste omezili časovací útoky.

Webhooky se ve výchozím nastavení deaktivují po 10 neúspěšných pokusech o doručení. Pokud váš endpoint vrátí neúspěšný stav, například 404 nebo jakoukoli chybu 5xx, webhook se pokusí doručit celkem 10krát. Pokud bude i dále vracet jiný kód než 2xx nebo 3xx, bude deaktivován. Za úspěšné odpovědi se považují:

• 2xx - značí úspěšné zpracování, např. 200 OK.
• 301 a 302 - přesměrovací odpovědi značící, že webhook byl úspěšně zpracován nebo předán dál.

Důrazně doporučujeme, aby váš endpoint vracel stavový kód 200 OK co nejdříve a potvrdil tak úspěšné přijetí webhooku. Za úspěšnou se sice považuje jakákoli odpověď 2xx nebo 3xx, ale 200 je nejběžnější a nejspolehlivější.

Abyste se vyhnuli vypršení časového limitu doručení nebo opakovaným pokusům, vraťte okamžitě 200 OK a payload webhooku zpracujte asynchronně, například na pozadí ve frontě nebo úloze. Pokud vašemu endpointu odpověď trvá příliš dlouho, může být pokus vyhodnocen jako neúspěšný, i když je odpověď nakonec úspěšná.

Odpovědi se stavovými kódy v rozsahu 4xx nebo 5xx a vypršení časového limitu spustí opakované pokusy podle mechanismu opakování.