Щоб користуватися 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, загальну кількість запитів, дозволену за хвилину.

Створюйте замовлення у 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": "0647185332"
  },
  "shipping_address": {
    "address": "Pierre cuypershof",
    "address2": "17",
    "city": "Amsterdam",
    "country_code": "NL",
    "country": "Netherlands",
    "postal_code": "1012 AB",
    "state": "North Holland",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "0647185332"
  },
  "shipping_label": {
    "method_name": "Post NL",
    "tracking_number": "3SYZXG1585577",
    "tracking_url": "https://postnl.nl/tracktrace/3SYZXG1585577",
    "label_pdf_url": "https://api.fabrixa.com/storage/8966630826422f36d822f91680012141.pdf",
    "date_created": "2024-01-01 00:00:00"
  }
}

Щоб отримати 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 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 – унікальне значення з платформи вбудовування, що ідентифікує позицію кошика, пов’язану з продуктом. Використовується для збереження налаштувань користувача; під час створення замовлення він визначає збережені налаштування та призначає їх до замовлення. Див. приклад нижче.

Запит на створення замовлення за допомогою 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",
  "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 – активується, коли оновлюється існуюче замовлення.

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

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

• Завершено – замовлення надіслано або отримано, а отримання підтверджено. Для цифрових продуктів клієнт оплатив і файли доступні для завантаження.
• Скасовано - клієнт скасував платіж; транзакція не була завершена.
• На утриманні - замовлення тимчасово заблоковано.
• Імпортовано - замовлення імпортовано на платформу.

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

• Невиконано – замовлення ще не підготовлено й не надіслано.
• Частково виконано – деякі позиції оброблено або відправлено, інші ще очікують на розгляд.
• Заплановано – замовлення заплановане та заплановано для обробки.
• Відхилено – запит на виконання відхилено, часто через недійсні деталі замовлення або недоступність.
• Виконано - замовлення повністю оброблено та доставлено або надано клієнту.

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

{
  "id": 23069,
  "number": "1250211835",
  "comments": null,
  "is_archived": false,
  "status": "imported",
  "fulfillment_status": "unfulfilled",
  "purchased_at": "2025-04-17T16:17:21.000000Z",
  "created_at": "2025-04-17T16:17:23.000000Z",
  "updated_at": "2025-04-18T07:43:52.000000Z",
  "rows": [
    {
      "id": 27954,
      "quantity": 1,
      "client_barcode": "1250211835",
      "fulfillment_status": "unfulfilled",
      "variant": {
        "id": 293457,
        "name": "Sherpa fleece deken",
        "subtitle": "100x150",
        "SKU": "SFD787231",
        "product": {
          "id": 5319,
          "name": "Sherpa fleece deken",
          "subtitle": "Sherpa fleece deken"
        }
      },
      "sources": [
        {
          "type": "print",
          "url": "https://storage.googleapis.com/fabrixa-api/storage/99b10aaa-df4d-47e4-9bc9-b1d6a785df4c/orders/merchandise-sources/120002795400.pdf",
          "properties": {
            "fill_style": "contain"
          }
        }
      ]
    }
  ]
}

Щоб переконатися, що 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 або тайм-аути ініціюють повторні спроби відповідно до механізму повторних спроб.