Közvetítőknek: a partnermodell

Mi jár egy hagyományos multi-tenant fióknak

• Egy API-token a fiók minden cégéhez (X-Peppol-Participant-Id fejléc a SAPI-SK-ban).
• Cégenként beállított értesítő webhook (GET/PUT /api/v1/companies/{id}/notifications) ugyanazzal az X-Verteco-Signature aláírással.
• Saját cég kijelentkeztetése (POST /api/v1/companies/{id}/deregister) és cégenkénti felhasználás (GET /api/v1/companies/usage).
• A cégeket mindig a tulajdonosuk kezeli, nem egy partner: egyoldalú ügyfélleválasztás és küldési fék a hagyományos modellben nincs.

Így lehet közvetítővé válni

A kérelmet a Legyen digitális postás oldalon tölti ki; a Pénzügyi Igazgatóság nyomtatványát mi írjuk alá és nyújtjuk be Ön helyett. A díj évente 99 € áfa nélkül. Miután megjelenik a Pénzügyi Igazgatóság választékában, az ügyfelek az Ön márkája alatt választják Önt, cégeik automatikusan az Ön partneri fiókja alatt jönnek létre, és bejegyzésre kerülnek a központi SMP-be, hacsak bejegyzésüket nem tartja másik szolgáltató (ekkor megkapja a company.smp_registered_elsewhere eseményt és a migrációs kódos eljárást). A tesztkörnyezetben a közvetítői regisztráció díjmentes, és azonnal kap egy teszt partneri végpontot.

• Legyen digitális postás (kérelem)
• Közvetítői üzleti feltételek
• Közvetítőink
• Ügyfél másik szolgáltatótól: migrációs kód (útmutató)
• Szerződések: ÁSZF, DPA, SLA, NDA

Ha számlázó alkalmazást, ERP-t vagy platformot üzemeltet, és több ügyfelét (tenant) szeretné rajtunk keresztül a Peppolhoz kötni, egyszer integrál, és N céget szolgál ki. A modell proxy: a backendje egy API-tokent (vpt_…) tart kizárólag szerveroldalon (soha a böngészőben), és minden tenantja = egy cég nálunk (egy token → N cég). A bővített nyilvános útmutató mintakóddal, webhook-aláírásokkal és go-live ellenőrzőlistával: peppol.verteco.digital/saas.

Biztonság az ügyfelei számára: a Szlovák Pénzügyi Igazgatóság tanúsított szolgáltatója vagyunk (EFSK000031), saját hozzáférési ponttal; az ISO/IEC 27001:2022 tanúsítás folyamatban van a 2026 szeptemberében kiválasztott, akkreditált SKQS, s. r. o. (Zsolna, SNAS) szervezetnél, a tanúsítványt 2027. július 1-jéig tervezzük; az OpenPeppol 2027. október 1-jétől minden szolgáltatótól megköveteli, jelenleg még senkinek nem kell birtokolnia. A szerződések (ÁSZF, DPA, SLA, NDA) teljes terjedelmükben a /zmluvy oldalon, a rendelkezésre állás a /status oldalon található.

1. 1

   Egy token, szerveroldalon

   Hozzon létre egy API-tokent, és tartsa biztonságos backend környezetben. Minden hívást a szervere végez (Bearer), nem az ügyfél böngészője.
2. 2

   Tenant felvétele = cég létrehozása

   Minden ügyfélhez hívja meg a POST /companies végpontot a cégazonosítójával (IČO) / adószámával (IČ DPH); a válasz { id, status: "pending_verification" }; tárolja az id-t a tenanthoz (részletek: Cégek).

   bashKopírovať

   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":"Firma s.r.o.",
        "street":"Príkladná 12","postalCode":"010 01","city":"Žilina","iban":"SK…"}'

3. 3

   Aktiválás a Peppolban (az ügyfél lépése az állam felé)

   pending_verification ≠ élő a Peppolban. Ahhoz, hogy egy cég fogadjon, az ügyfél a Pénzügyi Igazgatóság (Finančná správa, FS) portálján szolgáltatóválasztással aktiválja, eID-vel vagy a PI-portál belépési adataival bejelentkezve. Ön bejegyzett közvetítő: az ügyfél az Ön választási linkjén (vpdsUrl mező a GET /api/v1/resellers/me válaszában) az Ön márkáját választja, nem közvetlenül a Vertecót, mert a Verteco közvetlen választása kiveszi a céget az Ön programjából (company.released_to_direct esemény). Az FS a választást az Ön webhookjára küldi, Ön továbbítja nekünk (FS webhook fejezet), mi pedig aktiváljuk a céget, bejegyezzük az SMP-be, és elküldjük Önnek a company.activated eseményt. Ön nem bejegyzett közvetítő: az ügyfél a Vertecót választja szolgáltatónak, a többi ugyanígy zajlik. Az ellenőrzött választás egyben feljogosítja a céget a küldésre. Ha a Verteco közvetlen választása nem jutott el hozzánk, a tartalék út a Küldési ellenőrzés (POST /companies/{id}/verification). Ha az ügyfélnek már volt másik szolgáltatója, a cég a választás után aktiválódik, de az SMP-bejegyzést a régi postás tartja, és migrációs kód szükséges: lásd a fejezetet Ügyfél érkezik másik szolgáltatótól.
4. 4

   Számlák fogadása: webhook tenantonként

   Állítson be webhookot (és/vagy e-mailt) minden céghez, és kérje le az aláíró titkot:

   bashKopírovať

   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://vasa-saas.sk/peppol/webhook","notificationEmail":"…"}'
   
   curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
   # → { "secret": "…" }   (store it to verify X-Verteco-Signature)

   Számla beérkezésekor aláírt POST-ot kap (esemény: invoice.received; ugyanígy invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported, invoice.report_pending, invoice.report_rejected és company.* minden ügyfelére), tartós újrapróbálkozással/dead-letterrel. Az aláírás ellenőrzése, a payload és az „Otestovať webhook" (Webhook tesztelése) gomb: Értesítések és webhookok.
