Для розробників: довідник API

API Verteco це REST поверх HTTPS. Запит і відповідь мають формат JSON (UTF-8). Почніть зі створення облікового запису, потім API-токена, і зробіть перший виклик протягом хвилини. Усі шляхи вказано відносно базової URL-адреси нижче.

Повне тестове середовище (sandbox) доступне на test.peppol.verteco.digital. Воно поводиться так само, як продуктивне середовище, і додатково пропонує тестові інструменти (вебхук Фінансової адміністрації Словаччини (Finančná správa, FS), верифікаційний токен (Verifikačný údaj), видалення компанії) та симульований вибір постачальника замість порталу FS (VPDS).

Base URL

https://peppol.verteco.digital/api/v1

Версія

v1 (у шляху). Зворотно несумісні зміни виходитимуть під новою версією.

Протокол

HTTPS only · TLS 1.2+ · TLS A+

Формат

application/json (UTF-8)

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

cookie-сесія (портал) або Bearer-токен (server-to-server)

Часові мітки

ISO-8601 (UTC), напр. 2026-06-03T09:40:27Z

Обліковий запис і API-токен Ви створюєте в порталі (через браузер). Далі інтеграція працює виключно через API-токен. Вашому застосунку не потрібно обробляти реєстрацію, вхід чи паролі.

1. 1

   Створіть обліковий запис у порталі

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

   Згенеруйте API-токен

   У порталі перейдіть до API tokeny → Vytvoriť (API-токени → Створити). Токен vpt_… показується лише один раз. Зберігайте його надійно.
3. 3

   Зробіть перший виклик

   Використайте токен у заголовку Authorization:

   javascriptKopírovať

   const res = await fetch('https://peppol.verteco.digital/api/v1/companies', {
   headers: { Authorization: 'Bearer vpt_8f2a…' },
   });
   const companies = await res.json();

4. 4

   Вибір постачальника на порталі Фінансової адміністрації

   У продуктивному середовищі вибір Verteco на порталі FS (vpds.financnasprava.sk) потрібен навіть для суто відправлення: він розблоковує відправлення (верифікаційний токен) і активує компанію. Отримання при цьому може лишитися в постачальника вашої бухгалтерської програми: у мережі компанія має рівно одного отримувача, але може мати кілька відправників.

export BASE=https://test.peppol.verteco.digital   # production: https://peppol.verteco.digital
export KEY=vpt_…        # step 1

Окрім SAPI mock sandbox (нижче), ми також підтримуємо повнофункціональне тестове середовище, повну копію цього порталу з окремими даними, де можна випробувати весь процес (реєстрація → компанія → відправлення → отримання → сповіщення) від початку до кінця без жодного впливу на продуктивне середовище.

URL

https://test.peppol.verteco.digital

Реєстрація

без листа з підтвердженням; обліковий запис можна використовувати одразу

Схвалення компанії

автоматичне, безпосередньо в інтерфейсі або через API; немає вибору постачальника на порталі Фінансової адміністрації Словаччини (Finančná správa, FS) і немає входу на портал ФА; одразу після створення компанії з номером платника ПДВ (IČ DPH) Ви можете як відправляти, так і отримувати

Реєстрація в мережі

автоматична, до тестової мережі Peppol. Зверніть увагу на два рівні ідентифікатора: API і портал використовують той самий формат, що й продуктивне середовище (peppolParticipantId = 0245:<цифри DIČ>, де DIČ це словацький податковий ідентифікаційний номер; Ваш інтеграційний код не змінюється); у тестових SMP/SML компанія технічно реєструється як 9950:SK<DIČ>, оскільки схема 0245 вимагає верифікаційного коду Фінансової адміністрації, якого в тестовому середовищі не існує. У продуктивному середовищі 0245:<цифри DIČ> реєструється в робочій мережі Peppol лише після вибору постачальника на порталі ФА (вхід через eID або за обліковими даними)

Валідація

реальна: правила EN 16931 + Peppol BIS 3.0, ті самі, що й у продуктивному середовищі

Доставка

реальна, через тестову мережу Peppol (AS4, тестовий сертифікат, тестові SML/SMP): отримувач, зареєстрований у тестовій мережі, отримує рахунок як отриманий (включно з електронним листом, PDF і вебхуком); у робочу мережу нічого не потрапляє

Підтвердження доставки (MLS)

реальне підтвердження MLS з тестової мережі

Електронні листи

справді надсилаються (на адреси, які Ви вводите), з префіксом [TEST]

Симуляція помилок

