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.

Sicherheit für Ihre Kunden: Wir sind zertifizierter Anbieter der slowakischen Finanzverwaltung (EFSK000031) mit eigenem Access Point; die Zertifizierung nach ISO/IEC 27001:2022 läuft bei der akkreditierten Stelle SKQS, s. r. o., Žilina (SNAS), ausgewählt im September 2026, Zertifikat geplant bis 1. Juli 2027; OpenPeppol verlangt es ab 1. Oktober 2027 von allen Anbietern, derzeit muss es noch niemand besitzen. Verträge (AGB, DPA, SLA, NDA) sind vollständig unter /zmluvy veröffentlicht, die Verfügbarkeit unter /status.

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, aktiviert der Kunde sie durch die Auswahl eines Anbieters im Portal der Finanzverwaltung der Slowakischen Republik (Finančná správa, FS), dem VPDS, nach Anmeldung per eID oder mit den FS-Zugangsdaten. Sie sind eingetragener Vermittler: Der Kunde wählt über Ihren Auswahllink (Feld vpdsUrl in GET /api/v1/resellers/me) Ihre Marke, nicht Verteco direkt, denn eine direkte Auswahl von Verteco nimmt die Firma aus Ihrem Programm (Event company.released_to_direct). Die FS sendet die Auswahl an Ihren Webhook, Sie leiten sie an uns weiter (Kapitel FS-Webhook), und wir aktivieren die Firma, registrieren sie im SMP und senden Ihnen company.activated. Sie sind kein eingetragener Vermittler: Der Kunde wählt Verteco als Anbieter, der Rest läuft genauso. Die verifizierte Auswahl berechtigt die Firma zugleich zum Senden. Hat uns eine direkte Auswahl von Verteco nicht erreicht, ist der Ersatzweg die 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, invoice.report_pending, invoice.report_rejected 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 Eintragung als Vermittler setzt ein eigenes System voraus, das die Auswahlen der Kunden entgegennimmt und an uns weiterleitet. Tragen Sie nicht unsere Adresse in das FS-Formular ein: die FS muss Sie aufrufen. Ohne eigenes System sind Sie kein Vermittler; der richtige Weg ist eine Registrierungsseite mit Ihrer Kennzeichnung und eine Provision (/affiliate).

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
x-pds-secret: <unveränderter Wert aus der FS-Anfrage>
(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. Das Ereignis company.client_registered_directly kommt, wenn Ihr Kunde seine Firma direkt im Verteco-Portal hinzufügt: linked = true bedeutet, dass wir sein Konto als Mitinhaber verknüpft haben (die Kontakt-E-Mail der Firma stimmte überein), false ist nur eine Information über den Versuch (höchstens einmal täglich); an Ihrer Kundenbeziehung und der Abrechnung ändert sich nichts. Das Ereignis company.released_to_direct kommt, wenn Ihr Kunde auf dem Portal der Finanzverwaltung Verteco direkt auswählt: das Unternehmen verlässt damit Ihr Programm (Ihre Konten verlieren den Zugriff, White-Label wird aufgehoben, der Kontakt der Auswahl ist Inhaber); den Kunden informieren wir aus dem Portal, Sie erhalten zusätzlich eine E-Mail. Gilt für Auswahlen ab dem 21. 9. 2026. Die Gegenrichtung, eine Auswahl unter Ihrer Marke für ein Unternehmen, das Ihr Partnerkonto bereits besitzt (zum Beispiel Ihr eigenes, als Direktkunde angelegtes Unternehmen), registriert das Unternehmen nicht neu: Access Point und Eintrag im zentralen SMP bleiben gleich (die wiederholte Registrierung ist nur eine Bestätigung), das Unternehmen wechselt lediglich in den White-Label-Modus, erhält von uns ab dann keine E-Mails zu Belegen, Sie erfahren davon nur über Webhooks und die API, und es wird im Partnermodell abgerechnet; Archiv und Einstellungen bleiben. So lässt sich die Integration am eigenen Unternehmen prüfen.

Transportschlüssel (Header x-pds-secret): nach der Veröffentlichung Ihres Eintrags sendet die FS das Zip WebhookSecret_Verteco_<Name>.zip per E-Mail an den Antragsteller, also an uns, und das Passwort dazu per SMS an die Telefonnummer, die Sie im Formular /sprostredkovatel/ziadost angegeben haben (das FS-Formular vom 17. 9. 2026 hat dafür ein eigenes Feld), also an Sie. Das Zip laden Sie in der Partnerkonsole herunter, Reiter FS webhook (Schaltfläche FS-Zip herunterladen), öffnen es mit dem Passwort aus der SMS und tragen den 32-stelligen Schlüssel aus der Textdatei an derselben Stelle ein, wo Sie ihn später auch anzeigen oder als .txt herunterladen können (jedes Anzeigen wird im Audit-Protokoll Ihres Kontos festgehalten). Ist keine SMS angekommen, schreiben Sie uns. Bei Einträgen vor dem 17. 9. 2026 kam das Passwort an uns und wir haben den Schlüssel selbst hinterlegt. Ab dem Speichern des Schlüssels prüfen wir, dass die Signatur sha512(Body + Schlüssel) jedes Aufrufs stimmt. Bis der Schlüssel eingetragen ist, protokollieren wir die Signatur nur. Beim Speichern vergleichen wir den Schlüssel mit den Aufrufen, die die FS bereits an Ihren Endpunkt gesendet hat, und lehnen einen widersprechenden Schlüssel ab; Ihr Proxy muss den Body daher Byte für Byte weiterleiten (keine JSON-Reserialisierung).

3a · Was unser Endpoint antwortet

Wir verarbeiten den Aufruf sofort (synchron). Der Body einer 200-Antwort verrät absichtlich nicht, ob das Token gültig war oder eine Firma aktiviert wurde, damit sich über den Endpoint nicht ermitteln lässt, welche DIČ unser Kunde ist. Das Ergebnis erfahren Sie über das Ereignis company.activated an Ihrem Benachrichtigungs-Webhook, und Sie können es jederzeit über GET /api/v1/resellers/me/clients lesen (Status active, peppolParticipantId ausgefüllt).

Kommt nach einer 200-Antwort innerhalb weniger Minuten kein company.activated, senden Sie uns die Uhrzeit des Aufrufs; jeder Aufruf liegt in unserem dauerhaften Audit-Log.

3b · Prüfung der Anfrage bei Ihnen vor der Weiterleitung

Wir empfehlen, dass Ihr Proxy jede Anfrage vor der Weiterleitung prüft. So senden Sie uns nur echte FS-Auswahlen, und zufällige oder gefälschte Aufrufe verbrauchen Ihr Limit nicht.

1. Zuerst speichern: die ganze Anfrage (roher Body und Header). Die FS sendet eine Auswahl nie erneut, die gespeicherte Kopie ist der einzige Weg, sie wiederherzustellen.
2. Header x-pds-secret prüfen: er muss hex(SHA-512(rohe Body-Bytes + Ihr FS-Schlüssel)) entsprechen, 128 Hexadezimalzeichen. Hashen Sie den Body genau so, wie er ankam, vor jedem JSON-Parsing; hängen Sie den Schlüssel direkt ohne Trennzeichen an den Body an; vergleichen Sie in konstanter Zeit und ohne Rücksicht auf Groß- und Kleinschreibung.
3. Nur übereinstimmende Anfragen weiterleiten, mit unverändertem Body und dem ursprünglichen Header x-pds-secret. Bodies über 64 KB verwerfen; eine FS-Auswahl hat etwa 1 KB.

import crypto from 'node:crypto';

// rawBody = Buffer mit dem Body genau so, wie er ankam (z. B. 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));
}

