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. 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
• 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 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).
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), 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.

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.

// 200 OK (első beállítás)
{ "url": "https://vasa-appka.sk/peppol/events", "secret": "vpt_…", "hasSecret": true,
"events": ["company.activated","company.deactivated","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 partnerkonzolban (é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.