Für Vermittler: das Partnermodell

Was ein gewöhnliches Multi-Tenant-Konto hat

• Ein API-Token für alle Firmen des Kontos (Header X-Peppol-Participant-Id in SAPI-SK).
• Einen je Firma konfigurierten Benachrichtigungs-Webhook (GET/PUT /api/v1/companies/{id}/notifications) mit derselben Signatur X-Verteco-Signature.
• Die Abmeldung der eigenen Firma (POST /api/v1/companies/{id}/deregister) und den Verbrauch je Firma (GET /api/v1/companies/usage).
• Firmen werden immer von ihrem Eigentümer verwaltet, nicht von einem Partner: einseitige Kundentrennung und Versandbremse gibt es im gewöhnlichen Modell nicht.

So werden Sie Vermittler

Den Antrag füllen Sie auf der Seite Werden Sie digitaler Postbote aus; das Formular der Finanzverwaltung unterschreiben und reichen wir für Sie ein. Die Gebühr beträgt 99 € pro Jahr zzgl. USt. Sobald Sie in der Auswahl der Finanzverwaltung veröffentlicht sind, wählen Kunden Sie unter Ihrer Marke, ihre Firmen entstehen automatisch unter Ihrem Partnerkonto und werden im zentralen SMP registriert, sofern nicht ein anderer Anbieter ihren Eintrag hält (dann erhalten Sie das Event company.smp_registered_elsewhere und die Anleitung mit dem Migrationscode). In der Testumgebung ist die Vermittlerregistrierung gebührenfrei und Sie erhalten sofort einen Test-Partnerendpunkt.

• Werden Sie digitaler Postbote (Antrag)
• Vermittlungsbedingungen
• Unsere Vermittler
• Kunde von anderem Anbieter: Migrationscode (Anleitung)
• Verträge: AGB, DPA, SLA, NDA

Wenn Sie eine Rechnungs-App, ein ERP oder eine Plattform betreiben und über uns mehrere Ihrer Kunden (Tenants) an Peppol anbinden möchten, integrieren Sie sich einmal und bedienen N Firmen. Das Modell ist ein Proxy: Ihr Backend hält einen API-Token (vpt_…) nur auf dem Server (niemals im Browser) und jeder Ihrer Tenants = eine Firma bei uns (ein Token → N Firmen). Eine erweiterte öffentliche Anleitung mit Beispielcode, Webhook-Signaturen und Go-live-Checkliste: peppol.verteco.digital/saas.

1. 1

   Ein Token, server-side

   Erstellen Sie einen API-Token und bewahren Sie ihn in einer gesicherten Backend-Umgebung auf. Alle Aufrufe führt Ihr Server aus (Bearer), nicht der Browser des Kunden.
2. 2

   Onboarding eines Tenants = Anlegen der Firma

   Für jeden Kunden POST /companies mit seiner Handelsregisternummer (IČO)/USt-IdNr. (IČ DPH); gibt zurück { id, status: "pending_verification" }; speichern Sie die id beim Tenant (Details siehe Firmen).

   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

   Aktivierung in Peppol (Schritt des Kunden beim Staat)

   pending_verification ≠ live in Peppol. Damit die Firma empfängt, muss der Kunde im Portal der Finanzverwaltung der Slowakischen Republik (Finančná správa, FS), dem VPDS, nach Anmeldung per eID oder mit den FS-Zugangsdaten Verteco als Anbieter auswählen; dann registrieren wir sie im SMP und der Status wechselt auf active. Damit die Firma senden kann, hinterlegen Sie ihr Verifizierungsmerkmal (Verifikačný údaj) über Verifizierung des Versands (POST /companies/{id}/verification). Hatte der Kunde bereits einen anderen Anbieter, wird die Firma nach der Auswahl zwar aktiviert, der SMP-Eintrag bleibt aber beim alten Postboten und ein Migrationscode ist nötig: siehe Kapitel Ein Kunde kommt von einem anderen Anbieter.
