API-documentatie GenerateSEPA: authenticatie, endpoints en fouten

Je begint zelden met een leeg blad. Je betaalgegevens staan al in een ERP, een boekhoudpakket, een CSV-export of een oud bankformaat. Het probleem begint wanneer die gegevens een geldig SEPA XML-bestand moeten worden, zonder handmatig opschonen, zonder herhaalde afwijzingen door de bank en zonder een administratie die vraagt waarom een veld dat optioneel leek toch verplicht was.

Daar schiet veel technische documentatie tekort. Ze vertelt welk endpoint welk bericht accepteert, maar niet waarom een ontbrekend machtigingskenmerk ertoe doet, waarom het sequentietype de betekenis van een incasso verandert of waarom een IBAN dat er goed uitziet toch kan worden afgekeurd. In financiële workflows is syntaxis maar de helft van het werk.

Goede API-documentatie verbindt het verzoek met de zakelijke gebeurtenis erachter. Dat is wat deze pagina doet voor de GenerateSEPA API: van authenticatie tot foutcodes, met werkende voorbeelden.

Aan de slag

Handmatige SEPA-bestanden lopen op bekende plekken vast: een export met het verkeerde datumformaat, een rekening die intern klopt maar voor de bank niet, een omschrijving die rechtstreeks van de factuur is overgenomen terwijl het bestand een striktere structuur verwacht. Met Excel-correcties en XML-controles op het laatste moment wordt het proces traag en kwetsbaar.

Met de API is het eenvoudiger. Je systeem stuurt JSON, de service controleert de gegevens en je krijgt een bankklaar SEPA XML-bestand voor incasso’s of overboekingen terug. De API doet drie dingen:

• Gegevens ontvangen: je applicatie stuurt de batchgegevens in JSON.
• Omzetten volgens de regels: de service zet die gegevens in de juiste SEPA-structuur.
• Bestand leveren: je systeem krijgt toegang tot het gegenereerde XML-bestand en geeft het door aan je bankproces.

Eerste stap: je API-sleutel

Authenticatie komt eerst. Toegang loopt via een API-sleutel die je in je accountdashboard ophaalt. Twijfel je nog of de API de juiste koppeling is, lees dan eerst de API gebruiken vanuit je eigen systeem of bekijk de API-pagina.

Vuistregel: behandel de API-sleutel vanaf dag één als productiegegeven, ook tijdens het testen. De meeste problemen ontstaan doordat teams de eerste testsleutel als wegwerpdata zien en die gewoonten meenemen naar productie.

Basis-URL en je eerste aanroep

Alle verzoeken gaan naar één basis-URL:

https://api.generatesepa.com

Je eerste geslaagde aanroep heeft één doel: een minimale maar geldige batch insturen en controleren dat je een created-antwoord en een downloadpad terugkrijgt. Begin niet met alle randgevallen uit je ERP. Begin met één incassant, één debiteur, één bedrag, één uitvoeringsdatum en één duidelijke omschrijving.

Kernbegrippen en workflow

Je integreert geen bestandsgenerator, maar een betaalproces met bancaire en juridische aannames erin. Volgens een analyse die Speakeasy aanhaalt, komt 65% van de mislukte implementaties van financiële API’s voort uit het verkeerd begrijpen van het zakelijke doel, niet van de syntaxis (Speakeasy over documentatie).

Het remittance-object

Het centrale object is de remittance: de batch transacties die operationeel en financieel bij elkaar horen. Het is meer dan een lijst betalingen; het vertelt de bank wie int of betaalt, onder welke kenmerken en volgens welke regels. Een remittance bevat:

• gegevens van de incassant of opdrachtgever: de rechtspersoon die int of betaalt;
• uitvoeringscontext: wanneer de bank de batch moet verwerken;
• transactieregels: de afzonderlijke debiteuren of begunstigden;
• schemakenmerken: velden die het verzoek koppelen aan de SEPA-eisen.

Waarom de SEPA-velden bestaan

