GenerateSEPA: Technische API-Dokumentation

In den meisten Fällen beginnt die Integration nicht bei null. Die Zahlungsdaten liegen bereits in einem ERP, einem Buchhaltungssystem, einem CSV-Export oder einem alten AEB-Workflow vor. Das Problem entsteht, wenn diese Daten zu gültigem SEPA-XML werden müssen – ohne manuelle Korrekturen, wiederholte Bankablehnungen oder ein Finanzteam, das fragt, warum ein vermeintlich optionales Feld doch Pflicht war.

Genau hier versagt technische API-Dokumentation häufig. Sie erklärt, welcher Endpunkt einen Payload akzeptiert – aber nicht, warum eine fehlende Mandatsreferenz wichtig ist, warum der Sequenztyp die Bedeutung einer Lastschrift verändert oder warum eine IBAN, die korrekt aussieht, trotzdem zu Folgegebühren führen kann. In Finanz-Workflows ist die Syntax nur die halbe Arbeit.

Gute technische API-Dokumentation muss den Request-Body mit dem Geschäftsereignis verbinden. Klare, interaktive Dokumentation kann die Onboarding-Zeit um bis zu 50 % und das Ticketvolumen um 30 bis 40 % reduzieren.

Einführung und erste Schritte

Die manuelle SEPA-Dateierzeugung scheitert meist an vertrauten Stellen: falsches Datumsformat, ungültige Kontonummer, falsch formatierter Verwendungszweck. Wenn diese Probleme durch Tabellenkorrekturen und Last-Minute-XML-Prüfungen gelöst werden, wird der Prozess langsam und fehleranfällig.

Der API-Ansatz ist einfacher. Ihr System sendet JSON, der Dienst validiert die Daten, und das Ergebnis ist eine bankfertige SEPA-XML-Datei für Lastschriften oder Überweisungen.

Wofür die API gedacht ist

Die API erfüllt drei Aufgaben:

• Datenempfang: Ihre Anwendung sendet Überweisungsdaten als JSON.
• Compliance-orientierte Transformation: Der Dienst mappt die Daten auf die korrekte SEPA-Struktur.
• Dateiauslieferung: Ihr System erhält Zugriff auf die generierte XML-Datei.

Authentifizierung

Die Authentifizierung kommt zuerst. Der Zugriff wird über einen API-Schlüssel gesteuert, den Sie im Account-Dashboard abrufen.

Praxisregel: Behandeln Sie den API-Schlüssel von Tag eins an als Produktions-Credential – auch beim Testen.

Basis-URL

https://api.generatesepa.com

Kernkonzepte und API-Workflow

Das zentrale Objekt ist die Remittance. Sie ist der geschäftliche Container für einen Batch von Transaktionen, die operativ und finanziell zusammengehören.

Warum die SEPA-Felder existieren

• Gläubiger-ID: identifiziert die Partei, die Lastschriften einzieht.
• Mandat-ID: verknüpft die Abbuchung mit der signierten Genehmigung des Schuldners.
• Sequenztyp: FRST und RCUR teilen der Bank mit, ob es sich um die erste Lastschrift oder eine Folgeabbuchung handelt. Der falsche Wert ändert die rechtliche Bedeutung der Zahlung.

Der Workflow in der Praxis

1. Ihr System sendet JSON mit Remittance-Metadaten und Transaktionszeilen.
2. Die API validiert geschäftskritische Felder wie IBANs, Datumsformate und Kontonummern.
3. Der Dienst konvertiert den Request in SEPA-XML gemäß dem korrekten Schema.
4. Ihr System erhält eine Antwort mit Zugriff auf die generierte Datei.
5. Der Finanzprozess geht weiter mit Download und Bankeinreichung.

Authentifizierung und Sicherheit

Die API-Authentifizierung verwendet das Bearer-Schema im Authorization-Header:

Authorization: Bearer IHR_API_SCHLÜSSEL

