Довідник Fabrixa Integration API

Щоб користуватися Integration API, автентифікуйте requests за допомогою Application Access Token і Application Key:

Заголовок авторизації

Authorization: Bearer APPLICATION_ACCESS_TOKEN

Заголовок ключа програми

X-Application-Key: APPLICATION_KEY

Приклад команди 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'

Замініть APPLICATION_ACCESS_TOKEN на ваш фактичний маркер доступу, а APPLICATION_KEY на ваш фактичний ключ програми.

Endpoints Integration API організовані за resource type і відповідають REST-підходу. Кожен endpoint представляє resource, а дії виконуються стандартними HTTP methods.

Усі requests і responses Integration API використовують JSON, що забезпечує послідовну та зрозумілу взаємодію з API.

Щоб отримати повну інформацію про кожну кінцеву точку, включаючи приклади запитів і відповідей, перегляньте наш Swagger documentation.

Формат відповіді

Усі кінцеві точки повертають дані в стандартизованому форматі з такими об’єктами:

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

Опис об'єктів відповіді

Усі запити API повертають коди статусу HTTP, які дають уявлення про відповідь.

Тіло відповіді на помилку

Приклад тіла відповіді на помилку:

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

errors містить детальну інформацію про те, що не вдалося. Масив messages містить описи помилок. У разі неправильного запиту ви отримаєте назви полів, які не пройшли перевірку.

Інтеграційний API підтримує ліміт 30 запитів на програму за хвилину.

Якщо ви перевищите цей ліміт, ви отримаєте відповідь 429 Too Many Requests.

Усі відповіді Integration API включають заголовок X-RateLimit-Remaining, скільки запитів ще може зробити клієнт, і заголовок X-RateLimit-Limit, загальну кількість запитів, дозволену за хвилину.

Режим пісочниці дає змогу протестувати інтеграцію від початку до кінця, поки жодне реальне замовлення не виготовляється і не оплачується. Він діє на весь ваш акаунт: замовлення з усіх каналів продажу, зокрема Integration API та підключених магазинів Shopify і WooCommerce, не виготовляються і не списуються з вашого балансу. Акаунт перебуває в режимі пісочниці, поки його статус очікує активації.

У режимі пісочниці ви можете:

• підключити магазин Shopify або WooCommerce чи створити канал Integration API;
• додавати продукти та перевіряти ціни й оцінку вартості доставки;
• імпортувати, створювати, змінювати й скасовувати замовлення;
• переконатися, що жодне з цих замовлень не виготовляється і не списується з вашого балансу;
• перевіряти доставку вебхуків і підписи.

Щоб протестувати замовлення, додайте продукти з каталогу Fabrixa: відкрийте продукт, натисніть Продавати і виберіть варіанти та дизайни. Після цього вони з’являться в розділі Мої продукти.

Щоб перевести акаунт у режим пісочниці, відкрийте Platform, перейдіть до Налаштування → Компанія → Режим пісочниці і натисніть Перевести в режим пісочниці. Також його можна ввімкнути під час додавання нового каналу продажу, зокрема каналу Integration API, або написати на support@fabrixa.com, і ми переведемо ваш акаунт у режим пісочниці. Режим пісочниці доступний лише для активних акаунтів.

Коли будете готові, активуйте акаунт самостійно в Platform у розділі Налаштування → Компанія → Режим пісочниці. Також можна написати на support@fabrixa.com, і ми активуємо його за вас. Підключені магазини та облікові дані API продовжують працювати, тож нічого переналаштовувати не потрібно.

Після активації всі нові замовлення йдуть у виробництво і списуються з вашого балансу. Замовлення, створені до активації, залишаються тестовими: вони ніколи не виготовляються і не оплачуються, навіть після активації.

Каталог — це все, що виробляє Fabrixa. Ваші продукти — це каталожні продукти, які ви додали до свого облікового запису Fabrixa, з вашими власними назвами, описами, зображеннями та SKU. Рядок замовлення вказує варіант продукту — один розмір чи одну версію продукту — за його sku або variant_id: варіант одного з ваших продуктів або каталожний варіант, замовлений безпосередньо.