4. 4

   Rechnungsempfang: Webhook pro Tenant

   Richten Sie einen Webhook (und/oder E-Mail) für jede Firma ein und holen Sie das Signatur-Secret ab:

   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": "…" }   (zur Prüfung von X-Verteco-Signature speichern)

   Bei einer empfangenen Rechnung erhalten Sie einen signierten POST (Event invoice.received; ebenso invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported und company.* für alle Ihre Kunden), durable, mit Retry/Dead-Letter. Signaturprüfung, Payload und die Schaltfläche „Otestovať webhook" (Webhook testen) siehe Benachrichtigungen & Webhooks.
5. 5

   Rechnungsversand

   Senden Sie die Rechnung (UBL Peppol BIS 3.0) über die nationale Schnittstelle SAPI-SK 1.0: POST /sapi/document/send (OAuth2 client_credentials, client_secret = Ihr vpt_ Token). Die slowakische Steuermeldung (TDD/C5) ergänzen wir automatisch.
6. 6

   Grundlagen für die Weiterberechnung

   GET /companies/usage?month=YYYY-MM liefert die Anzahl gesendeter und empfangener Belege für jede Ihrer Firmen einzeln sowie in Summe, genau in den Einheiten, in denen die Preisliste aufgebaut ist, sodass Sie Ihren Kunden direkt daraus weiterberechnen können. Ohne Parameter wird der aktuelle Monat zurückgegeben; der Zeitraum ist halboffen und die Antwort enthält explizit die Felder from/to, damit Sie die Monatsgrenze nicht raten müssen. Firmen ohne Verkehr stehen mit Nullwerten in der Liste.
7. 7

   Skalierung und Robustheit

   Paginieren Sie Listen: GET /companies?page&limit sowie GET /companies/{id}/documents?page&limit (mit Headern X-Total-Count u. a.). Beachten Sie das Rate-Limit pro Token: beim Massen-Onboarding arbeiten Sie in Batches mit Backoff bei 429 (Retry-After) und behandeln Sie 409 ico_taken (idempotent).

Wenn Sie als Vermittler (sprostredkovateľ) eingetragen sind (Antrag über /sprostredkovatel/ziadost), sendet die Finanzverwaltung der Slowakischen Republik (Finančná správa, FS) an Ihre Webhook-URL immer dann eine Benachrichtigung, wenn ein Kunde Sie im FS-Portal (VPDS) auswählt. Dieses Handbuch beschreibt den exakten Kontrakt so, wie die FS ihn in der Produktion tatsächlich aufruft (verifiziert anhand echter Auswahlen). Die FS veröffentlicht zu den Webhooks kein eigenes Handbuch; das hier ist alles, was Sie für die Implementierung benötigen.

1 · Wie die Benachrichtigung aussieht + 2 · Echtheitsprüfung

3 · Was damit tun: den rohen Body an uns weiterleiten

Die empfohlene (und einfachste) Implementierung ist ein Raw-Byte-Proxy: Nehmen Sie den POST an, antworten Sie schnell und leiten Sie die rohen Bytes des Bodys an Ihren Registrierungs-Endpoint bei uns weiter. Dieser entsteht automatisch nach dem Ausfüllen des Formulars /sprostredkovatel/ziadost, ist sofort aktiv, und seine genaue URL (mit Ihrem Schlüssel) sehen Sie nach der Anmeldung über GET /api/v1/resellers/me:

POST https://peppol.verteco.digital/peppol/webhook/reseller/{vas-kluc}
Content-Type: application/json
(Body = unveränderte rohe Bytes von der FS)

Wir prüfen den verification_token kryptografisch, legen die Firma automatisch unter Ihrem Partnerkonto an (white-label), registrieren sie im zentralen SK SMP und stellen ihr ab diesem Moment E-Rechnungen zu. Sie können sich aus dem Payload die Kontaktdaten für Ihr eigenes Onboarding speichern; mehr ist nicht nötig. Ausnahme: hatte das Subjekt bereits einen anderen Anbieter, bleibt der SMP-Eintrag bei diesem, und Sie erhalten von uns das Event company.smp_registered_elsewhere plus eine E-Mail; die Lösung beschreibt ein eigenes Kapitel.

