Referenčná dokumentácia Fabrixa Integration API

Na prístup k Integration API overujte svoje požiadavky pomocou prístupového tokenu aplikácie a zároveň kľúča aplikácie:

Hlavička Authorization

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Hlavička s kľúčom aplikácie

X-Application-Key: APPLICATION_KEY

Ukážkový prí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 svojím skutočným prístupovým tokenom a APPLICATION_KEY svojím skutočným kľúčom aplikácie.

Endpointy Integration API sú usporiadané podľa typu zdroja a dodržiavajú architektonický štýl REST. Každý endpoint predstavuje zdroj a akcie s týmito zdrojmi sa vykonávajú štandardnými metódami HTTP.

Všetky požiadavky a odpovede Integration API sú vo formáte JSON, čo poskytuje konzistentné a jednoducho použiteľné rozhranie na prácu s API.

Úplné podrobnosti o každom endpointe vrátane ukážok požiadaviek a odpovedí nájdete v našej dokumentácii Swagger.

Formát odpovede

Všetky endpointy vracajú údaje v štandardizovanom formáte s týmito objektmi:

{
  "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 objektov odpovede

Všetky požiadavky na API vracajú stavové kódy HTTP, ktoré informujú o výsledku požiadavky.

Telo chybovej odpovede

Ukážka tela chybovej odpovede:

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

errors obsahuje podrobnosti o tom, čo zlyhalo. Pole messages obsahuje popisy chýb. Pri chybe Bad Request dostanete názvy polí, ktoré neprešli validáciou.

Integration API umožňuje najviac 30 požiadaviek na aplikáciu za minútu.

Ak tento limit prekročíte, dostanete odpoveď 429 Too Many Requests.

Všetky odpovede Integration API obsahujú hlavičku X-RateLimit-Remaining, ktorá udáva, koľko požiadaviek môže klient ešte odoslať, a hlavičku X-RateLimit-Limit s celkovým povoleným počtom za minútu.

Režim sandbox vám umožňuje otestovať integráciu od začiatku do konca skôr, ako sa akákoľvek skutočná objednávka vyrobí alebo spoplatní. Platí pre celý váš účet: objednávky zo všetkých predajných kanálov vrátane Integration API a pripojených obchodov Shopify a WooCommerce sa nevyrábajú a neúčtujú na váš zostatok. Váš účet je v režime sandbox, kým má stav čaká na aktiváciu.

V režime sandbox môžete:

• pripojiť obchod Shopify alebo WooCommerce, alebo vytvoriť kanál Integration API;
• pridávať produkty a kontrolovať ceny a odhady dopravy;
• importovať, vytvárať, upravovať a rušiť objednávky;
• overiť, že žiadna z týchto objednávok sa nevyrába ani neúčtuje na váš zostatok;
• overiť doručovanie webhookov a podpisy.

Ak chcete otestovať objednávky, pridajte produkty z katalógu Fabrixa: otvorte produkt, kliknite na Predávať a vyberte varianty a dizajny. Potom sa zobrazia v časti Moje produkty.

Ak chcete prepnúť účet do režimu sandbox, otvorte Platform, prejdite na Nastavenia → Firma → Režim sandbox a kliknite na Prepnúť do režimu sandbox. Môžete ho zapnúť aj pri pridaní nového predajného kanála vrátane kanála Integration API, alebo napísať na support@fabrixa.com a my váš účet prepneme za vás. Režim sandbox je dostupný len pre aktívne účty.

Keď budete pripravení, aktivujte účet sami v Platforme v časti Nastavenia → Firma → Režim sandbox. Môžete tiež napísať na support@fabrixa.com a my ho aktivujeme za vás. Pripojené obchody a prístupové údaje k API naďalej fungujú, takže nie je potrebné nič znova nastavovať.

Po aktivácii idú všetky nové objednávky do výroby a účtujú sa na váš zostatok. Objednávky vytvorené pred aktiváciou zostávajú testovacie: nikdy sa nevyrábajú ani neúčtujú, ani po aktivácii.

Katalóg je všetko, čo Fabrixa vyrába. Vaše produkty sú produkty z katalógu, ktoré ste pridali do svojho účtu Fabrixa, s vlastnými názvami, popismi, obrázkami a SKU. Riadok objednávky odkazuje na variant produktu - jednu veľkosť alebo vyhotovenie produktu - pomocou jeho sku alebo variant_id: na variant jedného z vašich produktov, alebo na variant z katalógu objednaný priamo.

Zoznam produktov, ktoré Fabrixa vyrába, získate požiadavkou GET na https://api.fabrixa.com/v2/integration/catalog/products so svojimi prihlasovacími údajmi. Obsahuje aktívne produkty, ktoré majú variant aktuálne vyrábaný tlačovým partnerom, a len tieto varianty - každý so svojím SKU, predajnou cenou, rozmermi a hodnotami možností.

Parametre dopytu

Ukážková požiadavka

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ážková odpoveď

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

Polia odpovede

Zoznam kategórií, do ktorých je katalóg usporiadaný, získate požiadavkou GET na https://api.fabrixa.com/v2/integration/catalog/categories so svojimi prihlasovacími údajmi. Odpoveď obsahuje kategórie najvyššej úrovne, každú s podkategóriami vnorenými v sub_categories a počtom produktov katalógu v nej v products_count. Pri prehliadaní katalógu odovzdajte id kategórie ako category_id, alebo id kategórie najvyššej úrovne ako parent_category_id, aby ste získali produkty všetkých jej podkategórií naraz.

Parametre dopytu

Ukážková požiadavka

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ážková odpoveď

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

Zoznam produktov vo svojom účte získate požiadavkou GET na https://api.fabrixa.com/v2/integration/products so svojimi prihlasovacími údajmi. Vaše produkty sú produkty z katalógu, ktoré ste pridali do svojho účtu Fabrixa: nesú názvy, popisy a obrázky, ktoré ste im tam dali, a ich varianty hodnoty SKU, ktoré ste zvolili. V zozname sú len aktívne produkty, desať na stránku, ak neodovzdáte limit.

Parametre dopytu

Ukážková požiadavka

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ážková odpoveď

{
    "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 prečítate požiadavkou GET na https://api.fabrixa.com/v2/integration/products/{product_id}, kde {product_id} je jeho id. Odpoveď obsahuje rovnaké polia ako zoznam. Produkt, ktorý nie je vo vašom účte, ani produkt z katalógu, odpovie 404 Not Found so správou Product not found.

Polia odpovede

Variant je jedno vyhotovenie produktu, ktoré možno objednať - jedna veľkosť, jedna farba - a práve naň odkazuje riadok objednávky pomocou sku alebo variant_id. Variant jedného zo svojich produktov prečítate požiadavkou GET na https://api.fabrixa.com/v2/integration/variants/{variant_id}, kde {variant_id} je jeho id. Variant produktu, ktorý nie je vo vašom účte, odpovie 404 Not Found so správou Variant not found.

Ukážková požiadavka

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ážková odpoveď

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

Polia odpovede

Riadok objednávky pre tento variant s PDF, ktorého strany sú jeho vrstvy:

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

Ktoré varianty možno objednať

Vytvárajte objednávky vo Fabrixe z vlastného e-shopu alebo platformy, pripojte potrebné tlačové súbory a sledujte, ako jednotlivé položky postupujú procesom vybavenia.

Ak chcete vytvoriť objednávku cez Fabrixa Integration API, odošlite požiadavku POST na https://api.fabrixa.com/v2/integration/orders. Telo požiadavky musí obsahovať:

Štruktúra tela požiadavky

Ukážková požiadavka

{
  "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ážková odpoveď

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

Ak chcete upraviť objednávku, odošlite požiadavku PATCH na https://api.fabrixa.com/v2/integration/orders/{order_id}, kde {order_id} je ID objednávky vo Fabrixe. Zmenia sa iba polia, ktoré odošlete, a stav objednávky zostane nezmenený. Odpoveď obsahuje upravenú objednávku. Zmeniť môžete:

Ukážková požiadavka

{
  "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ážková odpoveď

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

Ak chcete objednávku zrušiť, odošlite požiadavku POST bez tela na https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, kde {order_id} je ID objednávky vo Fabrixe (číselné pole id objednávky), nie vaše číslo objednávky. Odpoveď obsahuje objednávku so stavom canceled a odošle sa webhook order.updated.

Ukážková odpoveď

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

Ak objednávku nemožno zrušiť, API odpovie 412 Precondition Failed so správou, ktorá vysvetľuje dôvod: jej aktuálny stav to neumožňuje (stav je uvedený v správe) alebo sa už začala výroba.

{
    "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 sa sleduje pomocou troch stavov: poľa status objednávky, jej výrobného stavu fulfillment_status a poľa status každej zásielky v shipments. Každá zmena sa odosiela vo webhooku order.updated a vracia ju GET /orders/{order_id}.

Stavy objednávky

Hodnoty poľa status objednávky v poradí, v akom nastávajú:

• imported - objednávka bola prijatá cez API. Každá objednávka začína tu.
• on hold - zostatok nepokrýva cenu objednávky. Po jeho dobití sa objednávka vráti do stavu imported a pokračuje.
• accepted - objednávka bola prijatá na spracovanie a ide do výroby.
• completed (konečný) - všetky položky boli vyrobené.
• canceled (konečný) - objednávka bola zrušená. Je to možné, kým je v stave imported, accepted alebo on hold a výroba sa ešte nezačala.

Stavy vybavenia

Hodnoty poľa fulfillment_status objednávky a každej jej položky v poradí, v akom nastávajú. Stav sa mení iba dopredu, nikdy späť:

• unfulfilled - výroba sa ešte nezačala.
• scheduled - objednávka je naplánovaná vo výrobnej dávke. Od tejto chvíle ju už nemožno zrušiť.
• processing - výroba prebieha.
• partially fulfilled - niektoré položky sú hotové, ostatné sú ešte vo výrobe.
• fulfilled (konečný) - všetky položky sú hotové. Pole status objednávky sa potom zmení na completed.

Objednávka ako celok nie je nikdy zamietnutá. Jednotlivá položka môže byť zamietnutá pri kontrole kvality počas výroby. Potom sa vytlačí znova: vráti sa do stavu unfulfilled a prejde výrobou ešte raz, pričom objednávka si ponechá svoj stav a pokračuje, keď je položka hotová.

Stavy zásielky

Hodnoty poľa status každej zásielky v shipments v poradí, v akom nastávajú:

• pending - zásielka sa pripravuje.
• registered - štítok bol vytvorený u prepravcu.
• collected - prepravca zásielku vyzdvihol.
• in transit - zásielka je na ceste.
• delivered (konečný) - zásielka bola doručená.

Výnimky:

• failed - prepravca nahlásil problém.
• returned (konečný) - zásielka nám bola vrátená.
• canceled (konečný) - zásielka bola zrušená.

Ak chcete zistiť stav vybavenia konkrétnej objednávky, odošlite požiadavku GET na https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Odpoveď obsahuje zoznam záznamov o vybavení priradených k objednávke vrátane stavu každej položky, podrobností o produkte a priebehu výrobných krokov.

Ukážková odpoveď

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

Odpoveď obsahuje zoznam záznamov o vybavení, pričom každý z nich obsahuje:

Každý záznam o vybavení zodpovedá konkrétnemu produktu alebo variantu produktu v objednávke a každý kus produktu v objednávke má vlastný záznam o vybavení - každá položka sa počas výroby sleduje samostatne.

Ak sa pre objednávku nevrátia žiadne záznamy o vybavení, objednávka ešte nevstúpila do fázy spracovania.

Ak k objednávke prikladáte zdrojové súbory, uistite sa, že spĺňajú nasledujúce požiadavky:

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

Požiadavky na PDF a poradie strán

Poradie strán v PDF je dôležité. Strany sa priraďujú k vrstvám produktu podľa pozície a očakávané poradie strán závisí od typu produktu. Uistite sa, že strany vo vašom PDF dodržiavajú správne poradie vrstiev pre produkt, ktorý odosielate.

Dôležité: každá strana PDF musí zodpovedať požadovaným rozmerom pre svoju vrstvu produktu a mať správnu orientáciu. Umiestnite grafiku tak, aby bol horný okraj dizajnu zarovnaný s horným okrajom strany. Nesprávna veľkosť alebo orientácia strany môže vo výrobe spôsobiť problémy so škálovaním, otočením alebo zarovnaním.

Zistite, koľko bude stáť doprava objednávky a ako dlho bude na ceste, ešte predtým, ako ju vytvoríte, podľa rovnakých pravidiel, podľa ktorých Fabrixa počíta samotnú objednávku.

Ak chcete zistiť, do ktorých krajín možno variant produktu doručiť, odošlite požiadavku GET na https://api.fabrixa.com/v2/integration/shipping/countries so svojimi prihlasovacími údajmi. Zoznam obsahuje krajiny zoradené podľa názvu, do ktorých má miesto, kde sa variant vyrába, prepravnú sadzbu pre niektorý prepravný balík, do ktorého sa dá variant zabaliť. Krajina, ktorá v zozname nie je, nemá pre variant žiadnu prepravnú sadzbu.

Parametre dopytu

Ukážková požiadavka

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ážková odpoveď

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

Polia odpovede

Ak chcete zistiť, koľko by stála doprava variantu produktu a ako dlho by trvala, odošlite požiadavku GET na https://api.fabrixa.com/v2/integration/shipping/estimate so svojimi prihlasovacími údajmi. Odhad sa riadi pravidlami, podľa ktorých sa počíta cena objednávky: kusy sa zabalia do prepravných balíkov miesta, kde sa variant vyrába, a cena každého balíka sa určí podľa trasy z tohto miesta do cieľovej krajiny. Nič sa neobjednáva ani nerezervuje a cena objednávky sa počíta až pri jej zadaní, takže doprava môže stáť inak, ak sa sadzby medzitým zmenia.

Parametre dopytu

Ukážková požiadavka

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ážková odpoveď

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

Polia odpovede

Požiadavka, ktorá neprejde validáciou, je odmietnutá s 400 Bad Request a dôvodom pre každé pole, s rovnakými správami ako pri riadku objednávky, napríklad The variant not found. Ak kusy nedokáže pojať žiadny prepravný balík, odpoveďou je 400 Bad Request so správou No shipping package can carry the variant.

Fabrixa Studio je nástroj, ktorý používateľom umožňuje plynulo prispôsobovať a personalizovať produkty v reálnom čase v intuitívnom rozhraní, v ktorom môžu vytvárať alebo nahrávať vlastné dizajny.

Fabrixa Studio je ideálne pre firmy, ktoré ponúkajú produkty na mieru - zákazníci si môžu svoj dizajn pozrieť ešte pred dokončením objednávky.

Fabrixa Studio môžete vložiť na svoj web pomocou iframe. Vaši zákazníci tak môžu personalizovať produkty priamo na vašom webe počas nákupu.

Ukážka iframe na vloženie 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 svojimi dynamickými hodnotami.

• application_key - jedinečný kľúč na autentifikáciu voči Integration API.
• product_sku - SKU variantu produktu získané z Integration API.
• cart_item_key - jedinečná hodnota z platformy, do ktorej je Studio vložené, ktorá identifikuje položku košíka priradenú k produktu. Slúži na uloženie personalizácií používateľa; pri vytváraní objednávky podľa nej systém nájde uložené personalizácie a priradí ich k objednávke. Pozrite si ukážku nižšie.
• locale (voliteľné) - jazyk rozhrania Studia a jeho chybových hlásení, napr. de_DE alebo de. Bez neho sa Studio otvorí v jazyku prehliadača zákazníka, ak je podporovaný, inak v angličtine.

Hlavička Studia zobrazuje názov produktu tak, ako je vo vašom obchode - rovnaký názov, aký vidia vaši zákazníci - a pod ním možnosti zvolenej varianty. Ide o vlastnú kópiu produktu vo vašom obchode, takže názov, ktorý upravíte vo Fabrixa, sa zobrazí aj v Studiu; locale ho neprekladá.

Požiadavka na vytvorenie 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": {
    "...": "..."
  }
}

Keď sa v iframe klikne na tlačidlo Pridať do košíka, vykoná sa tento príkaz:

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

Podobne pri kliknutí na tlačidlo Späť:

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

Metóda postMessage umožňuje komunikáciu medzi iframe a jeho nadradeným oknom aj naprieč rôznymi pôvodmi (cross-origin), takže iframe môže nadradené okno upozorniť na konkrétne akcie používateľa.

Prvým argumentom postMessage sú údaje, ktoré chcete odoslať. Reťazec 'customizationFinished' znamená, že používateľ dokončil personalizáciu a pridáva produkt do košíka. 'closeButtonClicked' znamená, že sa používateľ rozhodol vrátiť späť.

V nadradenom okne tieto správy zachytávajte pomocou poslucháča udalosti 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 prichádzajúcich správ, aby ste mali istotu, že pochádzajú z dôveryhodného zdroja. Podľa prijatej správy vykonajte potrebné akcie - aktualizujte používateľské rozhranie, spracujte košík a podobne. Overovanie origin je pre bezpečnosť kľúčové - zabraňuje neoprávneným skriptom v interakcii s vašou aplikáciou.

Po dokončení personalizácie zobrazte výsledný dizajn pomocou URL náhľadu uvedenej nižšie. Táto URL vracia obrázok personalizovaného produktu, ktorý môžete použiť ako hodnotu src v značke <img>. Hodí sa na zobrazenie personalizovaného produktu v košíku, v súhrne objednávky alebo kdekoľvek v rozhraní vášho obchodu.

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

Nahraďte {CART_ITEM_KEY} skutočným kľúčom položky košíka a {APPLICATION_KEY} svojím platným kľúčom aplikácie.

Ukážka použitia v značke obrázka:

<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 pomocou webhookov informuje váš systém o udalostiach v reálnom čase - o vytvorení alebo aktualizácii objednávok. Keď nastane udalosť, Fabrixa odošle na váš server webhook s príslušnými informáciami. Váš server musí sprístupniť verejný POST endpoint, ktorý bude prichádzajúce webhooky spracúvať.

Požiadavka webhooku obsahuje nasledujúce hlavičky, ktoré vám pomôžu prichádzajúcu požiadavku identifikovať a overiť:

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

Prehľad hlavičiek

• content-type - pri webhookoch vždy nastavená na application/json.
• x-webhook-signature - podpis HMAC-SHA256 na overenie požiadavky.
• x-webhook-topic - typ udalosti alebo téma webhooku. Napríklad:
  • order.created - spustí sa pri vytvorení novej objednávky.
  • order.updated - spustí sa pri aktualizácii existujúcej objednávky.

Webhooky sa odosielajú s hlavičkou User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); ak váš endpoint filtruje automatizovanú prevádzku, povoľte ho. Ak chcete mať istotu, že požiadavku odoslala Fabrixa, overte x-webhook-signature.

Webhooky Fabrixa informujú váš systém o zmenách stavu objednávky alebo o aktivite. Každý webhook sa spúšťa konkrétnou hodnotou x-webhook-topic. Momentálne podporované témy:

Ukážka payloadu odosielaného s webhookom. Tento payload predstavuje aktualizáciu 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"
    }
  ]
}

