Обмін з обліковою системою

Цей розділ описує, як облікова система дистрибʼютора обмінюється даними з ApexSFA: як передати в ApexSFA довідники, залишки, продажі й борги і як забрати з ApexSFA заявки торгових, оплати, приходи, інвентаризації, заявки на обладнання та рейси.

• Базовий URL: https://api.apexsfa.com/api/v1
• Формат: JSON, UTF-8, Content-Type: application/json, лише POST.
• Автентифікація — підпис запиту ключем обміну (див. 2.2).

Примітка. Шляхи містять технічний сегмент /webhooks/1c/ — це назва каналу в API, змінювати його не треба. Він однаковий для будь-якої облікової системи.

Не хочете програмувати обмін? Для облікових систем BAS і сумісних є готова обробка обміну.

3.1. Модель обміну

Обидва напрямки ініціює облікова система — їй не потрібна публічна адреса, вистачить вихідного HTTPS:

  Облікова система                                        ApexSFA
  ────────────────                                        ───────
  довідники, ціни, залишки,   ── inbound/batch ──▶   записує в тенант
  продажі, борги, каса, рейси

  заявки, оплати, приходи,    ◀── outbox/pull ───   черга документів
  інвентаризації, рейси       ─── outbox/ack ───▶   позначка «синхронізовано»

Тенант в обміні

Кожна точка синхронізації (філія компанії, яка веде свою базу обліку) — окремий тенант ApexSFA зі своїм tenant_id і своїм ключем обміну. Усе, що надіслано з ключем тенанта, лягає в цей тенант; коди філій у payload конвертів (branch_external_id тощо) не впливають на те, куди лягають дані. Черга документів для забору теж одна на тенант — її забирає одна база обліку.

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