4 · Betriebsregeln (wichtig)

• Idempotenz: Dasselbe Subjekt kann die Auswahl wiederholen; die Verarbeitung derselben DIČ (slowakische Steuernummer) muss sicher sein (bei uns ist sie es).
• Quell-IP: Die Aufrufe kommen aus der Infrastruktur der FS (beobachtet von 194.1.2.13); eine IP-Allowlist empfehlen wir nur als Ergänzung, nicht als einzigen Schutz (den Adressbereich garantiert die FS nicht).
• Antwort: Geben Sie auch bei einem internen Verarbeitungsfehler 200 zurück (loggen Sie den Fehler); etwas anderes wertet die FS nicht aus.
• Reihenfolge der Inbetriebnahme: Der Webhook muss vor der Einreichung des Antrags bei der FS live sein; die erste Auswahl kann kurz nach der Veröffentlichung eintreffen.

Die Referenzimplementierung des Proxys hat ~30 Zeilen (POST annehmen → speichern → rohe Bytes weiterleiten). Wenn Sie die gesamte Kette noch vor der Veröffentlichung bei der FS prüfen möchten, senden Sie einen Test-POST an Ihren Registrierungs-Endpoint; auf unbekannte/unsignierte Inhalte antwortet er sicher und legt nichts an. Fragen: Support.

5 · Beendigung des Vermittlungsvertrags

Der Vermittlungsvertrag kann auch direkt aus der Anwendung heraus beendet werden: Der Inhaber des Partnerkontos füllt unter „Nastavenia poštára“ (Einstellungen des Postboten) den Antrag auf Beendigung aus (Kontrollfrage + Bestätigung der Folgen) und bestätigt die Kündigung über einen Link, den er per E-Mail erhält. Mit der Bestätigung ist die Kündigung zugegangen; die Kündigungsfrist beträgt einen Monat und läuft ab dem 1. Tag des Folgemonats (Art. 7.1 der Geschäftsbedingungen für die Vermittlung). Den Antrag auf Löschung aus der Liste der Vermittler reichen wir bei der Finanzverwaltung innerhalb von 5 Werktagen nach dem Erlöschen des Vertrags ein (Art. 7.3); die Unterlage erhält unser Team, an die Kunden des Vermittlers wird nichts gesendet. Ein nicht bestätigter Antrag kann in der Anwendung zurückgezogen werden. Programmatisch: GET/POST/DELETE /api/v1/resellers/me/termination.

Partner-Benachrichtigungs-Webhook (Vermittler, sprostredkovateľ)

Wenn Sie ein eingetragener Vermittler (sprostredkovateľ) sind, müssen Sie den Webhook nicht bei jeder Firma einzeln einrichten: ein einziger Partner-Benachrichtigungs-Webhook erhält alle Events der Firmen unter Ihrem Partnerkonto und hat Vorrang vor den Webhooks der einzelnen Firmen. Ihre Kunden richten also nichts ein; die Firma unterscheiden Sie anhand von companyDic / peppolParticipantId.

E-Mails zu einzelnen Rechnungen: Das Partnerkonto ist Mitglied jeder Kundenfirma und würde mit den Standardeinstellungen des Kontos zu jeder eingegangenen Rechnung jeder dieser Firmen eine E-Mail erhalten. White-Label-Kunden erhalten von uns nie E-Mails (der Kanal ist der Webhook); für die übrigen Firmen schalten Sie sie für das Partnerkonto unter „Nastavenia poštára“ (Einstellungen des Postboten) → Benachrichtigungen aus (ein Schalter; dieselbe Einstellung findet sich auch unter Einstellungen → Benachrichtigungen des Kontos).

// 200 OK (erste Einrichtung)
{ "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"] }

Die Signatur X-Verteco-Signature wird genauso berechnet wie beim Firmen-Webhook (unten), nur mit dem Partner-Secret.

Kundenverwaltung über die API (einseitige Trennung und Versandbremse)