Щоб отримати перелік продуктів, які виробляє Fabrixa, надішліть запит GET на https://api.fabrixa.com/v2/integration/catalog/products зі своїми обліковими даними. Він містить активні продукти, що мають варіант, який наразі виробляє друкарський партнер, і лише ці варіанти — кожен зі своїм SKU, ціною продажу, розмірами та значеннями опцій.

Параметри запиту

Зразок запиту

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'

Зразок відповіді

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

Поля відповіді

Щоб отримати перелік категорій, за якими впорядковано каталог, надішліть запит GET на https://api.fabrixa.com/v2/integration/catalog/categories зі своїми обліковими даними. Відповідь містить категорії верхнього рівня, кожна з підкатегоріями, вкладеними в sub_categories, і кількістю каталожних продуктів у ній у products_count. Передайте id категорії як category_id під час перегляду каталогу або id категорії верхнього рівня як parent_category_id, щоб отримати продукти всіх її підкатегорій одразу.

Параметри запиту

Зразок запиту

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'

Зразок відповіді

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

Щоб отримати перелік продуктів у вашому обліковому записі, надішліть запит GET на https://api.fabrixa.com/v2/integration/products зі своїми обліковими даними. Ваші продукти — це каталожні продукти, які ви додали до свого облікового запису Fabrixa: вони мають назви, описи та зображення, які ви їм там дали, а їхні варіанти — обрані вами значення SKU. У переліку лише активні продукти, по десять на сторінку, якщо не передати limit.

Параметри запиту

Зразок запиту

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'

Зразок відповіді

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

Щоб прочитати один продукт, надішліть запит GET на https://api.fabrixa.com/v2/integration/products/{product_id}, де {product_id} — його id. Відповідь містить ті самі поля, що й перелік. Продукт, якого немає у вашому обліковому записі, навіть каталожний, відповідає 404 Not Found із повідомленням Product not found.

Поля відповіді

Варіант — це одна версія продукту, яку можна замовити, — один розмір, один колір — і саме її вказує рядок замовлення за sku або variant_id. Щоб прочитати варіант одного з ваших продуктів, надішліть запит GET на https://api.fabrixa.com/v2/integration/variants/{variant_id}, де {variant_id} — його id. Варіант продукту, якого немає у вашому обліковому записі, відповідає 404 Not Found із повідомленням Variant not found.

Зразок запиту

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'

Зразок відповіді

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

Поля відповіді

Рядок замовлення для цього варіанта з PDF, сторінки якого є його шарами:

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

Які варіанти можна замовити

Створюйте замовлення у Fabrixa зі свого storefront або платформи, додавайте потрібні файли для друку та відстежуйте кожну позицію під час fulfilment.

Щоб створити order через Fabrixa Integration API, надішліть POST request на https://api.fabrixa.com/v2/integration/orders. Request body має містити:

Структура тіла запиту

Зразок запиту

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

Зразок відповіді

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

Щоб оновити замовлення, надішліть PATCH request на https://api.fabrixa.com/v2/integration/orders/{order_id}, де {order_id} — id замовлення у Fabrixa. Змінюються лише поля, які ви надіслали, а статус замовлення лишається тим самим. Відповідь містить оновлене замовлення. Можна змінити:

Зразок запиту

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

Зразок відповіді

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

Щоб скасувати замовлення, надішліть POST request без body на https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, де {order_id} — id замовлення у Fabrixa (числове поле id замовлення), а не ваш номер замовлення. Відповідь містить замовлення зі статусом canceled, і надсилається вебхук order.updated.

Зразок відповіді

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

Якщо замовлення не можна скасувати, API відповідає 412 Precondition Failed з повідомленням про причину: поточний статус цього не дозволяє (статус вказано в повідомленні) або виробництво вже почалося.

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

Замовлення відстежується за трьома статусами: полем status замовлення, його виробничим статусом fulfillment_status і полем status кожного відправлення в shipments. Кожна зміна надсилається у вебхуку order.updated і повертається в GET /orders/{order_id}.

Статуси замовлень

Значення поля status замовлення в тому порядку, у якому вони настають:

