A8AA8A Receiver Reliability
API

API

Опис основних endpoint-ів, flow інтеграції і параметрів.

Загальний підхід

API побудоване навколо двох сценаріїв: lookup по телефону і contribution-передача shipment events.

Auth і онбординг

  • POST /api/v1/partner/auth/register
  • POST /api/v1/partner/auth/login
  • GET /api/v1/partner/me
  • POST /api/v1/partner/auth/change-password

Основні partner API операції

  • POST /api/v1/partner/receivers:check
  • POST /api/v1/partner/shipments:ingest
  • POST /api/v1/partner/shipments/finalize
  • POST /api/v1/partner/imports/csv
  • POST /api/v1/partner/tokens
  • POST /api/v1/partner/tokens/:tokenId/revoke

Кабінет і sync

  • GET /api/v1/partner/dashboard
  • POST /api/v1/partner/np-connection
  • POST /api/v1/partner/np-sync
  • GET /api/v1/partner/sync-runs/:syncRunId/events

Lookup відповідь

Lookup повертає canonicalPhone, score, totalShipments, receivedCount, refusedCount, returnedCount, easyReturnCount, storageExpiredCount, canceledCount, awaitingPickupCount, inTransitCount, unknownCount і lastNegativeEventAt.

Auth і онбординг

POST/api/v1/partner/auth/register

Self-registration партнера: назва компанії, відповідальна особа, email, пароль, тариф, акцепт оферти і приватності.

Параметри: companyName, companyCode?, fullName, email, password, tariffCode, acceptContract, acceptPrivacy
POST/api/v1/partner/auth/login

Вхід партнера в кабінет і отримання partner_session токена.

Параметри: email, password
GET/api/v1/partner/me

Поточний користувач партнера та його організація.

Параметри: Bearer partner_session
POST/api/v1/partner/auth/change-password

Зміна пароля верифікованого партнера.

Параметри: currentPassword, newPassword

Основні partner API операції

POST/api/v1/partner/receivers:check

Lookup по телефону. Повертає score і лічильники по історії одержувача.

Параметри: phone
POST/api/v1/partner/shipments:ingest

Передача нових відправлень у базу: телефон, ТТН, ПІБ і початковий статус за потреби.

Параметри: items[].ttn, items[].phone, items[].fullName, shipmentCreatedAt?, rawStatus?, rawStatusCode?, rawSubstatus?, isEasyReturn?, sourceNote?
POST/api/v1/partner/shipments/finalize

Передача фінального статусу ТТН. Саме тут нараховуються contribution credits.

Параметри: items[].ttn, phone?, fullName?, rawStatus, rawStatusCode?, rawSubstatus?, isEasyReturn?, sourceNote?
POST/api/v1/partner/imports/csv

Історичний CSV-імпорт попередніх відправлень партнера.

Параметри: fileName?, content
POST/api/v1/partner/tokens

Створення окремого partner_api токена для сервер-сервер інтеграції.

Параметри: label, expiresAt?
POST/api/v1/partner/tokens/:tokenId/revoke

Відкликання створеного partner_api токена.

Параметри: tokenId

Операції кабінету і sync

GET/api/v1/partner/dashboard

Дані кабінету партнера: тариф, токени, останні sync runs, billing, ledger.

Параметри: Bearer partner_session
POST/api/v1/partner/np-connection

Збереження ключа НП у кабінеті партнера, якщо партнер вирішить його підключити.

Параметри: apiKey
POST/api/v1/partner/np-sync

Ручний sync вибраних ТТН або останніх відправок.

Параметри: limit? або ttns[]
GET/api/v1/partner/sync-runs/:syncRunId/events

Сирі події останньої синхронізації для відладки статусів.

Параметри: syncRunId, limit?

Що повертає lookup

У відповіді на lookup партнер отримує: `canonicalPhone`, `score`, `totalShipments`, `receivedCount`, `refusedCount`, `returnedCount`, `easyReturnCount`, `storageExpiredCount`, `canceledCount`, `awaitingPickupCount`, `inTransitCount`, `unknownCount` і `lastNegativeEventAt`.

Що важливо для contribution

Для якісного внеску в спільну базу нам потрібні реальні shipment events. Мінімум - `phone + ttn`. Бажано також передавати `fullName`, а фіналізувати ТТН через окремий endpoint з фінальним статусом доставки. Саме це відкриває механіку безкоштовних перевірок.

Версія публічного API-опису: 2026-03-25-v1