Файли заказів через API

Виробник (або мережа, що працює через виробника) надсилає дистрибʼютору замовлення файлом — так, як вивантажує їх зі своєї облікової системи. ApexSFA сам розпізнає формат файлу, створює з кожного документа файлу заявку, а коли менеджер дистрибʼютора опрацював усі заявки файлу, готує файл-відповідь зі станом кожного документа: «Опрацьовано», «Редаговано», «Відхилено» або «Помилка».

Увесь обмін — чотири виклики:

Базова адреса — https://api.apexsfa.com/api/v1. Ті самі файли можна класти й через SFTP — див. 5. SFTP.

4.1. Життєвий цикл файлу

POST ──▶ received ──┬──▶ failed      жоден шаблон не розпізнав файл або не створено жодної заявки
                    └──▶ parsed ───▶ completed   усі заявки опрацьовані, файл-відповідь готовий

Як заявка проходить шлях усередині ApexSFA:

1. Кожен документ файлу стає окремою заявкою.
2. Якщо точку доставки й усі товари документа впізнано — заявка одразу стає «Новою» і чекає на менеджера.
3. Якщо якийсь товар не впізнано — заявка зберігається чернеткою з позначкою «Неповні дані»; менеджер добирає номенклатуру вручну.
4. Якщо точку не впізнано — заявка створюється чернеткою зі статусом «Потребує обробки»; менеджер підставляє точку вручну (вибір запамʼятовується для наступних файлів).
5. Якщо в документі взагалі немає коду точки доставки — заявка не створюється, документ отримує стан «Помилка».
6. Менеджер погоджує, редагує або відхиляє заявки.
7. Щойно опрацьовані всі заявки файлу — status стає completed і генерується файл-відповідь.

Примітка. Стан файлу оновлюється в момент вашого запиту GET. Вебхука про готовність файл-відповіді немає — використовуйте опитування, див. 4.11.

4.2. Автентифікація

Заголовок Authorization: Bearer asfa_… — API-токен, який видає команда ApexSFA на запит дистрибʼютора, див. 2.1.

Один токен — один виробник. Кожен токен бачить лише файли, завантажені цим самим токеном (GET чужого файлу → 404). Токен привʼязаний до виробника в довіднику дистрибʼютора, тому:

• спершу пробується шаблон розбору, вказаний у картці цього виробника;
• заявки привʼязуються до цього виробника (склад відвантаження — з його картки);
• реквізити постачальника у файлі не обовʼязкові.

4.3. POST /api/v1/exchange/order-files — покласти файл

Файл можна передати двома способами.

A. multipart/form-data, поле file:

curl -X POST "https://api.apexsfa.com/api/v1/exchange/order-files" \
  -H "Authorization: Bearer $APEX_TOKEN" \
  -F "file=@orders_2026-10-27.xml"

import os, requests

resp = requests.post(
    "https://api.apexsfa.com/api/v1/exchange/order-files",
    headers={"Authorization": f"Bearer {os.environ['APEX_TOKEN']}"},
    files={"file": ("orders_2026-10-27.xml", open("orders_2026-10-27.xml", "rb"), "application/xml")},
    timeout=120,
)
batch = resp.json()
print(resp.status_code, batch["id"], batch["status"], batch["duplicate"])

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("orders_2026-10-27.xml")]), "orders_2026-10-27.xml");
const resp = await fetch("https://api.apexsfa.com/api/v1/exchange/order-files", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.APEX_TOKEN}` },
  body: form,
});
const batch = await resp.json();
console.log(resp.status, batch.id, batch.status, batch.duplicate);

B. Сире тіло запиту (будь-який Content-Type, крім multipart/form-data), імʼя файлу — у query-параметрі filename:

curl -X POST "https://api.apexsfa.com/api/v1/exchange/order-files?filename=orders_2026-10-27.json" \
  -H "Authorization: Bearer $APEX_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@orders_2026-10-27.json"

Імʼя файлу й Content-Type не впливають на вибір шаблону — формат визначається за вмістом (див. 4.7). Імʼя файлу видно менеджеру й використовується в назві файлу-відповіді.

Відповідь 201 Created (і для нового файлу, і для повтору того самого файлу — див. duplicate):

{
  "id": "3f2a9c1e-7b4d-4e2a-9f10-5c6d7e8f9a01",
  "filename": "orders_2026-10-27.xml",
  "template": "<ключ шаблону>",
  "status": "parsed",
  "error": null,
  "documents": 1,
  "orders_created": 1,
  "duplicates_skipped": 0,
  "unmatched_lines": 0,
  "response_ready": false,
  "uploaded_at": "2026-10-27T07:21:43.512345+00:00",
  "duplicate": false
}

Файл, який не вдалося розпізнати, теж повертає 201, але зі status: "failed" і поясненням у error («Файл не розпізнано жодним шаблоном розбору (…)»).

Поля відповіді (спільні для всіх ендпоінтів статусу)

4.4. GET /api/v1/exchange/order-files — статуси своїх файлів

Повертає останні 100 файлів, завантажених цим токеном через API, від найновіших: {"data": [ … ]} з полями з 4.3 (без duplicate). Пагінації й фільтрів немає. Файли, покладені через SFTP, у цьому списку не зʼявляються.

4.5. GET /api/v1/exchange/order-files/{id} — статус одного файлу

Відповідь — один обʼєкт з полями з 4.3 (без duplicate), не загорнутий у data.

4.6. GET /api/v1/exchange/order-files/{id}/response — забрати файл-відповідь

curl -OJ "https://api.apexsfa.com/api/v1/exchange/order-files/3f2a9c1e-7b4d-4e2a-9f10-5c6d7e8f9a01/response" \
  -H "Authorization: Bearer $APEX_TOKEN"

resp = requests.get(
    f"https://api.apexsfa.com/api/v1/exchange/order-files/{batch_id}/response",
    headers={"Authorization": f"Bearer {os.environ['APEX_TOKEN']}"}, timeout=60,
)
if resp.status_code == 200:
    open(f"response_{batch_id}", "wb").write(resp.content)
elif resp.status_code == 409:
    print("ще не всі заявки опрацьовані")

const r = await fetch(`https://api.apexsfa.com/api/v1/exchange/order-files/${batchId}/response`, {
  headers: { Authorization: `Bearer ${process.env.APEX_TOKEN}` },
});
if (r.status === 200) await writeFile(`response_${batchId}`, Buffer.from(await r.arrayBuffer()));
else if (r.status === 409) console.log("ще не всі заявки опрацьовані");