5. 5

   Számlák küldése

   A számlát (UBL Peppol BIS 3.0) a nemzeti SAPI-SK 1.0 interfészen küldi: POST /sapi/document/send (OAuth2 client_credentials, client_secret = az Ön vpt_ tokenje). A szlovák adójelentést (TDD/C5) automatikusan hozzáadjuk.
6. 6

   Felhasználási adatok a továbbszámlázáshoz

   A GET /companies/usage?month=YYYY-MM visszaadja az elküldött és beérkezett bizonylatok számát minden cégére külön és összesítve, pontosan azokban az egységekben, amelyekre az árlista épül, így közvetlenül ebből számlázhatja tovább ügyfeleit. Paraméter nélkül az aktuális hónapot adja; az időszak félig nyitott, és a válasz kifejezetten tartalmazza a from/to mezőket, így nem kell a hónaphatárt találgatni. A forgalom nélküli cégek nullákkal szerepelnek.
7. 7

   Skálázás és robusztusság

   Lapozza a listákat: GET /companies?page&limit és GET /companies/{id}/documents?page&limit (fejlécekkel, például X-Total-Count és társai). Tartsa be a tokenenkénti kérésszám-korlátot: tömeges felvételnél kötegeljen, 429 esetén backoffal (Retry-After), és kezelje a 409 ico_taken választ (idempotensen).

Ha közvetítőként (sprostredkovateľ) van bejegyezve (kérelem a /sprostredkovatel/ziadost oldalon), a Pénzügyi Igazgatóság (Finančná správa, FS) minden alkalommal értesítést küld az Ön webhook URL-jére, amikor egy ügyfél kiválasztja Önt az FS portálján (VPDS). Ez a kézikönyv a pontos kontraktust írja le, ahogyan az FS éles környezetben ténylegesen hívja (élő választásokon ellenőrizve). Az FS nem tesz közzé saját nyilvános webhook-kézikönyvet; az implementációhoz erre van szüksége.

1 · Hogyan néz ki az értesítés + 2 · hitelesség ellenőrzése

3 · Mit tegyen vele: továbbítsa nekünk a nyers törzset

A közvetítői bejegyzés saját rendszert feltételez, amely fogadja az ügyfelek választásait és továbbítja nekünk. Ne a mi címünket írja az FS űrlapjára: az FS-nek Önt kell hívnia. Saját rendszer nélkül Ön nem közvetítő; a helyes út a saját jelölésű regisztrációs oldal és a jutalék (/affiliate).

Az ajánlott (és legegyszerűbb) megvalósítás a nyers bájtos proxy: fogadja a POST-ot, válaszoljon gyorsan, és továbbítsa a törzs nyers bájtjait a nálunk lévő regisztrációs végpontjára. Ez a végpont automatikusan létrejön, amikor kitölti a /sprostredkovatel/ziadost űrlapot, azonnal aktív, és pontos URL-jét (az Ön kulcsával) bejelentkezés után a GET /api/v1/resellers/me hívással látja:

POST https://peppol.verteco.digital/peppol/webhook/reseller/{vas-kluc}
Content-Type: application/json
x-pds-secret: <az FS-kérés változatlan értéke>
(body = az FS-től érkező változatlan nyers bájtok)

Kriptográfiailag ellenőrizzük a verification_tokent, automatikusan létrehozzuk a céget az Ön partneri fiókja alatt (white-label), bejegyezzük a központi SK SMP-be, és attól a pillanattól e-számlákat kézbesítünk neki. A payloadban lévő kapcsolattartási adatokat saját felvételi folyamatához eltárolhatja; több nem szükséges. Kivétel: ha az alanynak már volt másik szolgáltatója, az SMP-bejegyzés nála marad, és tőlünk company.smp_registered_elsewhere eseményt és e-mailt kap; a megoldást külön fejezet írja le. A company.client_registered_directly esemény akkor érkezik, ha az ügyfele közvetlenül a Verteco portálon adja hozzá a cégét: linked = true azt jelenti, hogy fiókját társtulajdonosként hozzákapcsoltuk (a cég kapcsolattartói e-mail-címe egyezett), false csak tájékoztatás a kísérletről (naponta legfeljebb egyszer); az ügyfélkapcsolaton és a számlázáson semmi sem változik. A company.released_to_direct esemény akkor érkezik, ha ügyfele a Pénzügyi Igazgatóság portálján közvetlenül a Vertecót választja: a cég ezzel kilép az Ön programjából (fiókjai elveszítik a hozzáférést, a white-label megszűnik, a kiválasztás kapcsolattartója a tulajdonos); az ügyfelet a portálból értesítjük, Ön e-mailt is kap. A 2026. 9. 21-től tett kiválasztásokra érvényes. Az ellenkező irány, az Ön márkája alatti kiválasztás egy olyan cégre, amely már az Ön partnerfiókjához tartozik (például a közvetlen ügyfélként felvett saját cége), nem regisztrálja újra a céget: a hozzáférési pont és a központi SMP-bejegyzés változatlan marad (az ismételt regisztráció csak megerősítés), a cég csupán white-label módba kapcsol, ettől kezdve nem kap tőlünk e-mailt a bizonylatokról, ezekről csak webhookon és az API-n keresztül értesül, és a partnermodell szerint számlázzuk; az archívum és a beállítások megmaradnak. Ez kényelmes mód az integráció saját cégen való ellenőrzésére.