• Creditor ID: je incassant-ID, dat de partij identificeert die incasseert.
• Mandate ID: het machtigingskenmerk dat de incasso koppelt aan de ondertekende machtiging van de debiteur.
• Sequence type: FRST en RCUR vertellen de bank of het de eerste incasso onder een machtiging is of een herhaalde. De verkeerde waarde kiezen is geen opmaakfout; het verandert de betekenis van de opdracht.

Een ontwikkelaar ziet strings in JSON, de administratie ziet juridische en bancaire herleidbaarheid. Goede API-documentatie bedient beide.

De workflow in vijf stappen

1. Je systeem stuurt JSON met batchgegevens en transactieregels.
2. De API controleert de kritieke velden, zoals kenmerken, datumformaten en rekeninggegevens.
3. De service zet het verzoek om naar SEPA XML in de juiste structuur voor het type batch.
4. Je systeem krijgt een resultaat met een bevestiging en toegang tot het bestand.
5. Het financiële proces gaat verder: downloaden, eventueel controleren en indienen bij de bank.

Een breder beeld van die JSON-naar-SEPA-omzetting vind je in SEPA XML API-workflows.

Authenticatie en beveiliging

De API gebruikt het Bearer-schema in de Authorization-header:

Authorization: Bearer YOUR_API_KEY

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

Zet de sleutel nooit hard in je broncode. Bewaar hem in een omgevingsvariabele en lees hem tijdens runtime:

• Lokaal: in een lokaal omgevingsbestand dat niet wordt gecommit.
• Gedeelde omgevingen: via de secret manager van je deploymentplatform.
• Rotatie: zorg dat je de sleutel kunt vervangen zonder codewijziging.
• Logging: print de volledige sleutel nooit in logs, stacktraces of supportscreenshots.

Alle gegevens worden onderweg versleuteld met TLS 1.2+. Daarnaast worden klantgegevens 10 minuten na verwerking automatisch van de servers verwijderd. Dezelfde korte termijn geldt voor de toegang tot het gegenereerde bestand, dus je integratie moet het resultaat direct ophalen. Wil je de beveiliging met je securityteam doornemen, deel dan veilig online betalen.

Een veilige integratie heeft één sleutel per omgeving, een kort pad van verzoek naar ophalen en logt bij fouten request-ID’s en validatiefouten, nooit geheimen.

Endpoint: een batch aanmaken

Het hoofdendpoint voor het genereren van bestanden is:

POST /v1/remittances

Het accepteert een JSON-bericht en geeft een created-antwoord terug als de validatie slaagt en het XML-bestand is gegenereerd.

Voorbeeld van een verzoek

Gebruik realistische waarden tijdens de ontwikkeling. Volgens een studie die Gravitee bespreekt, ontstaat 42% van de integratiefouten in de financiële sector doordat voorbeelden plaatshouders gebruiken die niet aan echte bankeisen voldoen (Gravitee over API-documentatie).

{
  "type": "direct_debit",
  "execution_date": "2026-06-30",
  "creditor_name": "Acme Services S.L.",
  "creditor_iban": "ES9121000418450200051332",
  "creditor_id": "ES98ZZZ123456789",
  "currency": "EUR",
  "sequence_type": "FRST",
  "transactions": [
    {
      "debtor_name": "Laura Martin",
      "debtor_iban": "ES7921000813610123456789",
      "amount": 125.50,
      "concept": "Invoice INV-2026-0042",
      "mandate_id": "MANDATE-00045",
      "mandate_signature_date": "2025-12-15",
      "end_to_end_id": "INV-2026-0042"
    }
  ]
}

Veldreferentie

Veld	Type	Verplicht	Omschrijving
type	string	Ja	Soort batch, zoals incasso of overboeking
execution_date	string	Ja	Uitvoeringsdatum in ISO 8601-formaat
creditor_name	string	Ja	Naam van de partij die int of betaalt
creditor_iban	string	Ja	IBAN van de rekening die betaalt of int
creditor_id	string	Verplicht bij incasso	Incassant-ID
currency	string	Ja	Valutacode. Gebruik EUR voor SEPA
sequence_type	string	Verplicht bij incasso	Sequentie zoals FRST of RCUR
transactions	array	Ja	Lijst met betaal- of incasso-opdrachten

