Довідник ендпоінтів
Перелік ендпоінтів API інтеграцій ApexSFA з параметрами, тілами запитів і кодами відповідей; специфікація OpenAPI.
Перелік ендпоінтів для інтеграторів. Машиночитна версія — openapi.json (імпортується в Postman, Insomnia та інші OpenAPI-інструменти). Повні описи, приклади й семантика — у тематичних розділах.
Базова адреса: https://api.apexsfa.com. Шляхи нижче — повні, з /api/v1.
Обмін з обліковою системою
Підписані запити облікової системи: прийом даних і забір документів.
Автентифікація: Підпис: X-Tenant-Id + X-Signature: t=…,v2=…. Докладно: 03-accounting-exchange.md.
| Метод | Шлях | Призначення |
|---|---|---|
POST | /api/v1/webhooks/1c/inbound | Прийняти один конверт від облікової системи |
POST | /api/v1/webhooks/1c/inbound/batch | Прийняти пакет конвертів (до 5000) |
POST | /api/v1/webhooks/1c/outbox/ack | Підтвердити обробку забраних документів |
POST | /api/v1/webhooks/1c/outbox/pull | Забрати пачку документів для облікової системи |
POST /api/v1/webhooks/1c/inbound
Прийняти один конверт від облікової системи
Тіло (application/json; charset=utf-8):
| Поле | Тип | Обовʼязкове | Обмеження |
|---|---|---|---|
entity_type | string | так | перелік — у 3a |
operation | string | так | |
external_id | string | так | мін. довж. 1; макс. довж. 50 |
payload | object | ні |
Відповіді: 200 Успіх, 401 Невірний підпис / тенант / інтеграцію вимкнено, 422 Невалідний конверт або бізнес-помилка, 429 Перевищено ліміт; Retry-After.
POST /api/v1/webhooks/1c/inbound/batch
Прийняти пакет конвертів (до 5000)
Тіло (application/json; charset=utf-8):
| Поле | Тип | Обовʼязкове | Обмеження |
|---|---|---|---|
items | AccountingInboundEnvelope[] | так | мін. ел. 1; макс. ел. 5000 |
partial | boolean | ні | за замовч. true |
Відповіді: 200 Успіх, 401 Невірний підпис / тенант / інтеграцію вимкнено, 422 Невалідний конверт або бізнес-помилка, 429 Перевищено ліміт; Retry-After.
POST /api/v1/webhooks/1c/outbox/ack
Підтвердити обробку забраних документів
Тіло (application/json; charset=utf-8):
| Поле | Тип | Обовʼязкове | Обмеження |
|---|---|---|---|
tenant_id | string (uuid) | null | ні | |
results | OutboxAckResult[] | так | мін. ел. 1; макс. ел. 200 |
Відповіді: 200 Успіх, 401 Невірний підпис / тенант / інтеграцію вимкнено, 422 Невалідний конверт або бізнес-помилка, 429 Перевищено ліміт; Retry-After.
POST /api/v1/webhooks/1c/outbox/pull
Забрати пачку документів для облікової системи
Тіло (application/json; charset=utf-8):
| Поле | Тип | Обовʼязкове | Обмеження |
|---|---|---|---|
tenant_id | string (uuid) | null | ні | |
batch_size | integer | ні | ≥ 1; ≤ 100; за замовч. 50 |
entity_types | string[] | null | ні | макс. ел. 20 |
Відповіді: 200 Успіх, 401 Невірний підпис / тенант / інтеграцію вимкнено, 422 Невалідний конверт або бізнес-помилка, 429 Перевищено ліміт; Retry-After.
Файли заказів виробника
Файли заказів через API-токен.
Автентифікація: API-токен: Authorization: Bearer asfa_…. Докладно: 04-order-files.md.
| Метод | Шлях | Призначення |
|---|---|---|
GET | /api/v1/exchange/order-files | Статуси своїх файлів |
POST | /api/v1/exchange/order-files | Покласти файл заказів |
GET | /api/v1/exchange/order-files/{batch_id} | Статус файлу |
GET | /api/v1/exchange/order-files/{batch_id}/response | Забрати файл-відповідь |
GET /api/v1/exchange/order-files
Статуси своїх файлів
Відповіді: 200.
POST /api/v1/exchange/order-files
Покласти файл заказів
| Параметр | Де | Тип | Обовʼязковий | Обмеження |
|---|---|---|---|---|
filename | query | string | ні | за замовч. "orders.xml" |
Тіло (multipart/form-data):
| Поле | Тип | Обовʼязкове | Обмеження |
|---|---|---|---|
file | string | так |
Тіло (application/octet-stream): сирі байти файлу; імʼя — у параметрі filename.
Відповіді: 201 Файл прийнято, 401 Немає/невірний токен, 403 Немає scope exchange:orders, 413 Понад 20 МБ, 422 Порожній файл, 429 Ліміт токена.
GET /api/v1/exchange/order-files/{batch_id}
Статус файлу
| Параметр | Де | Тип | Обовʼязковий | Обмеження |
|---|---|---|---|---|
batch_id | path | string (uuid) | так |
Відповіді: 200, 422 Validation Error.
GET /api/v1/exchange/order-files/{batch_id}/response
Забрати файл-відповідь
| Параметр | Де | Тип | Обовʼязковий | Обмеження |
|---|---|---|---|---|
batch_id | path | string (uuid) | так |
Відповіді: 200 Файл-відповідь (тип залежить від шаблону), 404 Файл не знайдено або належить іншому токену, 409 Ще не всі заявки файлу оброблено.
Службові
Перевірка доступності.
Автентифікація: без автентифікації. Докладно: 01-overview.md.
| Метод | Шлях | Призначення |
|---|---|---|
GET | /api/v1/health | Перевірка живості |
GET /api/v1/health
Перевірка живості
Відповіді: 200.
Схеми
Повні схеми тіл і відповідей — у openapi.json, розділ components.schemas.