SAPI-SK für Entwickler

Was SAPI-SK ist

SAPI-SK ist die nationale REST-Schnittstelle zwischen dem Client-System (ERP, E-Shop, Buchhaltungssoftware) und dem Access Point. Ziel ist ein einheitlicher, anbieterunabhängiger Weg, über einen zertifizierten Zustelldienst („digitálny poštár“) Belege zu senden und zu empfangen, statt der proprietären API jedes Anbieters. Betrachten Sie die Unterstützung von SAPI-SK deshalb als Absicherung gegen Vendor-Lock-in.

Authentifizierung

Verwendet wird OAuth2 client_credentials. Im Portal erstellen Sie einen API-Token: seine UUID dient als client_id und der Wert vpt_… als client_secret. Über POST /sapi/auth/token erhalten Sie einen kurzlebigen Access Token und einen Refresh Token; den Access Token senden Sie dann im Header Authorization: Bearer …. Das Widerrufen des API-Tokens im Portal macht sofort auch die ausgestellten Tokens ungültig.

Senden und Empfang

• Senden: POST /sapi/document/send mit dem Header X-Peppol-Participant-Id (der Teilnehmer, FÜR DEN Sie senden: Ihr Unternehmen oder ein Mandant unter Ihrem Token; der Empfänger wird in den Metadaten des Dokuments angegeben) und Idempotency-Key (sicheres Wiederholen ohne Duplikate). Gebündelt über POST /sapi/document/batch (bis zu 100 Belege je Aufruf).
• Zustellstatus: GET /sapi/document/sent liefert die Status der gesendeten Belege (pending → delivered / rejected aus der MLS-Zustellbestätigung, oder undeliverable, wenn der Empfänger keine Adresse im Peppol-Netzwerk hat), mit ?since= für inkrementelles Abholen.
• Empfang: GET /sapi/document/receive (Seitennavigation, Filter nach Status) und Bestätigung der Verarbeitung über acknowledge.
• Nachweise und FS-Meldungen (ab 1.8.14): Jeder Beleg trägt ein Objekt fsReport (reported / pending / not_required mit Grund, Meldungs-ID und C5-Verdikt), gesendete Belege zusätzlich statusReason und xmlSha256; der Status von bis zu 200 Belegen auf einmal über POST /sapi/document/sent/status, die Zeitleiste über GET /sapi/document/sent/{id}/events. Webhooks tragen fsReport und die neuen Ereignisse invoice.report_pending und invoice.report_rejected.
• Tokenstatus / Erneuerung / Widerruf: eigene Endpunkte unter /sapi/auth/*.

Sandbox und Idempotenz

Den Kontrakt können Sie in der Sandbox ohne das Risiko einer echten Zustellung ausprobieren: Die Sandbox validiert die Anfragen und liefert Mock-Antworten. Verwenden Sie beim Senden immer einen Idempotency-Key: Beim Wiederholen derselben Anfrage (z. B. nach einem Timeout) entsteht kein doppelter Beleg. Leiten Sie den Schlüssel aus etwas für die Rechnung Beständigem ab (z. B. der ID oder der Rechnungsnummer in Ihrem System); ein neuer Schlüssel für dieselbe Rechnung umgeht diesen Schutz. Hat unsere Prüfung vor dem Versand den Beleg abgewiesen (z. B. Validierungsfehler), ist nichts ins Netzwerk gegangen und nichts wird an die Finanzverwaltung gemeldet: Korrigieren Sie ihn und senden Sie ihn mit demselben Schlüssel erneut, mit dem Ausstellungsdatum des Tages, an dem er tatsächlich hinausgeht. Eine zugestellte Rechnung wird nicht erneut gesendet, sondern mit einer Gutschrift oder einer Belastungsanzeige korrigiert. Fehlern beugen Sie mit POST /sapi/document/validate (prüft den Beleg ohne Versand) und GET /sapi/discovery (ist der Empfänger im Peppol-Netzwerk) vor.

Wo Sie die Details finden

Die vollständige Liste der Endpunkte, Beispiele für Anfragen und Antworten sowie die Fehlercodes stehen in unserer technischen Dokumentation (Abschnitt SAPI-SK), einschließlich der maschinenlesbaren OpenAPI-3.1-Spezifikation. Wir empfehlen, in der Sandbox zu beginnen und erst danach auf die Produktion zu wechseln.