Dieselbe Prüfung in PHP, Python und C#:

<?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 = die Body-Bytes genau so, wie sie ankamen (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 = die Body-Bytes genau so, wie sie ankamen (ASP.NET Core: Request.Body vor jedem JSON-Lesen in einen MemoryStream kopieren)
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));
}

• Schlüssel: Es ist derselbe FS-Schlüssel, mit dem wir die Signatur prüfen (aus dem FS-Zip, geöffnet mit dem Passwort aus der SMS); nach dem Eintragen finden Sie ihn in der Partnerkonsole, Tab FS-Webhook. Halten Sie ihn nur auf dem Server. Eine Übereinstimmung bei Ihnen bedeutet eine Übereinstimmung bei uns.
• Einen anderen Mechanismus gibt es nicht: Die FS signiert den Transport nicht mit einem asymmetrischen Schlüssel, einen öffentlichen Schlüssel für den Header gibt es nicht. Das verification_token im Body ist eine FS-Signatur über die Steuernummern; wir prüfen es gegen das FS-Zertifikat, Sie leiten es nur unverändert weiter.
• Limit: Die 600 Aufrufe pro Minute von einer IP-Adresse gelten für jeden Aufruf an /peppol/webhook/…, gültig oder nicht. Ein Aufruf ohne gültigen Header erhält von uns 403 und nichts wird verarbeitet, Spam würde aber das Limit Ihres Servers verbrauchen.
• Stimmt die Signatur schon bei der ersten echten Auswahl nicht, verwerfen Sie die Anfrage nicht: Speichern Sie sie und schreiben Sie uns, wir finden die Ursache gemeinsam.