Minimales HTTP-Beispiel:

POST /v1/remittances HTTP/1.1
Host: api.generatesepa.com
Authorization: Bearer IHR_API_SCHLÜSSEL
Content-Type: application/json

Alle Daten während der Übertragung sind mit TLS 1.2+ verschlüsselt. Kundendaten werden 10 Minuten nach der Verarbeitung automatisch gelöscht. Laden Sie die generierte Datei daher sofort nach Erhalt der Antwort herunter.

Endpunkt-Referenz: Remittance-Erstellung

POST /v1/remittances

Beispiel-Request-Body

{
  "type": "direct_debit",
  "execution_date": "2026-06-30",
  "creditor_name": "Acme Services GmbH",
  "creditor_iban": "DE89370400440532013000",
  "creditor_id": "DE98ZZZ09999999999",
  "currency": "EUR",
  "sequence_type": "FRST",
  "transactions": [
    {
      "debtor_name": "Laura Müller",
      "debtor_iban": "DE27100777770209299700",
      "amount": 125.50,
      "concept": "Rechnung INV-2026-0042",
      "mandate_id": "MANDAT-00045",
      "mandate_signature_date": "2025-12-15",
      "end_to_end_id": "INV-2026-0042"
    }
  ]
}

Feldübersicht

Feld	Typ	Pflicht	Beschreibung
type	string	Ja	Art der Remittance: Lastschrift oder Überweisung
execution_date	string	Ja	Verarbeitungsdatum im ISO-8601-Format
creditor_name	string	Ja	Rechtlicher Name der initiierenden Partei
creditor_iban	string	Ja	IBAN des Kontos, das Gelder sendet oder einzieht
creditor_id	string	Pflicht bei Lastschrift	SEPA-Gläubiger-ID
currency	string	Ja	Währungscode. EUR für SEPA-Remittances
sequence_type	string	Pflicht bei Lastschrift	FRST oder RCUR
transactions	array	Ja	Liste der Zahlungs- oder Abbuchungsanweisungen

Wichtige Validierungsregeln

• Daten müssen ISO 8601 verwenden: YYYY-MM-DD.
• IBAN-Werte werden validiert auf Ländercodestruktur, erwartete Länge und Prüfsumme.
• Sequenztyp muss zum Mandat-Status passen. FRST und RCUR sind nicht austauschbar.

API-Antworten verstehen

Eine erfolgreiche Anfrage gibt 201 Created zurück:

{
  "remittance_id": "rem_8f3c2a91",
  "status": "completed",
  "download_url": "https://api.generatesepa.com/downloads/rem_8f3c2a91.xml",
  "expires_at": "2026-06-25T10:25:00Z"
}

Die download_url läuft nach 10 Minuten ab. Laden Sie die XML-Datei sofort herunter und speichern Sie sie in Ihrem eigenen System.

Fehlerbehandlung und Referenzcodes

{
  "error_code": "INVALID_IBAN",
  "error_message": "Das Feld debtor_iban hat die IBAN-Validierung nicht bestanden.",
  "details": {
    "field": "transactions[0].debtor_iban"
  }
}

HTTP-Status	Fehlercode	Beschreibung	Empfohlene Aktion
400	INVALID_REQUEST	Request-Body fehlerhaft oder Pflichtfelder fehlen	JSON-Struktur und Pflichtfelder prüfen
400	INVALID_IBAN	Ein IBAN-Feld hat die Validierung nicht bestanden	Ländercode, Länge und Prüfsumme prüfen
400	INVALID_DATE_FORMAT	Ein Datumsfeld verwendet kein ISO-8601-Format	Datum als YYYY-MM-DD senden
401	UNAUTHORIZED	API-Schlüssel fehlt, abgelaufen oder ungültig	Authorization: Bearer-Header prüfen
429	RATE_LIMITED	Zu viele Anfragen in kurzer Zeit	Anfragen verlangsamen und mit Backoff wiederholen
500	INTERNAL_ERROR	Interner Serverfehler	Wiederholen und Anfrage-Kontext für Support protokollieren

