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.

Režim sandbox vám umožňuje otestovat integraci od začátku do konce dříve, než se jakákoli skutečná objednávka vyrobí nebo zaúčtuje. Platí pro celý váš účet: objednávky ze všech prodejních kanálů, včetně Integration API a připojených obchodů Shopify a WooCommerce, se nevyrábějí a neúčtují na váš zůstatek. Váš účet je v režimu sandbox, dokud má stav čeká na aktivaci.

V režimu sandbox můžete:

• připojit obchod Shopify nebo WooCommerce, nebo vytvořit kanál Integration API;
• přidávat produkty a kontrolovat ceny a odhady dopravy;
• importovat, vytvářet, upravovat a rušit objednávky;
• ověřit, že se žádná z těchto objednávek nevyrábí ani neúčtuje na váš zůstatek;
• ověřit doručování webhooků a podpisy.

Chcete-li otestovat objednávky, přidejte produkty z katalogu Fabrixa: otevřete produkt, klikněte na Prodávat a vyberte varianty a návrhy. Poté se zobrazí v části Moje produkty.

Chcete-li přepnout účet do režimu sandbox, otevřete Platform, přejděte na Nastavení → Firma → Režim sandbox a klikněte na Přepnout do režimu sandbox. Můžete jej zapnout také při přidání nového prodejního kanálu, včetně kanálu Integration API, nebo napsat na support@fabrixa.com a my váš účet přepneme za vás. Režim sandbox je dostupný pouze pro aktivní účty.

Až budete připraveni, aktivujte účet sami v Platformě v části Nastavení → Firma → Režim sandbox. Můžete také napsat na support@fabrixa.com a my jej aktivujeme za vás. Připojené obchody a přístupové údaje k API dál fungují, takže není třeba nic znovu nastavovat.

Po aktivaci jdou všechny nové objednávky do výroby a účtují se na váš zůstatek. Objednávky vytvořené před aktivací zůstávají testovací: nikdy se nevyrábějí ani neúčtují, ani po aktivaci.

Katalog je vše, co Fabrixa vyrábí. Vaše produkty jsou produkty z katalogu, které jste přidali do svého účtu Fabrixa, s vlastními názvy, popisy, obrázky a SKU. Řádek objednávky odkazuje na variantu produktu - jednu velikost nebo provedení produktu - pomocí jejího sku nebo variant_id: na variantu jednoho z vašich produktů, nebo na variantu z katalogu objednanou přímo.

Seznam produktů, které Fabrixa vyrábí, získáte požadavkem GET na https://api.fabrixa.com/v2/integration/catalog/products se svými přihlašovacími údaji. Obsahuje aktivní produkty, které mají variantu aktuálně vyráběnou tiskovým partnerem, a pouze tyto varianty - každou s jejím SKU, prodejní cenou, rozměry a hodnotami voleb.

Parametry dotazu

Ukázkový požadavek

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'

Ukázková odpověď

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

Pole odpovědi

Seznam kategorií, do kterých je katalog uspořádán, získáte požadavkem GET na https://api.fabrixa.com/v2/integration/catalog/categories se svými přihlašovacími údaji. Odpověď obsahuje kategorie nejvyšší úrovně, každou s podkategoriemi vnořenými v sub_categories a počtem produktů katalogu v ní v products_count. Při procházení katalogu předejte id kategorie jako category_id, nebo id kategorie nejvyšší úrovně jako parent_category_id, abyste získali produkty všech jejích podkategorií najednou.

Parametry dotazu

Ukázkový požadavek

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'

Ukázková odpověď

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

Seznam produktů ve svém účtu získáte požadavkem GET na https://api.fabrixa.com/v2/integration/products se svými přihlašovacími údaji. Vaše produkty jsou produkty z katalogu, které jste přidali do svého účtu Fabrixa: nesou názvy, popisy a obrázky, které jste jim tam dali, a jejich varianty hodnoty SKU, které jste zvolili. V seznamu jsou pouze aktivní produkty, deset na stránku, pokud nepředáte limit.

Parametry dotazu

Ukázkový požadavek

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'

Ukázková odpověď

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

Jeden produkt přečtete požadavkem GET na https://api.fabrixa.com/v2/integration/products/{product_id}, kde {product_id} je jeho id. Odpověď obsahuje stejná pole jako seznam. Produkt, který není ve vašem účtu, ani produkt z katalogu, odpoví 404 Not Found se zprávou Product not found.

Pole odpovědi

Varianta je jedno provedení produktu, které lze objednat - jedna velikost, jedna barva - a právě na ni odkazuje řádek objednávky pomocí sku nebo variant_id. Variantu jednoho ze svých produktů přečtete požadavkem GET na https://api.fabrixa.com/v2/integration/variants/{variant_id}, kde {variant_id} je její id. Varianta produktu, který není ve vašem účtu, odpoví 404 Not Found se zprávou Variant not found.

Ukázkový požadavek

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'

Ukázková odpověď

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

Pole odpovědi

Řádek objednávky pro tuto variantu s PDF, jehož stránky jsou její vrstvy:

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

Které varianty lze objednat

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

Ukázková odpověď

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

Chcete-li upravit objednávku, odešlete požadavek PATCH na https://api.fabrixa.com/v2/integration/orders/{order_id}, kde {order_id} je ID objednávky ve Fabrixa. Změní se jen pole, která odešlete, a stav objednávky zůstane stejný. Odpověď obsahuje upravenou objednávku. Můžete změnit:

Ukázkový požadavek

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

Ukázková odpověď

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

Chcete-li zrušit objednávku, odešlete požadavek POST bez těla na https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, kde {order_id} je ID objednávky ve Fabrixa (číselné pole id objednávky), nikoli vaše číslo objednávky. Odpověď obsahuje objednávku se stavem canceled a odešle se webhook order.updated.

