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.

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élnek eID-vel vagy a PI-portál belépési adataival bejelentkezve ki kell választania a Vertecót szolgáltatójának a Pénzügyi Igazgatóság (Finančná správa, FS) portálján; ezután bejegyezzük a céget az SMP-be, és állapota active lesz. Ahhoz, hogy egy cég küldjön, adja meg az ellenőrző tokenjét (Verifikačný údaj) a Küldési ellenőrzés végponton (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 é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

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
(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.

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).
• 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). Ha az egész láncot ellenőrizni akarja, mielőtt az FS közzéteszi Önt, küldjön teszt-POST-ot a regisztrációs végpontjára; ismeretlen/aláíratlan tartalomra biztonságosan válaszol, és nem hoz létre semmit. 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.

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

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.

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.