Szállítási kulcs (x-pds-secret fejléc): a bejegyzés közzététele után az FS a WebhookSecret_Verteco_<név>.zip fájlt e-mailben a kérelmezőnek, vagyis nekünk küldi, a jelszavát pedig SMS-ben arra a telefonszámra, amelyet a /sprostredkovatel/ziadost űrlapon megadott (a 2026. 9. 17-i FS űrlapon erre külön mező van), vagyis Önnek. A zipet a partnerkonzol FS webhook lapján töltheti le (FS zip letöltése gomb), az SMS-ben kapott jelszóval nyissa meg, a szöveges fájlban lévő 32 karakteres kulcsot pedig ugyanott adja meg, ahol később meg is jelenítheti vagy .txt-ként letöltheti (minden megjelenítés bekerül fiókja auditnaplójába). Ha az SMS nem érkezett meg, írjon nekünk. A 2026. 9. 17. előtt benyújtott bejegyzéseknél a jelszó hozzánk érkezett, és a kulcsot mi mentettük el. A kulcs mentésétől kezdve ellenőrizzük, hogy minden hívás sha512(törzs + kulcs) aláírása egyezik. Amíg a kulcs nincs megadva, az aláírást csak rögzítjük. Mentéskor a kulcsot összevetjük azokkal a hívásokkal, amelyeket az FS már elküldött a végpontjára, és az ezekkel ellentmondó kulcsot elutasítjuk; a proxyjának ezért bájtról bájtra kell továbbítania a törzset (JSON újraszerializálás nélkül).

3a · Mit válaszol a végpontunk

A hívást azonnal (szinkron módon) feldolgozzuk. A 200-as válasz törzse szándékosan nem árulja el, hogy a token érvényes volt-e, és aktiváltunk-e céget, így a végponttal nem lehet kideríteni, melyik DIČ az ügyfelünk. Az eredményt a company.activated eseményből tudja meg az értesítési webhookján, és bármikor lekérdezheti a GET /api/v1/resellers/me/clients hívással (active állapot, kitöltött peppolParticipantId).

Ha egy 200-as válasz után néhány percen belül nem érkezik company.activated, küldje el nekünk a hívás időpontját; minden hívást megőrzünk a tartós auditnaplóban.

3b · A kérés ellenőrzése Önnél a továbbítás előtt

Javasoljuk, hogy a proxy minden kérést a továbbítás előtt ellenőrizzen. Így csak valódi FS-választásokat küld nekünk, a véletlen vagy hamisított hívások pedig nem fogyasztják a keretét.

1. Először mentse el a teljes kérést (nyers törzs és fejlécek). Az FS egy választást soha nem küld újra, a mentett másolat az egyetlen mód a helyreállítására.
2. Ellenőrizze az x-pds-secret fejlécet: egyeznie kell a hex(SHA-512(nyers törzsbájtok + az Ön FS-kulcsa)) értékkel, 128 hexadecimális karakter. A hash-t a törzsből pontosan úgy számolja, ahogy megérkezett, JSON-feldolgozás előtt; a kulcsot elválasztó nélkül közvetlenül a törzs után fűzze; állandó idejű összehasonlítást használjon, a kis- és nagybetűket figyelmen kívül hagyva.
3. Csak az egyező kéréseket továbbítsa, változatlan törzzsel és az eredeti x-pds-secret fejléccel. A 64 KB feletti törzseket dobja el; egy FS-választás kb. 1 KB.

import crypto from 'node:crypto';

// rawBody = Buffer a törzzsel pontosan úgy, ahogy megérkezett (pl. express.raw({ type: '*/*' }))
function isFromFs(rawBody, header, fsKey) {
  const expected = crypto.createHash('sha512')
    .update(Buffer.concat([rawBody, Buffer.from(fsKey, 'utf8')]))
    .digest('hex');
  const got = String(header || '').trim().toLowerCase();
  return got.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

Ugyanez az ellenőrzés PHP-ban, Pythonban és C#-ban:

<?php
// $rawBody = file_get_contents('php://input'); $header = $_SERVER['HTTP_X_PDS_SECRET'] ?? null;
function isFromFs(string $rawBody, ?string $header, string $fsKey): bool
{
    $expected = hash('sha512', $rawBody . $fsKey);
    $got = strtolower(trim((string) $header));
    return hash_equals($expected, $got);
}

import hashlib
import hmac

# raw_body = a törzs bájtjai pontosan úgy, ahogy megérkeztek (Flask: request.get_data(), FastAPI: await request.body())
def is_from_fs(raw_body: bytes, header: str | None, fs_key: str) -> bool:
    expected = hashlib.sha512(raw_body + fs_key.encode("utf-8")).hexdigest()
    got = (header or "").strip().lower()
    return hmac.compare_digest(expected, got)

using System.Security.Cryptography;
using System.Text;

// rawBody = a törzs bájtjai pontosan úgy, ahogy megérkeztek (ASP.NET Core: a Request.Body-t bármilyen JSON-olvasás előtt másolja MemoryStreambe)
static bool IsFromFs(byte[] rawBody, string? header, string fsKey)
{
    byte[] key = Encoding.UTF8.GetBytes(fsKey);
    byte[] data = new byte[rawBody.Length + key.Length];
    Buffer.BlockCopy(rawBody, 0, data, 0, rawBody.Length);
    Buffer.BlockCopy(key, 0, data, rawBody.Length, key.Length);
    string expected = Convert.ToHexString(SHA512.HashData(data)).ToLowerInvariant();
    string got = (header ?? "").Trim().ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(got));
}

• Kulcs: ugyanaz az FS-kulcs, amellyel mi ellenőrizzük az aláírást (az FS zipjéből, amelyet az SMS-ben kapott jelszóval nyit meg); megadása után a partnerkonzol FS webhook lapján jelenítheti meg. Csak a szerveren tárolja. Ha Önnél egyezik, nálunk is egyezik.
• Más mechanizmus nincs: az FS a szállítást nem írja alá aszimmetrikus kulccsal, a fejléchez nincs nyilvános kulcs. A törzsben lévő verification_token az FS aláírása az adószámok felett; ezt mi ellenőrizzük az FS tanúsítványával, Ön csak változatlanul továbbítja.
• Keret: az egy IP-címről percenként 600 hívás minden /peppol/webhook/… hívásra vonatkozik, érvényesre és érvénytelenre is. Az érvényes fejléc nélküli hívás nálunk 403-at kap és semmi sem kerül feldolgozásra, a spam viszont az Ön szerverének keretét fogyasztaná.
• Ha az aláírás már az első valódi választásnál nem egyezik, ne dobja el a kérést: mentse el és írjon nekünk, az okot közösen megtaláljuk.