Ein Kunde, der den Partner verlässt, unternimmt in der Regel nichts. Deshalb sind diese Operationen einseitig und erfordern keinerlei Mitwirkung des Kunden. Der Rechnungsempfang ist davon nicht betroffen: Er ist an die Registrierung der Firma im zentralen SMP gebunden, nicht an das verwaltende Konto.

Abrechnungsmodell des Partners

In den Nastavenia poštára, Reiter Fakturácia (und über GET/PUT /api/v1/resellers/me/billing) wählen Sie das Abrechnungsmodell (die Wahl steht nur eingetragenen Vermittlern offen): per_company = 2 € monatlich pro aktiv sendende Handelsregisternummer (IČO), oder per_document = 0,01 € für jede gesendete Rechnung Ihrer Firmen (empfangene Belege kostenlos) mit einer monatlichen Mindestabrechnung von 300 € + MwSt. Ein Modellwechsel gilt immer ab dem 1. Tag des folgenden Monats (in der Response pendingModel und pendingFrom); die Response beider Aufrufe liefert außerdem die Umrechnung des laufenden Monats unter beiden Modellen, sodass Sie informiert umschalten.

Empfohlenes Vorgehen bei einem beendeten Kunden (Kostendeckel auf Ihrer Seite): den laufenden Verbrauchsstand sehen Sie in GET /api/v1/companies/usage?month=YYYY-MM (Aufschlüsselung sent/received je Firma, genau passend zur Weiterberechnung) und in GET /api/v1/resellers/me/clients (Zahlen für den laufenden Monat); zu jedem gesendeten und empfangenen Beleg Ihrer Firmen geht zudem ein Event an den Partner-Webhook, sodass Sie eine „beendete“ Firma sofort beim ersten Beleg erkennen. Dann genügt ein Aufruf von pause-sending oder release.

Die Slowakei hat ein zentrales SMP für alle Postboten, und jeder Teilnehmer hat darin genau einen Eintrag. Wählt Ihr Kunde Ihre Marke im Portal der Finanzverwaltung, verifizieren und aktivieren wir die Firma; hält seinen Eintrag aber noch der bisherige Anbieter, stellt das Netzwerk weiter an diesen zu. Den Wechsel bewirkt ein einmaliger Migrationscode, den der Kunde vom bisherigen Postboten erhält (Standardmechanismus des SML, FS-FAQ Beispiel 46; nach den PA-SK-Regeln muss der alte Postbote den Kunden innerhalb von 3 Arbeitstagen nach Vertragsende aus dem zentralen SMP abmelden). Hinweis: nach der FS-FAQ (Beispiele 36 und 73) darf ein Kunde weiter bei einem anderen Postboten empfangen und nur über Sie versenden; ist das gewollt, rufen Sie PUT /resellers/me/clients/{id}/receiving-provider mit elsewhere=true auf (Zustand smpState = "external"), und sowohl die Erinnerungen als auch die automatische Registrierung enden. Dieses Kapitel zeigt, wie Sie die Situation in Ihrer Plattform erkennen, speichern und lösen und was Sie dabei von uns erhalten.

