Für Entwickler: API-Referenz

Die Verteco API ist REST über HTTPS. Request und Response sind JSON (UTF-8). Beginnen Sie mit dem Anlegen eines Kontos, dann eines API-Tokens, und führen Sie den ersten Aufruf innerhalb einer Minute aus. Alle Pfade sind relativ zur unten angegebenen Basis-URL.

Die komplette Testumgebung (Sandbox) finden Sie auf test.peppol.verteco.digital. Sie verhält sich genauso wie die Produktion und bietet zusätzlich Testwerkzeuge (FS-Webhook, Verifizierungsmerkmal (Verifikačný údaj), Löschen einer Firma) und eine simulierte Anbieterauswahl anstelle des Portals der Finanzverwaltung der Slowakischen Republik (Finančná správa, FS).

Base URL

https://peppol.verteco.digital/api/v1

Version

v1 (im Pfad). Rückwärtsinkompatible Änderungen erscheinen unter einer neuen Version.

Protokoll

nur HTTPS · TLS 1.2+ · TLS A+

Format

application/json (UTF-8)

Auth

Cookie-Session (Portal) oder Bearer-Token (Server-to-Server)

Zeitangaben

ISO-8601 (UTC), z. B. 2026-06-03T09:40:27Z

Konto und API-Token legen Sie im Portal an (über den Browser). Die Integration läuft danach ausschließlich über den API-Token. Registrierung, Anmeldung und Passwörter muss Ihre App nicht behandeln.

1. 1

   Legen Sie ein Konto im Portal an

   Registrieren Sie sich per E-Mail und bestätigen Sie es über den Link in der E-Mail.
2. 2

   Generieren Sie einen API-Token

   Im Portal API tokeny → Vytvoriť (API-Tokens → Erstellen). Der Token vpt_… wird nur einmal angezeigt. Bewahren Sie ihn sicher auf.
3. 3

   Führen Sie den ersten Aufruf aus

   Verwenden Sie den Token im Header Authorization:

   javascriptKopírovať

   const res = await fetch('https://peppol.verteco.digital/api/v1/companies', {
   headers: { Authorization: 'Bearer vpt_8f2a…' },
   });
   const companies = await res.json();

4. 4

   Anbieterauswahl im Portal der Finanzverwaltung

   In der Produktion ist die Auswahl von Verteco im FS-Portal (vpds.financnasprava.sk) auch bei reinem Versand nötig: sie schaltet das Senden frei (Verifizierungsmerkmal) und aktiviert die Firma. Der Empfang kann beim Anbieter Ihres Buchhaltungsprogramms bleiben: eine Firma hat im Netz genau einen Empfänger, aber beliebig viele Sender.

export BASE=https://test.peppol.verteco.digital   # production: https://peppol.verteco.digital
export KEY=vpt_…        # step 1

Neben der SAPI-Mock-Sandbox (unten) betreiben wir auch eine vollwertige Testumgebung, eine vollständige Kopie dieses Portals mit getrennten Daten, in der Sie den gesamten Ablauf (Registrierung → Firma → Senden → Empfangen → Benachrichtigungen) end-to-end ausprobieren können, ohne jegliche Auswirkung auf den Produktivbetrieb.

URL

https://test.peppol.verteco.digital

Registrierung

ohne Bestätigungs-E-Mail; das Konto ist sofort nutzbar

Genehmigung der Firma

automatisch, direkt in der Oberfläche oder über die API; ohne Auswahl des Anbieters im Portal der Finanzverwaltung der Slowakischen Republik (Finančná správa, FS) und ohne Anmeldung im FS-Portal; unmittelbar nach dem Anlegen einer Firma mit USt-IdNr. (IČ DPH) können Sie sowohl senden als auch empfangen

Registrierung im Netzwerk

automatisch in das Peppol-Testnetzwerk. Beachten Sie die zwei Ebenen des Identifikators: API und Portal verwenden dasselbe Format wie die Produktion (peppolParticipantId = 0245:<DIČ-Ziffern>, DIČ = slowakische Steuernummer; Ihr Integrationscode ändert sich nicht); im Test-SMP/SML wird die Firma technisch als 9950:SK<DIČ> eingetragen, weil das Schema 0245 einen Verifizierungscode der Finanzverwaltung verlangt, der im Test nicht existiert. In der Produktion wird 0245:<DIČ-Ziffern> erst nach der Auswahl des Anbieters im FS-Portal (Anmeldung per eID oder mit den Zugangsdaten) in das produktive Netzwerk registriert

Validierung

real: Regeln nach EN 16931 + Peppol BIS 3.0, dieselben wie im Produktivbetrieb

Zustellung

real über das Peppol-Testnetzwerk (AS4, Testzertifikat, Test-SML/SMP): ein im Testnetzwerk registrierter Empfänger erhält die Rechnung als empfangene Rechnung (inklusive E-Mail, PDF und Webhook); in das produktive Netzwerk geht nichts hinaus

Zustellnachweis (MLS)

echter MLS-Zustellnachweis aus dem Testnetzwerk

E-Mails

werden real versendet (an die Adressen, die Sie angeben), mit dem Präfix [TEST]

Fehlersimulation