4 · Üzemeltetési szabályok (fontos)

• Idempotencia: ugyanaz a szervezet megismételheti a választást; ugyanazon DIČ (szlovák adószám) feldolgozásának biztonságosnak kell lennie (a mi oldalunkon az).
• Ha a továbbítás meghiúsul (például 403 vagy a szervere kiesése), az FS nem ismétli meg a választást. Küldje el nekünk újra a mentett eredeti törzset az eredeti x-pds-secret fejléccel; a feldolgozás idempotens, és a cég aktiválódik. Ha a hívást nem mentette el, írjon nekünk.
• Forrás-IP: a hívások az FS infrastruktúrájából jönnek (megfigyelt cím: 194.1.2.13); az IP-engedélyezési listát csak kiegészítésként ajánljuk, nem egyedüli védelemként (az FS nem garantálja a tartományt).
• Válasz: belső feldolgozási hiba esetén is adjon 200-at (a hibát maga naplózza); az FS mást nem értékel ki.
• Telepítési sorrend: a webhooknak azelőtt kell élnie, hogy a kérelmet benyújtják az FS-nél; az első választás röviddel a közzététel után megérkezhet.

Egy referencia proxy-implementáció ~30 sor (POST fogadása → mentés → nyers bájtok továbbítása). Az URL-t egy GET hívással ellenőrzi a regisztrációs végponton (válasz: ready). Miután a kulcsát elmentettük, egy érvényes x-pds-secret fejléc nélküli teszt-POST 403-at kap, és nem hoz létre semmit; a teljes láncot a cég aktiválásával együtt a test.peppol.verteco.digital tesztkörnyezetben próbálhatja ki (szimulált választás a /register-vpds-test oldalon; a közvetítői bejegyzés ott díjmentes, és nem kell benyújtani az FS-hez, a POST /companies hívással létrehozott cég azonnal aktív, a szimulált választás pedig úgy érkezik az Ön webhookjára, mint az FS-től). Kérdések: Ügyfélszolgálat.

5 · A közvetítői szerződés felmondása

A közvetítői szerződés közvetlenül az alkalmazásból is felmondható: a partneri fiók tulajdonosa a Nastavenia poštára (Postás beállításai) oldalon kitölti a felmondási kérelmet (ellenőrző kérdés + a következmények megerősítése), és az e-mailben kapott hivatkozással megerősíti a felmondást. A megerősítéssel a felmondás kézbesítettnek minősül; a felmondási idő egy hónap, és a következő hónap 1. napjától fut (a Közvetítői üzleti feltételek 7.1. cikke). A közvetítői listáról való törlés iránti kérelmet a szerződés megszűnése után 5 munkanapon belül mi nyújtjuk be a Pénzügyi Igazgatóságnál (7.3. cikk); csapatunk kapja az igazoló feljegyzést, a közvetítő ügyfeleinek semmit nem küldünk. A még meg nem erősített kérelem az alkalmazásban visszavonható. Programozottan: GET/POST/DELETE /api/v1/resellers/me/termination.

6 · Hogyan oszlik meg a felelősség

A Közvetítői üzleti feltételek (v1.8) 5. cikkének összefoglalója, hogy tudja, mit várunk Öntől a gyakorlatban. Az ügyfele bizonylatának puszta technikai továbbításából Önnek sem kötbér, sem kártérítési felelősség nem keletkezik, és nem köteles ellenőrizni az egyes bizonylatok gazdasági valóságát vagy tartalmi helyességét (5.8. cikk). A Pénzügyi Igazgatóság portálján eID-vel vagy belépési adatokkal megerősített választás az általunk ellenőrzött igazoló adattal (Verifikačný údaj) együtt elegendő igazolása a cég nevében való eljárás jogosultságának, és az API-hozzáférés biztosítása a saját ügyfelei számára nem minősül harmadik személy számára történő hozzáférhetővé tételnek (5.9. cikk). A kötbér felső határa eseményenként vagy egy okra visszavezethető szabályszegés-sorozatonként 5 000 EUR, naptári évenként 10 000 EUR (5.3. cikk). A hatóságok vagy a Peppol hálózat szervei által az Ön érdekkörébe tartozó magatartás miatt nekünk ténylegesen kiszabott szankciókat és intézkedéseket továbbra is felső határ nélkül továbbhárítjuk (5.2. cikk), mert ezeket a Pénzügyi Igazgatósággal és az OpenPeppollal szemben korlátlanul mi viseljük. Az igény azonban a saját részünk arányában csökken, mellékeljük a mögötte álló határozatot és írásos kimutatást, Önnek 15 nap áll rendelkezésére az észrevételre, a törölt vagy csökkentett szankciót felszólítás nélkül is 15 napon belül visszatérítjük, és az azt előidéző ügyféllel szembeni követeléseinket a dokumentumokkal együtt Önre engedményezzük (5.5. és 5.7. cikk). Ezért kéri a 4.1. cikk h) pontja, hogy a megfelelő kötelezettségeket vegye át az ügyfeleivel kötött szerződésekbe, és vezessen nyilvántartást arról, ki melyik bizonylatot hozta létre; a mintaklauzulát kérésre díjmentesen elküldjük.

Partneri értesítő webhook (közvetítők)

Ha bejegyzett közvetítő (sprostredkovateľ), nem kell minden céghez külön webhookot beállítania: egyetlen partneri értesítő webhook kapja a partneri fiókja alatti cégek minden eseményét, és elsőbbséget élvez az egyes cégek webhookjaival szemben. Ügyfelei így semmit nem állítanak be; a céget a companyDic / peppolParticipantId alapján különbözteti meg.

