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. In der Testumgebung ist die Vermittlerregistrierung gebührenfrei und Sie erhalten sofort einen Test-Partnerendpunkt.

• Werden Sie digitaler Postbote (Antrag)
• Vermittlungsbedingungen
• Unsere Vermittler
• 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, per eID 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).
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), 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.

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.

// 200 OK (erste Einrichtung)
{ "url": "https://vasa-appka.sk/peppol/events", "secret": "vpt_…", "hasSecret": true,
"events": ["company.activated","company.deactivated","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 der Partner-Konsole (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.