Praktische Integrationsbeispiele

cURL-Beispiel

curl -X POST "https://api.generatesepa.com/v1/remittances" \
  -H "Authorization: Bearer $GENERATESEPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "direct_debit",
    "execution_date": "2026-06-30",
    "creditor_name": "Acme Services GmbH",
    "creditor_iban": "DE89370400440532013000",
    "creditor_id": "DE98ZZZ09999999999",
    "currency": "EUR",
    "sequence_type": "FRST",
    "transactions": [{
      "debtor_name": "Laura Müller",
      "debtor_iban": "DE27100777770209299700",
      "amount": 125.50,
      "concept": "Rechnung INV-2026-0042",
      "mandate_id": "MANDAT-00045",
      "mandate_signature_date": "2025-12-15",
      "end_to_end_id": "INV-2026-0042"
    }]
  }'

Ratenlimits, SLAs und Best Practices

Die Plattform bietet 99,9 % Verfügbarkeit und verwendet ein versioniertes API-Modell unter /v1/.

Best Practices für Produktionsintegrationen:

• Ratenlimits beachten: 429-Antworten mit Backoff-Strategie behandeln.
• Idempotenz einplanen: Sicherstellen, dass Wiederholungsversuche erkennbar sind.
• Korrelationsdaten speichern: Interne Batch-ID mit der zurückgegebenen remittance_id verknüpfen.
• Changelogs vor Deployments prüfen: Versionierte APIs sind nur nützlich, wenn Sie auf Änderungen reagieren.

---

Wenn Sie SEPA-Dateien nicht mehr manuell erstellen und zu einem validierten JSON-zu-XML-Workflow wechseln möchten, bietet GenerateSEPA eine praktische Lösung für die Automatisierung von Remittances und die Erzeugung bankfertiger SEPA-XML-Dateien.

---

Häufig gestellte Fragen

Was macht die GenerateSEPA API?

Die GenerateSEPA API nimmt einen JSON-Payload mit Remittance-Daten entgegen, validiert die Daten gegen SEPA-Regeln und gibt eine bankfertige SEPA-XML-Datei zurück. Sie verarbeitet sowohl Lastschriften als auch Überweisungen und eliminiert die Notwendigkeit, XML manuell zu erstellen oder zu prüfen.

Wie authentifiziere ich mich bei der GenerateSEPA API?

Die Authentifizierung verwendet das Bearer-Schema im Authorization-Header: Authorization: Bearer IHR_API_SCHLÜSSEL. Den Schlüssel erhalten Sie im Account-Dashboard. Speichern Sie ihn in einer Umgebungsvariablen, niemals im Quellcode. Behandeln Sie den Schlüssel von Anfang an als Produktions-Credential, auch während der Testphase.

Was sind die wichtigsten SEPA-Felder im API-Request?

Für Lastschriften sind die Pflichtfelder über die grundlegenden Gläubiger- und Transaktionsdaten hinaus: creditor_id (die SEPA-Gläubiger-ID), mandate_id (Verknüpfung der Abbuchung mit einer signierten Genehmigung) und sequence_type (FRST für Erstlastschrift, RCUR für Folgelastschrift). Falsche Werte ändern die rechtliche Bedeutung der Zahlungsanweisung.

Wie lange ist die generierte SEPA-XML-Datei nach der Erstellung verfügbar?

Die Download-URL läuft nach 10 Minuten ab, und Kundendaten werden nach der Verarbeitung automatisch gelöscht. Laden Sie die XML-Datei sofort nach Erhalt der 201 Created-Antwort herunter und speichern Sie sie in Ihrem eigenen System. Bauen Sie keine Integrationen, die alte Download-Links aus historischen Logs verwenden.

---

Verwandte Artikel