Content-Type відповіді: application/xml для XML, application/json для JSON, text/csv для CSV. Файл-відповідь генерується один раз — у момент переходу в completed — і далі віддається той самий; забирати його можна скільки завгодно разів.

4.7. Формати файлів

Шаблон визначається автоматично за вмістом: ApexSFA по черзі пробує всі шаблони, перший, що розпізнав файл, виграє. Шаблон із картки виробника пробується першим.

Excel (xlsx) та інші формати не підтримуються — такий файл отримає status: "failed". Потрібен свій формат — напишіть нам.

Загальні правила для всіх форматів

• Числа: допускаються і крапка, і кома як десятковий роздільник; пробіли (зокрема нерозривні) усередині чисел ігноруються: 1 191,6, 1191.6 — коректні.
• Коди, штрихкоди, GLN, ЄДРПОУ порівнюються без пробілів: 4 820 000 900 017 = 4820000900017.
• Дати: YYYY-MM-DD, DD.MM.YYYY, YYYY-MM-DDTHH:MM:SS, DD.MM.YYYY HH:MM:SS. Береться лише календарна дата, час відкидається. Дата з суфіксом поясу (…Z, +02:00) не розпізнається.
• Логічні значення: Истина / Да / true / Так → так; Ложь / Нет / false / Ні → ні.
• Рядок товару без коду товару або без кількості пропускається.

4.7.1. XML «Заказы»

Структура: Заказы / Документы / Документ[] / Строки / Строка[]. Корінь — саме <Заказы> без простору імен. Зайві теги ігноруються (у файлі-відповіді зберігаються). Приклад: examples/order-file-example.xml.

Документ (Заказы/Документы/Документ):

* потрібен хоча б один із Идентификатор / Номер; рекомендовано обидва, ключ — не довший за 64 символи.

Рядок (Документ/Строки/Строка):

Блок Документ/Итоги/ВсегоСтрок у файлі-відповіді оновлюється, якщо рядки змінено.

4.7.2. CSV за номером документа

Один рядок файлу = одна позиція документа; шапка документа повторюється в кожному рядку. Колонки шукаються за назвою в шапці (порядок довільний, зайві колонки ігноруються). Приклад: examples/order-file-example.csv (Windows-1251).

** потрібна хоча б одна з колонок коду точки.

Увага. Файли цього формату надсилайте у кодуванні Windows-1251. Роздільник — ;, лапки CSV не обробляються (крапку з комою всередині значень використовувати не можна).

4.7.3. CSV поставки

Одна поставка містить багато замовлень мережі; рядок = позиція накладної. Документ (заявка) = група рядків з однаковим НомерЗамовлення. Кількість заявки — місця (ящики), цін у файлі немає.

Чи потрібна файл-відповідь для цього формату, узгоджуємо під час підключення.

4.7.4. JSON «Замовлення» / «Накладные»

Корінь — JSON-обʼєкт з масивом Замовлення (новіший варіант) або Накладные. Кожен елемент — документ, масив Товары — рядки. Значення можна передавати рядками (числа — з крапкою). Приклад: examples/order-file-example.json.

* документ без Ссылка і без Номер пропускається. ** потрібен хоча б один із КодТочкиGLN / АдресДоставки.

4.7.5. Як шукаються точка, контрагент і товар

Точка доставки (код з файлу, без пробілів) — по черзі: відповідність, яку раніше вручну обрав менеджер; коди мереж у картці точки дистрибʼютора; GLN і коди точок доставки; код точки дистрибʼютора. Якщо у файлі визначено контрагента-покупця, точка приймається лише якщо вона належить цьому контрагенту — тому передавайте ЄДРПОУ покупця.

