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();

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]

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.

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

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)

Vollständiger Fehlerkatalog

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." }

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 }

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.

{ "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 8× mit exponentiellem Backoff (30 s → max. 1 h), danach Dead-Letter. 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). 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, 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 8-mal im Abstand von 30 s bis 1 h; 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

Ü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. Unser Limit beträgt 25 MB pro Anlage. 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/SMP-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/SMP)
• validate_document: UBL-Validierung gegen EN 16931 + BIS 3.0 einschließlich der slowakischen Regeln
• 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

Ö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.

• POST/companies/{id}/peppol/register· Manuelle Registrierung im Peppol SMP über die API. Heute erfolgt sie automatisch bei der Auswahl des Anbieters im FS-Portal (VPDS) der Finanzverwaltung der Slowakischen Republik (Finančná správa, FS).

Möchten Sie frühzeitigen Zugang zur Integration, eine Sandbox oder haben Sie eine Frage? Melden Sie sich direkt:

Ihr Peppol-Kontakt

Miriama Mrkávková

+421 944 488 269·peppol​@​verteco.digital