4 · Betriebsregeln (wichtig)

• Idempotenz: Dasselbe Subjekt kann die Auswahl wiederholen; die Verarbeitung derselben DIČ (slowakische Steuernummer) muss sicher sein (bei uns ist sie es).
• Wenn die Weiterleitung scheitert (zum Beispiel 403 oder ein Ausfall Ihres Servers), wiederholt die FS die Auswahl nicht. Senden Sie uns den gespeicherten ursprünglichen Body erneut mit seinem ursprünglichen Header x-pds-secret; die Verarbeitung ist idempotent und die Firma wird aktiviert. Haben Sie den Aufruf nicht gespeichert, schreiben Sie uns.
• 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). Die URL prüfen Sie mit einem GET auf Ihren Registrierungs-Endpoint (Antwort ready). Sobald Ihr Schlüssel gespeichert ist, erhält ein Test-POST ohne gültigen Header x-pds-secret die Antwort 403 und legt nichts an; die ganze Kette einschließlich der Aktivierung der Firma testen Sie in der Testumgebung test.peppol.verteco.digital (simulierte Auswahl unter /register-vpds-test; der Vermittlereintrag ist dort gebührenfrei und ohne Einreichung bei der FS, eine mit POST /companies angelegte Firma ist sofort aktiv, und die simulierte Auswahl kommt wie von der FS an Ihrem Webhook 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.

6 · Wie die Verantwortung verteilt ist

Eine Zusammenfassung von Art. 5 der Geschäftsbedingungen für die Vermittlung (v1.8), damit Sie wissen, was wir in der Praxis von Ihnen erwarten. Aus der bloßen technischen Übermittlung eines Belegs Ihres Kunden entsteht Ihnen weder eine Vertragsstrafe noch eine Schadenshaftung, und Sie sind nicht verpflichtet, die wirtschaftliche Realität oder die inhaltliche Richtigkeit einzelner Belege zu prüfen (Art. 5.8). Eine Auswahl auf dem Portal der Finanzverwaltung, bestätigt mit eID oder Zugangsdaten, zusammen mit unserem geprüften Verifizierungsnachweis (Verifikačný údaj) gilt als ausreichender Nachweis der Vertretungsbefugnis, und der API-Zugang für Ihre eigenen Kunden gilt nicht als Zugänglichmachung an Dritte (Art. 5.9). Vertragsstrafen sind auf 5 000 EUR je Ereignis oder Serie von Verstößen mit einer Ursache und auf 10 000 EUR je Kalenderjahr begrenzt (Art. 5.3). Sanktionen und Maßnahmen, die Behörden oder die Instanzen des Peppol-Netzes uns für ein Verhalten in Ihrer Sphäre tatsächlich auferlegen, werden weiterhin ohne Obergrenze weitergegeben (Art. 5.2), weil wir sie gegenüber der Finanzverwaltung und OpenPeppol unbegrenzt tragen. Der Anspruch verringert sich jedoch anteilig um unseren Anteil, wir legen den zugrunde liegenden Bescheid und eine schriftliche Aufstellung bei, Sie haben 15 Tage für eine Stellungnahme, eine aufgehobene oder herabgesetzte Sanktion erstatten wir Ihnen innerhalb von 15 Tagen auch ohne Aufforderung, und unsere Ansprüche gegen den Kunden, der sie verursacht hat, treten wir samt Unterlagen an Sie ab (Art. 5.5 und 5.7). Deshalb verlangt Art. 4.1 Buchst. h), die entsprechenden Pflichten in Ihre Verträge mit den Kunden zu übernehmen und festzuhalten, wer welchen Beleg erstellt hat; eine Musterklausel senden wir auf Anfrage kostenlos.

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","company.client_registered_directly","company.released_to_direct","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.; das Limit von 1 000 Belegen pro Monat gilt bei per_document nicht, jede gesendete Rechnung wird ab der ersten abgerechnet (eine Gutschrift ist ein gesendeter Beleg) und empfangene Belege sind ohne Obergrenze kostenlos. 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.

