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

4. 4

   Szolgáltató kiválasztása a Pénzügyi Igazgatóság portálján

   Éles környezetben a Verteco kiválasztása az FS portálján (vpds.financnasprava.sk) tisztán küldő használathoz is szükséges: ez oldja fel a küldést (ellenőrző token) és aktiválja a céget. A fogadás közben maradhat a könyvelőprogram szolgáltatójánál: egy cégnek a hálózatban pontosan egy fogadója van, küldője viszont több is lehet.

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

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

Hibaszimuláció

az X-Sandbox-Simulate: 503 fejléc (vagy 502, 500, 429) bármely /sapi/document/* híváson érvényes tokennel a megfelelő hibát adja vissza; semmi sem kerül feldolgozásra vagy mentésre. 500 (SAPI-PROC-500) és 429 (SAPI-SYS-003, Retry-After fejléccel) esetén SAPI hibaborítékot kap; az 503 és 502 a hálózati peremen (DigitalOcean, Cloudflare) HTTP 504-ként, HTML törzzsel, boríték nélkül érkezik, pontosan így néz ki egy valódi kiesés kívülről, így a nem JSON válasz kezelését is tesztelheti. Validációs hibát érvénytelen XML-lel, 429-et percenként 300 hívás túllépésével is kiválthat. Az éles környezet a fejlécet figyelmen kívül hagyja

Á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. Próbabizonylat csak oda való: éles környezetben minden belföldi, áfaalanyok közötti bizonylatot jelentünk a Pénzügyi Igazgatóságnak, és a jelentés nem vonható vissza. Az éles portálon csak a „Poslať skúšobnú faktúru“ (próbaszámla küldése, 0,00 €) gombbal próbáljon; 2027. 1. 1-jétől az éles környezet elutasítja a TEST-/VITAJTE- számokat (test_document_in_production).

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 szerződés csak bővül: új mezők (null esetén kihagyva), új opcionális paraméterek, új végpontok és események. A meglévő mezőnevek, enum-értékek és státuszkódok nem változnak.
• Új enum-érték vagy webhook-esemény bármikor megjelenhet; hagyja figyelmen kívül az ismeretlent, és ismeretlen eseményre 2xx-szel válaszoljon.
• Az időbélyegek ISO 8601 UTC formátumúak változó számú tizedesjeggyel; elemezze, sose hasonlítsa szövegként. Az összegek két tizedesjegyű szövegként érkeznek.
• Ha egy változás nem lehetne additív, a changelogban (e-mail feliratkozással) legalább 90 nappal előre bejelentjük, és az átmeneti időszakban megtartjuk a régi alakot.
• Az API-kulcs biztonsági modellje (2026. október 3-tól): a kulcs bizonylatokat olvas és küld, cégeket, értesítéseket és webhookokat kezel. A fiók- és kulcskezelést (kulcs létrehozása, szűkítése, visszavonása, MFA, jelszó, munkamenetek, meghívók, cégátadás, szerződésaláírás) csak bejelentkezett személy végzi; a kulcs ott 403 token_not_allowed választ kap. A GET /api/v1/tokens kulccsal továbbra is elérhető.
• A szerződés verziója az openapi.json info.version mezője, és minden változásnak van API vagy Webhookok címkéjű changelog-sora.

/changelog · /changelog/odber · openapi.json

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)

Leggyakoribb hibakódok

A hozzáférési pont kiesése és az ismétlés

• Ha az API 502, 503 vagy 504 választ ad, vagy egyáltalán nem válaszol, a bizonylatot nem vettük át: ismételje meg a hívást később ugyanazzal az Idempotency-Key értékkel, semmi nem megy ki kétszer.
• Az API által elfogadott bizonylat (202 ACCEPTED, retrying: true esetén is) a helyreállítás után magától kimegy: a hozzáférési pont ismétli a kézbesítést, az állapotot a GET /sapi/document/sent hívással vagy webhookon látja; ha végül feladja, a bizonylat sikertelenként zárul, és ugyanaz a kulcs újra elküldi.
• A hálózati szintű fogadás nem függ a portáltól: a portál kiesése alatt át nem jutott kézbesítést a küldő hozzáférési pont a Peppol szabályai szerint megismétli, és a bizonylat a helyreállítás után megjelenik a portálon. A kiesés miatt el nem küldött FS-jelentéseket automatikus helyreállító futás pótolja (az átviteli hibát ismételjük, a tartalmi elutasítást nem).
• Az állapot és a rendelkezésre állás előzményei a /status oldalon vannak; a tesztkörnyezetben a kiesést az X-Sandbox-Simulate fejléccel szimulálhatja (Tesztkörnyezet szakasz).

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

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

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

MLS visszaigazolás és kézbesítési bizonyítékok

Az MLS visszaigazolás (Peppol Message Level Status) a fogadó Access Point válasza a küldeményünkre: AP = elfogadva és kézbesítve, AB = kézbesítve üzleti megerősítés nélkül, RE = elutasítva, indokkal. A portál a küldött dokumentumhoz menti, és ennek alapján váltja az állapotot: AP és AB egyaránt delivered (AB esetén a statusDetail „MLS AB: ” szöveggel kezdődik, az mls.responseCode AB; az SPOG on MLS szerint ez üzleti megerősítés nélküli kézbesítés, nem fenntartás), RE pedig rejected. A 222/2004. sz. törvény 76a § (2) bek. d) pontja szerint a szolgáltatónak bizonyítania kell a küldés, kézbesítés és átvétel dátumát és idejét; a GET /sapi/document/sent minden sora és minden webhook hordozza ezt a három időt: sentAt (átadás a kézbesítő szolgálatnak, ezzel a 85o § (11) bek. szerint a kiállító kötelezettsége teljesül), deliveredAt (a fogadó Access Point MLS-megerősítése) és fsReportedAt (adatszolgáltatás a pénzügyi igazgatóság felé). Külföldi Access Point esetleg soha nem küld MLS-t: a dokumentum ekkor delivered marad as4_receipt_only részlettel, visszaigazolás nélkül.

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

FS-jelentés bizonyítékai, integritás és idővonal (SAPI 1.8.14)

Az 1.8.14 óta a GET /sapi/document/sent minden sora, a küldött részlet, valamint a beérkezett lista és részlet fsReport objektumot hordoz: state = reported (a jelentés átadva a C5 gyűjtőpontnak, reportedAt = fsReportedAt), pending (a jelentés esedékes, az átadás sikertelen és automatikusan ismétlődik, reason = c5_unavailable) vagy not_required (nem keletkezik jelentés; a reason megmondja, miért: cross_border, self_send_test, issuer_without_vat_id, recipient_without_vat_id, not_billing_document, tdd_disabled, before_2026_09_01, not_recorded). Átadás után megjelenik a tddMessageId (a jelentés SBDH InstanceIdentifier-e), a C5 válasza után a c5ResponseCode (AP/AB/RE), c5ResponseAt, c5Detail és az összefoglaló outcome: accepted (AP), accepted_with_reservations (AB), rejected (RE) vagy null, amíg a C5 nem válaszolt. Az outcome = rejected azt jelenti, hogy a jelentést átadtuk, de a pénzügyi igazgatóság elutasította (a c5Detail a megsértett szabályt hordozza, pl. BR-AE-08); a state reported marad, mert az átadás megtörtént, és a portál a javított jelentést automatikusan újraküldi (elfogadás után az outcome accepted lesz). A küldött sorok ezen felül statusReason-t (gépi kód a statusDetail mögött: network_retrying, network_retrying_sent, as4_receipt_only, recipient_not_registered, transport_failed, mls_rejected, validation_failed), xmlSha256-ot (az átadott XML SHA-256-ja, a tartalom törlése után is megmarad), retention-t és receiptRetention = permanent-et hordoznak (az MLS visszaigazolás soha nem törlődik). A részletben a visszaigazolásnak van mls.sha256 és mls.messageId mezője. A beérkezett bizonylatok peppolMessageId, status (received/acknowledged), receivedAt, acknowledgedAt és xmlSha256 mezőt kaptak (az üzleti dokumentum bájtjainak SHA-256-ja pontosan úgy, ahogy a links.xml kiadja, SBDH szállítási boríték nélkül; beérkezéskor számoljuk, és a tartalom törlése után is megmarad). Mindkét lista szűrhető ?fsReport=reported|pending|not_required|rejected-del (rejected = outcome rejected), a küldött ?status=undeliverable-lel is. A POST /sapi/document/send válasza már az elfogadáskor hordozza a peppolMessageId-t. Minden csak bővítés, a meglévő mezők változatlanok.

// POST { "documentIds": ["7c1e…", "9af0…", "ismeretlen"] }  (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…", "ismeretlen"] }

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. Hitelesítési hiba (SAPI-AUTH-001) esetén a boríték tartalmaz egy hint mezőt (emberi nyelven, mi tartozik a Client Id és Client Secret mezőkbe) és egy docs mezőt (link az útmutatóra; MK-soft programok közvetlenül a /navody/mksoft#prepojenie oldalra). Mindkét mező opcionális, máshol hiányzik (1.8.20).

{ "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 12× újrapróbáljuk exponenciális visszatartással (30 s → max. 8 óra, összesen kb. 16 óra), majd dead-letter. A HTTP 401/403 azt jelenti, hogy az Ön végpontja olyan hitelesítést kér, amelyet nem küldünk; ehelyett ellenőrizze a webhook-signature aláírást, és válaszoljon 2xx-szel. 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); az invoice.undeliverable olyan címzettet jelez, akinek nincs bejegyzése a Peppol hálózatban (átvéve, a FS-nek jelentve, nem kézbesítve). 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, invoice.report_pending, invoice.report_rejected, 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 12-szer ismételjük 30 s és 8 h közötti időközökkel (összesen kb. 16 óra); 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

DIČ

Szlovák adóazonosító szám (10 számjegy). A szlovák Peppol-azonosító 0245: + a DIČ számjegyei, SK nélkül.

IČ DPH

Áfa-azonosító szám (SK + DIČ). Csak áfaalanyoknak van; nem alany O adókategóriával állít ki.

IČO

Cégjegyzékszám (8 számjegy). Az API-ban ico mező, UBL-ben BT-30.

Hitelesítő adat (VÚ)

A Pénzügyi Igazgatóság aláírása, amely a szolgáltató FS-portálon történő kiválasztásakor jön létre; feloldja a cég küldését.

VPDS

Az FS alkalmazása, ahol az adóalany kiválasztja kézbesítési szolgáltatóját (minket).

TDD

Tax Data Document, a számlaadat-jelentés a Pénzügyi Igazgatóságnak; mi állítjuk össze és küldjük Ön helyett.

C5 / C6

A Peppol-modell ötödik és hatodik sarka: a Pénzügyi Igazgatóság hozzáférési pontja, amely a TDD-ket fogadja (0242:001180).

MLS

Message Level Status, a címzett hozzáférési pontjának igazolása (AP = elfogadva, RE = elutasítva, AB = nyugtázva).

SBDH

Standard Business Document Header, a boríték, amelyben a bizonylat utazik; InstanceIdentifier-e a peppolMessageId.

SML / SMP

A hálózat címtára: az SML megtalálja a címzett SMP-jét, az SMP megmondja a hozzáférési pontot és az elfogadott bizonylattípusokat.

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 fogadott bizonylatoknál mellékletenként 25 MB-ig dolgozzuk fel a mellékleteket; küldésnél a teljes XML a base64 mellékletekkel együtt SAPI-SK-n keresztül 10 MB, a portál Odoslať súborom fülén 2 MB alatt kell maradjon. 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 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)
• validate_document: UBL validálás az EN 16931 + Peppol BIS 3.0 szerint
• 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

A portálon a cég bekapcsolja saját címét: <24 véletlen karakter>@peppol.send.verteco.app. Az engedélyezett postafiókból erre a címre küldött, UBL XML mellékletű e-mailt ugyanúgy elküldjük a Peppol-hálózaton, mintha a fájlt a Küldés fájlból lapon töltötte volna fel; a feladó mellékletenként egy választ kap az eredménnyel, a bizonylat pedig a portálon és az API-ban is elérhető kézbesítési állapottal, MLS-visszaigazolással és FS-jelentéssel. Beállítás: Kapcsolatok és integrációk → Küldés e-mailben (a cég tulajdonosa vagy adminisztrátora, bejelentkezve). /dashboard/integrations/email

Feldolgozási szabályok

• Csak a cég engedélyezett feladói listáján (legfeljebb 20) szereplő címről érkező levelet fogadunk; minden mást válasz nélkül eldobunk.
• Alapértelmezetten a feladó domainjének át kell mennie az SPF- vagy DKIM-ellenőrzésen a kézbesítő szervernél (DMARC-szerű, relaxed igazítás). A kézbesítő szerver emellett elutasítja azokat a leveleket, amelyek sem SPF-en, sem DKIM-en nem mennek át, és a feladó DMARC-szabályzatát sértő leveleket. Az ellenőrzés a beállításokban kikapcsolható; nem ajánlott.
• Melléklet: UBL 2.1 Invoice vagy CreditNote (Peppol BIS Billing 3.0), .xml kiterjesztés, akár SBDH-borítékban; üzenetenként legfeljebb 10 melléklet, mellékletenként 15 MB, címenként napi 200 üzenet. PDF-et és az üzenet szövegét nem dolgozzuk fel.
• IFS Finvoice 2.0: az IFS SOAP-borítékos (IFSFinvoice) vagy csupasz Finvoice .xml mellékletet UBL-re alakítjuk, majd ugyanúgy dolgozzuk fel. Átalakítási szabályok: INV02 vagy negatív végösszeg = jóváíró számla (381) pozitív összegekkel és az eredeti számla hivatkozásával (OriginalInvoiceNumber, IFS-nél OrderIdentifier); eladó és vevő a szlovák adószám szerint (SellerOrganisationTaxCode, BuyerOrganisationTaxCode → 0245:DIČ), Szlovákián kívüli vevőt nem alakítunk át; áfabontás a VatSpecificationDetails-ből, a 0 %-os sorok E kategóriával és a VatFreeText indokával, különben „Oslobodené od DPH”; az IFS kerekítő sorai (nettó 0,00, áfa 0,01) kimaradnak, a sor összegével nem egyező egységárat újraszámoljuk; mértékegységek UN/ECE szerint (kg → KGM, pcs → H87, h → HUR, ismeretlen → C62 az eredeti szöveggel a sor megjegyzésében); a beágyazott számlakép (InvoiceAttachments, PDF) 5 MB-ig a bizonylat melléklete lesz; csak EUR. Az átalakítás eredménye a válaszban és a cég naplójában szerepel.
• Eredménycím: ha a számlákat rendszerpostafiók küldi, a beállításokban más címet adhat meg az eredményt tartalmazó válasznak (replyTo a PUT /companies/{id}/email-send kérésben, üres = válasz a feladónak).
• Az XML-ben az eladó (szállítói EndpointID, BT-34) ez a cég kell legyen, különben az üzenetet elutasítjuk (a saját szállítójától továbbított számla soha nem megy ki az Ön számlájaként). A vevőnek sémával ellátott EndpointID-vel kell szerepelnie (BT-49).
• Ugyanaz az üzenet (Message-ID) egyszer kerül feldolgozásra. A bizonylat az API-ban és a webhookokban origin = email jelölést visel, a szereplő = a feladó címe.

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.

Már éles üzemben (gyakran hiányzónak hitt)

• A POST /companies/{id}/documents/send stabil portálfelület; ERP-integrációkhoz továbbra is a SAPI-SK ajánlott Idempotency-Key-jel.
• Az SMP-regisztráció az FS-portálon történő választás után automatikus; átállás másik szolgáltatótól a POST /companies/{id}/smp-migrate végponttal, migrációs kóddal.
• MLS-igazolások, kézbesítési bizonyítékok és FS-jelentések (fsReport) a /sapi/document/sent minden sorában; webhook-visszajátszás időablakra.
• Kiválasztott cégekre szűkített kulcsok; MCP-szerver AI-asszisztenseknek; UBL-minták a /vzory oldalon; nyilvános validátor.

Előkészületben (az integrátori igények sorrendjében)

• Aszinkron kötegelés: a POST /sapi/document/batch 202-vel válaszol, job-hivatkozással és tételenkénti állapottal.
• Változásfolyam GET /sapi/document/changes?since&cursor kurzorral az offset-lapozás helyett.
• API-kulcsok lejárata és forgatása a portálon, csak olvasható kulcs.
• Több webhook-végpont cégenként eseményszűrővel.