Elk item in transactions ondersteunt:

• debtor_name: string, verplicht bij incasso. Naam van de rekeninghouder.
• debtor_iban: string, verplicht. Rekening in IBAN-formaat.
• amount: number, verplicht. Bedrag van de transactie.
• concept: string, verplicht. Leesbare omschrijving.
• mandate_id: string, verplicht bij incasso. Machtigingskenmerk.
• mandate_signature_date: string, verplicht bij incasso. ISO 8601-datum.
• end_to_end_id: string, optioneel maar aanbevolen. Kenmerk dat het afletteren vergemakkelijkt.

Validatieregels die ertoe doen

• Datums in ISO 8601: YYYY-MM-DD, geen lokale notatie zoals 30/06/2026.
• IBAN’s worden gecontroleerd op landcode, lengte en controlegetal. Een rekening die er goed uitziet kan toch falen; test vooraf met de IBAN-validator.
• Houd de omschrijving kort en bankveilig; het is geen vrij notitieveld uit je CRM.
• Het sequentietype moet passen bij de status van de machtiging: FRST en RCUR zijn niet uitwisselbaar.
• Valuta volgt het SEPA-schema: gebruik EUR.

Implementatietip: valideer je JSON vóór verzending, maar kopieer niet elke bankregel naar je eigen applicatie. Vang aan jouw kant de duidelijke opmaakfouten af en laat de API de autoriteit zijn voor de SEPA-specifieke controles.

Oude bankformaten koppelen

Komen je brongegevens uit oudere bankbestanden, maak de API-laag dan je vertaalpunt en niet je bedrijfslogica. Rekeninggegevens van de opdrachtgever gaan naar creditor_iban en de velden op batchniveau, betaler- of begunstigdenregels naar transactions, oude referentienummers naar mandate_id of end_to_end_id (afhankelijk van hun rol) en incassotype-indicatoren meestal naar sequence_type. Bouw het oude bestand dus niet regel voor regel na, maar bepaal eerst wat elk veld betekent en koppel die betekenis aan het schema.

API-antwoorden

Een geslaagd verzoek geeft 201 Created terug met een JSON-body:

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

Veld	Betekenis	Gebruik
remittance_id	Unieke ID van de gegenereerde batch	Bewaar in logs, afletterrecords en supporttickets
status	Verwerkingsresultaat	Controleer dat het XML-bestand klaar is voordat je het ophaalt
download_url	Tijdelijke beveiligde link naar het bestand	Haal het XML-bestand direct op en sla het op
expires_at	Verlooptijd van de toegang	Voorkom pogingen om een verlopen bestand op te halen

De download_url verloopt na 10 minuten. Bewaar het XML-bestand in je eigen beveiligde opslag als je het langer nodig hebt voor audit of operationele redenen. Een volwassen client doet direct na 201 Created:

1. remittance_id opslaan bij de interne batch-ID;
2. controleren dat status op voltooid staat;
3. het XML-bestand downloaden via download_url;
4. het bestand opslaan of doorgeven aan de volgende interne stap;
5. het resultaat vastleggen voor de audittrail.

Kernpunt: eerst ophalen, dan afletteren. Draai je dat om, dan wordt een geldige batch een onnodige ophaalfout.

Foutafhandeling en foutcodes

Elke fout bevat een HTTP-statuscode, een machineleesbare error_code en een leesbare error_message:

{
  "error_code": "INVALID_IBAN",
  "error_message": "The debtor_iban field failed IBAN validation.",
  "details": {
    "field": "transactions[0].debtor_iban"
  }
}