Ukázková odpověď

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

Pokud objednávku nelze zrušit, API odpoví 412 Precondition Failed a zprávou s důvodem: její aktuální stav to nedovoluje (stav je uveden ve zprávě), nebo výroba již začala.

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

Objednávka se sleduje pomocí tří stavů: pole status objednávky, jejího výrobního stavu fulfillment_status a pole status každé zásilky v shipments. Každá změna se odesílá ve webhooku order.updated a vrací ji GET /orders/{order_id}.

Stavy objednávky

Hodnoty pole status objednávky v pořadí, v jakém nastávají:

• imported - objednávka byla přijata přes API. Každá objednávka začíná zde.
• on hold - zůstatek nepokrývá cenu objednávky. Po jeho dobití se objednávka vrátí do stavu imported a pokračuje.
• accepted - objednávka byla přijata ke zpracování a odchází do výroby.
• completed (konečný) - všechny položky byly vyrobeny.
• canceled (konečný) - objednávka byla zrušena. To je možné, dokud je ve stavu imported, accepted nebo on hold a výroba ještě nezačala.

Stavy plnění

Hodnoty pole fulfillment_status objednávky a každé její položky v pořadí, v jakém nastávají. Stav se mění pouze dopředu, nikdy zpět:

• unfulfilled - výroba ještě nezačala.
• scheduled - objednávka je naplánována ve výrobní dávce. Od této chvíle ji již nelze zrušit.
• processing - výroba probíhá.
• partially fulfilled - některé položky jsou hotové, ostatní jsou stále ve výrobě.
• fulfilled (konečný) - všechny položky jsou hotové. Pole status objednávky se pak změní na completed.

Objednávka jako celek není nikdy zamítnuta. Jednotlivá položka může být zamítnuta při kontrole kvality během výroby. Poté se vytiskne znovu: vrátí se do stavu unfulfilled a projde výrobou ještě jednou, zatímco objednávka si ponechá svůj stav a pokračuje, jakmile je položka hotová.

Stavy zásilky

Hodnoty pole status každé zásilky v shipments v pořadí, v jakém nastávají:

• pending - zásilka se připravuje.
• registered - štítek byl vytvořen u dopravce.
• collected - dopravce zásilku vyzvedl.
• in transit - zásilka je na cestě.
• delivered (konečný) - zásilka byla doručena.

Výjimky:

• failed - dopravce nahlásil problém.
• returned (konečný) - zásilka nám byla vrácena.
• canceled (konečný) - zásilka byla zrušena.

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.

Zjistěte, kolik bude stát doprava objednávky a jak dlouho bude na cestě, ještě než ji vytvoříte, a to podle stejných pravidel, podle kterých Fabrixa počítá samotnou objednávku.

Do kterých zemí lze variantu produktu doručit, zjistíte požadavkem GET na https://api.fabrixa.com/v2/integration/shipping/countries se svými přihlašovacími údaji. Seznam obsahuje země seřazené podle názvu, do kterých má místo, kde se varianta vyrábí, přepravní sazbu pro přepravní balík, do kterého lze variantu zabalit. Země, která v seznamu není, pro variantu žádnou přepravní sazbu nemá.

Parametry dotazu

Ukázkový požadavek

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'

Ukázková odpověď

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

Pole odpovědi

Kolik by stála doprava varianty produktu a jak dlouho by zásilka byla na cestě, zjistíte požadavkem GET na https://api.fabrixa.com/v2/integration/shipping/estimate se svými přihlašovacími údaji. Odhad se řídí pravidly, podle kterých se počítá cena objednávky: kusy se zabalí do přepravních balíků místa, kde se varianta vyrábí, a cena každého balíku se určí podle trasy z tohoto místa do cílové země. Nic se neobjednává ani nerezervuje a cena objednávky se počítá až při jejím zadání, takže cena její dopravy se může lišit, pokud se mezitím změní sazby.

Parametry dotazu

Ukázkový požadavek

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'

Ukázková odpověď

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

Pole odpovědi

Na požadavek, který neprojde validací, přijde odpověď 400 Bad Request s důvodem u každého pole a se stejnými zprávami jako u řádku objednávky, například The variant not found. Pokud kusy nepojme žádný přepravní balík, odpovědí je 400 Bad Request se zprávou No shipping package can carry the variant.

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.
• locale (volitelné) - jazyk rozhraní Studia a jeho chybových hlášení, např. de_DE nebo de. Bez něj se Studio otevře v jazyce prohlížeče zákazníka, pokud je podporován, jinak v angličtině.

Záhlaví Studia zobrazuje název produktu tak, jak je ve vašem obchodě - stejný název, jaký vidí vaši zákazníci - a pod ním možnosti zvolené varianty. Jde o vlastní kopii produktu ve vašem obchodě, takže název, který upravíte ve Fabrixa, se zobrazí i ve Studiu; locale ho nepřekládá.

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",
  "user-agent": "Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook)",
  "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 se odesílají s User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); pokud váš endpoint filtruje automatický provoz, povolte jej. Abyste měli jistotu, že požadavek pochází od Fabrixa, ověřte x-webhook-signature.

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:

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

Jakmile je objednávka odeslána, shipments obsahuje každou zásilku s jejím dopravcem (carrier), způsobem dopravy (method), stavem (status: pending, registered, collected, in transit, delivered, failed, returned nebo canceled) a sledováním: tracking_number a tracking_url, a totéž pro každý balík v packages, pokud má zásilka balíků více. Při každé změně stavu nebo sledování zásilky se odešle webhook order.updated a stejné pole vrací i GET /orders/{order_id}.

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