Огляд, формат і ліміти

ApexSFA — хмарна система для дистрибʼюторів: заявки торгових з мобільного застосунку, склад і WMS, логістика, продажі, B2B-кабінет. Інтеграції потрібні, щоб ApexSFA працювала разом з обліковою системою дистрибʼютора, з виробниками й постачальниками та з вашими CRM і BI.

1.1. Які є інтеграції

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

1.2. Середовища

Перевірка доступності: GET /api/v1/health → {"status":"ok"}.

curl -s https://api.apexsfa.com/api/v1/health
# {"status":"ok"}

1.3. Формат

• Протокол — лише HTTPS.
• Кодування — UTF-8. Тіла запитів і відповідей — JSON (Content-Type: application/json), крім файлів заказів (розділ 4).
• Ідентифікатори обʼєктів ApexSFA — UUID (рядок).
• Ваші ідентифікатори (external_id) — рядки до 50 символів; рекомендуємо GUID обʼєкта з вашої системи (36 символів).
• Ціни, кількості, суми сервер приймає числом або рядком; у відповідях суми приходять рядком ("1250.00") — не перетворюйте їх у float, якщо важлива точність.
• Дата й час у відповідях — ISO 8601 з часовим поясом (UTC, 2026-10-27T08:15:00+00:00). Дати без часу — YYYY-MM-DD.

Стандартна обгортка відповіді

{
  "data": { "...": "..." },
  "meta": { "request_id": null, "timestamp": "2026-10-27T10:15:00.123456" }
}

Ендпоінти файлів заказів (розділ 4) повертають «плоский» обʼєкт або {"data": [...]}; ендпоінти обміну з обліковою системою — {"data": {...}}.

Помилки

Усі помилки повертаються в єдиному форматі:

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Bearer API token required",
    "details": [],
    "request_id": "req_3ef16c7613ef48e0b78dfa8d"
  }
}

request_id дублюється в заголовку відповіді X-Request-Id — указуйте його, коли звертаєтесь у підтримку. Можна передати власний X-Request-Id у запиті — сервер поверне його ж (зручно для наскрізного логування).

Орієнтуйтеся насамперед на HTTP-статус, а code і message використовуйте для діагностики.

Порада. Повторювати запит має сенс лише для 429, 5xx і мережевих помилок — з паузою, що зростає (наприклад, 5 с → 30 с → 2 хв). 4xx (крім 429) без виправлення запиту повторювати не треба.

1.4. Ліміти

1.5. Версіонування

Версія API — у шляху: /api/v1. У межах v1 зміни лише сумісні: можуть додаватися нові ендпоінти, нові необовʼязкові поля запиту й нові поля відповіді. Ваш клієнт має ігнорувати невідомі поля у відповідях. Несумісні зміни можливі лише в новій версії шляху (/api/v2) — з попереднім повідомленням.

1.6. Тенант і точка синхронізації

Тенант — ізольований простір даних однієї компанії-клієнта ApexSFA. Компанія-дистрибʼютор може складатися з кількох тенантів: кожна філія з окремою базою облікової системи — окрема точка синхронізації зі своїм тенантом і своїм ключем обміну. Усе, що надходить із ключем точки, потрапляє лише в цю точку; усе, що облікова система забирає з ApexSFA, — лише документи цієї точки.

• Ідентифікатор тенанта (Tenant Id, UUID) потрібен для обміну з обліковою системою (заголовок X-Tenant-Id).
• API-токени (asfa_…) самі визначають тенант — передавати його не треба.
• Дані різних тенантів суворо ізольовані.

1.7. Як отримати доступ

1. Залиште запит «Запросити доступ» на apexsfa.com/developers або напишіть на hello@apexsfa.com: яка інтеграція потрібна, для якої компанії, хто інтегратор.
2. Для обміну з обліковою системою ви отримаєте Tenant Id і ключ обміну.
3. Для файлів заказів через API — API-токен asfa_…, привʼязаний до виробника. Токен показується один раз — збережіть його в сховищі секретів.
4. Для SFTP обліковку виробника створює дистрибʼютор на порталі ApexSFA і передає виробнику логін, адресу сервера, порт, відбиток ключа сервера й приватний ключ.
5. Для вебхуків — передайте нам URL-приймач і перелік подій; ми видамо секрет підпису.

Рекомендований порядок: тестове середовище → перевірка сценаріїв → прод.