HTTP-status	Foutcode	Omschrijving	Wat je doet
400	INVALID_REQUEST	Body is onjuist of mist verplichte velden	Controleer JSON-structuur en verplichte velden
400	INVALID_IBAN	Een IBAN-veld is niet geldig	Controleer landcode, lengte en controlegetal
400	INVALID_DATE_FORMAT	Een datum heeft niet het verwachte formaat	Stuur datums als ISO 8601, bijvoorbeeld YYYY-MM-DD
400	INVALID_SEQUENCE_TYPE	Sequentietype past niet bij de context	Bepaal of de machtiging eerste of herhaald is
401	UNAUTHORIZED	API-sleutel ontbreekt, is verlopen of ongeldig	Controleer de Authorization: Bearer-header
429	RATE_LIMITED	Te veel verzoeken in korte tijd	Verlaag het tempo en probeer opnieuw met backoff
500	INTERNAL_ERROR	De service faalde bij een geldig verzoek	Probeer opnieuw indien zinvol en log de context voor support

Validatiefouten stoppen de workflow en worden een correctietaak. Authenticatiefouten vragen om een configuratiecheck, niet om blind opnieuw proberen. Bij 429 gebruik je een retry-strategie met tussenpozen. Serverfouten log je met de metadata die support nodig heeft, nooit met credentials.

Codevoorbeelden

cURL

Gebruik cURL voor je eerste live test: zo controleer je het API-contract zonder applicatielogica ertussen.

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 S.L.",
    "creditor_iban": "ES9121000418450200051332",
    "creditor_id": "ES98ZZZ123456789",
    "currency": "EUR",
    "sequence_type": "FRST",
    "transactions": [
      {
        "debtor_name": "Laura Martin",
        "debtor_iban": "ES7921000813610123456789",
        "amount": 125.50,
        "concept": "Invoice INV-2026-0042",
        "mandate_id": "MANDATE-00045",
        "mandate_signature_date": "2025-12-15",
        "end_to_end_id": "INV-2026-0042"
      }
    ]
  }'

Slaagt de aanroep, test dan meteen het ophalen via download_url. Mislukt hij, lees dan eerst de error_code voordat je in de JSON gaat zoeken.

JavaScript (Node.js)

import axios from "axios";

const apiKey = process.env.GENERATESEPA_API_KEY;

const payload = {
  type: "direct_debit",
  execution_date: "2026-06-30",
  creditor_name: "Acme Services S.L.",
  creditor_iban: "ES9121000418450200051332",
  creditor_id: "ES98ZZZ123456789",
  currency: "EUR",
  sequence_type: "FRST",
  transactions: [
    {
      debtor_name: "Laura Martin",
      debtor_iban: "ES7921000813610123456789",
      amount: 125.5,
      concept: "Invoice INV-2026-0042",
      mandate_id: "MANDATE-00045",
      mandate_signature_date: "2025-12-15",
      end_to_end_id: "INV-2026-0042"
    }
  ]
};

async function createRemittance() {
  try {
    const response = await axios.post(
      "https://api.generatesepa.com/v1/remittances",
      payload,
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        }
      }
    );

    console.log("Remittance created:", response.data.remittance_id);
    console.log("Status:", response.data.status);
    console.log("Download URL:", response.data.download_url);
  } catch (error) {
    if (error.response) {
      console.error("HTTP status:", error.response.status);
      console.error("Error code:", error.response.data.error_code);
      console.error("Message:", error.response.data.error_message);
    } else {
      console.error("Request failed:", error.message);
    }
  }
}

createRemittance();

Een uitgebreide uitleg voor Node.js vind je in de SEPA-API integreren in Node.

Python

Python past goed bij backoffice-automatisering, geplande taken en middleware voor de administratie.

import os
import requests

api_key = os.environ.get("GENERATESEPA_API_KEY")

