Справочник за Fabrixa Integration API

За достъп до Integration API удостоверявайте заявките си едновременно с токен за достъп на приложението (Application Access Token) и ключ на приложението (Application Key):

Заглавка Authorization

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 – с ключа на вашето приложение.

Крайните точки на Integration API са организирани по тип ресурс и следват архитектурния стил REST. Всяка крайна точка представлява ресурс, а действията с тези ресурси се извършват чрез стандартни HTTP методи.

Всички заявки и отговори на Integration API са във формат JSON, което осигурява последователен и удобен интерфейс за работа с API.

Пълна информация за всяка крайна точка, включително примери за заявки и отговори, ще намерите в нашата документация в Swagger.

Формат на отговора

Всички крайни точки връщат данни в стандартизиран формат със следните обекти:

{
  "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 изброява описанията на грешките. При Bad Request ще получите имената на полетата, които не са преминали валидирането.

Integration 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 от собствения си онлайн магазин или платформа, прикачвайте необходимите файлове за печат и следете всеки артикул по пътя му през изпълнението.

За да създадете поръчка чрез Fabrixa Integration API, изпратете POST заявка към https://api.fabrixa.com/v2/integration/orders. Тялото на заявката трябва да съдържа:

Структура на тялото на заявката

Примерна заявка

{
  "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 заявка към https://api.fabrixa.com/v2/integration/orders/{order_id}, където {order_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 заявка без тяло към https://api.fabrixa.com/v2/integration/orders/{order_id}/cancel, където {order_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 (краен) - пратката е отменена.

За да получите статуса на изпълнение на конкретна поръчка, изпратете GET заявка към https://api.fabrixa.com/v2/integration/orders/{order_id}/fulfillments. Отговорът съдържа списък с изпълненията, свързани с поръчката, включително статуса на всеки артикул, данни за продукта и напредъка по производствените етапи.

Примерен отговор

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

Отговорът включва списък с изпълнения, всяко от които съдържа:

Всеки запис за изпълнение съответства на конкретен продукт или вариант на продукт в поръчката, като всеки екземпляр на продукта в поръчката има собствен запис – всеки артикул се проследява поотделно през цялото производство.

Ако за поръчката не се връщат изпълнения, тя все още не е преминала към етапа на обработка.

Когато включвате изходни файлове в поръчката си, уверете се, че те отговарят на следните изисквания:

"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. Така клиентите ви могат да персонализират продукти директно на сайта ви по време на поръчката.

Примерен 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 – уникален ключ за удостоверяване пред Integration API.
• product_sku – SKU на варианта на продукта, получен от Integration API.
• cart_item_key – уникална стойност от платформата, в която е вградено Studio, която идентифицира артикула в количката, свързан с продукта. Използва се за запазване на персонализациите на потребителя; при създаване на поръчката по нея се намират запазените персонализации и се присвояват на поръчката. Вижте примера по-долу.
• 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 осигурява комуникация между различни източници (cross-origin) между iframe и родителския му прозорец, като позволява на 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;" />

Fabrixa използва уебхуци, за да уведомява вашата система за събития в реално време – създаване или актуализиране на поръчки. Когато настъпи събитие, Fabrixa изпраща уебхук до вашия сървър със съответната информация. Вашият сървър трябва да предоставя публична POST крайна точка за обработка на входящите уебхуци.

Заявката на уебхука съдържа следните заглавки, които ви помагат да идентифицирате и валидирате входящата заявка:

{
  "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); ако крайната ви точка филтрира автоматизиран трафик, разрешете го. За да сте сигурни, че заявката идва от Fabrixa, проверявайте x-webhook-signature.

Уебхуците на Fabrixa уведомяват вашата система за промени в статуса или активността на поръчките. Всеки уебхук се задейства от конкретна стойност на x-webhook-topic. Поддържани в момента теми:

Пример за съдържанието (payload), изпращано с уебхука. Това съдържание представя актуализация на поръчка:

{
  "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} връща същото поле.

За да се уверите, че заявката на уебхука е автентична и непроменена, проверете заглавката x-webhook-signature. За целта изчислете отново подписа HMAC-SHA256 от необработеното тяло на заявката и вашия таен ключ, след което го сравнете с получения подпис.

Пример на чист 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 за сравняване на подписи, за да се предпазите от атаки по времето за изпълнение (timing attacks).

По подразбиране уебхуците се деактивират след 10 неуспешни опита за доставка. Ако крайната ви точка върне неуспешен статус, например 404 или която и да е грешка 5xx, уебхукът ще бъде изпращан повторно – общо до 10 пъти. Ако крайната точка продължи да връща код, различен от 2xx или 3xx, уебхукът ще бъде деактивиран. Успешни отговори са:

• 2xx – показва успешна обработка, напр. 200 OK.
• 301 и 302 – отговори с пренасочване, които показват, че уебхукът е обработен успешно или е препратен.

Силно препоръчваме крайната ви точка да връща код на състоянието 200 OK възможно най-бързо, за да потвърди успешното получаване на уебхука. Въпреки че всеки отговор 2xx или 3xx се счита за успешен, 200 е най-често използваният и най-надеждният.

За да избегнете изтичане на времето за доставка или повторни опити, върнете 200 OK веднага и обработете съдържанието на уебхука асинхронно, например чрез фонова задача или опашка. Ако крайната ви точка отговаря твърде бавно, доставката може да се счита за неуспешна, дори ако в крайна сметка отговорът е успешен.

Отговорите с кодове на състоянието в диапазона 4xx или 5xx, както и изтичането на времето за изчакване, задействат повторни опити съгласно механизма за повторни опити.