Keď je objednávka odoslaná, shipments obsahuje zoznam všetkých zásielok s ich dopravcom (carrier), spôsobom dopravy (method), stavom (status - pending, registered, collected, in transit, delivered, failed, returned alebo canceled) a sledovacími údajmi: tracking_number a tracking_url, a rovnako pre každý balík v packages, ak má zásielka viac balíkov. Webhook order.updated sa odošle vždy, keď sa zmení stav alebo sledovacie údaje zásielky, a GET /orders/{order_id} vracia rovnaké pole.

Aby ste mali istotu, že požiadavka webhooku je pravá a nikto ju nezmenil, overte hlavičku x-webhook-signature. Znamená to znova vypočítať podpis HMAC-SHA256 z nespracovaného payloadu požiadavky a vášho tajného kľúča a potom ho porovnať s prijatým podpisom.

Ukážka v čistom 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ážka v Laraveli

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 svojím zdieľaným tajným kľúčom. Na porovnávanie podpisov vždy používajte hash_equals, aby ste sa chránili pred časovacími útokmi.

Webhooky sa predvolene deaktivujú po 10 neúspešných pokusoch o doručenie. Ak váš endpoint vráti neúspešný stav, napríklad 404 alebo akúkoľvek chybu 5xx, webhook sa pokúsi o doručenie celkovo 10-krát. Ak bude endpoint naďalej vracať iný kód ako 2xx alebo 3xx, webhook sa deaktivuje. Za úspešné odpovede sa považujú:

• 2xx - znamená úspešné spracovanie, napr. 200 OK.
• 301 a 302 - odpovede s presmerovaním, ktoré znamenajú, že webhook bol úspešne spracovaný alebo presmerovaný ďalej.

Dôrazne odporúčame, aby váš endpoint čo najskôr vrátil stavový kód 200 OK a potvrdil tak úspešné prijatie webhooku. Hoci sa za úspešnú považuje akákoľvek odpoveď 2xx alebo 3xx, 200 je najbežnejšia a najspoľahlivejšia.

Aby ste predišli vypršaniu časového limitu doručenia alebo opakovaným pokusom, vráťte okamžite 200 OK a payload webhooku spracujte asynchrónne, napríklad pomocou úlohy na pozadí alebo frontu. Ak odpoveď vášho endpointu trvá príliš dlho, pokus sa môže považovať za neúspešný, aj keď je odpoveď nakoniec úspešná.

Odpovede so stavovými kódmi v rozsahu 4xx alebo 5xx, ako aj vypršanie časového limitu, spustia opakované pokusy podľa mechanizmu opakovania.