Товар — по черзі: код рядка в кодах і артикулах каталогу дистрибʼютора (крім JSON-формату, де код — ваш власний); штрихкод одиниці або упаковки; артикули рядка в кодах товарів дистрибʼютора. Ручний вибір менеджера запамʼятовується — наступні файли з тими самими кодами розпізнаються автоматично.

4.8. Файл-відповідь

Файл-відповідь — це ваш вихідний файл, до якого для кожного документа додано стан. Формат і кодування — того самого формату.

Для документа-дубля (див. 4.9) стан береться з раніше створеної заявки.

• XML — у кожен <Документ> додається тег <Состояние>. Для «Редаговано» <Строки> приводяться до фактичної заявки: видалені позиції прибираються, Количество змінюється, суми перераховуються, Итоги/ВсегоСтрок оновлюється. Позиції, які менеджер додав, у файл не дописуються. Приклад: examples/order-file-response-example.xml.
• JSON (UTF-8 з BOM) — у кожен документ додається ключ "Состояние" перед "Товары"; для «Редаговано» масив Товары і СуммаДокумента приводяться до фактичної заявки. Приклад: examples/order-file-response-example.json.
• CSV (Windows-1251, рядки через CRLF) — до шапки додається колонка Состояние, до кожного рядка — стан його документа; рядки не переписуються. Приклад: examples/order-file-response-example.csv.

4.9. Ідемпотентність і повтори

1. Той самий файл (байт у байт). Якщо такий файл уже приймали, POST повертає 201 з наявним файлом і "duplicate": true; нових заявок немає. Тому повторна відправка після мережевої помилки чи таймауту безпечна. Файл, що раніше отримав failed, при повторі обробляється заново (новий id).

2. Той самий документ у новому файлі. Ключ — пара (ключ документа, дата документа), де ключ документа — Идентификатор/Ссылка, а якщо їх немає — Номер (НомерДокумента, НомерЗамовлення для CSV). Якщо за таким документом уже є заявка (не скасована й не відхилена), нову не створюємо: документ рахується в duplicates_skipped і у файлі-відповіді отримає стан раніше створеної заявки.

• Виправлений документ надсилайте з новим номером/ідентифікатором або іншою датою. Змінити замовлення повторною відправкою не можна.
• Тримайте ключ документа не довшим за 64 символи.

Файл, у якому всі документи — дублі, не вважається помилкою: status: "parsed" (а потім completed), orders_created: 0, error: "Нових замовлень немає: усі N документів уже завантажували раніше".

4.10. Помилки й ліміти

Помилки вмісту файлу (не розпізнано, немає точки, не впізнано товар) — це не HTTP-помилки: файл приймається з кодом 201, а проблеми видно в status, error, unmatched_lines і згодом — у стані документів у файлі-відповіді.

4.11. Рекомендований сценарій опитування

1. POST файл → збережіть id. Якщо duplicate: true — файл уже був, працюйте з поверненим id. Якщо status: "failed" — виправте файл і надішліть знову.
2. Раз на 5–15 хвилин викликайте GET /exchange/order-files (один запит покриває до 100 файлів) і шукайте файли з response_ready: true, які ви ще не забрали.
3. Для кожного такого файлу — GET /exchange/order-files/{id}/response, збережіть файл-відповідь, позначте у себе як забраний.
4. Файли у parsed довше доби — сигнал зʼясувати в менеджера дистрибʼютора (часто це документи «без точки» або з нерозпізнаними товарами).

Опрацювання заявок — ручна робота менеджера, тож файл-відповідь зазвичай зʼявляється за години. Частіше ніж раз на хвилину опитувати немає сенсу.

4.12. Часові пояси

• Дати у файлі — календарні дати без поясу; час, якщо вказаний, відкидається.
• Дата документа з файлу не стає датою заявки чи датою доставки: заявка отримує власну дату створення, а ДатаПоставки/ДатаОтгрузки зберігаються довідково.
• uploaded_at — ISO 8601, UTC.

4.13. Часті питання

Чи можна надіслати кілька документів в одному файлі? Так — кожен стане окремою заявкою.

Файл прийнято (201), але заявок немає. Дивіться status і error: failed — формат не розпізнано; duplicates_skipped > 0 — документи вже завантажували раніше.

Що означає unmatched_lines > 0? Частину товарів не знайдено в каталозі дистрибʼютора. Заявки з ними — чернетки, менеджер добере товари вручну. Щоб уникнути — передавайте штрихкоди й артикули.

Як змінити або скасувати вже надіслане замовлення? Через API — ніяк. Зверніться до менеджера дистрибʼютора.

Файл-відповідь повертає 409 уже кілька днів. Менеджер ще не опрацював усі заявки файлу.

Чи змінюється файл-відповідь після генерації? Ні — вона генерується один раз, коли опрацьовано останню заявку.

Чи можна класти файли на SFTP замість API? Так — див. 5. SFTP.