• imported - замовлення отримано через API. З цього статусу починається кожне замовлення.
• on hold - балансу не вистачає, щоб покрити вартість замовлення. Щойно його поповнять, замовлення повертається до imported і продовжується.
• accepted - замовлення прийнято й передано у виробництво.
• completed (фінальний) - усі вироби виготовлено.
• canceled (фінальний) - замовлення скасовано. Це можливо, поки воно має статус imported, accepted або on hold і виробництво ще не почалося.

Статуси виконання

Значення поля fulfillment_status замовлення та кожного його рядка в тому порядку, у якому вони настають. Статус змінюється лише вперед, ніколи не назад:

• unfulfilled - виробництво ще не почалося.
• scheduled - замовлення заплановано у виробничу партію. Відтепер його вже не можна скасувати.
• processing - триває виробництво.
• partially fulfilled - частину виробів готово, решта ще у виробництві.
• fulfilled (фінальний) - усі вироби готові. Після цього status замовлення стає completed.

Замовлення в цілому ніколи не відхиляється. Окремий виріб можуть відхилити під час контролю якості на виробництві. Тоді його друкують повторно: він повертається до unfulfilled і ще раз проходить виробництво, а замовлення зберігає свій статус і продовжується, щойно виріб буде готовий.

Статуси відправлень

Значення поля status кожного відправлення в shipments у тому порядку, у якому вони настають:

• pending - відправлення готується.
• registered - етикетку створено в перевізника.
• collected - перевізник забрав посилку.
• in transit - посилка в дорозі.
• delivered (фінальний) - посилку доставлено.

Винятки:

• failed - перевізник повідомив про проблему.
• returned (фінальний) - посилку повернули нам.
• canceled (фінальний) - відправлення скасовано.

Щоб отримати fulfilment status для конкретного order, надішліть GET request на https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Response містить fulfillments для order, включно зі статусом item, product details і прогресом production steps.

Зразок відповіді

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

Відповідь містить перелік виконання, кожне з яких містить:

Кожен запис про виконання відповідає певному продукту або варіанту продукту в замовленні, а кожна копія продукту в замовленні має власний запис про виконання – кожен товар відстежується окремо протягом усього виробництва.

Якщо для замовлення не повернуто виконання, це означає, що замовлення ще не перейшло в стадію обробки.

Додаючи source files до order, переконайтеся, що вони відповідають таким вимогам:

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

Вимоги до PDF та порядок сторінок

Порядок сторінок у PDF-файлі важливий. Сторінки зіставляються з шарами продукту за позицією, а очікуваний порядок сторінок залежить від типу продукту. Переконайтеся, що сторінки у вашому PDF відповідають правильній послідовності шарів для продукту, який ви надсилаєте.

Важливо: кожна PDF-сторінка має відповідати необхідним розмірам для свого продукту та бути правильно орієнтована. Розмістіть ілюстрацію так, щоб верхня частина дизайну збігалася з верхньою частиною сторінки. Неправильний розмір або орієнтація сторінки можуть спричинити проблеми з масштабуванням, поворотом або вирівнюванням у виробництві.

Дізнайтеся, скільки коштуватиме доставка замовлення і скільки часу воно буде в дорозі, ще до його створення, за тими самими правилами, за якими Fabrixa розраховує саме замовлення.

Щоб дізнатися, до яких країн можна доставити варіант продукту, надішліть запит GET на https://api.fabrixa.com/v2/integration/shipping/countries зі своїми обліковими даними. Список містить відсортовані за назвою країни, до яких локація, що виробляє варіант, має тариф доставки для одного з пакувань для відправлення, у які можна запакувати варіант. Країна, якої немає в списку, не має тарифу доставки для цього варіанта.

Параметри запиту

Зразок запиту

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'

Зразок відповіді

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

Поля відповіді

Щоб дізнатися, скільки коштуватиме доставка варіанта продукту і скільки часу вона триватиме, надішліть запит GET на https://api.fabrixa.com/v2/integration/shipping/estimate зі своїми обліковими даними. Оцінка розраховується за тими самими правилами, що й ціна замовлення: одиниці розміщуються в пакуваннях для відправлення, які має локація, що виробляє варіант, а вартість кожної посилки визначається за маршрутом від цієї локації до країни призначення. Нічого не замовляється й не резервується, а ціна замовлення розраховується в момент його оформлення, тож вартість доставки може відрізнятися, якщо тарифи тим часом зміняться.