Rechner: welches Modell bei Ihrer Zahl von Firmen und Belegen günstiger ist, inklusive Jahressumme mit Eintrag und MwSt., berechnen Sie auf /de/sprostredkovatel (Abschnitt Rechner).

Monatlicher Verbrauchsauszug je Kunde: GET /api/v1/resellers/me/usage?month=YYYY-MM (ohne Parameter der Vormonat) liefert für jede Firma unter Ihrer Marke, die Ihr Konto besitzt, die Zahl gesendeter und empfangener Belege, die Belege über dem Limit von 1 000 (gesendete und empfangene zusammen), den Betrag in Modell A (2 € für eine Firma, die im Monat einen Beleg gesendet hat, plus 0,01 € für jeden Beleg über dem Limit; das Archiv wird einer Firma unter Ihrer Marke nie berechnet) und in Modell B (0,01 € je gesendeten Beleg), die Summen beider Modelle mit der Auffüllung auf das Minimum von 300 € in Modell B sowie das Modell, das in diesem Monat für Sie galt (appliedModel); Direktkunden, bei denen Ihr Konto Mitglied ist, zahlen aus ihrem eigenen Guthaben und stehen nicht im Auszug. Die Beträge sind Cent zzgl. MwSt., bewertet wie in der Monatsabrechnung, aber aus dem aktuellen Stand der Firmen zum Zeitpunkt des Abrufs (verbindlich sind die Abrechnungspositionen in Ihrem Guthaben), und bei Firmen über dem Limit weichen sie von der Vorschau des laufenden Monats in GET /resellers/me/billing ab, die Modell A als 2 € × aktive Firmen rechnet. Mit ?format=csv erhalten Sie dasselbe als Datei für die Buchhaltung (UTF-8 mit BOM, Semikolon als Trennzeichen, slowakische Spaltenköpfe, Beträge mit Dezimalkomma, letzte Zeile Spolu), und die Partnerkonsole zeigt den Auszug im Reiter Verbrauch mit Auswahl der letzten 12 Monate.

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.

Der empfohlene Ablauf für ein eigenes Portal oder eine eigene Anwendung des Partners (aus Partnerfragen im Oktober 2026):

1. Behalten Sie Kopien der Belege bei sich. Bei Firmen unter Ihrer Marke ist das Datenarchiv standardmäßig ausgeschaltet, der Beleginhalt (XML, PDF) bleibt bei uns also 14 Tage nach der Zustellung und wird dann gelöscht; die Zustellnachweise (Quittung, Zeitstempel, Meldestatus) bleiben. Ihr Portal liest daher aus der eigenen Kopie und holt bei uns nur neue Belege.
2. Neue Belege per Webhook, nicht per Abfrage. Der Partner-Benachrichtigungs-Webhook (oben) erhält invoice.received für jede Firma; den Beleg laden Sie mit GET /sapi/document/receive/{id} (XML, PDF, HTML und Anhänge haben eigene Pfade) und bestätigen ihn mit POST /sapi/document/receive/{id}/acknowledge. Der Rückfallweg ist seitenweises Lesen, GET /sapi/document/receive?status=received&limit=200 mit pageToken (älteste zuerst; bestätigte Belege fallen aus dem Filter).
3. Status gesendeter Belege kommen ebenfalls per Webhook (invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported) und lassen sich mit GET /sapi/document/sent abfragen.
4. Eigene Domain für Kunden. Ihre Anwendung kann unsere API über eine eigene Brücke (etwa api.ihre-domain.sk) mit einem Partnerschlüssel für alle Firmen unter Ihrem Konto aufrufen; Kunden brauchen unsere Adresse nie, und Webhooks leiten Sie von Ihrer Seite an sie weiter.
5. Limits. 300 Aufrufe pro Minute je API-Schlüssel, die Header RateLimit-* liefern den Rest; ein höheres Limit stellen wir auf Anfrage ein. Die Grenze von 1 000 Belegen pro Monat und Firma gilt im Modell A (gesendete und empfangene zusammen, jeder weitere Beleg 0,01 €); im Modell B gilt sie nicht.

