Fejlesztőknek: API-referencia

A Verteco API REST alapú, HTTPS felett. A kérés és a válasz egyaránt JSON (UTF-8). Kezdje egy fiók, majd egy API-token létrehozásával, és egy percen belül elküldheti az első hívást. Minden útvonal az alábbi alap-URL-hez (base URL) képest értendő.

A teljes tesztkörnyezet (sandbox) a következő címen érhető el: test.peppol.verteco.digital. Ugyanúgy viselkedik, mint az éles környezet, és ezen felül teszteszközöket (a Szlovák Köztársaság Pénzügyi Igazgatóságának (Finančná správa, FS) webhookja, ellenőrző token (Verifikačný údaj), cég eltávolítása) és egy szimulált szolgáltatóválasztást kínál az FS portál (VPDS) helyett.

Alap-URL (base URL)

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

Verzió

v1 (az útvonalban). A visszafelé nem kompatibilis változások új verzió alatt jelennek meg.

Protokoll

csak HTTPS · TLS 1.2+ · TLS A+

Formátum

application/json (UTF-8)

Hitelesítés

cookie alapú munkamenet (portál) vagy Bearer token (szerver-szerver)

Időbélyegek

ISO-8601 (UTC), pl. 2026-06-03T09:40:27Z

A fiókot és az API-tokent is a portálon (böngészőben) hozza létre. Az integráció ezután kizárólag az API-tokenen keresztül működik. Az alkalmazásának nem kell regisztrációt, bejelentkezést vagy jelszavakat kezelnie.

1. 1

   Hozzon létre fiókot a portálon

   Regisztráljon az e-mail-címével, és erősítse meg az e-mailben kapott hivatkozással.
2. 2

   Generáljon API-tokent

   A portálon nyissa meg az API tokeny → Vytvoriť (API-tokenek → Létrehozás) menüpontot. A vpt_… token csak egyszer jelenik meg. Tárolja biztonságosan.
3. 3

   Küldje el az első hívást

   Használja a tokent az Authorization fejlécben:

   javascriptKopírovať

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

A SAPI mock sandbox (lásd lent) mellett egy teljes értékű tesztkörnyezetet is üzemeltetünk, e portál teljes másolatát külön adatokkal, ahol a teljes folyamatot (regisztráció → cég → küldés → fogadás → értesítések) végigpróbálhatja az éles környezetre gyakorolt bármilyen hatás nélkül.

URL

https://test.peppol.verteco.digital

Regisztráció

nincs megerősítő e-mail; a fiók azonnal használható

Cég jóváhagyása

automatikus, közvetlenül a felületen vagy az API-n keresztül; nincs szolgáltatóválasztás a Szlovák Köztársaság Pénzügyi Igazgatóságának (Finančná správa, FS) portálján és nincs bejelentkezés az FS-portálra; közvetlenül egy áfaazonosítóval (IČ DPH) rendelkező cég létrehozása után küldhet és fogadhat is

Hálózati regisztráció

automatikus, a Peppol teszthálózatba. Figyeljen az azonosító két rétegére: az API és a portál ugyanazt a formátumot használja, mint az éles környezet (peppolParticipantId = 0245:<DIČ számjegyei>, ahol a DIČ a szlovák adóazonosító szám; az integrációs kódja nem változik); a teszt SMP/SML-ben a cég technikailag 9950:SK<DIČ> formában van regisztrálva, mert a 0245 séma a Pénzügyi Igazgatóság ellenőrző kódját igényli, amely a tesztkörnyezetben nem létezik. Az éles környezetben a 0245:<DIČ számjegyei> azonosító csak az FS-portálon végzett szolgáltatóválasztás után (eID-vel vagy belépési adatokkal) kerül regisztrálásra az éles Peppol hálózatban

Validáció

valódi: EN 16931 + Peppol BIS 3.0 szabályok, ugyanúgy, mint az éles környezetben

Kézbesítés

valódi, a Peppol teszthálózaton keresztül (AS4, tesztcertifikát, teszt SML/SMP): a teszthálózatban regisztrált címzett fogadott számlaként kapja meg a számlát (e-maillel, PDF-fel és webhookkal együtt); az éles hálózatba semmi nem kerül

Kézbesítési igazolás (MLS)

valódi MLS igazolás a teszthálózatból

E-mailek

valóban elküldésre kerülnek (a megadott címekre), [TEST] előtaggal

Ár

ingyenes, tesztelési korlátok nélkül

