SAPI-SK для розробників

Що таке SAPI-SK

SAPI-SK є національним REST-інтерфейсом між клієнтською системою (ERP, інтернет-магазин, бухгалтерське програмне забезпечення) і Access Point. Мета в єдиному, незалежному від постачальника способі надсилати та отримувати документи через «цифрового листоношу», замість пропрієтарного API кожного постачальника. Підтримку SAPI-SK тому сприймайте як страховку від прив’язки до постачальника (vendor lock-in).

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

Використовується OAuth2 client_credentials. На порталі ви створюєте API-токен: його UUID слугує як client_id, а значення vpt_… як client_secret. Через POST /sapi/auth/token отримуєте короткостроковий access token і refresh token; access token потім надсилаєте в заголовку Authorization: Bearer …. Скасування API-токена на порталі негайно робить недійсними і видані токени.

Надсилання та отримання

• Надсилання: POST /sapi/document/send із заголовком X-Peppol-Participant-Id (учасник, ВІД ІМЕНІ якого надсилаєте: ваша компанія або клієнт під вашим токеном; одержувач вказується в метаданих документа) і Idempotency-Key (безпечне повторення без дублікатів). Масово через POST /sapi/document/batch (до 100 документів на виклик).
• Стан доставки: GET /sapi/document/sent повертає стани надісланих документів (pending → delivered / rejected із квитанції MLS, або undeliverable, коли одержувач не має адреси в мережі Peppol), з ?since= для інкрементного завантаження.
• Отримання: GET /sapi/document/receive (посторінковий перегляд, фільтр за станом) і підтвердження опрацювання через acknowledge.
• Докази та повідомлення ФА (від 1.8.14): кожен документ несе об’єкт fsReport (reported / pending / not_required із причиною, id повідомлення та вердикт C5), надіслані також statusReason і xmlSha256; стан до 200 документів одразу через POST /sapi/document/sent/status, хронологія через GET /sapi/document/sent/{id}/events. Вебхуки несуть fsReport і нові події invoice.report_pending та invoice.report_rejected.
• Стан токена / оновлення / скасування: окремі кінцеві точки під /sapi/auth/*.

Sandbox та ідемпотентність

Контракт можете випробувати в sandbox без ризику реальної доставки: sandbox валідує запити і повертає mock-відповіді. Під час надсилання завжди використовуйте Idempotency-Key: при повторенні того самого запиту (напр. після тайм-ауту) не виникне дублікат документа. Ключ виведіть із чогось сталого для рахунку (напр. ID або номер рахунку у вашій системі); новий ключ для того самого рахунку обійде цей захист. Якщо документ відхилила наша перевірка перед відправленням (напр. помилка валідації), до мережі нічого не пішло і нічого не повідомляється Фінансовій адміністрації: виправте його і надішліть знову з тим самим ключем, з датою виставлення за днем, коли він справді піде. Доставлений рахунок повторно не надсилається, виправляється кредит-нотою або дебет-нотою. Помилкам запобіжите через POST /sapi/document/validate (перевірить документ без надсилання) і GET /sapi/discovery (чи є одержувач у мережі Peppol).

Де знайдете деталі

Повний перелік кінцевих точок, приклади запитів/відповідей і коди помилок є в нашій технічній документації (розділ SAPI-SK), включно з машиночитною специфікацією OpenAPI 3.1. Радимо починати в sandbox і лише потім переходити на продакшн.