Public API v1

De Public API is de machine-to-machine API voor externe systemen. In tegenstelling tot de interne frontend-API gebruikt deze API stabiele contracten, serviceaccounts en natuurlijke sleutels zoals externe request- en batchreferenties.

Basis

Onderdeel	Waarde
Base path	/api/v1
Swagger UI	/api/v1/docs
ReDoc	/api/v1/redoc
OpenAPI	/api/v1/openapi.json

Alle requests zijn organisatiegebonden en worden gelogd als inbound messages. Externe systemen horen geen interne database-ID's te gebruiken.

Beschikbare domeinen

Domein	Endpoints	Gebruik
Payment requests	/payment-requests	Externe betaalverzoeken indienen en volgen
Payment instruction batches	/payment-instruction-batches	Complete externe betaalruns importeren

Payment requests

Een payment request vertegenwoordigt een extern verzoek om een betaling door ERP-NL te laten verwerken. Het request bevat onder meer:

• external_request_id;
• begunstigde of payee-informatie;
• bankrekeninggegevens;
• regels en verdelingen;
• valuta en bedrag;
• organisatiecontext.

ERP-NL valideert het request, koppelt waar mogelijk natuurlijke sleutels aan interne records en geeft de status terug zonder interne IDs te lekken.

Payment instruction batches

Payment instruction batches zijn bedoeld voor externe betaalruns, bijvoorbeeld uit Oracle EBS. Een batch bevat een externe batchreferentie, debtor-informatie en een lijst betalingsinstructies.

Belangrijke regels:

• alle instructies in de batch gebruiken dezelfde valuta als de batch;
• external_payment_id moet uniek zijn binnen de payload;
• per regel is external_invoice_id of invoice_number verplicht;
• onbekende creditor bank accounts falen tenzij het serviceaccount auto-approval-recht heeft;
• idempotente replay met dezelfde payload geeft hetzelfde resultaat terug.

Idempotentie

De Public API gebruikt externe sleutels en payload hashes om dubbele verwerking te voorkomen.

Situatie	Gedrag
Zelfde externe sleutel, zelfde payload	Bestaande resource teruggeven
Zelfde externe sleutel, andere payload	409 Conflict
Andere externe sleutel	Nieuwe verwerking

Rechten

Recht	Gebruik
payables.payment_request.create	Payment request indienen
payables.payment_request.read	Payment requests lezen
payments.instruction_batch.create	Payment instruction batch indienen
payments.instruction_batch.read	Batchimports lezen
payments.instruction_batch.bank_account.auto_approve	Onbekende creditor bank accounts automatisch toestaan

Verdiepende referentie

De technische contractdetails en payloadvoorbeelden staan in de repo onder docs/reference/public-api.md. Die referentie is geen onderdeel van de gepubliceerde VitePress-site, maar is wel nuttig voor integratiebouwers en reviewers.