РОЗРОБНИКАМ - ПОСІБНИК З ІНТЕГРАЦІЇ

Підписати за п'ятнадцять хвилин.

Покрокова інструкція з використання Fabrixa REST API: автентифікація, перелік доступних продуктів, оформити замовлення, зареєструвати веб-хук, обробити події життєвого циклу. JSON через HTTPS, автентифікація за допомогою токенів на пред'явника, недійсні запити, безпечні для повторних спроб веб-хуки. Ніяких сюрпризів.

Повне посилання на API → Завантажити колекцію "Листоноша

REST + JSON - BEARER AUTH - IDEMPOTENT - WEBHOOK-DRIVEN

ПЕРЕДУМОВИ

Що потрібно перед початком роботи.

01

API KEY

Видаються з панелі керування вашого акаунта Fabrixa. Ключ пісочниці для розробки, ключ виробництва для реальних замовлень. Обидва є токенами на пред'явника.

02

КІНЦЕВА ТОЧКА WEBHOOK

Загальнодоступна кінцева точка HTTPS на вашому боці, яка може приймати JSON POST запити. Localhost працює в розробці за допомогою інструментів тунелювання.

03

ФАЙЛИ З РОБОТАМИ

Готові до друку ілюстрації доступні за посиланням HTTPS. Adobe Illustrator, Photoshop, растровий або векторний. Ми завантажуємо файл під час виконання завдання друку.

КРОК 1 - АВТЕНТИФІКАЦІЯ

Перевірте ключ API за допомогою дзвінка привітання.

Авторизація за допомогою токенів на пред'явника. Базова URL-адреса пісочниці https://sandbox.api.fabrixa.com/v1; production змінює субдомен на інший.

GET /v1/account

# Перевірка авторизації та доступу до облікового запису
скручуватися https://sandbox.api.fabrixa.com/v1/account \
  -H "Авторизація: Пред'явник $FABRIXA_API_KEY" \
  -H "Прийняти: application/json"

# 200 OK
{
  "account_id": "acct_4fK8B2qZ",
  "навколишнє середовище": "пісочниця",
  "рівень": "виробництво",
  "webhook_url": нуль
}

401 означає, що ключ неправильний або відкликаний. Згенеруйте новий за допомогою панелі керування. A 403 означає, що ключ дійсний, але у вас немає дозволу на доступ до ресурсу (рідко зустрічається на /account).

КРОК 2 - СКЛАДІТЬ СПИСОК ПРОДУКТІВ

Відкрийте для себе SKUs, доступні для вашого облікового запису.

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

GET /v1/products

GET /v1/products?category=apparel&page=1&limit=20

# Відповідь (усічена)
{
  "дані": [
    {
      "product_id": "prod_tee_unisex_aop",
      "категорія": "apparel.tees-tops",
      "ім'я": "Футболка AOP унісекс",
      "база": "organic-cotton-160gsm",
      "розміри": ["XS","S","M","Л","XL","XXL"],
      "print": "reactive-aop",
      "production_hub": "ПТ",
      "lead_time_days": { "min": 6, "max": 9 }
    }
  ],
  "page": 1,
  "has_more": правда
}

КРОК 3 - ОФОРМИТИ ЗАМОВЛЕННЯ

Створення безсилого порядку.

Набір Idempotency-Key для кожного запиту на замовлення - безпечно повторювати один і той самий виклик без створення дублікатів замовлень. Використовуйте UUID для кожного логічного замовлення на вашому боці.

POST /v1/замовлення

НАДІСЛАТИ /v1/orders
Idempotency-Key: 8e6f4b2a-7c1d-4f3e-9a8b-1e2d3c4b5a6f

{
  "order_ref": "shopify-1042",
  "предмети": [
    {
      "product_id": "prod_tee_unisex_aop",
      "розмір": "Л",
      "кількість": 2,
      "url_твору_мистецтва": "https://cdn.yourbrand.com/art/drop-001.png"
    }
  ],
  "одержувач": {
    "ім'я": "Лєна Коста",
    "address_line1": "Руа дас Флорес 12",
    "місто": "Порту",
    "країна": "ПТ",
    "поштовий_індекс": "4050-262"
  },
  "упаковка": "біла етикетка"
}

# 201 Створено
{
  "order_id": "ord_8e6f4b2a",
  "статус": "отримано",
  "estimated_dispatch": "2026-05-15",
  "webhook_events": ["order.printed","order.dispatched"]
}

КРОК 4 - КІНЦЕВА ТОЧКА ВЕБ-ХУКА

Підпишіться на життєвий цикл замовлення.

Встановіть URL-адресу веб-хука один раз на рівні акаунта. Події життєвого циклу кожного замовлення POST на цю URL-адресу. Перевіряйте підпис HMAC перед обробкою.

PUT /v1/account/webhook

PUT /v1/account/webhook

{
  "url": "https://api.yourbrand.com/fabrixa/webhook",
  "події": [
    "order.received",
    "order.printed",
    "order.dispatched",
    "order.failed"
  ]
}

# Корисне навантаження Webhook (POST на кінцеву точку)
{
  "подія": "order.dispatched",
  "order_id": "ord_8e6f4b2a",
  "order_ref": "shopify-1042",
  "timestamp": "2026-05-15T11:32:08Z",
  "відстеження": {
    "перевізник": "DHL",
    "номер_відстеження": "JJD0123456789",
    "tracking_url": "https://dhl.com/track/JJD0123456789"
  }
}

Повне посилання на подію та перевірка підписів на сайті сторінка веб-хуків.

ОБРОБКА ПОМИЛОК ТА ОБМЕЖЕННЯ ШВИДКОСТІ

Чого очікувати, якщо щось піде не так.

ФОРМА РЕАКЦІЇ НА ПОМИЛКУ

Помилки - це JSON, а не HTML.

Реакція на помилку

{
  "помилка": {
    "код": "artwork_unreachable",
    "повідомлення": "GET on artwork_url failed (timeout 30s)",
    "request_id": "req_94kQ7r2L",
    "повторна спроба": правда
  }
}

Коди - це стабільні рядки, які безпечно вмикати. retryable: true означає, що можна повторити спробу з тим самим ключем idempotency.

ОБМЕЖЕННЯ ПО ТАРИФАМ

Розсувне вікно, заголовки показують бюджет.

Пісочниця: 60 запитів/хв за клавішу
Виробництво: 600 у.о./хв за ключ (підвищується за запитом)
Заголовки: X-RateLimit-Remaining, X-RateLimit-Reset
429 відповідь про надлишок з Повторна спроба після секунди
Доставка за допомогою Webhook не враховується у вашому бюджеті на вхідні дзвінки

ЗАСТРЯГ?

Поговоріть з інженером з розробки рішень.

Для інтеграційної підтримки, проблем з пісочницею, індивідуальними вимогами або плануванням потужностей технічний канал SE, а не відділ продажів. Середня відповідь протягом одного робочого дня.

Зв'язатися з інженером з рішень Завантажити колекцію "Листоноша

Посібник з інтеграції