Welches Vergütungsmodell: Modell B (0,01 € je gesendetem Beleg, mindestens 300 € pro Monat, empfangene kostenlos) ist erst dann günstiger als Modell A (2 € je Firma, die im Monat einen Beleg gesendet hat), wenn in einem Monat mehr als 150 Firmen senden und je sendender Firma im Durchschnitt weniger als 200 Belege gesendet werden (150 Firmen = bis 30 000 Belege, 300 Firmen = bis 60 000); das Modell wechseln Sie in der Partnerkonsole mit Wirkung ab dem Folgemonat.

Das Datenarchiv eines Kunden über die Partner-API: Muss Ihr Portal das Archiv eines Kunden ein- oder ausschalten, muss es den Kunden nicht in unser Portal schicken.

Was ein eingeschaltetes Archiv für den Preis einer Firma unter Ihrer Marke bedeutet, genau nach dem Abrechnungscode: ein eingeschaltetes Datenarchiv löst bei einer Firma unter der Marke eines Vermittlers nie die Grundgebühr von 2 € aus, in Modell A zahlen Sie also 2 € nur für einen Monat, in dem die Firma einen Beleg gesendet hat, plus 0,01 € für jeden Beleg über 1 000 (gesendete und empfangene zusammen), und in Modell B 0,01 € je gesendeten Beleg; das Einschalten des Archivs ändert damit nur, wie lange wir die Originale aufbewahren (für die Vertragsdauer statt der Frist), nicht den Betrag. Der Speicher wird einmal pro Nacht gemessen, und die Hinweise bei 80 % und bei einem weiteren angefangenen GB gehen an die Kontakt-E-Mail des Partners (ersatzweise an den Inhaber des Eintrags), nie an den Kunden; die Monatsabrechnung enthält keine Speicherposition. Die Felder archiveReceived, archiveSent, wipeDaysReceived, wipeDaysSent und storageUsedBytes stehen auch bei jeder Firma in GET /resellers/me/clients.

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.

Wechseln Sie später von uns zu einem anderen zertifizierten Anbieter, gehen Ihre Kunden mit. Die technische Übergabe der Registrierungen erledigen wir gesammelt und ohne Ausfall; einen Schritt bestimmt jedoch die Finanzverwaltung, nicht wir, und er gilt für jeden Anbieter in der Slowakei gleich. Die Freiheit zu wechseln ist eine Garantie, kein Szenario, mit dem wir rechnen: Unsere Partnergarantie (die Eintragsgebühr gleichen wir bis auf null an, der Jahrespreis pro Dokument liegt 10 % unter jedem vergleichbaren Angebot) gilt für die gesamte Zusammenarbeit, ein Grund zu gehen entsteht also gar nicht.

1. 1

   Kündigung aus der Konsole

   In den Postbote-Einstellungen reichen Sie die Kündigung ein und bestätigen sie über den E-Mail-Link; die Frist beträgt einen Monat ab dem 1. des Folgemonats (Art. 7.1). Bis zum Vertragsende läuft alles wie bisher.
2. 2

   Migrationscodes gesammelt

   Senden Sie uns die Liste der Steuernummern Ihrer Kunden. Die Codes aus dem zentralen SMP stellen wir für alle auf einmal aus (nicht einzeln im Portal) und übergeben sie Ihnen für den neuen Anbieter. Alternativ melden wir die Kunden innerhalb der gesetzlichen 3 Arbeitstage nach Vertragsende ab (PA-SK-Regeln).
3. 3

   Übernahme im SMP ohne Ausfall

   Der neue Anbieter registriert jeden Kunden mit dem Migrationscode in seinem SMP; die SML bindet sofort um und unser Eintrag wird „Unpublished“. Dokumente fließen die ganze Zeit weiter: In der Slowakei hat jeder Teilnehmer einen SMP-Eintrag für den Empfang, senden darf er aber über mehrere Anbieter, sodass der neue Anbieter für den Kunden senden kann, sobald er dessen Verifizierungswert hat, auch bevor er den Empfang übernimmt.
4. 4

   Auswahl des neuen Anbieters im Portal der Finanzverwaltung

   Der Verifizierungswert, den die FS bei der Anbieterauswahl ausstellt, ist ihre Signatur über das Paar Anbieter-Steuernummer und Kunden-Steuernummer, also an einen konkreten Anbieter gebunden. Das zentrale SMP verlangt ihn bei jeder Registrierung eines slowakischen Teilnehmers, auch mit Migrationscode. Der neue Anbieter braucht daher einen für ihn ausgestellten Verifizierungswert, und der entsteht nur durch die Auswahl im FS-Portal: per eID oder mit den Zugangsdaten zum FS-Portal, auch durch eine autorisierte Person (etwa den Buchhalter). Es ist dieselbe Vollmacht, mit der Umsatzsteuererklärung und Kontrollmeldung eingereicht werden, und derselbe Vorgang wie bei der ersten Auswahl. Der Migrationscode beseitigt Ausfall und Wartezeit auf die Abmeldung; die FS-Auswahl ersetzt er nicht.