Minden, ami itt működik, ott is működik: a portál, a REST API, a SAPI-SK 1.0, a webshop-bővítmények és a webhookok. Csak váltsa át az integrációjában a domaint a test.peppol.verteco.digital címre, és használja a tesztkörnyezetben létrehozott tokeneket. Ideális integrációfejlesztéshez, CI-tesztekhez és a könyvelők betanításához az éles bevezetés előtt.

Megjegyzés: a tesztdomain peremvédelme (edge) a generikus User-Agent: Python-urllib és User-Agent: Java/1.8.x fejléceket (a Java 8HttpsURLConnection alapértelmezett User-Agentje) HTTP 403 "error code: 1010" válasszal blokkolja, még mielőtt a kérés elérné az API-nkat; az éles peppol.verteco.digital domain átengedi őket. Állítson be saját User-Agentet: Java alatt vagy a -Dhttp.agent=my-app/1.0 JVM-kapcsolóval (kódmódosítás nélkül; a Java hozzáfűzi a "Java/1.8" részt, és az így kapott "my-app/1.0 Java/1.8.0_xxx" átjut, csak a "Java/1.8" kezdetű fejléc van blokkolva), vagy a kapcsolaton a conn.setRequestProperty("User-Agent", "my-app/1.0") hívással. A gyakori kliensek (requests, httpx, Java 11+, Apache HttpClient, okhttp, axios, Go, PHP, curl) változtatás nélkül működnek.

Miért kerülnek a cégek automatikusan jóváhagyásra

A Pénzügyi Igazgatóságnak nincs tesztkörnyezete a VPDS portálhoz: a szolgáltatóválasztás a vpds.financnasprava.sk portálon csak élesben fut, és az FS-portálra való bejelentkezéssel (eID vagy belépési adatok) ellenőrzik, így élesben nem lehet tetszőleges, nem saját céget „kiválasztani”. Hogy az integrációját mégis tesztelhesse, ezt a lépést a tesztkörnyezetben szimuláljuk: minden létrehozott cég automatikusan jóváhagyásra kerül (FS-nél történő választás nélkül), így beállíthat küldőt és címzettet is, és végigmehet a teljes folyamaton.

Az FS webhookok (szolgáltatóválasztás) teszteléséhez saját megfelelőnk van a Pénzügyi Igazgatóság eszközéhez: test.peppol.verteco.digital/sandbox-nastroje. Itt érvényes, FS-stílusú ellenőrző tokent (Verifikačný údaj) generálhat, és teljes webhookot küldhet a saját végpontjára, pontosan úgy, ahogy az FS portál teszi egy valódi választásnál. A teszteléshez létrehozott cégek pedig kiregisztrálhatók (a portálról és a teszt SMP-ből), éppen a Pénzügyi Igazgatóság oldalán hiányzó tesztmód miatt.

Az integrációja API-tokennel hitelesít az Authorization: Bearer vpt_… fejlécben. A tokent a portálon hozza létre (API-tokenek); formátuma vpt_ + 40 hexadecimális karakter, mi csak a SHA-256 hash-ét tároljuk, és ugyanolyan hozzáférése van, mint az Ön fiókjának. Tesztelje az /auth/me hívással:

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

Hiányzó vagy érvénytelen token esetén az API a következőt adja vissza:

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

Lapozás és idempotencia

A hibák egységes alakúak, géppel olvasható error kóddal. A validációs hibák egy fields térképet is tartalmaznak (mezőnként az első hiba).

// 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-státuszok

200 / 201 / 204

siker (OK / Created / No Content)

400

érvénytelen bemenet (lásd error / fields)

401

hiányzó vagy érvénytelen hitelesítés

403

nincs elegendő jogosultság (szerepkör)

404

az erőforrás nem létezik, vagy nincs hozzá hozzáférése

405

a HTTP-metódus nem támogatott ezen az útvonalon

409

ütközés (az IČO / e-mail már létezik)

415

nem támogatott Content-Type (az XML végpontok application/xml-t várnak)

429

kérésszám-korlát (rate limit) túllépve (RateLimit-* és Retry-After fejlécek, JSON törzs: rate_limited)

Teljes hibakatalógus

Az API-t kérésszám-korlátozás védi 60 másodperces ablakban (példányonként). A korlátot és a fennmaradó keretet minden válasz fejlécekben adja vissza; túllépés esetén az API 429 Too Many Requests választ ad Retry-After fejléccel.

Rendes hívások