E-mailek az egyes számlákról: a partneri fiók tagja minden ügyfélcégnek, így a fiók alapbeállításaival minden egyes cég minden beérkezett számlájáról e-mailt kapna. A white-label ügyfeleknek sosem küldünk e-mailt (a csatorna a webhook); a többi cégnél a partneri fiók számára a Nastavenia poštára (Postás beállításai) → Értesítések alatt kapcsolja ki (egy kapcsoló; ugyanez a beállítás a fiók Beállítások → Értesítések alatt is megtalálható).

// 200 OK (első beállítás)
{ "url": "https://vasa-appka.sk/peppol/events", "secret": "vpt_…", "hasSecret": true,
"events": ["company.activated","company.deactivated","company.smp_registered_elsewhere","company.client_registered_directly","company.released_to_direct","invoice.received","invoice.sent","invoice.delivered","invoice.rejected"] }

Az X-Verteco-Signature aláírás ugyanúgy számítódik, mint a céges webhooknál (lent), csak a partneri titokkal.

Ügyfelek kezelése az API-n keresztül (egyoldalú leválasztás és küldési fék)

A partnertől távozó ügyfél általában semmit nem tesz, ezért ezek a műveletek egyoldalúak, és nem igénylik az ügyfél közreműködését. A számlák fogadását nem érintik: az a cég központi SMP-beli bejegyzéséhez kötődik, nem a kezelő fiókhoz.

Partneri számlázási modell

A Nastavenia poštára oldalon, Fakturácia fül (és a GET/PUT /api/v1/resellers/me/billing hívással) választja ki a számlázási modellt (a választás csak bejegyzett közvetítőknek érhető el): per_company = 2 € havonta minden aktívan küldő cégazonosítóra (IČO), vagy per_document = 0,01 € minden, a cégei által elküldött számláért (a beérkezett bizonylatok ingyenesek), havi minimum 300 € + áfa számlázással; a havi 1 000 bizonylatos limit a per_document modellben nem érvényes, minden elküldött számlát az elsőtől számlázunk (a jóváírás is elküldött bizonylat), a beérkezettek korlát nélkül ingyenesek. A modellváltás mindig a következő hónap 1. napjától lép hatályba (a válaszban pendingModel és pendingFrom); mindkét hívás válasza az aktuális hónap újraszámítását is visszaadja mindkét modell szerint, így tájékozottan vált.

Kalkulátor: hogy az Ön cég- és bizonylatszámánál melyik modell olcsóbb, az éves összeggel, bejegyzéssel és áfával együtt, a /sprostredkovatel oldalon számolhatja ki (Kalkulačka szakasz).

Havi fogyasztási kimutatás ügyfelenként: a GET /api/v1/resellers/me/usage?month=YYYY-MM (paraméter nélkül az előző hónap) minden, az Ön fiókja által birtokolt, az Ön márkája alatti cégre visszaadja az elküldött és fogadott bizonylatok számát, az 1 000-es limit feletti bizonylatokat (elküldött és fogadott együtt), az összeget az A modellben (2 € minden cégért, amely a hónapban bizonylatot küldött, plusz 0,01 € minden limit feletti bizonylatért; az archívumot az Ön márkája alatti cégnek soha nem számlázzuk) és a B modellben (0,01 € elküldött bizonylatonként), mindkét modell összegét a B modell 300 €-s minimumára való kiegészítéssel, valamint az adott hónapban Önre érvényes modellt (appliedModel); a közvetlen cégek, amelyeknek a fiókja tagja, a saját keretükből fizetnek, és nem szerepelnek a kimutatásban. Az összegek centben, áfa nélkül értendők, a havi elszámolással azonos módon, de a cégek lekérdezéskori aktuális állapotából számolva (kötelező érvényűek az Ön keretében szereplő elszámolási tételek), és a limit feletti cégeknél eltérnek az aktuális hónap előnézetétől a GET /resellers/me/billing hívásban, amely az A modellt 2 € × aktív cég szerint számolja. A ?format=csv paraméterrel ugyanezt kapja fájlként a könyvelés számára (UTF-8 BOM-mal, pontosvessző elválasztó, szlovák fejlécek, tizedesvesszős összegek, utolsó sor Spolu), a partneri konzolban pedig a kimutatás a Fogyasztás fülön érhető el az utolsó 12 hónap kiválasztásával.

Ajánlott eljárás megszűnt ügyfélnél (költségplafon az Ön oldalán): az aktuális felhasználást a GET /api/v1/companies/usage?month=YYYY-MM (elküldött/beérkezett bontás cégenként, pontosan a továbbszámlázáshoz) és a GET /api/v1/resellers/me/clients (az aktuális hónap darabszámai) mutatja; emellett a partneri webhookra minden, a cégei által küldött vagy fogadott bizonylatról esemény megy, így a „megszűnt” céget már az első bizonylatánál észreveszi. Ezután egyszerűen hívja meg a pause-sending vagy release végpontot.

A partner saját portáljához vagy alkalmazásához ajánlott folyamat (a 2026. októberi partneri kérdések alapján):

