Для розробників: довідник 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();

Окрім 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]

Ціна

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

Усе, що працює тут, працює і там: портал, REST API, SAPI-SK 1.0, плагіни для інтернет-магазинів і вебхуки. Достатньо змінити домен у Вашій інтеграції на test.peppol.verteco.digital і використовувати токени, створені в тестовому середовищі. Ідеально для розробки інтеграції, CI-тестів і навчання бухгалтерів перед продуктивним запуском.

Примітка: захист периметра (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" }

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

Помилки мають єдину структуру з машинозчитуваним кодом 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 захищене обмеженням частоти запитів у 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." }

Непрозорі (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 }

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

// 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 для служби підтримки.

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

Про отриманий рахунок ми можемо повідомити компанію електронною поштою або вебхуком (POST на Вашу URL-адресу). Доставка надійна (durable): сповіщення зберігається у вихідній черзі та доставляється асинхронно (тайм-аут 15 с); у разі збою ми повторюємо до 8 разів з експоненційною затримкою (30 с → макс. 1 год), потім dead-letter. Отже, збій Вашого сервера не втрачає сповіщення; ми доставимо його при наступній спробі. Захист від 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 (відхилено, або мережею, або під час валідації перед відправленням). Вони містять ідентифікацію документа та компанії (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, 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 секунд, а важку обробку відкладайте у власну чергу. Невдалу доставку ми повторюємо 8 разів з інтервалом від 30 с до 1 год; потім вона потрапляє в 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

Поза межами 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 МБ на вкладення. Peppol не визначає єдиного ліміту для всієї мережі; окремі постачальники встановлюють власні (FS FAQ 9/DPH/2025/IM, приклад № 67), тому для дуже великих вкладень також перевірте ліміт постачальника іншої сторони.

Два допоміжні endpoint-и без автентифікації: те саме ядро валідації і той самий SML/SMP 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/SMP)
• validate_document: валідація UBL за EN 16931 + 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-сервер

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

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

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

• POST/companies/{id}/peppol/register· Ручна реєстрація в Peppol SMP через API. Сьогодні це відбувається автоматично при виборі постачальника на порталі FS (VPDS) Фінансової адміністрації Словаччини (Finančná správa, FS).

Хочете отримати ранній доступ до інтеграції, sandbox або маєте запитання? Зв'яжіться з нами безпосередньо:

Ваш контакт з Peppol

Miriama Mrkávková

+421 944 488 269·peppol​@​verteco.digital