5. 5

   Datenexport

   Auf Wunsch exportieren wir gesammelt die originalen XML-Dokumente, Zustellnachweise und Metadaten, die wir bei Vertragsende halten; wir löschen sie nicht früher als 90 Tage nach dem Ende oder bis Sie den Export bestätigen (Art. 7.4).

Vertragliche Grundlage: Art. 7.1, 7.3 und 7.4 der Vermittlerbedingungen. Die Gegenrichtung (ein Kunde kommt von einem anderen Anbieter) steht im vorigen Kapitel.

Die Finanzverwaltung führt über Sie als Vermittler die Daten aus dem Formular, das wir für Sie eingereicht haben (Firmenname, Sitz, Firmen-ID, Steuernummer, Kontaktperson, E-Mail, Telefon, Web, Adresse Ihres Webhooks). Eine Änderung beantragen Sie nicht per E-Mail: Öffnen Sie in der Vermittlerkonsole den Tab Daten bei der FS, tragen Sie die neuen Werte neben den aktuellen ein, lassen Sie den Rest unverändert und bestätigen Sie alle Änderungen auf einmal. Wir senden einen vom Geschäftsführer von Verteco unterzeichneten Antrag mit dem aktualisierten Formular an peppol​@​financnasprava.sk und informieren Sie per E-Mail über das Ergebnis (Kontoinhaber und Kontaktadresse).

In der FS-Liste und in der Auswahl erscheinen Sie unter dem Firmennamen der juristischen Person aus dem Formular; einen Produktnamen kennt das Formular nicht. Marke, Website und Beschreibung des Dienstes tragen Sie in der Vermittlerkonsole im Tab Informationen ein, und so erscheinen Sie auf /partneri und /nasi-sprostredkovatelia (Marke groß, Firmenname darunter); die Karte existiert ab dem Tag der Einreichung.

Anträge gehen an Arbeitstagen zwischen 08:00 und 16:00 Uhr hinaus (slowakische Feiertage ausgenommen), frühestens 2 Stunden nach der Einreichung; bis dahin (und außerhalb des Fensters bis zum nächsten Versand) wartet der Antrag und kann storniert werden. Eine Änderung von Firmenname, Sitz oder Land prüft zuerst unser Team (Nachweis, z. B. Registerauszug) und versendet sie erst danach. Es gilt ein Antrag je 48 Stunden und nur einer darf offen sein (wartend oder an die FS übergeben), also nehmen Sie alle Änderungen hinein. Dasselbe per API: GET /resellers/me/fs-registration (aktuelle Werte, offener Antrag, Verlauf, Versandfenster), POST /resellers/me/fs-change-requests mit changes, note und confirm: true (429 mit Retry-After während der 48 h), DELETE /resellers/me/fs-change-requests/{id}, solange der Antrag wartet.

Änderungen der Vermittlungsbedingungen für den Zustelldienst veröffentlichen wir auf der Seite der Bedingungen (auch als PDF) und kündigen sie dem Kontoinhaber und der Kontaktperson per E-Mail an. Nach Punkt 9.1 bedürfen sie nicht Ihrer Zustimmung und gelten ab dem Tag der Veröffentlichung; die Partnerkonsole fordert keine Bestätigung an und blockiert nichts. Sind Sie mit einer Änderung nicht einverstanden, können Sie den Vertrag nach Punkt 9.2 durch Mitteilung an [email protected] mit sofortiger Wirkung und ohne Sanktion beenden.

Geben Sie im Tab „Bedingungen“ an, wo Sie die Kundeninformation nach Punkt 4.4 veröffentlicht haben (die Information nach Anhang A in Ihren AGB, auf Ihrer Website und in Ihrer Software an der Aktivierungsstelle der E-Rechnung); bei bestehenden Verträgen spätestens 30 Tage nach der Änderungsmitteilung. Unser Team prüft die Präsentation (Punkt 4.5), das Ergebnis erscheint im selben Tab.