1. A bizonylatok másolatait tartsa magánál. Az Ön márkája alatti cégeknél az Adatarchívum alapértelmezetten ki van kapcsolva, így a bizonylat tartalma (XML, PDF) nálunk a kézbesítés után 14 napig marad meg, majd törlődik; a kézbesítési bizonyítékok (igazolás, időbélyegek, bejelentési állapot) megmaradnak. Az Ön portálja ezért a saját másolatából olvas, és tőlünk csak az új bizonylatokat tölti le.
2. Új bizonylatok webhookon, nem lekérdezéssel. A partneri értesítési webhook (fent) minden céghez megkapja az invoice.received eseményt; a bizonylatot a GET /sapi/document/receive/{id} hívással tölti le (az XML, PDF, HTML és a mellékletek saját útvonallal rendelkeznek), és a POST /sapi/document/receive/{id}/acknowledge hívással nyugtázza. Tartalék út a lapozott olvasás, GET /sapi/document/receive?status=received&limit=200 a pageToken paraméterrel (legrégebbi elöl; a nyugtázott bizonylatok kiesnek a szűrőből).
3. A küldött bizonylatok állapotai szintén webhookon érkeznek (invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported), és lekérdezhetők a GET /sapi/document/sent hívással.
4. Saját domain az ügyfeleknek. Az Ön alkalmazása saját hídon keresztül (például api.sajat-domain.sk) hívhatja az API-nkat egyetlen partneri kulccsal a fiókja alatti összes céghez; az ügyfeleknek soha nincs szükségük a mi címünkre, a webhookokat az Ön oldaláról továbbítja nekik.
5. Limitek. API-kulcsonként 300 hívás percenként, a RateLimit-* fejlécek adják vissza a maradékot; magasabb limitet kérésre állítunk be. A havi 1 000 bizonylat cégenkénti limitje az A modellben érvényes (küldött és fogadott együtt, minden további bizonylat 0,01 €); a B modellben nem érvényes.

Melyik díjazási modell: a B modell (0,01 € küldött bizonylatonként, havi minimum 300 €, a fogadottak ingyenesek) csak akkor olcsóbb az A modellnél (2 € minden olyan cégért, amely a hónapban bizonylatot küldött), ha egy hónapban több mint 150 cég küld, és egy küldő cégre átlagosan kevesebb mint 200 küldött bizonylat jut (150 cég = legfeljebb 30 000 bizonylat, 300 cég = legfeljebb 60 000); a modellt a partneri konzolban váltja, a következő hónaptól hatályosan.

Az ügyfél Adatarchívuma a partneri API-n keresztül: ha az Ön portáljának be vagy ki kell kapcsolnia egy ügyfél archívumát, nem kell az ügyfelet a mi portálunkra küldenie.

Mit jelent a bekapcsolt archívum az Ön márkája alatti cég árára nézve, pontosan az elszámolási kód szerint: a bekapcsolt Adatarchívum a közvetítő márkája alatti cégnél soha nem indítja el a 2 €-s alapdíjat, így az A modellben csak azért a hónapért fizet 2 €-t, amelyben a cég bizonylatot küldött, plusz 0,01 €-t minden 1 000 feletti bizonylatért (elküldött és fogadott együtt), a B modellben pedig 0,01 €-t elküldött bizonylatonként; az archívum bekapcsolása tehát csak azt változtatja meg, meddig őrizzük az eredetiket (a szerződés időtartamára a határidő helyett), az összeget nem. A tárhelyet éjszakánként egyszer mérjük, a 80 %-nál és az újabb megkezdett GB-nál küldött értesítések a partner kapcsolattartói e-mail-címére mennek (ennek hiányában a bejegyzés tulajdonosának), soha nem az ügyfélnek; a havi elszámolásban nincs tárhelytétel. Az archiveReceived, archiveSent, wipeDaysReceived, wipeDaysSent és storageUsedBytes mezők minden cégnél a GET /resellers/me/clients válaszban is láthatók.

Szlovákiában egy központi SMP van minden postás számára, és minden résztvevőnek egy bejegyzése van benne. Amikor ügyfele az FS-portálon az Ön márkáját választja, mi igazoljuk és aktiváljuk a céget, de ha bejegyzését még a korábbi szolgáltató tartja, a hálózat továbbra is neki kézbesít. Az átállást egyszer használható migrációs kód végzi, amelyet az ügyfél a jelenlegi postásától kap (az SML szabványos mechanizmusa, PI GYIK 46. példa; a PA SK szabályai szerint a régi postásnak a szerződés megszűnése után 3 munkanapon belül ki kell jelentkeztetnie az ügyfelet a központi SMP-ből). Megjegyzés: a PI GYIK (36. és 73. példa) szerint az ügyfél fogadhat továbbra is másik postásnál, és Önön keresztül csak küldhet; ha ez a szándék, hívja a PUT /resellers/me/clients/{id}/receiving-provider végpontot elsewhere=true értékkel (állapot: smpState = "external"), és az emlékeztetők és az automatikus regisztráció is leáll. Ez a fejezet bemutatja, hogyan ismerje fel, tárolja és oldja meg a helyzetet a platformjában, és mit kap tőlünk közben.

1. 1

   Készítse elő a fogadót: partneri webhook

   Egy webhookot minden ügyfeléhez a PUT /resellers/me/notification-webhook végponton állít be (fent). Ellenőrizze az X-Verteco-Signature aláírást, és dolgozza fel a company.smp_registered_elsewhere eseményt: jelentése „másik szolgáltató tartja a bejegyzést, migrációs kód szükséges“. Deduplikáljon companyId + event szerint; az esemény hetente ismétlődik, amíg az ügyfél be nem írja a kódot.

   jsonKopírovať

   // POST az Ön webhookjára, fejlécek: X-Verteco-Event + X-Verteco-Signature
   {
     "event": "company.smp_registered_elsewhere",
     "occurredAt": "2026-09-03T15:04:05Z",
     "companyId": "bb6eb4a7-1a98-48fe-97e6-e5abbaa56e54",
     "companyDic": "SK1028310426",
     "peppolParticipantId": "0245:1028310426",
     "status": "active",
     "action": "migration_code_required",
     "migrateUrl": "https://peppol.verteco.digital/dashboard/companies/migrate"
   }