der Header X-Sandbox-Simulate: 503 (oder 502, 500, 429) auf einem beliebigen /sapi/document/*-Aufruf mit gültigem Token liefert den passenden Fehler; nichts wird verarbeitet oder gespeichert. Bei 500 (SAPI-PROC-500) und 429 (SAPI-SYS-003 mit Retry-After) erhalten Sie den SAPI-Fehlerumschlag; 503 und 502 kommen über den Netzwerkrand (DigitalOcean, Cloudflare) als HTTP 504 mit HTML-Body ohne Umschlag an, genau so sieht ein echter Ausfall von außen aus, sodass Sie auch die Verarbeitung einer Nicht-JSON-Antwort testen. Validierungsfehler erzeugen Sie mit ungültigem XML, 429 auch durch mehr als 300 Aufrufe pro Minute. Die Produktion ignoriert den Header

Preis

kostenlos, ohne Limits zum Ausprobieren

Dort funktioniert alles wie hier: Portal, REST API, SAPI-SK 1.0, E-Shop-Plugins und Webhooks. Es genügt, in Ihrer Integration die Domain durch test.peppol.verteco.digital zu ersetzen und die in der Testumgebung erstellten Token zu verwenden. Ideal für die Entwicklung der Integration, CI-Tests und die Schulung von Buchhaltern vor dem Produktivstart. Testbelege gehören nur dorthin: In der Produktion wird jeder inländische Beleg zwischen Umsatzsteuerzahlern an die Finanzverwaltung gemeldet, und die Meldung lässt sich nicht zurückziehen. Im Produktivportal testen Sie nur mit der Schaltfläche „Poslať skúšobnú faktúru“ (Testrechnung senden, 0,00 €); ab dem 1. 1. 2027 lehnt die Produktion Nummern TEST-/VITAJTE-ab (test_document_in_production).

Hinweis: Der Edge-Schutz der Testdomain blockiert die generischen Header User-Agent: Python-urllib und User-Agent: Java/1.8.x (der Standard-User-Agent von HttpsURLConnection in Java 8) mit HTTP 403 "error code: 1010" noch vor unserer API; die Produktivdomain peppol.verteco.digital lässt sie durch. Setzen Sie einen eigenen User-Agent: in Java entweder per JVM-Parameter -Dhttp.agent=meine-app/1.0(ohne Codeänderung; Java hängt "Java/1.8" an, das resultierende "meine-app/1.0 Java/1.8.0_xxx" wird durchgelassen, blockiert wird nur ein Header, der direkt mit "Java/1.8" beginnt) oder auf der Verbindung mit conn.setRequestProperty("User-Agent", "meine-app/1.0"). Gängige Clients (requests, httpx, Java 11+, Apache HttpClient, okhttp, axios, Go, PHP, curl) funktionieren unverändert.

Warum Firmen automatisch genehmigt werden

Die Finanzverwaltung hat keine Testumgebung des VPDS-Portals: Die Auswahl des Anbieters auf vpds.financnasprava.sk läuft nur in der Produktion und wird durch Anmeldung im FS-Portal (eID oder FS-Zugangsdaten) verifiziert, sodass Sie im Produktivbetrieb keine beliebige fremde Firma „auswählen" können. Damit Sie Ihre Integration trotzdem testen können, simulieren wir diesen Schritt in der Testumgebung: Jede Firma, die Sie anlegen, wird automatisch genehmigt (ohne Auswahl bei der FS), sodass Sie Absender und Empfänger anlegen und den gesamten Ablauf durchlaufen können.

Zum Testen der FS-Webhooks (Auswahl des Anbieters) haben wir ein eigenes Gegenstück zum Werkzeug der Finanzverwaltung: test.peppol.verteco.digital/sandbox-nastroje. Dort erzeugen Sie ein gültiges Verifizierungs-Token (Verifizierungsmerkmal, Verifikačný údaj) im Stil der FS und senden einen vollständigen Webhook an Ihren Endpoint, genau so, wie es das FS-Portal bei einer realen Auswahl tut. Zu Testzwecken angelegte Firmen können Sie wiederum deregistrieren (aus dem Portal und aus dem Test-SMP), gerade weil es auf Seiten der Finanzverwaltung keinen Testmodus gibt.

Die Integration authentifiziert sich mit einem API-Token im Header Authorization: Bearer vpt_…. Den Token erstellen Sie im Portal (API-Tokens); er hat das Format vpt_ + 40 Hex-Zeichen, wir speichern nur seinen SHA-256-Hash und er hat dieselben Zugriffsrechte wie Ihr Konto. Testen Sie ihn über /auth/me:

curl https://peppol.verteco.digital/api/v1/auth/me -H 'Authorization: Bearer vpt_8f2a…'
# 200 → { "id": "…", "email": "vy(at)firma.sk" }   (Token funktioniert)

Bei fehlendem oder ungültigem Token gibt die API zurück:

// 401 Unauthorized
{ "error": "unauthorized", "message": "Authentication required" }

Paginierung & Idempotenz

• Der Vertrag wächst nur: neue Felder (bei null weggelassen), neue optionale Parameter, neue Endpunkte und Ereignisse. Bestehende Feldnamen, Enum-Werte und Statuscodes ändern sich nicht.
• Ein neuer Enum-Wert oder ein neues Webhook-Ereignis kann jederzeit erscheinen; ignorieren Sie Unbekanntes und beantworten Sie ein unbekanntes Ereignis mit 2xx.
• Zeitstempel sind ISO 8601 UTC mit variabler Anzahl Nachkommastellen; parsen, nie als Text vergleichen. Beträge kommen als Zeichenketten mit zwei Dezimalstellen.
• Sollte eine Änderung je nicht additiv sein, kündigen wir sie im Changelog (E-Mail-Abo verfügbar) mindestens 90 Tage vorher an und behalten die alte Form während einer Übergangszeit.
• Sicherheitsmodell des API-Schlüssels (seit 3. Oktober 2026): ein Schlüssel liest und sendet Belege und verwaltet Firmen, Benachrichtigungen und Webhooks. Konto- und Schlüsselverwaltung (Schlüssel erstellen, einschränken oder widerrufen, MFA, Passwort, Sitzungen, Einladungen, Firmenübertragung, Vertragsunterschriften) erledigt nur eine angemeldete Person; ein Schlüssel erhält dort 403 token_not_allowed. GET /api/v1/tokens bleibt für Schlüssel offen.
• Die Vertragsversion steht in info.version von openapi.json, jede Änderung hat eine Changelog-Zeile mit Tag API oder Webhooks.

/changelog · /changelog/odber · openapi.json

Fehler haben eine einheitliche Form mit einem maschinenlesbaren error-Code. Validierungsfehler ergänzen eine Map fields (erster Fehler pro Feld).

// Business-Fehler
{ "error": "invalid_credentials", "message": "Invalid email or password" }

// Validierungsfehler (400); die Texte in "fields" liefert die API auf Slowakisch
{ "error": "validation_failed", "message": "Some fields are invalid",
"fields": { "ico": "IČO musí byť 8 číslic" } }

HTTP-Status

200 / 201 / 204

Erfolg (OK / erstellt / kein Inhalt)

400

ungültige Eingabe (siehe error / fields)

401

fehlende oder ungültige Authentifizierung

403

unzureichende Berechtigung (Rolle)

404

Ressource existiert nicht oder Sie haben keinen Zugriff darauf

405

HTTP-Methode für diesen Pfad nicht unterstützt

409

Konflikt (Handelsregisternummer IČO / E-Mail existiert bereits)

415

nicht unterstützter Content-Type (XML-Endpoints erwarten application/xml)

429

Rate-Limit überschritten (Header RateLimit-* und Retry-After, JSON-Body rate_limited)

Häufigste Fehlercodes

Ausfall des Access Points und Wiederholung

• Antwortet die API mit 502, 503 oder 504 oder gar nicht, haben wir den Beleg nicht übernommen: wiederholen Sie den Aufruf später mit demselben Idempotency-Key, nichts wird doppelt gesendet.
• Ein von der API angenommener Beleg (202 ACCEPTED, auch mit retrying: true) geht nach der Wiederherstellung von selbst hinaus: der Access Point wiederholt die Zustellung, den Stand sehen Sie über GET /sapi/document/sent oder per Webhook; gibt er die Zustellung am Ende auf, endet der Beleg als fehlgeschlagen und derselbe Key sendet ihn erneut.
• Der Empfang auf Netzebene hängt nicht vom Portal ab: eine Zustellung, die während eines Portalausfalls nicht durchkam, wiederholt der sendende Access Point nach den Peppol-Regeln, und der Beleg erscheint nach der Wiederherstellung im Portal. Meldungen an die Finanzverwaltung, die wegen des Ausfalls nicht hinausgingen, holt ein automatischer Wiederherstellungslauf nach (ein Übertragungsfehler wird wiederholt, eine inhaltliche Ablehnung nicht).
• Status und Verfügbarkeitshistorie finden Sie auf /status; in der Testumgebung simulieren Sie einen Ausfall mit dem Header X-Sandbox-Simulate (Abschnitt Testumgebung).

Die API ist durch Rate-Limiting in einem Fenster von 60 Sekunden geschützt (pro Instanz). Limit und Restkontingent liefern wir in jeder Response über Header; bei Überschreitung kommt 429 Too Many Requests mit Retry-After zurück.

Normale Aufrufe

dynamisches Limit mit großer Reserve, pro API-Token (oder Session, sonst IP); den aktuellen Wert liefert der Header RateLimit-Limit

Auth (/auth/*)

strengeres Limit pro IP (Anti-Brute-Force; außer /auth/me und /auth/logout)

RateLimit-Limit

Limit im Fenster

RateLimit-Remaining

wie viel noch übrig ist

RateLimit-Reset

Sekunden bis zum Zurücksetzen des Fensters

Retry-After

Sekunden bis zum nächsten Versuch (bei 429)

HTTP/2 429 Too Many Requests
RateLimit-Limit: <Limit im Fenster>
RateLimit-Remaining: 0
RateLimit-Reset: 37
Retry-After: 37

{ "error": "rate_limited", "message": "Too many requests. Slow down." }

HTTP/2 200
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41
RateLimit-Policy: 300;w=60

Opake Tokens vpt_… für den Server-to-Server-Zugriff. Der Klartext wird nur einmal bei der Erstellung angezeigt. Speichern Sie ihn. Wir speichern nur den SHA-256-Hash und ein 12-stelliges Präfix zur Anzeige.

curl -X POST https://peppol.verteco.digital/api/v1/tokens -b cookies.txt \
-H 'Content-Type: application/json' -d '{"name":"moja-appka"}'
# 201 Created
{ "id":"…","name":"moja-appka","token":"vpt_8f2a…","prefix":"vpt_8f2a3b…","createdAt":"…" }

Firmen (Handelsregisternummer IČO / USt-IdNr. IČ DPH), die Sie verwalten. Der Zugriff ist an die Mitgliedschaft gebunden: Sie sehen nur Firmen, deren Mitglied Sie sind. Wer eine Firma anlegt, wird ihr owner.

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":"Verteco digital services, s. r. o."}'

# 201 Created
{ "id":"08dd…","ico":"53412834","dic":"SK2121358349","legalName":"…",
"registeredAddress":null,"peppolParticipantId":null,
"status":"pending_verification","role":"owner","createdAt":"2026-06-03T09:40:27Z" }

Feld status

pending_verification

nach dem Anlegen; das Senden ist noch nicht freigeschaltet

active

verifiziert, Senden freigeschaltet

Rolle des Mitglieds

owner

Ersteller der Firma (Vollzugriff)

admin

Administrator (Änderungen, Webhooks, Verifizierung)

member

Mitglied (Lesen)

viewer

nur Lesen

Vor dem Senden muss die Firma über das Verifizierungsmerkmal (Verifikačný údaj, VÚ) verifiziert werden, ein signiertes Token der Finanzverwaltung der Slowakischen Republik (Finančná správa, FS). Nach erfolgreicher Verifizierung wechselt der status der Firma auf active und das Senden wird freigeschaltet.

curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/verification \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"token":"<1024-hex VÚ>"}'

# 200 OK
{ "companyId":"08dd…","status":"active","sendingVerified":true,
"verificationMethod":"self","verifiedAt":"2026-06-15T…Z" }

Protokoll der Peppol-Belege (empfangene und gesendete) je Firma. Es füllt sich, während Rechnungen über den Access Point fließen. An die Mitgliedschaft in der Firma gebunden, sortiert nach createdAt absteigend.

curl 'https://peppol.verteco.digital/api/v1/companies/{id}/documents?direction=received' \
-H 'Authorization: Bearer vpt_8f2a…'
# 200 OK
[ { "id":"…","direction":"received","peppolMessageId":"…","docTypeId":"…",
  "senderId":"0088:7300010000001","receiverId":"0245:2121358349",
  "invoiceNumber":"2026001","issueDate":"2026-06-03",
  "currency":"EUR","totalAmount":120.00,"status":"received","createdAt":"…" } ]

SAPI-SK ist die standardisierte nationale REST-Schnittstelle zwischen dem Kunden-/ERP-System und dem Access Point (sapi-sk.sk). Wir implementieren sie in vollem Umfang. Dadurch sind Sie nicht an die proprietäre Form unserer API gebunden und schreiben die Integration einmal für jeden beliebigen SAPI-SK Access Point.

Base URL

https://peppol.verteco.digital/sapi

Authentifizierung

OAuth2 client_credentials → kurzlebiger Access Token (JWT)

client_id

UUID Ihres API-Tokens (Liste im Dashboard-Bereich „API tokeny“, dt. API-Tokens)

client_secret

der vpt_…-Token selbst aus dem Portal

Version

1.3 (10 Operationen: 4× Auth, 6× Dokumente)

Sandbox (Probeumgebung)

Möchten Sie SAPI-SK ohne Registrierung und ohne Risiko ausprobieren? Verwenden Sie die öffentlichen Sandbox-Zugangsdaten. Die Sandbox validiert Requests genau wie der Produktivbetrieb, sendet aber niemals etwas in das Peppol-Netzwerk und arbeitet nicht mit realen Daten; sie liefert realistische Mock-Responses. Ideal für Entwicklung, CI und das Onboarding einer Integration.

client_id

sandbox

client_secret

sandbox

send

vollständige Validierung des API-Kontrakts + Mock 202 (es wird nichts zugestellt)

receive

1 Beispielbeleg sandbox-doc-0001 zum Testen von Parsing und Acknowledge

# 1) Sandbox-Token (ohne Registrierung)
curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "sandbox", "client_secret": "sandbox",
      "grant_type": "client_credentials" }'

# 2) Mock-Versand: wird validiert, aber es wird NICHTS real zugestellt
curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer <sandbox access_token>' \
-H 'X-Peppol-Participant-Id: 0245:0000000000' \
-H 'Content-Type: application/json' \
-d '{ "metadata": { "documentId": "TEST-1",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "senderParticipantId": "0088:sandbox-sender",
        "receiverParticipantId": "0088:sandbox-receiver" },
      "payload": "<Invoice>…</Invoice>", "payloadFormat": "XML" }'
# 202 { "providerDocumentId": "sandbox-…", "status": "ACCEPTED", … }

# 3) Beispiel-Postfach + Detail des Beispielbelegs
curl https://peppol.verteco.digital/sapi/document/receive \
-H 'Authorization: Bearer <sandbox access_token>'
curl https://peppol.verteco.digital/sapi/document/receive/sandbox-doc-0001 \
-H 'Authorization: Bearer <sandbox access_token>'

Authentifizierung

curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "<UUID des Tokens>", "client_secret": "vpt_8f2a…",
      "grant_type": "client_credentials" }'
# 200 OK
{ "access_token": "eyJhbGciOi…", "token_type": "Bearer",
"expires_in": 900, "refresh_token": "eyJhbGciOi…" }

// Body
{ "refresh_token": "eyJhbGciOi…" }

Versand eines Dokuments

curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer eyJ…' \
-H 'X-Peppol-Participant-Id: 0245:2121358349' \
-H 'Idempotency-Key: 7b1f0e2a-…' \
-H 'Content-Type: application/json' \
-d '{ "metadata": {
        "documentId": "INV-2026-001",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "processId": "urn:…:bis:billing:3.0",
        "senderParticipantId": "0245:2121358349",
        "receiverParticipantId": "0088:7300010000001",
        "creationDateTime": "2026-06-17T10:00:00Z" },
      "payload": "<Invoice …>…</Invoice>",
      "payloadFormat": "XML" }'
# 202 Accepted
{ "providerDocumentId": "…", "status": "ACCEPTED",
"receivedAt": "2026-06-17T10:00:01Z", "timestamp": "…" }
# bei Status "REJECTED" enthält die Response zusätzlich das Feld "detail"
# mit dem Ablehnungsgrund (Validierungsregeln, z. B. BR-CO-15)

curl -X POST https://peppol.verteco.digital/sapi/document/validate \
-H 'Authorization: Bearer eyJ…' \
-H 'Content-Type: application/xml' \
--data-binary @rechnung.xml
# 200 OK
{ "valid": false,
  "errors": [ "BR-CO-15: Invoice total amount with VAT (BT-112) = … " ],
  "warnings": [],
  "checkedAt": "2026-09-10T12:00:00Z" }

Empfang von Dokumenten

// 200 OK
{ "documents": [ { "documentId":"…","documentTypeId":"…",
  "senderParticipantId":"0088:…","receiverParticipantId":"0245:…",
  "creationDateTime":"2026-06-17T…Z" } ],
"nextPageToken": "50" }

Status gesendeter Dokumente

// 200 OK
{ "documents": [ {
  "documentId": "…",
  "receiverParticipantId": "0245:1084695645",
  "peppolMessageId": "befc9112-…",
  "status": "delivered",
  "statusDateTime": "2026-07-09T14:52:31Z",
  "creationDateTime": "2026-07-09T14:52:12Z" } ],
"nextPageToken": null }

MLS-Empfangsbestätigung und Zustellnachweise

Die MLS-Empfangsbestätigung (Peppol Message Level Status) ist die Antwort des empfangenden Access Points auf unsere Übertragung: AP = angenommen und zugestellt, AB = zugestellt ohne fachliche Bestätigung, RE = abgelehnt mit Grund. Das Portal speichert sie beim gesendeten Dokument und setzt den Status entsprechend: AP und AB bedeuten beide delivered (bei AB beginnt statusDetail mit „MLS AB: “ und mls.responseCode ist AB; nach SPOG on MLS ist das eine Zustellung ohne fachliche Bestätigung, kein Vorbehalt), RE bedeutet rejected. Nach § 76a Abs. 2 Buchst. d des Gesetzes 222/2004 muss der Anbieter Datum und Uhrzeit von Versand, Zustellung und Empfang nachweisen können; jede Zeile von GET /sapi/document/sent und jeder Webhook trägt diese drei Zeiten: sentAt (Übergabe an den Zustelldienst, damit ist nach § 85o Abs. 11 die Pflicht des Ausstellers erfüllt), deliveredAt (Bestätigung des Empfänger-Access-Points per MLS) und fsReportedAt (Meldung an die Finanzverwaltung). Ein ausländischer Access Point sendet unter Umständen nie eine MLS: das Dokument bleibt dann delivered mit dem Detail as4_receipt_only und ohne Bestätigung.

// 200 OK
{ "document": {
    "documentId": "…", "peppolMessageId": "befc9112-…", "status": "delivered",
    "sentAt": "2026-09-17T08:00:12Z", "deliveredAt": "2026-09-17T08:00:31Z", "fsReportedAt": null,
    "hasMls": true,
    "links": { "detail": "…/sapi/document/sent/…", "mls": "…/sapi/document/sent/…/mls" } },
  "mls": { "responseCode": "AP", "receivedAt": "2026-09-17T08:00:31Z", "url": "…/sapi/document/sent/…/mls" } }

Nachweise der FS-Meldung, Integrität und Zeitleiste (SAPI 1.8.14)

Seit 1.8.14 tragen jede Zeile von GET /sapi/document/sent, das Detail sowie Liste und Detail der empfangenen Belege ein Objekt fsReport: state = reported (Meldung an die Sammelstelle C5 übergeben, reportedAt = fsReportedAt), pending (Meldung geschuldet, Übergabe fehlgeschlagen, wird automatisch wiederholt, reason = c5_unavailable) oder not_required (keine Meldung; reason erklärt warum: cross_border, self_send_test, issuer_without_vat_id, recipient_without_vat_id, not_billing_document, tdd_disabled, before_2026_09_01, not_recorded). Nach der Übergabe kommt tddMessageId (SBDH InstanceIdentifier der Meldung) hinzu, nach der Antwort von C5 c5ResponseCode (AP/AB/RE), c5ResponseAt, c5Detail und die Zusammenfassung outcome: accepted (AP), accepted_with_reservations (AB), rejected (RE) oder null, solange C5 nicht geantwortet hat. outcome = rejected heißt: die Meldung wurde übergeben, aber die Finanzverwaltung hat sie abgelehnt (c5Detail trägt die verletzte Regel, z. B. BR-AE-08); state bleibt reported, weil die Übergabe stattgefunden hat, und das Portal sendet die korrigierte Meldung automatisch erneut (nach der Annahme wird outcome zu accepted). Gesendete Zeilen haben zusätzlich statusReason (Maschinencode hinter statusDetail: network_retrying, network_retrying_sent, as4_receipt_only, recipient_not_registered, transport_failed, mls_rejected, validation_failed), xmlSha256 (SHA-256 des übergebenen XML, bleibt nach der Inhaltslöschung erhalten), retention und receiptRetention = permanent (die MLS-Bestätigung wird nie gelöscht). Die Bestätigung im Detail hat mls.sha256 und mls.messageId. Empfangene Belege erhielten peppolMessageId, status (received/acknowledged), receivedAt, acknowledgedAt und xmlSha256 (SHA-256 der Bytes des Geschäftsdokuments genau so, wie links.xml sie liefert, ohne SBDH-Transporthülle; beim Empfang berechnet und nach der Inhaltslöschung erhalten). Beide Listen filtern Sie mit ?fsReport=reported|pending|not_required|rejected (rejected = outcome rejected), gesendete auch mit ?status=undeliverable. Die Antwort von POST /sapi/document/send trägt peppolMessageId bereits bei der Annahme. Alles ist additiv, bestehende Felder bleiben unverändert.

// POST { "documentIds": ["7c1e…", "9af0…", "unbekannt"] }  (max 200)
{ "documents": [ {
    "documentId": "7c1e…", "status": "delivered", "statusReason": null, "peppolMessageId": "befc9112-…",
    "sentAt": "2026-09-21T08:00:12Z", "deliveredAt": "2026-09-21T08:00:31Z", "fsReportedAt": "2026-09-21T08:05:40Z",
    "fsReport": { "state": "reported", "reportedAt": "2026-09-21T08:05:40Z", "reason": null, "outcome": "accepted",
                  "tddMessageId": "3f2a…", "c5ResponseCode": "AP", "c5ResponseAt": "2026-09-21T08:06:02Z", "c5Detail": null },
    "xmlSha256": "9b74…", "retention": { "mode": "storage", "contentAvailableUntil": null }, "receiptRetention": "permanent",
    "hasMls": true, "links": { "detail": "…", "mls": "…" },
    "mls": { "responseCode": "AP", "receivedAt": "2026-09-21T08:00:31Z", "url": "…", "sha256": "e1c0…", "messageId": "mls-…" } } ],
  "missing": ["9af0…", "unbekannt"] }

Massenversand

// Request
{ "documents": [ {
  "itemId": "fa-2026-001",
  "idempotencyKey": "fa-2026-001",
  "metadata": { "documentId": "2026001", "documentTypeId": "…", "processId": "…",
                "senderParticipantId": "0245:2121358349", "receiverParticipantId": "0245:1084695645" },
  "payload": "<Invoice …>", "payloadFormat": "XML" } ] }

// 202 Accepted
{ "total": 2, "accepted": 1, "rejected": 1, "failed": 0,
"results": [
  { "itemId": "fa-2026-001", "ok": true,  "providerDocumentId": "…", "status": "ACCEPTED" },
  { "itemId": "fa-2026-002", "ok": false, "errorCode": "SAPI-AUTH-003", "errorMessage": "…" } ] }

Fehlermodell

Alle SAPI-Fehler haben einen einheitlichen Envelope mit Kategorie, stabilem Code, dem Flag retryable und einer correlation_id für den Support. Bei einem Anmeldefehler (SAPI-AUTH-001) enthält der Envelope zusätzlich hint (eine verständliche Erklärung, was in Client Id und Client Secret gehört) und docs (Link zur Anleitung; MK-soft-Programme direkt auf /navody/mksoft#prepojenie). Beide Felder sind optional und fehlen sonst (1.8.20).

{ "error": {
  "category": "AUTH",
  "code": "SAPI-AUTH-001",
  "message": "Invalid client credentials.",
  "retryable": false,
  "correlation_id": "b4191dfc-…" } }

Bei einer empfangenen Rechnung können wir die Firma per E-Mail oder per Webhook (POST an Ihre URL) benachrichtigen. Die Zustellung ist durable: Sie wird in eine Ausgangsqueue geschrieben und asynchron zugestellt (15 s Timeout); bei einem Fehlschlag wiederholen wir bis zu 12× mit exponentiellem Backoff (30 s → max. 8 h, insgesamt rund 16 Stunden), danach Dead-Letter. HTTP 401/403 bedeutet, dass Ihr Endpunkt eine Authentifizierung verlangt, die wir nicht mitsenden; prüfen Sie stattdessen die Signatur webhook-signature und antworten Sie mit 2xx. Ein Ausfall Ihres Servers verliert die Benachrichtigung also nicht, wir stellen sie beim nächsten Versuch zu. Der SSRF-Schutz blockiert Loopback-/lokale Adressen; die Webhook-URL muss öffentlich erreichbar sein.

curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/webhook \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"url":"https://vas-system.sk/peppol/webhook"}'
# 200 OK { "url":"https://vas-system.sk/peppol/webhook", "hasSecret": true }

// 200 OK
{ "secret": "vpt_8f2a…" }

// 200 OK
{
"sent":     { "url": "https://vas-system.sk/peppol/webhook", "event": "webhook.test",
              "signed": true, "payload": "{…}" },
"received": { "status": 200, "body": "OK", "durationMs": 142, "error": null }
}
// 400 webhook_not_configured, wenn keine Webhook-URL gespeichert ist

Webhook-Payload

Sowohl bei einer empfangenen (invoice.received) als auch bei einer gesendeten (invoice.sent) Rechnung senden wir einen POST mit diesem Body; das Feld event unterscheidet den Typ.

Zwei weitere Events melden das Urteil des Netzwerks zu einer Rechnung, die Sie gesendet haben: invoice.delivered (der Access Point des Empfängers hat die Zustellung mit einem Zustellnachweis (MLS) bestätigt) und invoice.rejected (abgelehnt, entweder durch das Netzwerk oder bereits bei der Validierung vor dem Versand); invoice.undeliverable meldet einen Empfänger ohne Eintrag im Peppol-Netz (übernommen, der FS gemeldet, nicht zugestellt). Sie tragen die Identifikation des Belegs und der Firma (documentId, invoiceNumber, receiverId, peppolMessageId, companyDic, peppolParticipantId) sowie status, statusDetail mit dem Ablehnungsgrund und statusDateTime. Ist der erste Zustellversuch fehlgeschlagen und wiederholt ihn der Access Point selbst (in der Regel innerhalb einer Stunde), bleibt das Dokument submitted und statusDetail beginnt mit network_retrying: ; eine Zustellung ergibt dann delivered, ein Aufgeben rejected mit dem Präfix network_gave_up: . Dank ihnen müssen Sie den Status gesendeter Rechnungen nicht per Polling abfragen.

Das Event company.activated kommt, wenn ein Kunde die Auswahl des Anbieters im FS-Portal (VPDS) der Finanzverwaltung der Slowakischen Republik (Finančná správa, FS) abschließt (Body: event, companyId, companyDic, peppolParticipantId, status, verifiedAt); company.deactivated dagegen bei der Abmeldung der Firma aus dem Netzwerk (gleicher Body ohne verifiedAt). company.smp_registered_elsewhere kommt, wenn eine Firma die FS-Auswahl abgeschlossen hat, ihr Eintrag im nationalen SMP aber von einem anderen Anbieter gehalten wird (Body wie company.activated plus action: "migration_code_required" und migrateUrl). Das Vorgehen für Partner steht in der Vermittler-Dokumentation. Bis der Kunde einen Migrationscode eingibt, stellt das Netzwerk an den alten Anbieter zu. Details in der Anleitung /saas:

{
"event": "invoice.received",
"eventId": "7f1c2d9e-4b1a-4e3d-9c1f-0a2b3c4d5e6f",
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"documentId": "…",
"invoiceNumber": "2026001",
"senderId": "0088:7300010000001",
"supplierName": "Dodávateľ s.r.o.",
"receiverId": "0245:2121358349",
"issueDate": "2026-06-03",
"dueDate": "2026-06-17",
"deliveryDate": "2026-06-03",
"currency": "EUR",
"totalAmount": "120.00",
"peppolMessageId": "…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349"
}

Die Felder companyDic und peppolParticipantId identifizieren die Firma, auf die sich das Event bezieht (wichtig für Partner, die eine einzige Webhook-URL für alle ihre Kunden verwenden).

Urteil des Netzwerks zu einer gesendeten Rechnung:

{
"event": "invoice.delivered",          // oder "invoice.rejected"
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"documentId": "…",
"invoiceNumber": "2026001",
"receiverId": "0245:2120049096",
"peppolMessageId": "…",
"status": "delivered",                 // oder "rejected"
"statusDetail": null,                  // bei rejected: Ablehnungsgrund
"statusDateTime": "2026-06-03T10:15:42Z"
}

Aktivierung der Firma nach der Auswahl im FS-Portal (VPDS):

{
"event": "company.activated",          // company.deactivated hat denselben Body ohne verifiedAt
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"status": "active",
"verifiedAt": "2026-06-03T10:02:11Z"
}

Den Event-Namen trägt auch der Header X-Verteco-Event. Vollständige Liste der Events: invoice.received, invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported, invoice.report_pending, invoice.report_rejected, company.activated, company.deactivated, company.smp_registered_elsewhere sowie das Test-Event webhook.test. Einen unbekannten Event-Typ sollten Sie beiseitelegen und protokollieren; einen neuen Typ kündigen wir immer im Voraus an. Jedes Event trägt zusätzlich occurredAt (Ereigniszeit, ISO-8601 UTC) zum Sortieren sowie eventId (derselbe Wert wie im Header X-Verteco-Delivery-Id): eindeutig pro Event und bei jeder Wiederholung unverändert, also der richtige Schlüssel zum Deduplizieren (peppolMessageId wiederholt sich über invoice.sent, invoice.delivered und invoice.reported). invoice.*-Events tragen zusätzlich die Zeiten sentAt, deliveredAt, receivedAt und fsReportedAt (ISO-8601 UTC, null, bis das Ereignis eingetreten ist). invoice.reported kommt, wenn die Steuermeldung an die Finanzverwaltung (TDD) zum Beleg dem Zustellnetz übergeben wurde (§ 85o Abs. 11), bei einem Ausfall des C5 auch Tage später. Formale Schemata aller Events stehen im Abschnitt webhooks der OpenAPI-Spezifikation.

Signaturprüfung

Hat die Firma ein Secret, senden wir den Header X-Verteco-Signature in der Form sha256=HMAC-SHA256(secret, raw Body) (lowercase hex). Berechnen Sie den HMAC immer über die exakten Bytes des Bodys:

import crypto from 'node:crypto';

// rawBody = die exakten Bytes des Request-Bodys (kein erneut serialisiertes JSON)
function verify(rawBody, header, secret) {
const expected = 'sha256=' +
  crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Header jeder Zustellung: X-Verteco-Event (Event-Name), X-Verteco-Delivery-Id (= eventId im Body, bei jeder Wiederholung identisch), X-Verteco-Signature (der HMAC oben) und parallel die Standard-Webhooks-Header: webhook-id (= eventId), webhook-timestamp (Unix-Sekunden dieses Versuchs) und webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + body)). Schlüssel sind die UTF-8-Bytes Ihres Secrets; eine standardwebhooks-Bibliothek erwartet es als whsec_ + base64(secret). Empfohlene Verarbeitung: Signatur prüfen, Zustellungen mit einem webhook-timestamp älter als 5 Minuten ablehnen (Replay-Schutz), idempotent nach eventId verarbeiten, innerhalb von 15 Sekunden mit 2xx antworten und schwere Arbeit in die eigene Queue verlagern. Eine fehlgeschlagene Zustellung wiederholen wir 12-mal im Abstand von 30 s bis 8 h (insgesamt rund 16 Stunden); danach landet sie im Dead-Letter mit E-Mail-Hinweis und bleibt im Realtime-Log sichtbar. Eine produktive Webhook-URL muss https:// sein; die Testumgebung akzeptiert auch http://.

Massenkonfiguration: ein Token, mehrere Firmen

Ein einziger API-Token (an Ihr Konto/Ihre E-Mail gebunden) verwaltet alle Firmen, die dieses Konto besitzt: Wer eine Firma über POST /companies anlegt, wird deren owner und kann ihren Webhook einrichten. Der Webhook gilt pro Firma (eigene URL und eigenes Secret), sodass Sie mit demselben Token beliebig viele Firmen anbinden:

# 1) Liste Ihrer Firmen (seitenweise, siehe Firmen)
curl 'https://peppol.verteco.digital/api/v1/companies?page=0&limit=100' -H 'Authorization: Bearer vpt_8f2a…'

# 2) für JEDE Firma {id}: Webhook (und/oder E-Mail) setzen
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://vas-system.sk/peppol/webhook","notificationEmail":"faktury@firma.sk"}'

# 3) Signatur-Secret abholen (wird NUR EINMAL zurückgegeben) und für die Signaturprüfung speichern
curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
# → { "secret": "…" }

• Der Token muss owner/admin der jeweiligen Firma sein; bei einer Firma, in der er nur member/viewer ist, kommt 403 forbidden zurück (kein Cross-Tenant-Zugriff).
• Sie können jeder Firma eine andere URL geben oder allen dieselbe; im Payload unterscheiden Sie sie anhand von companyId (und receiverId).
• Bei Hunderten von Firmen beachten Sie das Rate-Limit pro Token (den aktuellen Wert liefert der Header RateLimit-Limit); arbeiten Sie in Batches mit Backoff bei 429 (Header Retry-After).
• Der Webhook wird erst dann tatsächlich ausgelöst, wenn die Firma in Peppol aktiv ist (nach der Auswahl von Verteco als Anbieter bei der Finanzverwaltung) und somit tatsächlich Belege empfängt.

Felder der von der API zurückgegebenen Objekte.

Company

Document

User · Token · Webhook

DIČ

Slowakische Steueridentifikationsnummer (10 Ziffern). Die slowakische Peppol-ID ist 0245: + die DIČ-Ziffern, ohne SK.

IČ DPH

Umsatzsteuer-Identifikationsnummer (SK + DIČ). Nur Umsatzsteuerzahler haben sie; ein Nichtzahler stellt mit Steuerkategorie O aus.

IČO

Unternehmensregisternummer (8 Ziffern). Feld ico in der API, BT-30 in UBL.

Verifikationstoken (VÚ)

Signatur der Finanzverwaltung, die bei der Anbieterwahl im FS-Portal entsteht; sie schaltet den Versand für die Firma frei.

VPDS

Die FS-Anwendung, in der ein Steuerpflichtiger seinen Zustelldienstleister (uns) wählt.

TDD

Tax Data Document, die Rechnungsmeldung an die Finanzverwaltung; wir erstellen und senden sie für Sie.

C5 / C6

Fünfte und sechste Ecke des Peppol-Modells: der Zugangspunkt der Finanzverwaltung, der TDDs empfängt (0242:001180).

MLS

Message Level Status, die Empfangsbestätigung des Zugangspunkts des Empfängers (AP = angenommen, RE = abgelehnt, AB = bestätigt).

SBDH

Standard Business Document Header, der Umschlag, in dem ein Beleg reist; sein InstanceIdentifier ist die peppolMessageId.

SML / SMP

Das Netzverzeichnis: SML findet das SMP des Empfängers, das SMP nennt Zugangspunkt und akzeptierte Belegtypen.

Über Peppol BIS Billing 3.0 hinaus einigen sich die slowakischen Hersteller von ERP- und Fakturierungssystemen laufend auf eine gemeinsame Interpretation optionaler Felder (die Diskussion läuft im Slack-Kanal der Finanzverwaltung der Slowakischen Republik, Finančná správa, FS). Nachfolgend die Konventionen, die unser Portal bereits heute berücksichtigt: Alles sind gültige BIS-Konstrukte, sie passieren unsere API unverändert, und empfangene Belege zeigen sie auch in der menschenlesbaren Vorschau und im PDF an.

• Abzug einer versteuerten Anzahlung auf Positionsebene: eine negative Position mit cac:DocumentReference, wobei cbc:ID die Nummer des Steuerbelegs zur erhaltenen Zahlung trägt und cbc:DocumentTypeCode den Wert 130 hat (BIS: invoice line object identifier, max. 1 pro Position). Eine empfangene Rechnung mit einer solchen Position wird in unserer Vorschau mit dem Hinweis „odpočet zálohy – daňový doklad č. …" (Abzug der Anzahlung, Steuerbeleg Nr. …) angezeigt.
• Steuerbeleg zur erhaltenen Zahlung: gemäß den FAQ der Finanzverwaltung wird InvoiceTypeCode 388 (Tax invoice) verwendet. Er passiert sowohl unsere API als auch die Validierung; der Abzug einer nicht bezahlten (nicht versteuerten) Anzahlung wird über cbc:PrepaidAmount ausgedrückt.
• Stornierung einer Rechnung: Gutschrift 381 (CreditNote) mit cac:BillingReference auf die ursprüngliche Rechnung, keine negative Rechnung 380. Achtung: Den Code 384 lehnt das Netzwerk für slowakische Parteien ab (die Regel PEPPOL-EN16931-P0112 erlaubt ihn nur zwischen deutschen Subjekten); für eine Korrektur nach oben dient die Belastungsanzeige 383.
• BT-83 PaymentID: in der slowakischen Praxis setzt sich für die Zahlerreferenz das Format /VS…/SS…/KS… durch; das variable Symbol allein ist ebenfalls üblich. Unsere Verarbeitung überträgt den Wert unverändert und zeigt ihn bei den Zahlungsangaben an.
• Zusätzliche Positionsangaben (Chargen, Seriennummern, Verfallsdaten) über cac:AdditionalItemProperty mit etablierten Bezeichnungen wie BatchNumber, SerialNumber, ExpirationDate.

An eine E-Rechnung können Anlagen (PDF, Bilder) als base64 im Element cac:AdditionalDocumentReference (BT-125) angehängt werden. Bei empfangenen Belegen verarbeiten wir Anlagen bis 25 MB je Anlage; beim Senden muss das gesamte XML einschließlich Base64-Anlagen unter 10 MB über SAPI-SK und unter 2 MB über den Portal-Reiter Odoslať súborom bleiben. Peppol legt kein einheitliches netzwerkweites Limit fest, die einzelnen Anbieter bestimmen es selbst (FS FAQ 9/DPH/2025/IM, Beispiel Nr. 67); prüfen Sie daher bei sehr großen Anlagen auch das Limit des Anbieters der Gegenseite.

Zwei Hilfs-Endpoints ohne Authentifizierung: derselbe Validierungskern und derselbe SML-Lookup, die auch unser Access Point verwendet. Sie eignen sich für CI ebenso wie für Prüfungen vor dem Versand; für sie gilt ein strengeres öffentliches Rate Limit.

curl -X POST https://peppol.verteco.digital/api/v1/public/peppol-validate \
-H "Content-Type: application/xml" \
--data-binary @faktura.xml

// 200 OK
{
"valid": false,
"errors": [
  "BR-CO-09: [BR-CO-09]-The Seller VAT identifier (BT-31) … shall have a prefix in accordance with ISO code…"
],
"warnings": []
}
// 400 = leerer Body (empty_document) oder Dokument über 3 MB (document_too_large)

// 200 OK
{
"registered": true,
"participantId": "0245:2121358349",
"smp": "sml.peppol-smp.sk",
"capabilities": ["Faktúra (BIS Billing)", "Dobropis", "Self-billing", "MLS doručenky"],
"lastCheckedAt": "2026-08-31T…Z"
}

Das Portal betreibt einen eigenen Server für das Model Context Protocol, den offenen Standard, über den KI-Assistenten (Claude Code, Claude Desktop, Cursor, VS Code Copilot und andere) externe Systeme anbinden. Der Assistent meldet sich mit einem gewöhnlichen API-Schlüssel des Kontos an und erhält sechs Werkzeuge; er sieht nie mehr als dieses Konto, und jeder Aufruf erscheint im API-Log des Schlüssels.

Adresse: https://peppol.verteco.digital/api/mcp. Transport: Streamable HTTP, JSON-RPC 2.0, zustandslos (POST /api/mcp, kein SSE-Stream, GET antwortet 405). Anmeldung mit dem Header Authorization: Bearer <API-Schlüssel>. Unterstützte Methoden: initialize, ping, tools/list, tools/call, resources/list, prompts/list.

Werkzeuge

• list_companies: Firmen des Kontos mit Peppol-ID, Status und Rolle (Beginn jedes Gesprächs)
• list_documents: gesendete/empfangene Rechnungen einer Firma mit Zustell- und Meldestatus, seitenweise
• get_document: eine Rechnung im Detail samt MLS-Quittung und Meldung, optional das UBL-XML (bis 1 MB)
• check_participant: Live-Prüfung des Empfängers im Peppol-Netz (SML)
• validate_document: UBL-Validierung gegen EN 16931 + Peppol BIS 3.0
• send_document: Versand einer Rechnung im Namen der Firma, erfordert confirm = true, die Versandfreigabe (Verifikačný údaj) gilt

Anbindung in Claude Code

claude mcp add --transport http verteco-peppol https://peppol.verteco.digital/api/mcp \
  --header "Authorization: Bearer vpt_..."

Claude Desktop (über die Brücke mcp-remote, benötigt Node.js)

{
  "mcpServers": {
    "verteco-peppol": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://peppol.verteco.digital/api/mcp", "--header", "Authorization: Bearer vpt_..."]
    }
  }
}

Der Versand einer Rechnung ist rechtlich bindend: Das Werkzeug lehnt einen Aufruf ohne confirm = true ab, und die Serveranweisungen verpflichten den Assistenten, die ausdrückliche Zustimmung des Nutzers zur konkreten Rechnung und zum Empfänger einzuholen. Fertige Konfigurationen für Cursor und VS Code sowie eine Schaltfläche zum Erstellen des Schlüssels finden Sie im Portal: API-Schlüssel → Reiter MCP-Server. API-Schlüssel → MCP-Server

Im Portal aktiviert ein Unternehmen seine eigene Adresse <24 zufällige Zeichen>@peppol.send.verteco.app. Eine E-Mail mit UBL-XML-Anhang, die aus einem freigegebenen Postfach an diese Adresse geht, versenden wir über das Peppol-Netz genau so, als wäre die Datei auf dem Reiter Per Datei senden hochgeladen worden; der Absender erhält eine Antwort mit dem Ergebnis je Anhang, und der Beleg steht mit Zustellstatus, MLS-Empfangsbestätigung und FS-Meldung im Portal und in der API. Einrichtung: Anbindungen und Integrationen → Versand per E-Mail (Eigentümer oder Administrator des Unternehmens, angemeldet). /dashboard/integrations/email

Verarbeitungsregeln

• Angenommen wird nur Post von einer Adresse auf der Freigabeliste des Unternehmens (höchstens 20); alles andere wird ohne Antwort verworfen.
• Standardmäßig muss die Absenderdomain beim zustellenden Server SPF oder DKIM bestehen (Angleichung wie bei DMARC, relaxed). Der zustellende Server weist zusätzlich Post ab, die weder SPF noch DKIM besteht, sowie Post gegen die DMARC-Richtlinie des Absenders. Die Prüfung lässt sich in den Einstellungen abschalten; nicht empfohlen.
• Anhang: UBL 2.1 Invoice oder CreditNote (Peppol BIS Billing 3.0), Endung .xml, optional in einer SBDH-Hülle; höchstens 10 Anhänge pro Nachricht, 15 MB pro Anhang, 200 Nachrichten pro Adresse und Tag. PDF und Nachrichtentext werden nicht verarbeitet.
• IFS Finvoice 2.0: ein .xml-Anhang mit IFS-SOAP-Hülle (IFSFinvoice) oder ein reines Finvoice wird in UBL umgewandelt und dann gleich verarbeitet. Umwandlungsregeln: INV02 oder negative Summe = Gutschrift (381) mit positiven Beträgen und Verweis auf die Ursprungsrechnung (OriginalInvoiceNumber, bei IFS OrderIdentifier); Verkäufer und Käufer nach slowakischer USt-IdNr. (SellerOrganisationTaxCode, BuyerOrganisationTaxCode → 0245:DIČ), ein Käufer außerhalb der Slowakei wird nicht umgewandelt; MwSt.-Aufschlüsselung aus VatSpecificationDetails, 0-%-Zeilen als Kategorie E mit Begründung aus VatFreeText, sonst „Oslobodené od DPH“; IFS-Rundungszeilen (Netto 0,00, MwSt. 0,01) entfallen, ein Einzelpreis, der nicht zur Zeilensumme passt, wird neu berechnet; Einheiten nach UN/ECE (kg → KGM, pcs → H87, h → HUR, unbekannt → C62 mit Originaltext in der Zeilennotiz); das eingebettete Rechnungsbild (InvoiceAttachments, PDF) wird bis 5 MB als Anhang mitgeführt; nur EUR. Das Ergebnis der Umwandlung steht in der Antwort und im Firmenprotokoll.
• Ergebnisadresse: sendet ein Systempostfach die Rechnungen, wählen Sie in den Einstellungen eine andere Adresse für die Antwort mit dem Ergebnis (replyTo in PUT /companies/{id}/email-send, leer = dem Absender antworten).
• Der Verkäufer im XML (EndpointID des Lieferanten, BT-34) muss dieses Unternehmen sein, sonst wird die Nachricht abgelehnt (eine weitergeleitete Rechnung Ihres eigenen Lieferanten wird nie als Ihre versendet). Der Käufer braucht eine EndpointID mit Schema (BT-49).
• Dieselbe Nachricht (Message-ID) wird einmal verarbeitet. Der Beleg trägt in API und Webhooks origin = email, Akteur = Absenderadresse.

Öffentlicher Health-Check-Endpoint, geeignet für das Monitoring.

// 200 OK
{ "service": "peppol-portal-backend", "status": "ok", "timestamp": "2026-06-17T…Z" }

Eine Live-Übersicht aller Komponenten finden Sie auf der Systemstatus-Seite.

Bereits in Produktion (oft fälschlich als fehlend angenommen)

• POST /companies/{id}/documents/send ist eine stabile Portalschnittstelle; für ERP-Integrationen bleibt SAPI-SK mit Idempotency-Key die Empfehlung.
• Die SMP-Registrierung erfolgt automatisch nach der Wahl im FS-Portal; Wechsel von einem anderen Anbieter über POST /companies/{id}/smp-migrate mit Migrationscode.
• MLS-Empfangsbestätigungen, Zustellnachweise und FS-Meldungen (fsReport) in jeder Zeile von /sapi/document/sent; Webhook-Replay für ein Zeitfenster.
• Auf Firmen beschränkte Schlüssel; MCP-Server für KI-Assistenten; UBL-Muster auf /vzory; öffentlicher Validator.

In Vorbereitung (Reihenfolge nach Nachfrage der Integratoren)

• Asynchroner Batch: POST /sapi/document/batch antwortet 202 mit Job-Link und Status je Position.
• Änderungsfeed GET /sapi/document/changes?since&cursor mit Cursor statt Offset-Paging.
• Ablauf und Rotation von API-Schlüsseln im Portal, Nur-Lese-Schlüssel.
• Mehrere Webhook-Endpunkte je Firma mit Ereignisfilter.