payload = {
    "type": "direct_debit",
    "execution_date": "2026-06-30",
    "creditor_name": "Acme Services S.L.",
    "creditor_iban": "ES9121000418450200051332",
    "creditor_id": "ES98ZZZ123456789",
    "currency": "EUR",
    "sequence_type": "FRST",
    "transactions": [
        {
            "debtor_name": "Laura Martin",
            "debtor_iban": "ES7921000813610123456789",
            "amount": 125.50,
            "concept": "Invoice INV-2026-0042",
            "mandate_id": "MANDATE-00045",
            "mandate_signature_date": "2025-12-15",
            "end_to_end_id": "INV-2026-0042"
        }
    ]
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.generatesepa.com/v1/remittances",
    json=payload,
    headers=headers,
    timeout=30
)

if response.status_code == 201:
    data = response.json()
    print("Remittance created:", data["remittance_id"])
    print("Status:", data["status"])
    print("Download URL:", data["download_url"])
else:
    try:
        error = response.json()
        print("HTTP status:", response.status_code)
        print("Error code:", error.get("error_code"))
        print("Message:", error.get("error_message"))
    except ValueError:
        print("HTTP status:", response.status_code)
        print("Non-JSON error response:", response.text)

Deze voorbeelden gebruiken bewust credentials uit omgevingsvariabelen, een realistisch incassobericht, uitvoer met de kenmerken die je nodig hebt en een basiscontrole van de gestructureerde foutbody.

Rate limits, beschikbaarheid en best practices

Het platform biedt 99,9% beschikbaarheid en gebruikt een geversioneerde API onder /v1/, zodat je een stabiel integratiedoel hebt terwijl de API verder kan groeien. Gewoonten die supportwerk voorkomen:

• Respecteer rate limiting: herken 429 en probeer opnieuw met backoff.
• Zorg zelf voor idempotentie: probeert je jobrunner opnieuw na een timeout, controleer dan of de batch al is aangemaakt.
• Bewaar correlatiegegevens: koppel je eigen batch-ID aan de teruggegeven remittance_id.
• Lees de changelog vóór een release.

Een stabiele client heeft één request-builder voor batches, één response-handler voor succes en downloaden, één gedeelde foutparser en één retry-beleid voor tijdelijke fouten, niet voor validatiefouten. Draait je administratie dagelijks op deze batches, behandel de koppeling dan als een betaalpijplijn met een duidelijke eigenaar.

---

Wil je stoppen met het handmatig bouwen van SEPA-bestanden en overstappen op een gevalideerde JSON-naar-XML-workflow? Bekijk de GenerateSEPA API en genereer bankklare SEPA XML zonder zelf de conversielogica te onderhouden.

---

Veelgestelde vragen

Wat doet de GenerateSEPA API?

De GenerateSEPA API ontvangt een JSON-bericht met een incasso- of betaalbatch, controleert de gegevens op de SEPA-regels en geeft een bankklaar SEPA XML-bestand terug. Hij werkt voor zowel incasso's als overboekingen, zodat niemand nog handmatig XML hoeft te bouwen of te controleren.

Hoe authenticeer je bij de GenerateSEPA API?

Authenticatie gebeurt met het Bearer-schema in de Authorization-header: Authorization: Bearer YOUR_API_KEY. Je haalt de sleutel op in je accountdashboard en bewaart hem in een omgevingsvariabele, niet in je broncode. Behandel de sleutel vanaf de eerste testdag als productiegegeven.

Welke SEPA-velden zijn het belangrijkst in het API-verzoek?

Bij incasso's zijn naast de basisgegevens vooral creditor_id (je incassant-ID), mandate_id (het machtigingskenmerk) en sequence_type (FRST voor de eerste incasso, RCUR voor herhaalde incasso's) belangrijk. Een fout in deze velden verandert de juridische betekenis van de opdracht, niet alleen de opmaak.

Hoe lang is het gegenereerde SEPA XML-bestand beschikbaar?

De download-URL verloopt na 10 minuten en de klantgegevens worden na verwerking automatisch van de servers verwijderd. Haal het XML-bestand dus direct op na het antwoord 201 Created en bewaar het in je eigen beveiligde systeem. Bouw geen integraties die later oude downloadlinks uit logbestanden openen.

---

Gerelateerde artikelen