1. 1

   Empfänger vorbereiten: Partner-Webhook

   Einen Webhook für alle Kunden richten Sie über PUT /resellers/me/notification-webhook (oben) ein. Prüfen Sie X-Verteco-Signature und verarbeiten Sie das Event company.smp_registered_elsewhere: es bedeutet „ein anderer Anbieter hält den Eintrag, Migrationscode nötig“. Deduplizieren Sie über companyId + event; das Event wiederholt sich wöchentlich, bis der Kunde den Code eingibt.

   jsonKopírovať

   // POST an Ihren Webhook, Header 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

   Lookup ergänzen: wann fragen, was lesen

   Der Webhook kann fehlen (noch nicht eingerichtet) oder bei einem Ausfall verloren gehen, lesen Sie den Zustand deshalb auch aktiv: GET /resellers/me/clients liefert je Firma smpRegistered und smpState; das Detail steht in GET /companies/{id}. Empfohlener Rhythmus: einmal täglich für alle Kunden, beim Öffnen der Kundenseite in Ihrer Anwendung und 2 bis 3 Minuten nach einem company.activated-Event (die SMP-Registrierung ist meist binnen einer Minute abgeschlossen). Vor dem Anlegen eines Kunden lohnt GET /public/peppol-check?id=0245:<DIČ>: ist die Steuernummer schon im Netzwerk, wird der Kunde einen Code brauchen, und Sie können es ihm vorab sagen.

   smpState	Bedeutung	Was tun
   registered	Der SMP-Eintrag liegt unter unserem Konto, das Netzwerk stellt an uns zu.	Nichts, der Kunde empfängt.
   pending	Registrierung läuft (Sekunden; bei SMP-Ausfall Stunden; wir wiederholen automatisch).	Warten, in einigen Minuten erneut lesen.
   elsewhere	Ein anderer Anbieter hält den Eintrag; der Kunde braucht einen Migrationscode.	Hinweis anzeigen, Code beschaffen, smp-migrate aufrufen (Schritt 4).
   rejected	Das FS-Verifizierungsmerkmal wurde abgelehnt.	Der Kunde muss die Auswahl im FS-Portal wiederholen.
   null	Nicht anwendbar (Firma noch nicht durch die FS-Auswahl verifiziert).	Kunden zur Auswahl im FS-Portal führen.

3. 3

   Zustand bei Ihnen speichern

   Halten Sie je Kunde companyId, peppolParticipantId, smpState, smpStateAt (zuletzt gesehen) und noticeShownAt (wann Sie den Kunden informiert haben). Bei elsewhere zeigen Sie in Ihrer Anwendung einen dauerhaften Hinweis mit Eingabefeld für den Code; den Versand nicht blockieren, die Firma darf senden. Bei registered den Hinweis entfernen.

   textKopírovať

   // Verarbeitung des Events in Ihrem Backend (Pseudocode)
   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

   Code beschaffen und Eintrag übernehmen

   Der Kunde fordert beim bisherigen Anbieter den SMP-Migrationscode für seine Steuernummer an; der Code ist einmalig und zeitlich begrenzt, sofort verwenden. Rufen Sie POST /companies/{companyId}/smp-migrate mit Ihrem Partner-Token auf (Sie sind Inhaber der Firma). Eine 200-Antwort enthält die Firma mit smpRegistered = true; das Netzwerk wechselt sofort und ohne Ausfall. Ein eigenes Event gibt es nicht: übernehmen Sie den Zustand aus der Antwort oder lesen Sie ihn per GET erneut.

   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 · Code	Bedeutung	Was tun
   400 migration_code_rejected	Code ungültig, verbraucht oder abgelaufen.	Neuen Code beim alten Anbieter anfordern.
   409 registered_elsewhere	Das SMP hat den Code nicht akzeptiert; der Eintrag liegt weiter beim anderen Anbieter.	Prüfen, ob der Code zu dieser Steuernummer gehört; mit neuem Code wiederholen.
   403 company_not_verified	Firma noch nicht durch die FS-Auswahl verifiziert.	Zuerst Auswahl im FS-Portal.
   503 smp_unavailable	Das zentrale SMP antwortet nicht.	In einigen Minuten wiederholen (Code bleibt gültig).

5. 5

   Was wir Ihnen senden

   Bei Erkennung senden wir eine E-Mail an die Partner-Kontaktadresse (aus der Vermittler-Registrierung) mit Steuernummer, Peppol-ID und Vorgehen, danach wöchentlich bis zur Übernahme (höchstens viermal); dieselbe Information geht als Webhook. Einem White-Label-Kunden schreiben wir nie. Erhalten Sie den Code, möchten aber die API nicht aufrufen, senden Sie ihn an peppol​@​verteco.digital, und wir führen die Übernahme aus der Administration durch.

   Text für den Kunden zur Übernahme:

   Ihre Firma ist bei uns bereits aktiviert, den Eintrag im nationalen Peppol-Register (SMP) hält aber noch Ihr bisheriger Anbieter, sodass E-Rechnungen derzeit an ihn gehen. Fordern Sie dort den SMP-Migrationscode für die Steuernummer … an und geben Sie ihn hier ein. Der Wechsel erfolgt sofort und ohne Ausfall.