dinamikus korlát nagy ráhagyással, API-tokenenként (vagy munkamenetenként, egyébként IP-címenként); az aktuális értéket a RateLimit-Limit fejléc adja vissza

Hitelesítés (/auth/*)

szigorúbb korlát IP-címenként (brute force ellen; kivéve /auth/me és /auth/logout)

RateLimit-Limit

korlát az ablakban

RateLimit-Remaining

hány kérés maradt

RateLimit-Reset

másodpercek az ablak újraindulásáig

Retry-After

másodpercek a következő próbálkozásig (429 esetén)

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." }

Átlátszatlan (opaque) vpt_… tokenek szerver-szerver hozzáféréshez. A nyílt szöveg csak egyszer jelenik meg, a létrehozáskor. Mentse el. Mi csak a SHA-256 hash-t és egy 12 karakteres előtagot tárolunk a megjelenítéshez.

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":"…" }

Az Ön által kezelt, cégjegyzékszámmal (IČO) / áfaazonosítóval (IČ DPH) azonosított cégek. A hozzáférés a tagsághoz kötött: csak azokat a cégeket látja, amelyeknek tagja. A cég létrehozója lesz annak owner-e.

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" }

A status mező

pending_verification

létrehozás után; a küldés még nincs feloldva

active

ellenőrzött, a küldés feloldva

Tagi szerepkör

owner

a cég létrehozója (teljes hozzáférés)

admin

adminisztrátor (szerkesztés, webhookok, ellenőrzés)

member

tag (olvasás)

viewer

csak olvasás

Küldés előtt a céget ellenőrizni kell az ellenőrző tokennel (Verifikačný údaj, VÚ), amely a Szlovák Köztársaság Pénzügyi Igazgatósága (Finančná správa, FS) által kiállított aláírt token. Sikeres ellenőrzés után a cég status mezője active értékre vált, és a küldés feloldódik.

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" }

A cég Peppol bizonylatainak (fogadott és küldött) naplója. Ahogy a számlák áthaladnak a hozzáférési ponton (Access Point), úgy telik meg. A cégtagsághoz kötött, createdAt szerint csökkenő sorrendben.

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":"…" } ]

A SAPI-SK a szabványosított nemzeti REST interfész az ügyfél/ERP-rendszer és a hozzáférési pont (Access Point) között (sapi-sk.sk). Teljes körűen implementáljuk. Ez azt jelenti, hogy Ön nincs a saját API-formátumunkhoz kötve, és az integrációt egyszer írja meg, bármely SAPI-SK hozzáférési ponthoz.

Alap-URL (base URL)

https://peppol.verteco.digital/sapi

Hitelesítés

OAuth2 client_credentials → rövid élettartamú access token (JWT)

client_id

az Ön API-tokenjének UUID-ja (az API-tokenek szakaszban / a vezérlőpulton látható)

client_secret

maga a portálról származó vpt_… token

Verzió

1.3 (10 művelet: 4× hitelesítés, 6× bizonylatok)

Sandbox (próbakörnyezet)

Kipróbálná a SAPI-SK-t regisztráció nélkül és kockázat nélkül? Használja a nyilvános sandbox hitelesítő adatokat. A sandbox pontosan úgy validálja a kéréseket, mint az éles környezet, de soha semmit nem küld a Peppol hálózatba, és nem dolgozik valódi adatokkal; valósághű mock válaszokat ad vissza. Ideális fejlesztéshez, CI-hoz és az integráció bevezetéséhez.

client_id

sandbox

client_secret

sandbox

send

teljes szerződésvalidáció + mock 202 (semmi nem kerül kézbesítésre)

receive

1 mintabizonylat sandbox-doc-0001 a feldolgozás és az acknowledge teszteléséhez

# 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>'

Hitelesítés

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…" }

Bizonylat küldése

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 @szamla.xml
# 200 OK
{ "valid": false,
  "errors": [ "BR-CO-15: Invoice total amount with VAT (BT-112) = … " ],
  "warnings": [],
  "checkedAt": "2026-09-10T12:00:00Z" }

Bizonylatok fogadása

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

Küldött bizonylatok állapota

// 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 }

Tömeges küldés

// 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": "…" } ] }

Hibamodell

Minden SAPI hiba egységes borítékot használ kategóriával, stabil kóddal, egy retryable jelzővel és egy correlation_id értékkel a támogatás számára.

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

Fogadott számláról a céget e-mailben vagy webhookkal (POST az Ön URL-jére) értesíthetjük. A kézbesítés tartós: kimenő várólistában tároljuk, és aszinkron módon kézbesítjük (15 s időtúllépés); hiba esetén legfeljebb 8× újrapróbáljuk exponenciális visszatartással (30 s → max. 1 óra), majd dead-letter. Az Ön szerverének kimaradása így nem veszíti el az értesítést; a következő próbálkozásnál kézbesítjük. Az SSRF-védelem blokkolja a loopback/helyi címeket; a webhook-URL-nek nyilvánosnak kell lennie.

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

Webhook payload

Fogadott (invoice.received) és küldött (invoice.sent) számla esetén is POST kérést küldünk ezzel a törzzsel; a típust az event mező különbözteti meg.

Két további esemény jelzi a hálózat ítéletét az Ön által küldött számláról: invoice.delivered (a címzett hozzáférési pontja kézbesítési igazolással (MLS) megerősítette a kézbesítést) és invoice.rejected (elutasítva, vagy a hálózat által, vagy a küldés előtti validáció során). A bizonylat és a cég azonosítóit hordozzák (documentId, invoiceNumber, receiverId, peppolMessageId, companyDic, peppolParticipantId), valamint a status mezőt, a statusDetail mezőt az elutasítás okával és a statusDateTime mezőt. Ha az első kézbesítési kísérlet nem sikerült és a hozzáférési pont magától újrapróbálja (általában egy órán belül), a dokumentum submitted marad, és a statusDetail a network_retrying: előtaggal kezdődik; a kézbesítés után delivered, feladás után rejected lesz network_gave_up: előtaggal. Ezeknek köszönhetően nem kell lekérdezéssel figyelnie a küldött számlák állapotát.

A company.activated esemény akkor érkezik, amikor egy ügyfél befejezi a szolgáltatóválasztást a Szlovák Köztársaság Pénzügyi Igazgatóságának (Finančná správa, FS) portálján (VPDS); törzs: event, companyId, companyDic, peppolParticipantId, status, verifiedAt. A company.deactivated pedig akkor érkezik, amikor egy céget kiregisztrálnak a hálózatból (ugyanaz a törzs verifiedAt nélkül). A company.smp_registered_elsewhere akkor érkezik, amikor a cég befejezte a PI-választást, de nemzeti SMP bejegyzését másik szolgáltató tartja (törzs mint a company.activated, plusz action: "migration_code_required" és migrateUrl). A partnerek teendői a közvetítői dokumentációban találhatók. Amíg az ügyfél be nem írja a migrációs kódot, a hálózat a régi szolgáltatónak kézbesít. Részletek a /saas útmutatóban:

{
"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"
}

A companyDic és a peppolParticipantId mező azonosítja azt a céget, amelyre az esemény vonatkozik (fontos azoknak a partnereknek, amelyek egyetlen webhook-URL-t használnak minden ügyfelükhöz).

A hálózat ítélete a küldött számláról:

{
"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"
}

Cég aktiválása az FS portálon (VPDS) végzett szolgáltatóválasztás után:

{
"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"
}

Az esemény neve az X-Verteco-Event fejlécben is szerepel. Az események teljes listája: invoice.received, invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported, company.activated, company.deactivated, company.smp_registered_elsewhere és a webhook.test tesztesemény. Az ismeretlen eseménytípust javasoljuk félretenni és naplózni; új típust mindig előre bejelentünk. Minden esemény tartalmaz occurredAt mezőt is (az esemény ideje, ISO-8601 UTC) a rendezéshez, valamint eventId mezőt (ugyanaz az érték, mint az X-Verteco-Delivery-Id fejlécben): eseményenként egyedi, ismétléskor változatlan, ezért ez a helyes deduplikációs kulcs (a peppolMessageId ismétlődik az invoice.sent, invoice.delivered és invoice.reported események között). Az invoice.* események tartalmazzák a sentAt, deliveredAt, receivedAt és fsReportedAt időpontokat is (ISO-8601 UTC, null, amíg az esemény be nem következett). Az invoice.reported akkor érkezik, amikor a bizonylathoz tartozó adóhatósági jelentés (TDD) átadásra került a kézbesítő hálózatnak (85o. § (11) bek.), C5-kimaradás esetén akár napokkal később. Az összes esemény formális sémája az OpenAPI-specifikáció webhooks szakaszában található.

Aláírás ellenőrzése

Ha a cégnek van titka, az X-Verteco-Signature fejlécet küldjük sha256=HMAC-SHA256(secret, raw body) formában (kisbetűs hex). A HMAC-et mindig a törzs pontos bájtjain számolja:

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));
}

Minden kézbesítés fejlécei: X-Verteco-Event (az esemény neve), X-Verteco-Delivery-Id (= a törzsben lévő eventId, minden ismétlésnél azonos), X-Verteco-Signature (a fenti HMAC), valamint párhuzamosan a Standard Webhooks fejlécek: webhook-id (= eventId), webhook-timestamp (a kísérlet unix másodperce) és webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + body)). A kulcs a titok UTF-8 bájtjai; a standardwebhooks könyvtár whsec_ + base64(secret) formában várja. Ajánlott feldolgozás: ellenőrizze az aláírást, utasítsa el az 5 percnél régebbi webhook-timestamp értékű kézbesítést (visszajátszás elleni védelem), dolgozzon fel idempotensen az eventId alapján, válaszoljon 2xx-szel 15 másodpercen belül, és a nehéz feldolgozást tegye saját várólistára. A sikertelen kézbesítést 8-szor ismételjük 30 s és 1 h közötti időközökkel; utána dead-letterbe kerül e-mail figyelmeztetéssel, és látható marad a Realtime logban. Az éles webhook URL-nek https://-nek kell lennie; a tesztkörnyezet a http://-t is elfogadja.

Tömeges beállítás: egy token, több cég

Egyetlen API-token (a fiókjához/e-mail-címéhez kötve) kezeli az összes tulajdonában lévő céget: aki a POST /companies hívással céget hoz létre, annak owner-e lesz, és beállíthatja a webhookját. A webhook cégenkénti (saját URL és titok), így ugyanazzal a tokennel tetszőleges számú céget csatlakoztathat:

# 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": "…" }

• A tokennek az adott cég owner/admin szerepkörével kell rendelkeznie; olyan cégnél, ahol csak member/viewer, 403 forbidden választ ad (nincs bérlők közötti hozzáférés).
• Minden cégnek adhat eltérő URL-t, vagy mindnek ugyanazt; a payloadban a companyId (és a receiverId) alapján különbözteti meg őket.
• Több száz cég esetén tartsa be a tokenenkénti kérésszám-korlátot (az aktuális értéket a RateLimit-Limit fejléc adja vissza); kötegeljen visszatartással 429 esetén (Retry-After fejléc).
• A webhook ténylegesen csak akkor sül el, amikor a cég aktív a Peppolban (miután a Pénzügyi Igazgatóságnál a Vertecót választotta szolgáltatónak) és így ténylegesen fogad bizonylatokat.

Az API által visszaadott objektumok mezői.

Company

Document

User · Token · Webhook

A Peppol BIS Billing 3.0-n túl a szlovák ERP- és számlázószoftver-gyártók fokozatosan közös értelmezésre jutnak az opcionális mezőkről (az egyeztetés a Szlovák Köztársaság Pénzügyi Igazgatósága (Finančná správa, FS) által működtetett Slack-csatornán zajlik). Alább azok a konvenciók, amelyeket a portálunk már ma is tiszteletben tart: mindegyik érvényes BIS-konstrukció, változatlanul haladnak át az API-nkon, és a fogadott bizonylatokban az emberi olvasásra szánt előnézetben és a PDF-ben is megjelennek.

• Adózott előleg levonása egy soron: negatív sor cac:DocumentReference elemmel, ahol a cbc:ID a kapott fizetésről szóló adóbizonylat számát hordozza, és a cbc:DocumentTypeCode értéke 130 (BIS: invoice line object identifier, soronként max. 1). Az ilyen sort tartalmazó fogadott számlát az előnézetünk az „odpočet zálohy – daňový doklad č. …” megjegyzéssel jeleníti meg (előleg levonása, adóbizonylat száma: …).
• Adóbizonylat kapott fizetésről: a Pénzügyi Igazgatóság GYIK-je szerint az InvoiceTypeCode 388 (Tax invoice) kódot használják. Átmegy az API-nkon és a validáción is; a ki nem fizetett (nem adózott) előleg levonását a cbc:PrepaidAmount fejezi ki.
• Számla érvénytelenítése (sztornó): 381 jóváíró számla (CreditNote) cac:BillingReference hivatkozással az eredeti számlára, nem negatív 380-as számla. Megjegyzés: a hálózat a 384-es kódot szlovák felek között elutasítja (a PEPPOL-EN16931-P0112 szabály csak német szervezetek között engedi); felfelé történő korrekcióhoz használja a 383-as terhelési értesítőt (debit note).
• BT-83 PaymentID: a szlovák gyakorlat a /VS…/SS…/KS… fizetői hivatkozási formátum felé tart; a puszta változó szimbólum (variabilný symbol) is gyakori. A feldolgozásunk az értéket változatlanul továbbítja, és a fizetési adatokkal együtt jeleníti meg.
• További tételadatok (gyártási tételszámok, sorozatszámok, lejárati dátumok) a cac:AdditionalItemProperty elemen keresztül, bevett nevekkel, például BatchNumber, SerialNumber, ExpirationDate.

Mellékletek (PDF, képek) base64 formában csatolhatók az e-számlához a cac:AdditionalDocumentReference elemben (BT-125). A mi korlátunk mellékletenként 25 MB. A Peppol nem határoz meg egységes, hálózatszintű korlátot; az egyes szolgáltatók sajátot állapítanak meg (FS GYIK 9/DPH/2025/IM, 67. példa), ezért nagyon nagy mellékleteknél ellenőrizze a másik fél szolgáltatójának korlátját is.

Két segédvégpont hitelesítés nélkül: ugyanaz a validációs mag és ugyanaz az SML/SMP lekérdezés, amelyet a hozzáférési pontunk használ. CI-hoz és küldés előtti ellenőrzésekhez alkalmasak; szigorúbb nyilvános kérésszám-korlát vonatkozik rájuk.

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"
}

A portál saját szervert működtet a Model Context Protocolhoz, a nyílt szabványhoz, amelyen keresztül az AI-asszisztensek (Claude Code, Claude Desktop, Cursor, VS Code Copilot és mások) külső rendszerekhez kapcsolódnak. Az asszisztens a fiók közönséges API-kulcsával jelentkezik be, és hat eszközt kap; soha nem lát többet, mint az adott fiók, és minden hívása megjelenik a kulcs API-naplójában.

Cím: https://peppol.verteco.digital/api/mcp. Átvitel: Streamable HTTP, JSON-RPC 2.0, állapotmentes (POST /api/mcp, nincs SSE-folyam, a GET 405-öt ad). Bejelentkezés az Authorization: Bearer <API-kulcs> fejléccel. Támogatott metódusok: initialize, ping, tools/list, tools/call, resources/list, prompts/list.

Eszközök

• list_companies: a fiók cégei Peppol-azonosítóval, állapottal és szereppel (minden beszélgetés kezdete)
• list_documents: egy cég elküldött/fogadott számlái kézbesítési és adóhatósági jelentési állapottal, lapozva
• get_document: egy számla részletesen az MLS-visszaigazolással és jelentéssel, opcionálisan az UBL XML (1 MB-ig)
• check_participant: a címzett élő ellenőrzése a Peppol-hálózatban (SML/SMP)
• validate_document: UBL validálás az EN 16931 + BIS 3.0 szerint a szlovák szabályokkal
• send_document: számla küldése a cég nevében, confirm = true szükséges, és érvényes a Verifikačný údaj kapu

Csatlakozás a Claude Code-ban

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

Claude Desktop (az mcp-remote hídon keresztül, Node.js szükséges)

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

A számlaküldés jogilag kötelező erejű: az eszköz confirm = true nélkül elutasítja a hívást, és a szerver utasításai kötelezik az asszisztenst, hogy kérje a felhasználó kifejezett hozzájárulását a konkrét számlához és címzetthez. A Cursor és VS Code kész konfigurációi és a kulcs létrehozásának gombja a portálon található: API-kulcsok → MCP-szerver fül. API-kulcsok → MCP-szerver

Nyilvános health-check végpont, monitorozásra alkalmas.

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

Az összes komponens élő áttekintése a rendszerállapot oldalon érhető el.

• POST/companies/{id}/peppol/register· Manuális regisztráció a Peppol SMP-ben az API-n keresztül. Ma ez automatikusan történik a Szlovák Köztársaság Pénzügyi Igazgatóságának (Finančná správa, FS) portálján (VPDS) végzett szolgáltatóválasztáskor.

Korai hozzáférést szeretne az integrációhoz, sandboxot, vagy kérdése van? Vegye fel velünk a kapcsolatot közvetlenül:

Az Ön Peppol-kapcsolattartója

Miriama Mrkávková

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