заголовок X-Sandbox-Simulate: 503 (або 502, 500, 429) на будь-якому виклику /sapi/document/* з дійсним токеном повертає відповідну помилку; нічого не обробляється й не зберігається. Для 500 (SAPI-PROC-500) і 429 (SAPI-SYS-003 з Retry-After) ви отримаєте конверт помилки SAPI; 503 і 502 проходять через мережевий периметр (DigitalOcean, Cloudflare) як HTTP 504 з HTML-тілом без конверта, саме так виглядає справжній збій ззовні, тож ви перевірите й обробку відповіді, що не є JSON. Помилки валідації викликає недійсний XML, 429 також перевищення 300 викликів за хвилину. У продуктивному середовищі заголовок ігнорується

Ціна

безкоштовно, без обмежень для тестування

Усе, що працює тут, працює і там: портал, REST API, SAPI-SK 1.0, плагіни для інтернет-магазинів і вебхуки. Достатньо змінити домен у Вашій інтеграції на test.peppol.verteco.digital і використовувати токени, створені в тестовому середовищі. Ідеально для розробки інтеграції, CI-тестів і навчання бухгалтерів перед продуктивним запуском. Тестові документи належать лише туди: у продуктивному середовищі кожен внутрішній документ між платниками ПДВ звітується Фінансовій адміністрації, і звіт не можна відкликати. У продуктивному порталі пробуйте лише кнопкою „Poslať skúšobnú faktúru“ (надіслати тестовий рахунок, 0,00 €); з 1. 1. 2027 продуктивне середовище відхиляє номери TEST-/VITAJTE- (test_document_in_production).

Примітка: захист периметра (edge) тестового домену блокує загальні заголовки User-Agent: Python-urllib і User-Agent: Java/1.8.x (стандартний User-Agent HttpsURLConnection у Java 8) відповіддю HTTP 403 "error code: 1010" ще до того, як запит дійде до нашого API; продуктивний домен peppol.verteco.digitalїх пропускає. Встановіть власний User-Agent: у Java або прапорцем JVM -Dhttp.agent=my-app/1.0 (без зміни коду; Java додає "Java/1.8", і результат "my-app/1.0 Java/1.8.0_xxx" проходить, блокується лише заголовок, що починається з "Java/1.8"), або на з'єднанні через conn.setRequestProperty("User-Agent", "my-app/1.0"). Поширені клієнти (requests, httpx, Java 11+, Apache HttpClient, okhttp, axios, Go, PHP, curl) працюють без змін.

Чому компанії схвалюються автоматично

Фінансова адміністрація не має тестового середовища для порталу VPDS: вибір постачальника на vpds.financnasprava.sk працює лише в продуктивному середовищі та перевіряється входом на портал ФА (eID або облікові дані порталу), тому в продуктивному середовищі Ви не можете «обрати» довільну компанію, яка не є Вашою. Щоб Ви все ж могли протестувати свою інтеграцію, у тестовому середовищі ми симулюємо цей крок: кожна створена Вами компанія схвалюється автоматично (без вибору у FS), тож Ви можете налаштувати як відправника, так і отримувача та пройти весь процес.

Для тестування вебхуків FS (вибір постачальника) ми маємо власний аналог інструменту Фінансової адміністрації: test.peppol.verteco.digital/sandbox-nastroje. Там можна згенерувати валідний верифікаційний токен (Verifikačný údaj) у стилі FS і надіслати повний вебхук на Ваш endpoint, точно так, як це робить портал FS під час реального вибору. Компанії, створені для тестування, натомість можна зняти з реєстрації (з порталу та з тестового SMP), саме через відсутність тестового режиму на боці Фінансової адміністрації.

Ваша інтеграція автентифікується за допомогою API-токена в заголовку Authorization: Bearer vpt_…. Токен Ви створюєте в порталі (API-токени); він має формат vpt_ + 40 hex-символів, ми зберігаємо лише його SHA-256 хеш, і він має той самий доступ, що і Ваш обліковий запис. Перевірте його через /auth/me:

curl https://peppol.verteco.digital/api/v1/auth/me -H 'Authorization: Bearer vpt_8f2a…'
# 200 → { "id": "…", "email": "vy(at)firma.sk" }   (token works)

Якщо токен відсутній або недійсний, API повертає:

// 401 Unauthorized
{ "error": "unauthorized", "message": "Authentication required" }

Пагінація та ідемпотентність

• Контракт лише зростає: нові поля (пропущені, коли null), нові необов’язкові параметри, нові кінцеві точки та події. Наявні назви полів, значення enum і коди статусів не змінюються.
• Нове значення enum або подія вебхука можуть з’явитися будь-коли; ігноруйте невідоме і відповідайте на невідому подію 2xx.
• Часові мітки у форматі ISO 8601 UTC зі змінною кількістю дробових цифр; розбирайте їх, ніколи не порівнюйте як текст. Суми надходять рядками з двома десятковими знаками.
• Якщо зміна не може бути адитивною, ми оголошуємо її в changelog (є підписка e-mail) щонайменше за 90 днів і зберігаємо стару форму на перехідний період.
• Модель безпеки API-ключа (з 3 жовтня 2026): ключ читає і надсилає документи, керує компаніями, сповіщеннями та вебхуками. Керування обліковим записом і ключами (створення, обмеження або відкликання ключа, MFA, пароль, сесії, запрошення, передача компанії, підписання договорів) виконує лише авторизована особа; ключ отримує там 403 token_not_allowed. GET /api/v1/tokens лишається доступним для ключа.
• Версія контракту — info.version в openapi.json, і кожна зміна має рядок у changelog з тегом API або Webhooks.

/changelog · /changelog/odber · openapi.json

Помилки мають єдину структуру з машинозчитуваним кодом error. Помилки валідації додають мапу fields (перша помилка для кожного поля).

// business error
{ "error": "invalid_credentials", "message": "Invalid email or password" }

// validation error (400); field messages are returned in Slovak ("IČO musí byť 8 číslic" = "IČO must be 8 digits")
{ "error": "validation_failed", "message": "Some fields are invalid",
"fields": { "ico": "IČO musí byť 8 číslic" } }

HTTP-статуси

200 / 201 / 204

успіх (OK / Created / No Content)

400

недійсні вхідні дані (див. error / fields)

401

відсутня або недійсна автентифікація

403

недостатньо прав (роль)

404

ресурс не існує або Ви не маєте до нього доступу

405

HTTP-метод не підтримується для цього шляху

409

конфлікт (IČO / електронна адреса вже існує)

415

непідтримуваний Content-Type (XML endpoint-и очікують application/xml)

429

перевищено ліміт запитів (заголовки RateLimit-* і Retry-After, тіло JSON rate_limited)

Найчастіші коди помилок

Збій точки доступу та повторні спроби

• Якщо API відповідає 502, 503 або 504, або не відповідає взагалі, документ ми не прийняли: повторіть виклик пізніше з тим самим Idempotency-Key, нічого не буде надіслано двічі.
• Документ, який API прийняв (202 ACCEPTED, також із retrying: true), після відновлення вийде сам: точка доступу повторює доставку, стан видно через GET /sapi/document/sent або вебхук; якщо вона зрештою відмовиться, документ завершиться як невдалий, і той самий ключ надішле його знову.
• Отримання на рівні мережі не залежить від порталу: доставку, яка не пройшла під час збою порталу, відправна точка доступу повторює за правилами Peppol, і документ з'явиться в порталі після відновлення. Звіти Фінансовій адміністрації, що не вийшли через збій, доповнює автоматичний відновлювальний запуск (транспортний збій повторюється, змістовна відмова ні).
• Стан та історія доступності на /status; у тестовому середовищі збій можна зімітувати заголовком X-Sandbox-Simulate (розділ Тестове середовище).

API захищене обмеженням частоти запитів у 60-секундному вікні (на інстанс). Ліміт і залишок квоти повертаються в кожній відповіді через заголовки; при перевищенні API повертає 429 Too Many Requests із Retry-After.

Звичайні виклики

динамічний ліміт із великим запасом, на API-токен (або сесію, інакше IP); поточне значення повертається в заголовку RateLimit-Limit

Auth (/auth/*)

суворіший ліміт на IP (захист від brute-force; крім /auth/me і /auth/logout)

RateLimit-Limit

ліміт у вікні

RateLimit-Remaining

скільки запитів залишилося

RateLimit-Reset

секунд до скидання вікна

Retry-After

секунд до наступної спроби (при 429)

HTTP/2 429 Too Many Requests
RateLimit-Limit: <limit in the window>
RateLimit-Remaining: 0
RateLimit-Reset: 37
Retry-After: 37

{ "error": "rate_limited", "message": "Too many requests. Slow down." }

HTTP/2 200
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41
RateLimit-Policy: 300;w=60

Непрозорі (opaque) токени vpt_… для доступу server-to-server. Відкритий текст показується лише один раз при створенні. Збережіть його. Ми зберігаємо лише SHA-256 хеш і 12-символьний префікс для відображення.

curl -X POST https://peppol.verteco.digital/api/v1/tokens -b cookies.txt \
-H 'Content-Type: application/json' -d '{"name":"moja-appka"}'
# 201 Created
{ "id":"…","name":"moja-appka","token":"vpt_8f2a…","prefix":"vpt_8f2a3b…","createdAt":"…" }

Компанії, ідентифіковані за реєстраційним номером (IČO) / номером платника ПДВ (IČ DPH), якими Ви керуєте. Доступ залежить від членства: Ви бачите лише компанії, учасником яких є. Творець компанії стає її owner.

curl -X POST https://peppol.verteco.digital/api/v1/companies \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"ico":"53412834","dic":"SK2121358349","legalName":"Verteco digital services, s. r. o."}'

# 201 Created
{ "id":"08dd…","ico":"53412834","dic":"SK2121358349","legalName":"…",
"registeredAddress":null,"peppolParticipantId":null,
"status":"pending_verification","role":"owner","createdAt":"2026-06-03T09:40:27Z" }

Поле status

pending_verification

після створення; відправлення ще не розблоковано

active

верифікована, відправлення розблоковано

Роль учасника

owner

творець компанії (повний доступ)

admin

адміністратор (редагування, вебхуки, верифікація)

member

учасник (читання)

viewer

лише читання

Перед відправленням компанію необхідно верифікувати за допомогою верифікаційного токена (Verifikačný údaj, VÚ), підписаного токена, який видає Фінансова адміністрація Словаччини (Finančná správa, FS). Після успішної верифікації status компанії змінюється на active і відправлення розблоковується.

curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/verification \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"token":"<1024-hex VÚ>"}'

# 200 OK
{ "companyId":"08dd…","status":"active","sendingVerified":true,
"verificationMethod":"self","verifiedAt":"2026-06-15T…Z" }

Журнал документів Peppol (отриманих і відправлених) для компанії. Він наповнюється в міру того, як рахунки проходять через Access Point. Залежить від членства в компанії, відсортовано за createdAt за спаданням.

curl 'https://peppol.verteco.digital/api/v1/companies/{id}/documents?direction=received' \
-H 'Authorization: Bearer vpt_8f2a…'
# 200 OK
[ { "id":"…","direction":"received","peppolMessageId":"…","docTypeId":"…",
  "senderId":"0088:7300010000001","receiverId":"0245:2121358349",
  "invoiceNumber":"2026001","issueDate":"2026-06-03",
  "currency":"EUR","totalAmount":120.00,"status":"received","createdAt":"…" } ]

SAPI-SK це стандартизований національний REST-інтерфейс між клієнтською/ERP-системою та Access Point (sapi-sk.sk). Ми реалізуємо його повністю. Це означає, що Ви не залежите від нашої пропрієтарної форми API і пишете інтеграцію один раз для будь-якого SAPI-SK Access Point.

Base URL

https://peppol.verteco.digital/sapi

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

OAuth2 client_credentials → короткостроковий access-токен (JWT)

client_id

UUID Вашого API-токена (наведений у розділі API-токени / dashboard)

client_secret

сам токен vpt_… з порталу

Версія

1.3 (10 операцій: 4× auth, 6× документи)

Sandbox (пробне середовище)

Хочете випробувати SAPI-SK без реєстрації і без жодного ризику? Використайте публічні облікові дані sandbox. Sandbox валідує запити точно так, як продуктивне середовище, але ніколи нічого не надсилає в мережу Peppol і не працює з реальними даними; він повертає реалістичні mock-відповіді. Ідеально для розробки, CI та онбордингу інтеграції.

client_id

sandbox

client_secret

sandbox

send

повна валідація контракту + mock 202 (ніщо не доставляється)

receive

1 зразковий документ sandbox-doc-0001 для тестування парсингу та acknowledge

# 1) sandbox token (no registration required)
curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "sandbox", "client_secret": "sandbox",
      "grant_type": "client_credentials" }'

# 2) mock send: it is validated, but NOTHING is actually delivered
curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer <sandbox access_token>' \
-H 'X-Peppol-Participant-Id: 0245:0000000000' \
-H 'Content-Type: application/json' \
-d '{ "metadata": { "documentId": "TEST-1",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "senderParticipantId": "0088:sandbox-sender",
        "receiverParticipantId": "0088:sandbox-receiver" },
      "payload": "<Invoice>…</Invoice>", "payloadFormat": "XML" }'
# 202 { "providerDocumentId": "sandbox-…", "status": "ACCEPTED", … }

# 3) sample inbox + detail of the sample document
curl https://peppol.verteco.digital/sapi/document/receive \
-H 'Authorization: Bearer <sandbox access_token>'
curl https://peppol.verteco.digital/sapi/document/receive/sandbox-doc-0001 \
-H 'Authorization: Bearer <sandbox access_token>'

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

curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "<token UUID>", "client_secret": "vpt_8f2a…",
      "grant_type": "client_credentials" }'
# 200 OK
{ "access_token": "eyJhbGciOi…", "token_type": "Bearer",
"expires_in": 900, "refresh_token": "eyJhbGciOi…" }

// body
{ "refresh_token": "eyJhbGciOi…" }

Відправлення документа

curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer eyJ…' \
-H 'X-Peppol-Participant-Id: 0245:2121358349' \
-H 'Idempotency-Key: 7b1f0e2a-…' \
-H 'Content-Type: application/json' \
-d '{ "metadata": {
        "documentId": "INV-2026-001",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "processId": "urn:…:bis:billing:3.0",
        "senderParticipantId": "0245:2121358349",
        "receiverParticipantId": "0088:7300010000001",
        "creationDateTime": "2026-06-17T10:00:00Z" },
      "payload": "<Invoice …>…</Invoice>",
      "payloadFormat": "XML" }'
# 202 Accepted
{ "providerDocumentId": "…", "status": "ACCEPTED",
"receivedAt": "2026-06-17T10:00:01Z", "timestamp": "…" }
# when status is "REJECTED", the response also carries a "detail" field
# with the rejection reason (validation rules, e.g. BR-CO-15)

curl -X POST https://peppol.verteco.digital/sapi/document/validate \
-H 'Authorization: Bearer eyJ…' \
-H 'Content-Type: application/xml' \
--data-binary @rakhunok.xml
# 200 OK
{ "valid": false,
  "errors": [ "BR-CO-15: Invoice total amount with VAT (BT-112) = … " ],
  "warnings": [],
  "checkedAt": "2026-09-10T12:00:00Z" }

Отримання документів

// 200 OK
{ "documents": [ { "documentId":"…","documentTypeId":"…",
  "senderParticipantId":"0088:…","receiverParticipantId":"0245:…",
  "creationDateTime":"2026-06-17T…Z" } ],
"nextPageToken": "50" }

Стан відправлених документів

// 200 OK
{ "documents": [ {
  "documentId": "…",
  "receiverParticipantId": "0245:1084695645",
  "peppolMessageId": "befc9112-…",
  "status": "delivered",
  "statusDateTime": "2026-07-09T14:52:31Z",
  "creationDateTime": "2026-07-09T14:52:12Z" } ],
"nextPageToken": null }

Підтвердження MLS і докази доставки

Підтвердження MLS (Peppol Message Level Status) є відповіддю Access Point отримувача на нашу передачу: AP = прийнято й доставлено, AB = доставлено без ділового підтвердження, RE = відхилено з причиною. Портал зберігає його разом із відправленим документом і за ним змінює стан: AP і AB обидва означають delivered (при AB statusDetail починається з «MLS AB: », а mls.responseCode дорівнює AB; за SPOG on MLS це доставка без ділового підтвердження, а не застереження), RE означає rejected. Згідно з § 76a абз. 2 літ. d закону 222/2004 провайдер повинен довести дату й час відправлення, доставки та отримання; кожний рядок GET /sapi/document/sent і кожний webhook несуть ці три часи: sentAt (передача службі доставки, чим за § 85o абз. 11 виконано обов'язок виставника), deliveredAt (підтвердження Access Point отримувача через MLS) і fsReportedAt (звіт до фінансового управління). Іноземний Access Point може ніколи не надіслати MLS: документ тоді залишається delivered з деталлю as4_receipt_only і без підтвердження.

// 200 OK
{ "document": {
    "documentId": "…", "peppolMessageId": "befc9112-…", "status": "delivered",
    "sentAt": "2026-09-17T08:00:12Z", "deliveredAt": "2026-09-17T08:00:31Z", "fsReportedAt": null,
    "hasMls": true,
    "links": { "detail": "…/sapi/document/sent/…", "mls": "…/sapi/document/sent/…/mls" } },
  "mls": { "responseCode": "AP", "receivedAt": "2026-09-17T08:00:31Z", "url": "…/sapi/document/sent/…/mls" } }

Докази звіту ФС, цілісність і хронологія (SAPI 1.8.14)

Від версії 1.8.14 кожен рядок GET /sapi/document/sent, деталі відправленого та список і деталі отриманих документів містять об'єкт fsReport: state = reported (звіт передано до пункту збору C5, reportedAt = fsReportedAt), pending (звіт ще належить подати, передача не вдалася і повторюється автоматично, reason = c5_unavailable) або not_required (звіт не виникає; reason пояснює чому: cross_border, self_send_test, issuer_without_vat_id, recipient_without_vat_id, not_billing_document, tdd_disabled, before_2026_09_01, not_recorded). Після передачі з'являється tddMessageId (SBDH InstanceIdentifier звіту), після відповіді C5 c5ResponseCode (AP/AB/RE), c5ResponseAt, c5Detail і підсумок outcome: accepted (AP), accepted_with_reservations (AB), rejected (RE) або null, поки C5 не відповіло. outcome = rejected означає, що звіт передано, але фінансове управління його відхилило (c5Detail містить порушене правило, напр. BR-AE-08); state залишається reported, бо передача відбулася, і портал автоматично надсилає виправлений звіт повторно (після прийняття outcome стає accepted). Відправлені рядки додатково мають statusReason (машинний код за statusDetail: network_retrying, network_retrying_sent, as4_receipt_only, recipient_not_registered, transport_failed, mls_rejected, validation_failed), xmlSha256 (SHA-256 переданого XML, зберігається й після видалення вмісту), retention і receiptRetention = permanent (підтвердження MLS ніколи не видаляється). Підтвердження в деталях має mls.sha256 і mls.messageId. Отримані документи отримали peppolMessageId, status (received/acknowledged), receivedAt, acknowledgedAt і xmlSha256 (SHA-256 байтів бізнес-документа саме таких, як їх видає links.xml, без транспортної обгортки SBDH; обчислюється при отриманні і зберігається після видалення вмісту). Обидва списки фільтруються через ?fsReport=reported|pending|not_required|rejected (rejected = outcome rejected), відправлені також через ?status=undeliverable. Відповідь POST /sapi/document/send містить peppolMessageId уже при прийнятті. Усе додано як нові поля, наявні поля не змінилися.

// POST { "documentIds": ["7c1e…", "9af0…", "невідоме"] }  (max 200)
{ "documents": [ {
    "documentId": "7c1e…", "status": "delivered", "statusReason": null, "peppolMessageId": "befc9112-…",
    "sentAt": "2026-09-21T08:00:12Z", "deliveredAt": "2026-09-21T08:00:31Z", "fsReportedAt": "2026-09-21T08:05:40Z",
    "fsReport": { "state": "reported", "reportedAt": "2026-09-21T08:05:40Z", "reason": null, "outcome": "accepted",
                  "tddMessageId": "3f2a…", "c5ResponseCode": "AP", "c5ResponseAt": "2026-09-21T08:06:02Z", "c5Detail": null },
    "xmlSha256": "9b74…", "retention": { "mode": "storage", "contentAvailableUntil": null }, "receiptRetention": "permanent",
    "hasMls": true, "links": { "detail": "…", "mls": "…" },
    "mls": { "responseCode": "AP", "receivedAt": "2026-09-21T08:00:31Z", "url": "…", "sha256": "e1c0…", "messageId": "mls-…" } } ],
  "missing": ["9af0…", "невідоме"] }

Пакетне відправлення

// request
{ "documents": [ {
  "itemId": "fa-2026-001",
  "idempotencyKey": "fa-2026-001",
  "metadata": { "documentId": "2026001", "documentTypeId": "…", "processId": "…",
                "senderParticipantId": "0245:2121358349", "receiverParticipantId": "0245:1084695645" },
  "payload": "<Invoice …>", "payloadFormat": "XML" } ] }

// 202 Accepted
{ "total": 2, "accepted": 1, "rejected": 1, "failed": 0,
"results": [
  { "itemId": "fa-2026-001", "ok": true,  "providerDocumentId": "…", "status": "ACCEPTED" },
  { "itemId": "fa-2026-002", "ok": false, "errorCode": "SAPI-AUTH-003", "errorMessage": "…" } ] }

Модель помилок

Усі помилки SAPI мають єдину обгортку з категорією, стабільним кодом, прапорцем retryable і correlation_id для служби підтримки. У разі помилки автентифікації (SAPI-AUTH-001) обгортка додатково містить hint (зрозуміле пояснення, що саме належить до Client Id і Client Secret) та docs (посилання на інструкцію; програми MK-soft спрямовуються одразу на /navody/mksoft#prepojenie). Обидва поля необов'язкові й відсутні в інших випадках (1.8.20).

{ "error": {
  "category": "AUTH",
  "code": "SAPI-AUTH-001",
  "message": "Invalid client credentials.",
  "retryable": false,
  "correlation_id": "b4191dfc-…" } }

Про отриманий рахунок ми можемо повідомити компанію електронною поштою або вебхуком (POST на Вашу URL-адресу). Доставка надійна (durable): сповіщення зберігається у вихідній черзі та доставляється асинхронно (тайм-аут 15 с); у разі збою ми повторюємо до 12 разів з експоненційною затримкою (30 с → макс. 8 год, загалом близько 16 годин), потім dead-letter. HTTP 401/403 означає, що Ваш endpoint вимагає автентифікації, якої ми не надсилаємо; натомість перевіряйте підпис webhook-signature і відповідайте 2xx. Отже, збій Вашого сервера не втрачає сповіщення; ми доставимо його при наступній спробі. Захист від SSRF блокує loopback/локальні адреси; URL вебхука має бути публічною.

curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/webhook \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"url":"https://vas-system.sk/peppol/webhook"}'
# 200 OK { "url":"https://vas-system.sk/peppol/webhook", "hasSecret": true }

// 200 OK
{ "secret": "vpt_8f2a…" }

// 200 OK
{
"sent":     { "url": "https://vas-system.sk/peppol/webhook", "event": "webhook.test",
              "signed": true, "payload": "{…}" },
"received": { "status": 200, "body": "OK", "durationMs": 142, "error": null }
}
// 400 webhook_not_configured if no webhook URL is stored

Payload вебхука

Як для отриманого (invoice.received), так і для відправленого (invoice.sent) рахунка ми надсилаємо POST із таким тілом; поле event розрізняє тип.

Ще дві події повідомляють про вердикт мережі щодо відправленого Вами рахунка: invoice.delivered (Access Point отримувача підтвердив доставку підтвердженням доставки (MLS)) і invoice.rejected (відхилено, або мережею, або під час валідації перед відправленням); invoice.undeliverable повідомляє про одержувача без запису в мережі Peppol (прийнято, повідомлено FS, не доставлено). Вони містять ідентифікацію документа та компанії (documentId, invoiceNumber, receiverId, peppolMessageId, companyDic, peppolParticipantId), а також status, statusDetail із причиною відхилення та statusDateTime. Якщо перша спроба доставки не вдалася і точка доступу сама її повторює (зазвичай протягом години), документ залишається submitted, а statusDetail починається з префікса network_retrying: ; після доставки стан стає delivered, після відмови rejected з префіксом network_gave_up: . Завдяки їм Вам не потрібно опитувати стан відправлених рахунків.

Подія company.activated надходить, коли клієнт завершує вибір постачальника на порталі (VPDS) Фінансової адміністрації Словаччини (Finančná správa, FS); тіло: event, companyId, companyDic, peppolParticipantId, status, verifiedAt. company.deactivated натомість надходить, коли компанію знімають з реєстрації в мережі (те саме тіло без verifiedAt). company.smp_registered_elsewhere надходить, коли компанія завершила вибір на порталі ФА, але її запис у національному SMP тримає інший провайдер (тіло як у company.activated плюс action: "migration_code_required" і migrateUrl). Порядок дій для партнерів наведено в документації для посередників. Доки клієнт не введе код міграції, мережа доставляє старому провайдеру. Докладніше в посібнику /saas:

{
"event": "invoice.received",
"eventId": "7f1c2d9e-4b1a-4e3d-9c1f-0a2b3c4d5e6f",
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"documentId": "…",
"invoiceNumber": "2026001",
"senderId": "0088:7300010000001",
"supplierName": "Dodávateľ s.r.o.",
"receiverId": "0245:2121358349",
"issueDate": "2026-06-03",
"dueDate": "2026-06-17",
"deliveryDate": "2026-06-03",
"currency": "EUR",
"totalAmount": "120.00",
"peppolMessageId": "…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349"
}

Поля companyDic і peppolParticipantId ідентифікують компанію, якої стосується подія (важливо для партнерів, які використовують одну URL вебхука для всіх своїх клієнтів).

Вердикт мережі щодо відправленого рахунка:

{
"event": "invoice.delivered",          // or "invoice.rejected"
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"documentId": "…",
"invoiceNumber": "2026001",
"receiverId": "0245:2120049096",
"peppolMessageId": "…",
"status": "delivered",                 // or "rejected"
"statusDetail": null,                  // for rejected: the rejection reason
"statusDateTime": "2026-06-03T10:15:42Z"
}

Активація компанії після вибору постачальника на порталі FS (VPDS):

{
"event": "company.activated",          // company.deactivated has the same body without verifiedAt
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"status": "active",
"verifiedAt": "2026-06-03T10:02:11Z"
}

Назва події також передається в заголовку X-Verteco-Event. Повний список подій: invoice.received, invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported, invoice.report_pending, invoice.report_rejected, company.activated, company.deactivated, company.smp_registered_elsewhere і тестова подія webhook.test. Рекомендуємо відкладати невідомий тип події та логувати його; про новий тип ми завжди повідомляємо заздалегідь. Кожна подія також містить occurredAt (час події, ISO-8601 UTC) для впорядкування, а також eventId (те саме значення, що й у заголовку X-Verteco-Delivery-Id): унікальний для кожної події та незмінний при повторній доставці, тому це правильний ключ дедуплікації (peppolMessageId повторюється в invoice.sent, invoice.delivered та invoice.reported). Події invoice.* містять також часи sentAt, deliveredAt, receivedAt і fsReportedAt (ISO-8601 UTC, null, доки факт не настав). invoice.reported надходить, коли податкове повідомлення до Фінансової адміністрації (TDD) щодо документа передано мережі доставки (§ 85o абз. 11), у разі збою C5 навіть із затримкою в кілька днів. Формальні схеми всіх подій наведено в розділі webhooks специфікації OpenAPI.

Перевірка підпису

Якщо компанія має секрет, ми надсилаємо заголовок X-Verteco-Signature у формі sha256=HMAC-SHA256(secret, raw body) (hex у нижньому регістрі). Завжди обчислюйте HMAC над точними байтами тіла:

import crypto from 'node:crypto';

// rawBody = the exact bytes of the request body (not re-serialized JSON)
function verify(rawBody, header, secret) {
const expected = 'sha256=' +
  crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Заголовки кожної доставки: X-Verteco-Event (назва події), X-Verteco-Delivery-Id (= eventId у тілі, однаковий при кожному повторі), X-Verteco-Signature (HMAC вище) і паралельно заголовки за стандартом Standard Webhooks: webhook-id (= eventId), webhook-timestamp (unix-секунди цієї спроби) та webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + body)). Ключ = байти Вашого секрету в UTF-8; бібліотека standardwebhooks очікує його як whsec_ + base64(secret). Рекомендована обробка: перевірте підпис, відхиляйте доставку з webhook-timestamp старшим за 5 хвилин (захист від повторного відтворення), обробляйте ідемпотентно за eventId, відповідайте 2xx протягом 15 секунд, а важку обробку відкладайте у власну чергу. Невдалу доставку ми повторюємо 12 разів з інтервалом від 30 с до 8 год (загалом близько 16 годин); потім вона потрапляє в dead-letter із сповіщенням e-mail і залишається видимою в Realtime-логу. Продуктивна webhook-URL має бути https://; тестове середовище приймає також http://.

Масове налаштування: один токен, кілька компаній

Один API-токен (прив'язаний до Вашого облікового запису / електронної адреси) керує усіма компаніями, якими він володіє: хто створює компанію через POST /companies, стає її owner і може налаштувати її вебхук. Вебхук є окремим для кожної компанії (власна URL і секрет), тож одним і тим самим токеном Ви можете підключити будь-яку кількість компаній:

# 1) list of your companies (paginated, see Companies)
curl 'https://peppol.verteco.digital/api/v1/companies?page=0&limit=100' -H 'Authorization: Bearer vpt_8f2a…'

# 2) for EACH company {id}: set the webhook (and/or e-mail)
curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/notifications \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"webhookUrl":"https://vas-system.sk/peppol/webhook","notificationEmail":"faktury@firma.sk"}'

# 3) fetch the signing secret (returned ONLY ONCE) and store it for signature verification
curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
# → { "secret": "…" }

• Токен має бути owner/admin відповідної компанії; для компанії, де він лише member/viewer, повертається 403 forbidden (жодного доступу між клієнтами (cross-tenant)).
• Кожній компанії можна задати іншу URL або одну й ту саму для всіх; у payload Ви розрізняєте їх за companyId (і receiverId).
• За сотень компаній дотримуйтеся ліміту запитів на токен (поточне значення повертається в заголовку RateLimit-Limit); групуйте запити з затримкою (backoff) при 429 (заголовок Retry-After).
• Вебхук фактично спрацьовує лише тоді, коли компанія активна в Peppol (після вибору Verteco як постачальника у Фінансовій адміністрації) і, отже, фактично отримує документи.

Поля об'єктів, які повертає API.

Company

Document

User · Token · Webhook

DIČ

Словацький податковий ідентифікаційний номер (10 цифр). Словацький Peppol ID = 0245: + цифри DIČ, без SK.

IČ DPH

Ідентифікаційний номер платника ПДВ (SK + DIČ). Є лише в платників ПДВ; неплатник виставляє з категорією O.

IČO

Реєстраційний номер організації (8 цифр). Поле ico в API, BT-30 в UBL.

Верифікаційний токен (VÚ)

Підпис Фінансової адміністрації, що виникає при виборі провайдера на порталі FS; розблоковує відправлення для компанії.

VPDS

Застосунок FS, де платник податків обирає провайдера служби доставки (нас).

TDD

Tax Data Document, звіт про рахунок для Фінансової адміністрації; ми формуємо і надсилаємо його за вас.

C5 / C6

П’ятий і шостий кути моделі Peppol: точка доступу Фінансової адміністрації, що приймає TDD (0242:001180).

MLS

Message Level Status, квитанція від точки доступу одержувача (AP = прийнято, RE = відхилено, AB = підтверджено).

SBDH

Standard Business Document Header, конверт, у якому документ подорожує мережею; його InstanceIdentifier = peppolMessageId.

SML / SMP

Каталог мережі: SML знаходить SMP одержувача, SMP повідомляє точку доступу і типи документів, які одержувач приймає.

Поза межами Peppol BIS Billing 3.0 словацькі постачальники ERP і програм для виставлення рахунків поступово сходяться на спільній інтерпретації опціональних полів (обговорення відбувається в Slack-каналі, який веде Фінансова адміністрація Словаччини, Finančná správa, FS). Нижче наведено конвенції, яких наш портал дотримується вже сьогодні: усі вони є валідними конструкціями BIS, проходять через наше API без змін, а отримані документи відображають їх також у зрозумілому для людини попередньому перегляді та PDF.

• Вирахування оподаткованого авансу в рядку: від'ємний рядок із cac:DocumentReference, де cbc:ID містить номер податкового документа на отриманий платіж, а cbc:DocumentTypeCode дорівнює 130 (BIS: invoice line object identifier, макс. 1 на рядок). Отриманий рахунок із таким рядком відображається в нашому попередньому перегляді з приміткою „odpočet zálohy – daňový doklad č. …" (вирахування авансу, податковий документ №…).
• Податковий документ на отриманий платіж: згідно з FAQ Фінансової адміністрації використовується код InvoiceTypeCode 388 (Tax invoice). Він проходить як наше API, так і валідацію; вирахування неоплаченого (неоподаткованого) авансу виражається через cbc:PrepaidAmount.
• Анулювання рахунка: кредит-нота 381 (CreditNote) з cac:BillingReference на початковий рахунок, а не від'ємний рахунок 380. Примітка: мережа відхиляє код 384 для словацьких сторін (правило PEPPOL-EN16931-P0112 дозволяє його лише між німецькими суб'єктами); для коригування в бік збільшення використовуйте дебет-ноту 383.
• BT-83 PaymentID: словацька практика сходиться на форматі референсу платника /VS…/SS…/KS…; лише змінний символ (variabilný symbol) також поширений. Наша обробка передає значення без змін і відображає його разом із платіжними реквізитами.
• Додаткові дані позицій (партії, серійні номери, терміни придатності) через cac:AdditionalItemProperty з усталеними назвами, такими як BatchNumber, SerialNumber, ExpirationDate.

Вкладення (PDF, зображення) можна додати до е-рахунка у форматі base64 в елементі cac:AdditionalDocumentReference (BT-125). Для отриманих документів ми обробляємо вкладення до 25 МБ кожне; при надсиланні весь XML разом із base64-вкладеннями має бути до 10 МБ через SAPI-SK і до 2 МБ через вкладку порталу Odoslať súborom. Peppol не визначає єдиного ліміту для всієї мережі; окремі постачальники встановлюють власні (FS FAQ 9/DPH/2025/IM, приклад № 67), тому для дуже великих вкладень також перевірте ліміт постачальника іншої сторони.

Два допоміжні endpoint-и без автентифікації: те саме ядро валідації і той самий SML lookup, які використовує наш Access Point. Вони підходять для CI та перевірок перед відправленням; на них діє суворіший публічний ліміт запитів.

curl -X POST https://peppol.verteco.digital/api/v1/public/peppol-validate \
-H "Content-Type: application/xml" \
--data-binary @faktura.xml

// 200 OK
{
"valid": false,
"errors": [
  "BR-CO-09: [BR-CO-09]-The Seller VAT identifier (BT-31) … shall have a prefix in accordance with ISO code…"
],
"warnings": []
}
// 400 = empty body (empty_document) or document over 3 MB (document_too_large)

// 200 OK
{
"registered": true,
"participantId": "0245:2121358349",
"smp": "sml.peppol-smp.sk",
"capabilities": ["Faktúra (BIS Billing)", "Dobropis", "Self-billing", "MLS doručenky"], // Slovak labels: Invoice (BIS Billing), Credit note, Self-billing, MLS delivery receipts
"lastCheckedAt": "2026-08-31T…Z"
}

Портал має власний сервер для Model Context Protocol, відкритого стандарту, через який ШІ-асистенти (Claude Code, Claude Desktop, Cursor, VS Code Copilot та інші) підключаються до зовнішніх систем. Асистент входить звичайним API-ключем облікового запису й отримує шість інструментів; він ніколи не бачить більше, ніж цей обліковий запис, і кожен виклик з’являється в журналі API ключа.

Адреса: https://peppol.verteco.digital/api/mcp. Транспорт: Streamable HTTP, JSON-RPC 2.0, без стану (POST /api/mcp, без SSE-потоку, GET повертає 405). Вхід заголовком Authorization: Bearer <API-ключ>. Підтримувані методи: initialize, ping, tools/list, tools/call, resources/list, prompts/list.

Інструменти

• list_companies: компанії облікового запису з Peppol ID, станом і роллю (початок кожної розмови)
• list_documents: надіслані/отримані рахунки компанії зі станом доставки та звіту до податкової, посторінково
• get_document: один рахунок детально, включно з квитанцією MLS і звітом, за бажанням UBL XML (до 1 МБ)
• check_participant: жива перевірка отримувача в мережі Peppol (SML)
• validate_document: валідація UBL за EN 16931 + Peppol BIS 3.0
• send_document: надсилання рахунка від імені компанії, потребує confirm = true, діє перевірка Verifikačný údaj

Підключення в Claude Code

claude mcp add --transport http verteco-peppol https://peppol.verteco.digital/api/mcp \
  --header "Authorization: Bearer vpt_..."

Claude Desktop (через міст mcp-remote, потрібен Node.js)

{
  "mcpServers": {
    "verteco-peppol": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://peppol.verteco.digital/api/mcp", "--header", "Authorization: Bearer vpt_..."]
    }
  }
}

Надсилання рахунка є юридично зобов’язальним: інструмент відхиляє виклик без confirm = true, а інструкції сервера зобов’язують асистента отримати явну згоду користувача на конкретний рахунок і отримувача. Готові конфігурації для Cursor і VS Code та кнопка створення ключа є в порталі: API-ключі → вкладка MCP-сервер. API-ключі → MCP-сервер

У порталі компанія вмикає власну адресу <24 випадкові символи>@peppol.send.verteco.app. Лист із вкладенням UBL XML, надісланий на цю адресу з дозволеної поштової скриньки, ми відправляємо через мережу Peppol так само, як якби файл завантажили на вкладці Надіслати файлом; відправник отримує одну відповідь з результатом за кожне вкладення, а документ доступний у порталі та API зі статусом доставки, квитанцією MLS і звітом FS. Налаштування: З’єднання та інтеграції → Надсилання електронною поштою (власник або адміністратор компанії, після входу). /dashboard/integrations/email

Правила обробки

• Приймаємо лише листи з адреси, що є в списку дозволених відправників компанії (не більше 20); усе інше відкидаємо без відповіді.
• За замовчуванням домен відправника має пройти перевірку SPF або DKIM на сервері доставки (вирівнювання як у DMARC, relaxed). Сервер доставки додатково відхиляє листи, які не пройшли ні SPF, ні DKIM, та листи всупереч політиці DMARC відправника. Перевірку можна вимкнути в налаштуваннях; не рекомендуємо.
• Вкладення: UBL 2.1 Invoice або CreditNote (Peppol BIS Billing 3.0), розширення .xml, за потреби в конверті SBDH; не більше 10 вкладень у листі, 15 МБ на вкладення, 200 листів на адресу за день. PDF і текст листа не обробляються.
• IFS Finvoice 2.0: вкладення .xml з SOAP-конвертом IFS (IFSFinvoice) або сам Finvoice ми перетворюємо на UBL і далі обробляємо так само. Правила перетворення: INV02 або від’ємна сума = кредит-нота (381) з додатними сумами та посиланням на первинний рахунок (OriginalInvoiceNumber, в IFS OrderIdentifier); продавець і покупець за словацьким ІПН ПДВ (SellerOrganisationTaxCode, BuyerOrganisationTaxCode → 0245:DIČ), покупець поза Словаччиною не перетворюється; розбивка ПДВ із VatSpecificationDetails, рядки з 0 % як категорія E з підставою з VatFreeText, інакше „Oslobodené od DPH“; рядки округлення IFS (база 0,00, ПДВ 0,01) пропускаються, ціна за одиницю, що не збігається із сумою рядка, перераховується; одиниці за UN/ECE (kg → KGM, pcs → H87, h → HUR, невідомі → C62 з оригінальним текстом у примітці рядка); вбудоване зображення рахунка (InvoiceAttachments, PDF) додається до документа до 5 МБ; лише EUR. Результат перетворення зазначено у відповіді та в журналі компанії.
• Адреса для результатів: якщо рахунки надсилає системна поштова скринька, у налаштуваннях оберіть іншу адресу для відповіді з результатом (replyTo у PUT /companies/{id}/email-send, порожнє = відповісти відправнику).
• Продавець у XML (EndpointID постачальника, BT-34) має бути цією компанією, інакше лист відхиляється (переслана рахунок-фактура вашого постачальника ніколи не відправляється як ваша). Покупець повинен мати EndpointID зі схемою (BT-49).
• Той самий лист (Message-ID) обробляється один раз. Документ має в API та вебхуках origin = email, дійова особа = адреса відправника.

Публічний endpoint перевірки стану (health-check), придатний для моніторингу.

// 200 OK
{ "service": "peppol-portal-backend", "status": "ok", "timestamp": "2026-06-17T…Z" }

Актуальний огляд усіх компонентів доступний на сторінці стану системи.

Уже в продакшні (часто помилково вважають відсутнім)

• POST /companies/{id}/documents/send — стабільний інтерфейс порталу; для ERP-інтеграцій і далі рекомендовано SAPI-SK з Idempotency-Key.
• Реєстрація в SMP відбувається автоматично після вибору на порталі FS; перехід від іншого провайдера через POST /companies/{id}/smp-migrate з міграційним кодом.
• Квитанції MLS, докази доставки та звіти FS (fsReport) у кожному рядку /sapi/document/sent; повторне відправлення вебхуків за часове вікно.
• Ключі, обмежені обраними компаніями; MCP-сервер для ШІ-асистентів; зразки UBL на /vzory; публічний валідатор.

У підготовці (у порядку попиту інтеграторів)

• Асинхронний batch: POST /sapi/document/batch відповідає 202 з посиланням на job і статусом по кожній позиції.
• Канал змін GET /sapi/document/changes?since&cursor з курсором замість офсетної пагінації.
• Термін дії та ротація API-ключів у порталі, ключ лише для читання.
• Кілька кінцевих точок вебхуків на компанію з фільтром подій.