Параметри запиту

Зразок запиту

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'

Зразок відповіді

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

Поля відповіді

Запит, який не пройшов перевірку, відхиляється з 400 Bad Request і причиною для кожного поля, з тими самими повідомленнями, що й для рядка замовлення, наприклад The variant not found. Якщо жодне пакування для відправлення не може вмістити одиниці, відповідь — 400 Bad Request із повідомленням No shipping package can carry the variant.

Fabrixa Studio — це інструмент, який дозволяє користувачам безперешкодно налаштовувати та персоналізувати продукти в реальному часі за допомогою інтуїтивно зрозумілого інтерфейсу, де користувачі можуть створювати або завантажувати власні дизайни.

Fabrixa Studio ідеально підходить для підприємств, які пропонують продукцію на замовлення, дозволяючи клієнтам візуалізувати свої проекти перед завершенням замовлення.

Ви можете вбудувати Fabrixa Studio на сайт за допомогою iframe. Це дозволяє клієнтам персоналізувати products безпосередньо на сайті під час checkout.

Приклад iframe для вбудовування Fabrixa Studio:

<iframe id="fabrixa-studio"
    src="https://studio.fabrixa.com?application_key={application_key}&sku={product_sku}&cart_item_key={cart_item_key}"
    name="FabrixaStudio"
    scrolling="no"
    frameborder="1"
    width="100%"
    height="100%"
    allowfullscreen="">
</iframe>

Замініть значення для product_sku, cart_item_key і application_key своїми динамічними значеннями.

• application_key – унікальний ключ для автентифікації в API інтеграції.
• product_sku – SKU варіанта продукту, отриманий з API інтеграції.
• cart_item_key – унікальне значення з платформи вбудовування, що ідентифікує позицію кошика, пов’язану з продуктом. Використовується для збереження налаштувань користувача; під час створення замовлення він визначає збережені налаштування та призначає їх до замовлення. Див. приклад нижче.
• locale (необов'язково) – мова інтерфейсу Studio та його повідомлень про помилки, напр. de_DE або de. Без нього Studio відкривається мовою браузера покупця, якщо вона підтримується, інакше англійською.

У заголовку Studio показано назву товару так, як вона є у вашому магазині, – ту саму, яку бачать ваші клієнти, – а під нею опції вибраного варіанта. Це власна копія товару у вашому магазині, тож назва, яку ви змінили у Fabrixa, показується і в Studio; locale її не перекладає.

Запит на створення замовлення за допомогою 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": {
    "...": "..."
  }
}

Після натискання кнопки Додати до кошика всередині iframe виконується така команда:

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

Аналогічно, якщо натиснути кнопку Назад:

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

Метод postMessage полегшує перехресний зв’язок між iframe і його батьківським вікном, дозволяючи йому сповіщати батьків про певні дії користувача.

Перший аргумент postMessage — це дані, які ви хочете надіслати. Рядок 'customizationFinished' вказує на те, що користувач завершив налаштування та додає продукт у кошик. 'closeButtonClicked' вказує, що користувач вирішив повернутися.

У батьківському вікні прослухайте ці повідомлення за допомогою прослуховувача подій 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.');
        }
    }
});

Завжди перевіряйте origin вхідних повідомлень, щоб переконатися, що вони надходять із надійного джерела. Залежно від отриманого повідомлення виконайте необхідні дії — оновіть інтерфейс користувача, обробіть кошик тощо. Перевірка origin має вирішальне значення для безпеки — вона запобігає взаємодії несанкціонованих сценаріїв із вашим додатком.

Після завершення налаштування відобразіть остаточний дизайн, використовуючи URL попереднього перегляду нижче. Ця URL-адреса повертає зображення налаштованого продукту, яке підходить як значення src у тегу <img>. Ідеально підходить для показу налаштованого продукту у вашому кошику, підсумку замовлення або будь-де в інтерфейсі вашого магазину.

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