2. 2

   Egészítse ki lekérdezéssel: mikor kérdezzen, mit olvasson

   A webhook hiányozhat (még nincs beállítva) vagy kimaradás alatt elveszhet, ezért az állapotot olvassa is: a GET /resellers/me/clients minden cégnél visszaadja az smpRegistered és smpState mezőt; a részletek a GET /companies/{id} válaszban vannak. Ajánlott ritmus: naponta egyszer minden ügyfélre, az ügyféloldal megnyitásakor az alkalmazásában, és 2–3 perccel a company.activated esemény után (az SMP-regisztráció általában egy percen belül lezajlik). Ügyfél létrehozása előtt érdemes a GET /public/peppol-check?id=0245:<DIČ>: ha az adószám már a hálózatban van, az ügyfélnek kódra lesz szüksége, és ezt előre elmondhatja.

   smpState	Jelentés	Teendő
   registered	Az SMP-bejegyzés a mi fiókunk alatt van, a hálózat hozzánk kézbesít.	Semmi, az ügyfél fogad.
   pending	A regisztráció folyamatban (másodpercek; SMP-kimaradásnál órák; automatikusan ismételjük).	Várjon, néhány perc múlva olvassa újra.
   elsewhere	Másik szolgáltató tartja a bejegyzést; az ügyfélnek migrációs kód kell.	Mutasson felhívást az ügyfélnek, szerezze meg a kódot, hívja az smp-migrate végpontot (4. lépés).
   rejected	Az FS ellenőrző tokent elutasították.	Az ügyfélnek meg kell ismételnie a választást az FS-portálon.
   null	Nem alkalmazható (a cég még nincs igazolva FS-választással).	Vezesse az ügyfelet az FS-portálon történő választáshoz.

3. 3

   Tárolja az állapotot saját oldalán

   Minden ügyfélhez tárolja: companyId, peppolParticipantId, smpState, smpStateAt (mikor látta utoljára) és noticeShownAt (mikor értesítette az ügyfelet). elsewhere esetén jelenítsen meg tartós figyelmeztetést az alkalmazásában a kód beírására szolgáló mezővel; a küldést ne tiltsa le, a cég küldhet. registered esetén vegye le a figyelmeztetést.

   textKopírovať

   // az esemény feldolgozása az Ön backendjében (pszeudokód)
   on webhook(event):
     verify X-Verteco-Signature == sha256=HMAC(secret, rawBody)   // else 401
     if event.event == "company.smp_registered_elsewhere":
         tenant = tenants.byCompanyId(event.companyId)
         tenant.smpState = "elsewhere"; tenant.smpStateAt = event.occurredAt
         showBanner(tenant, "Vyžiadajte si migračný kód od doterajšieho poskytovateľa")   // + input
     if event.event == "company.activated":
         schedule(in 3 min): tenant.smpState = GET /companies/{id}.smpState
   
   daily job:
     for row in GET /resellers/me/clients: tenants[row.companyId].smpState = row.smpState
   
   on code entered by the client:
     r = POST /companies/{id}/smp-migrate { migrationCode }
     if r.status == 200: tenant.smpState = "registered"; hideBanner(tenant)
     else: showError(tenant, r.error)   // 400 migration_code_rejected → ask for a new code

4. 4

   Szerezze meg a kódot és vegye át a bejegyzést

   Az ügyfél kérje a jelenlegi szolgáltatótól az SMP migrációs kódot az adószámához; a kód egyszer használható és időben korlátozott, azonnal használja. Hívja a POST /companies/{companyId}/smp-migrate végpontot a partneri tokenjével (Ön a cég tulajdonosa). A 200 válasz a céget smpRegistered = true értékkel adja vissza; a hálózat azonnal, kiesés nélkül átáll. Külön esemény nincs: az állapotot a válaszból jegyezze fel, vagy olvassa újra GET-tel.

   bashKopírovať

   curl -X POST https://peppol.verteco.digital/api/v1/companies/<companyId>/smp-migrate \
     -H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
     -d '{ "migrationCode": "MIGR-7K3Q-…" }'
   # 200 { "company": { …, "smpRegistered": true, "smpState": "registered" }, "outcome": "REGISTERED" }

   HTTP · kód	Jelentés	Teendő
   400 migration_code_rejected	A kód érvénytelen, felhasznált vagy lejárt.	Kérjen új kódot a régi szolgáltatótól.
   409 registered_elsewhere	Az SMP nem fogadta el a kódot; a bejegyzést továbbra is másik szolgáltató tartja.	Ellenőrizze, hogy a kód ehhez az adószámhoz tartozik; próbálja új kóddal.
   403 company_not_verified	A cég még nincs igazolva FS-választással.	Először választás az FS-portálon.
   503 smp_unavailable	A központi SMP nem válaszol.	Ismételje meg néhány perc múlva (a kód érvényes marad).

5. 5

   Mit küldünk Önnek

   Észleléskor e-mailt küldünk a partner kapcsolattartói címére (a közvetítői bejegyzésből) az adószámmal, Peppol ID-val és a teendőkkel, majd hetente az átvételig (legfeljebb négyszer); ugyanez az információ webhookon is megérkezik. White-label ügyfélnek soha nem írunk. Ha a kódot Ön kapja meg, de nem akarja hívni az API-t, küldje a peppol​@​verteco.digital címre, és az átvételt mi végezzük el az adminisztrációból.

   Az ügyfélnek átadható szöveg:

   Cége nálunk már aktiválva van, de a nemzeti Peppol-nyilvántartásban (SMP) a bejegyzését még a korábbi szolgáltató tartja, így az e-számlák jelenleg hozzá érkeznek. Kérje tőle az SMP migrációs kódot a(z) … adószámhoz, és írja be ide. Az átállás azonnali és kiesés nélküli.

Ha később tőlünk másik tanúsított szolgáltatóhoz tér át, az ügyfelei Önnel mennek. A regisztrációk technikai átadását tömegesen és leállás nélkül elvégezzük; egy lépést azonban a Pénzügyi Igazgatóság határoz meg, nem mi, és az Szlovákiában minden szolgáltatóra egyformán vonatkozik. A távozás szabadsága garancia, nem olyan helyzet, amellyel számolunk: partneri garanciánk (a bejegyzési díjat akár nullára csökkentjük, a dokumentumonkénti éves ár 10 %-kal alacsonyabb bármely összehasonlítható ajánlatnál) az együttműködés teljes idejére érvényes, így távozásra nincs ok.