Кожен запит до /api/v1/webhooks/1c/* містить:

v2 = lowercase_hex( SHA256( "<t>" + "." + <тіло запиту як є, байти UTF-8> + "." + <ключ обміну> ) )
X-Signature: t=<t>,v2=<v2>

Повний опис, приклади на трьох мовах і контрольний приклад — у 2.2.

Коли повертається 401

Відповідь 401 з тілом {"error": {"code": "INVALID_CREDENTIALS", "message": "...", "details": [], "request_id": "..."}}:

3.3. Облікова система → ApexSFA: конверти

Усі дані з облікової системи передаються конвертами:

Типи сутностей коротко:

• довідники: branch, warehouse, supplier, supplier_point, price_type, manufacturer, product_category, product, product_external_code, counterparty, client (торгова точка), agent (торговий), client_assignment, driver, vehicle, transport_list, equipment_type, equipment_unit, manufacturer_price_type, manufacturer_payment_term;
• ціни й залишки: price_list_item, product_stock, product_stock_snapshot, wms_stock, stock_document, excise_marks;
• продажі, борги, каса: sale, goods_document, goods_period, debt_document, debt_reset, cash_document, cash_balance, cash_period, order_state, order_state_period;
• логістика й рейси: trip, logistics_order, logistics_manufacturer, logistics_own_manufacturer, logistics_counterparty, logistics_point, logistics_warehouse, logistics_product_category, logistics_product, logistics_product_code, logistics_stock.

POST /api/v1/webhooks/1c/inbound/batch

Пакет конвертів — основний спосіб передачі.

Порядок конвертів у пакеті має значення: обробка йде послідовно, тому довідники-«батьки» ставте раніше за залежні записи (див. порядок первинного завантаження).

Порада. Завжди надсилайте дані через /inbound/batch з partial: true — так кожен рядок отримує власний результат, а збій одного не зупиняє інші.

Відповідь 200:

{
  "data": {
    "accepted_count": 2,
    "failed_count": 1,
    "results": [
      {"index": 0, "entity_type": "warehouse", "external_id": "8d3b4c5e-6f70-11ee-9a0b-0050569a1b2c",
       "accepted": true, "entity_id": "0192e004-5555-7ccc-8ddd-4c5d6e7f8091", "operation_performed": "upsert",
       "error": null, "details": null},
      {"index": 1, "entity_type": "client", "external_id": "5b1f2c3d-4e5f-11ee-9a0b-0050569a1b2c",
       "accepted": true, "entity_id": "0192e001-2222-7ccc-8ddd-1e2f3a4b5c6d", "operation_performed": "upsert",
       "error": null, "details": null},
      {"index": 2, "entity_type": "supplier_point", "external_id": "00000000-0000-0000-0000-000000000000",
       "accepted": false, "entity_id": null, "operation_performed": null,
       "error": "Supplier … not found — push the supplier first", "details": null}
    ]
  }
}

Помилка окремого конверта в режимі partial=true не змінює HTTP-код: відповідь лишається 200, перевіряйте failed_count і results[].accepted.

POST /api/v1/webhooks/1c/inbound

Один конверт. Тіло — сам конверт (+ необовʼязковий tenant_id):

{"entity_type": "warehouse", "operation": "upsert", "external_id": "8d3b4c5e-6f70-11ee-9a0b-0050569a1b2c",
 "payload": {"name": "Склад Основний"}}

Відповідь 200: {"data": {"accepted": true, "entity_id": "…", "operation_performed": "upsert", "details": null}}. Відповідь 422 — конверт відхилено (запис не знайдено, порушено бізнес-правило): {"error": {"accepted": false, "error": "…"}}.

Порядок первинного завантаження

Під час першого підключення передавайте дані в такому порядку:

1. Філія, склади, постачальники (+ їхні точки), типи цін.
2. Групи номенклатури, виробники, номенклатура.
3. Контрагенти, торгові, точки, привʼязки точок до торгових, обладнання, ціни.
4. Залишки.
5. Продажі, борги, рухи товару, каса.
6. Рейси.

Деталі за кожною сутністю — у 3a.

3.4. ApexSFA → облікова система: pull і ack

Документи, які мають потрапити в облікову систему, ApexSFA кладе в чергу тенанта. Облікова система за розкладом (рекомендовано кожні 5–15 хв):

1. викликає outbox/pull і отримує пачку елементів;
2. створює або оновлює документи в себе;
3. викликає outbox/ack з результатом по кожному елементу;
4. якщо has_more = true — повторює з кроку 1.

POST /api/v1/webhooks/1c/outbox/pull

Відповідь 200 (повний приклад — examples/exchange-outbox-pull-response.json):

{
  "data": {
    "items": [
      {
        "queue_id": "0192f3a1-7c2e-7b10-9a4d-5e6f7a8b9c01",
        "entity_type": "order",
        "entity_id": "0192f3a0-1111-7aaa-8bbb-0c0d0e0f1a2b",
        "operation": "create",
        "attempt": 1,
        "payload": {"order_number": "ORD-20261027-0042", "...": "..."}
      }
    ],
    "has_more": false
  }
}

Порядок видачі: за пріоритетом, потім від старіших до новіших.

Повторна видача. Виданий елемент закріплюється за вашою обліковою системою до ack. Якщо ack не прийшов протягом 5 хвилин, елемент знову потрапляє у видачу (attempt зростає).

Увага. Ідемпотентність на вашому боці обовʼязкова. Той самий queue_id (і той самий документ) може прийти повторно — якщо ack загубився, запізнився понад 5 хв або ви отримали відповідь pull, але впали до ack. Шукайте вже створений документ за ключем з payload (order_number, payment_number, arrival_id, request_id, trip_number/external_id) і не створюйте дубль; у ack відповідайте ok з тим самим external_id. Якщо ви вже відповідали на елемент помилкою — на повтор відповідайте тією самою помилкою.

operation:

Примітка. Якщо pull повернув 200, а ви не змогли обробити відповідь (обрив звʼязку) — нічого робити не треба: елементи повернуться у видачу через 5 хв.

Помилки: 401 — див. 3.2; 429 — зробіть паузу 5–60 с. Тримайте batch_size у межах 1..100, а results в ack — 1..200.

POST /api/v1/webhooks/1c/outbox/ack

Приклад тіла — examples/exchange-outbox-ack-request.json.

{
  "results": [
    {"queue_id": "0192f3a1-7c2e-7b10-9a4d-5e6f7a8b9c01", "status": "ok", "external_id": "d18f9a01-b2c3-11ee-9a0b-0050569a1b2c"},
    {"queue_id": "0192f3a1-7c2e-7b10-9a4d-5e6f7a8b9c02", "status": "error", "error_message": "Не знайдено точку", "permanent": false}
  ]
}

Відповідь 200: {"data": {"acked": 2, "synced": 1, "retrying": 1, "failed": 0, "not_found": 0}}

Відповідь завжди 200, навіть якщо частина результатів — помилки; дивіться лічильники.

Що відбувається після ack:

• ok → елемент «доставлено»; документ у ApexSFA отримує позначку синхронізації й ваш external_id. Для заявки з кабінету покупця (B2B) перший ok — це підтвердження: покупець отримує повідомлення «Підтверджено».
• error без permanent → повтор за розкладом (60 с, 5 хв, 30 хв, 2 год, далі 12 год); після вичерпання спроб (6) — стан «помилка», далі елементом займається оператор на порталі.
• error з permanent=true → стан «помилка», оператор бачить ваш текст.
• Повторний ack для вже доставленого елемента — безпечний.

3.5. Що лежить у черзі: payload за типами

Загальні правила:

• Суми, кількості, ціни, ставки ПДВ — рядки з десятковою крапкою ("1250.00"). Виняток — у delivery_trip вага, сума й відстань — числа.
• *_code_1c, *_external_id, external_id_1c — ідентифікатори (GUID) обʼєктів облікової системи, які раніше прийшли в ApexSFA конвертами. Якщо обʼєкт заведено лише в ApexSFA — null.
• Payload — знімок на момент постановки в чергу.

Заявки, що прийшли з облікової системи, назад у чергу не потрапляють.

order — заявка торгового (продаж або повернення)

Рядок lines[]:

Для operation=cancel payload має той самий формат (повний знімок заявки на момент скасування).

logistics_order — логістична заявка

Формат як у order (без manufacturers/multi_manufacturer), плюс:

Логістичні заявки зручно забирати окремим викликом pull з entity_types: ["logistics_order"].

order_payment — оплата (прибутковий касовий ордер)

arrival — прихід товару

stock_document — результат інвентаризації

equipment_request — заявка на встановлення або зняття обладнання

delivery_trip — рейс

Потрапляє в чергу, якщо для тенанта увімкнено передачу рейсів в облік і диспетчер натиснув у рейсі «Передати в облік».

cancel: {trip_id, trip_number, external_id}. Якщо рейс змінили після забору, зміна приходить окремим елементом update.

3.6. Повтори й журнал

• Облікова система → ApexSFA: сервер не повторює за вас. Відхилений конверт (accepted=false) виправте й надішліть ще раз — повтор з тим самим external_id безпечний. На 429 — повторіть пакет після Retry-After; на 5xx або обрив — повторіть пакет цілком.
• ApexSFA → облікова система: див. поведінку після ack вище.
• Журнал обміну видно на порталі (розділ «Журнал дій», фільтр «Обмін з обліковою системою»): скільки прийнято й відхилено за типами, номери забраних документів, тексти помилок.
• Якщо черга не порожня, а успішного обміну не було понад 30 хв, адміністратору приходить лист «Обмін з обліковою системою зупинився».
• На порталі можна повторно поставити заявку в чергу («Повторно в облікову систему») і передати рейс в облік.

За потреби можливий режим, коли ApexSFA сам надсилає документи на HTTPS-адресу вашої системи (push) замість pull, — узгоджується під час підключення.

3.7. Ліміти

3.8. Дати й часові пояси

У черзі (ApexSFA → облік):

• Дати без часу (order_date, requested_delivery_date, arrival_date, trip_date, inventory_date) — YYYY-MM-DD, календарна дата.
• Моменти часу (collected_at, completed_at, requested_at, approved_at) — ISO 8601 у UTC (2026-10-27T09:41:12.512000+00:00). Переводьте в локальний час на своєму боці.

У конвертах (облік → ApexSFA):

• Дати без часу — YYYY-MM-DD.
• Дата й час — завжди з явним зсувом: 2026-10-27T12:00:00+03:00 або …Z.
• Періоди date_from/date_to (у goods_period, cash_period) — від 00:00 першого до 24:00 останнього дня за київським часом.

3.9. Приклади

Надіслати пакет довідників

BASE="https://api.apexsfa.com/api/v1"
TENANT="3f2a9c1e-5b7d-4e2a-9c1f-0a1b2c3d4e5f"
SECRET="<ключ обміну>"

BODY='{"partial":true,"items":[{"entity_type":"warehouse","operation":"upsert","external_id":"8d3b4c5e-6f70-11ee-9a0b-0050569a1b2c","payload":{"name":"Склад Основний"}}]}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY.$SECRET" | sha256sum | cut -d' ' -f1)
curl -sS -X POST "$BASE/webhooks/1c/inbound/batch" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: $TENANT" \
  -H "X-Signature: t=$TS,v2=$SIG" \
  --data-binary "$BODY"

import hashlib, json, time, requests

BASE = "https://api.apexsfa.com/api/v1"
TENANT = "3f2a9c1e-5b7d-4e2a-9c1f-0a1b2c3d4e5f"
SECRET = "<ключ обміну>"

def post_signed(path: str, payload: dict) -> dict:
    body = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
    ts = int(time.time())
    sig = hashlib.sha256(f"{ts}.{body}.{SECRET}".encode()).hexdigest()
    resp = requests.post(
        f"{BASE}{path}",
        data=body.encode("utf-8"),
        headers={"Content-Type": "application/json", "X-Tenant-Id": TENANT,
                 "X-Signature": f"t={ts},v2={sig}"},
        timeout=300,
    )
    resp.raise_for_status()
    return resp.json()["data"]

result = post_signed("/webhooks/1c/inbound/batch", {"partial": True, "items": [
    {"entity_type": "warehouse", "operation": "upsert",
     "external_id": "8d3b4c5e-6f70-11ee-9a0b-0050569a1b2c", "payload": {"name": "Склад Основний"}},
]})
print(result["accepted_count"], result["failed_count"])

import { createHash } from "node:crypto";

const BASE = "https://api.apexsfa.com/api/v1";
const TENANT = "3f2a9c1e-5b7d-4e2a-9c1f-0a1b2c3d4e5f";
const SECRET = process.env.APEX_SECRET;

async function postSigned(path, payload) {
  const body = JSON.stringify(payload);
  const ts = Math.floor(Date.now() / 1000);
  const sig = createHash("sha256").update(`${ts}.${body}.${SECRET}`, "utf8").digest("hex");
  const resp = await fetch(BASE + path, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-Tenant-Id": TENANT, "X-Signature": `t=${ts},v2=${sig}` },
    body,
  });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
  return (await resp.json()).data;
}

const result = await postSigned("/webhooks/1c/inbound/batch", {
  partial: true,
  items: [{ entity_type: "warehouse", operation: "upsert",
            external_id: "8d3b4c5e-6f70-11ee-9a0b-0050569a1b2c", payload: { name: "Склад Основний" } }],
});
console.log(result.accepted_count, result.failed_count);

Забрати заявки й підтвердити

BODY="{\"batch_size\":100,\"entity_types\":[\"order\",\"order_payment\"],\"request_nonce\":\"$(uuidgen)\"}"
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY.$SECRET" | sha256sum | cut -d' ' -f1)
curl -sS -X POST "$BASE/webhooks/1c/outbox/pull" \
  -H "Content-Type: application/json" -H "X-Tenant-Id: $TENANT" \
  -H "X-Signature: t=$TS,v2=$SIG" --data-binary "$BODY"

BODY='{"results":[{"queue_id":"0192f3a1-7c2e-7b10-9a4d-5e6f7a8b9c01","status":"ok","external_id":"d18f9a01-b2c3-11ee-9a0b-0050569a1b2c"}]}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY.$SECRET" | sha256sum | cut -d' ' -f1)
curl -sS -X POST "$BASE/webhooks/1c/outbox/ack" \
  -H "Content-Type: application/json" -H "X-Tenant-Id: $TENANT" \
  -H "X-Signature: t=$TS,v2=$SIG" --data-binary "$BODY"

import uuid

while True:
    data = post_signed("/webhooks/1c/outbox/pull", {
        "batch_size": 100, "entity_types": ["order", "order_payment"],
        "request_nonce": str(uuid.uuid4()),
    })
    results = []
    for item in data["items"]:
        try:
            doc_id = create_or_find_document(item)  # ваша логіка, ідемпотентна за order_number
            results.append({"queue_id": item["queue_id"], "status": "ok", "external_id": doc_id})
        except Exception as exc:
            results.append({"queue_id": item["queue_id"], "status": "error",
                            "error_message": str(exc)[:2000]})
    if results:
        print(post_signed("/webhooks/1c/outbox/ack", {"results": results}))
    if not data["has_more"]:
        break

import { randomUUID } from "node:crypto";

for (;;) {
  const data = await postSigned("/webhooks/1c/outbox/pull", {
    batch_size: 100, entity_types: ["order", "order_payment"], request_nonce: randomUUID(),
  });
  const results = [];
  for (const item of data.items) {
    try {
      const docId = await createOrFindDocument(item); // ваша логіка, ідемпотентна за order_number
      results.push({ queue_id: item.queue_id, status: "ok", external_id: docId });
    } catch (err) {
      results.push({ queue_id: item.queue_id, status: "error", error_message: String(err).slice(0, 2000) });
    }
  }
  if (results.length) console.log(await postSigned("/webhooks/1c/outbox/ack", { results }));
  if (!data.has_more) break;
}

Використовуйте --data-binary (а не -d), щоб curl не змінив тіло після підпису. На macOS замість sha256sum — shasum -a 256. Повний мінімальний клієнт на Python — examples/exchange_client.py.