Замініть {CART_ITEM_KEY} справжнім ключем елемента кошика, а {APPLICATION_KEY} — дійсним ключем програми.

Приклад використання в тегу зображення:

<img
    src="https://api.fabrixa.com/v2/studio/customizations/{CART_ITEM_KEY}/preview?Application-Key={APPLICATION_KEY}"
    alt="Customized Product Preview"
    style="max-width: 100%; height: auto;" />

Webhooks використовуються Fabrixa для сповіщення вашої системи про події в реальному часі - оновлення замовлень або створення. Коли відбувається подія, Fabrixa надсилає на ваш сервер вебхук із відповідною інформацією. Щоб обробляти вхідні веб-перехоплювачі, ваш сервер має відкрити загальнодоступну кінцеву точку POST.

Webhook request містить такі headers, які допомагають ідентифікувати та перевірити вхідний request:

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

Розбивка заголовка

• content-type – завжди встановлено значення application/json для вебхуків.
• x-webhook-signature – підпис HMAC-SHA256 для перевірки запиту.
• x-webhook-topic – тип події або тема вебхуку. Наприклад:
  • order.created – активується, коли створюється нове замовлення.
  • order.updated – активується, коли оновлюється існуюче замовлення.

Вебхуки надсилаються з User-Agent Fabrixa/2.0 (+https://api.fabrixa.com/docs/integration#webhooks; webhook); якщо ваш endpoint фільтрує автоматичний трафік, дозвольте його. Щоб переконатися, що запит надійшов від Fabrixa, перевіряйте x-webhook-signature.

Fabrixa webhooks повідомляють вашу систему про зміни order status або активність. Кожен webhook запускається певним значенням x-webhook-topic. Поточні підтримувані topics:

Приклад корисного навантаження, надісланого з вебхуком. Це корисне навантаження представляє оновлення замовлення:

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

Щойно замовлення відправлено, shipments містить кожну відправку з перевізником (carrier), способом доставки (method), статусом (status: pending, registered, collected, in transit, delivered, failed, returned або canceled) і трекінгом: tracking_number і tracking_url, а також те саме для кожної посилки в packages, коли їх у відправці кілька. Щоразу, коли змінюється статус або трекінг відправки, надсилається вебхук order.updated, а GET /orders/{order_id} повертає те саме поле.

Щоб переконатися, що webhook request автентичний і не змінений, перевірте header x-webhook-signature. Повторно обчисліть HMAC-SHA256 signature з raw request payload і вашою secret key, а потім порівняйте її з отриманою signature.

Необроблений приклад 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');
}

Приклад Laravel

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

Замініть $yourSecret вашим спільним секретним ключем. Завжди використовуйте hash_equals для порівняння сигнатур, щоб пом’якшити атаки за часом.

За замовчуванням вебхуки вимикаються після 10 невдалих спроб доставки. Якщо ваша кінцева точка повертає невдалий статус, наприклад 404 або будь-яку помилку 5xx, вебхук повторить спробу загалом 10 разів. Якщо він продовжує повертати код відповіді не 2xx або не 3xx, його буде деактивовано. Серед успішних відповідей:

• 2xx - вказує на успішну обробку, напр. 200 OK.
• 301 і 302 – відповіді на переспрямування, які вказують на те, що вебхук було успішно оброблено або переслано.

Ми наполегливо рекомендуємо вашій кінцевій точці якомога швидше повертати код стану 200 OK, щоб підтвердити успішне отримання вебхуку. Хоча будь-яка відповідь 2xx або 3xx вважається успішною, 200 є найпоширенішим і надійним.

Щоб уникнути тайм-аутів доставки або повторних спроб, негайно поверніть 200 OK і обробіть корисне навантаження вебхуку асинхронно, наприклад, через фонове завдання або чергу. Якщо вашій кінцевій точці потрібно занадто багато часу, щоб відповісти, це може вважатися невдачею, навіть якщо відповідь остаточно успішна.

Відповіді з кодами стану в діапазоні 4xx або 5xx або тайм-аути ініціюють повторні спроби відповідно до механізму повторних спроб.