1. 1

   Felmondás a konzolból

   A Postás beállításokban beadja a felmondást, és az e-mailben kapott linkkel megerősíti; a felmondási idő egy hónap a következő hónap 1. napjától (7.1. cikk). A szerződés megszűnéséig minden a szokásos módon működik.
2. 2

   Migrációs kódok tömegesen

   Küldje el az ügyfelei adószámainak listáját. A kódokat a központi SMP-ből mindenki számára egyszerre állítjuk ki (nem egyesével a portálon), és átadjuk Önnek az új szolgáltató számára. Alternatívaként az ügyfeleket a szerződés megszűnése után a törvényes 3 munkanapon belül kijelentjük (PA SK szabályok).
3. 3

   Átvétel az SMP-ben leállás nélkül

   Az új szolgáltató a migrációs kóddal regisztrálja minden ügyfelet a saját SMP-jében; az SML azonnal átköti a kapcsolatot, a mi bejegyzésünk „Unpublished” lesz. A dokumentumok egész idő alatt megszakítás nélkül áramlanak: Szlovákiában minden alanynak egy SMP bejegyzése van a fogadásra, küldeni viszont több szolgáltatón keresztül is lehet, így az új szolgáltató azonnal küldhet az ügyfél nevében, amint megvan az ellenőrző adata, még a fogadás átvétele előtt.
4. 4

   Az új szolgáltató kiválasztása a Pénzügyi Igazgatóság portálján

   A szolgáltatóválasztáskor az FS által kiadott ellenőrző adat az FS aláírása a szolgáltató adószáma és az ügyfél adószáma páros felett, tehát egy konkrét szolgáltatóhoz kötött. A központi SMP minden szlovák résztvevő regisztrációjánál megköveteli, migrációs kóddal is. Az új szolgáltatónak ezért saját magára kiadott ellenőrző adat kell, és az csak az FS portálon történő kiválasztással keletkezik: eID-vel vagy az FS portál belépési adataival, meghatalmazott személy (például a könyvelő) is elvégezheti. Ugyanaz a meghatalmazás, amellyel az áfabevallást és az ellenőrző kimutatást benyújtják, és ugyanaz a művelet, mint az első kiválasztásnál. A migrációs kód a leállást és a kijelentésre várást szünteti meg; az FS-választást nem helyettesíti.
5. 5

   Adatexport

   Kérésre tömegesen exportáljuk az eredeti XML dokumentumokat, a kézbesítési igazolásokat és a metaadatokat, amelyeket a szerződés megszűnésekor tárolunk; a megszűnés után 90 napon belül, illetve az export visszaigazolásáig nem töröljük (7.4. cikk).

Szerződéses alap: a közvetítői feltételek 7.1., 7.3. és 7.4. cikke. Az ellenkező irány (ügyfél érkezik másik szolgáltatótól) az előző fejezetben található.

A Pénzügyi Igazgatóság Önről mint közvetítőről az általunk beadott nyomtatvány adatait tartja nyilván (cégnév, székhely, cégazonosító, adószám, kapcsolattartó, e-mail, telefon, web, a webhookja címe). A módosítást nem e-mailben kéri: a közvetítői konzolban nyissa meg az Adatok az FS-nél fület, írja be az új értékeket a jelenlegiek mellé, a többit hagyja változatlanul, és erősítse meg az összes módosítást egyszerre. Mi a Verteco ügyvezetője által aláírt kérelmet a frissített nyomtatvánnyal együtt elküldjük a peppol​@​financnasprava.sk címre, és az eredményről e-mailben tájékoztatjuk (a fiók tulajdonosát és a kapcsolattartási címet).

Az FS listájában és választójában a nyomtatványon szereplő jogi személy cégneve alatt jelenik meg; terméknevet a nyomtatvány nem ismer. A márkát, a webcímet és a szolgáltatás leírását a közvetítői konzol Információk fülén tölti ki, és így jelenik meg a /partneri és a /nasi-sprostredkovatelia oldalon (a márka nagy betűkkel, alatta a cégnév); a kártya a kérelem beadásának napjától létezik.

A kérelmek munkanapokon 8:00 és 16:00 között mennek el (a szlovák ünnepnapok kivételével), legkorábban a beadás után 2 órával; addig (és az időablakon kívül a következő küldésig) a kérelem várakozik, és visszavonható. A cégnév, a székhely vagy az ország módosítását először csapatunk ellenőrzi (igazoló irat, pl. cégkivonat), és csak ezután küldi el. 48 óránként egy kérelem adható be, és egyszerre csak egy lehet nyitott (várakozó vagy az FS-nek átadott), ezért minden módosítást egyben adjon meg. Ugyanez API-n: GET /resellers/me/fs-registration (jelenlegi értékek, nyitott kérelem, előzmények, küldési ablak), POST /resellers/me/fs-change-requests changes, note és confirm: true mezőkkel (429 Retry-After fejléccel a 48 óra alatt), DELETE /resellers/me/fs-change-requests/{id}, amíg a kérelem várakozik.

A kézbesítési szolgáltatás közvetítői feltételeinek módosításait a feltételek oldalán (PDF-ként is) tesszük közzé, és e-mailben értesítjük róluk a fiók tulajdonosát és a kapcsolattartót. A 9.1. pont szerint nem igénylik a hozzájárulását, és a közzététel napjától hatályosak; a partnerkonzol nem kér megerősítést és semmit sem blokkol. Ha egy módosítással nem ért egyet, a szerződést a 9.2. pont szerint a [email protected] címre küldött értesítéssel azonnali hatállyal és szankció nélkül megszüntetheti.

A „Feltételek” fülön adja meg, hol tette közzé a 4.4. pont szerinti ügyféltájékoztatót (az A. melléklet szerinti tájékoztató az ÁSZF-jében, a weboldalán és a szoftverében az e-számla aktiválási pontján); meglévő szerződéseknél legkésőbb a módosítás bejelentésétől számított 30 napon belül. Csapatunk ellenőrzi a megjelenítést (4.5. pont), az eredmény ugyanazon a fülön jelenik meg.