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
Integratie-ingest	/integrations/{definition_code}/ingest	Generieke payloads ontvangen via Integration Control Center
Integratiecatalogus	/integrations/catalog	Contract-aware documentatielinks per actieve inbound integratie
Integratie OpenAPI	/integrations/{definition_code}/openapi.json	Concrete payloaddocumentatie per integratie

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.

Integratie-ingest

Integratie-ingest is de Public API-ingang voor het Integration Control Center. Een extern systeem post een payload naar POST /api/v1/integrations/{definition_code}/ingest. ERP-NL zoekt de actieve integratiedefinitie op, legt de inbound message vast en verwerkt de payload via de geconfigureerde mapping en flow.

Gebruik dit voor generieke inbound integraties die niet direct als payment request of payment instruction batch worden aangeboden. De runtime gebruikt de actieve mapping en flowconfiguratie. De algemene /api/v1/docs en /api/v1/redoc tonen de catalogus-operatie als navigatiepunt; de runtime-call zelf blijft beschermd. Een directe browserklik naar de catalogus zonder service-account Bearer-token geeft daarom 401 Not authenticated. Voor iedere actieve inbound integratie kan een service-account met integrations.execute de concrete documentatie ophalen via:

GET /api/v1/integrations/catalog?organization_short_code=MINKD
GET /api/v1/integrations/{definition_code}/openapi.json?organization_short_code=MINKD
GET /api/v1/integrations/{definition_code}/docs?organization_short_code=MINKD
GET /api/v1/integrations/{definition_code}/redoc?organization_short_code=MINKD

Gebruik in Swagger UI eerst Authorize of stuur dezelfde Authorization: Bearer <access_token> header mee vanuit Postman of een integratieclient.

Bij een inbound mapping documenteert ERP-NL het externe source contract, bijvoorbeeld OracleEbsPaymentBatch.v1 of CustomAppPaymentBatch.v1, terwijl de IntegrationDefinition zelf naar het canonieke business contract PaymentInstructionBatch.v1 kan blijven wijzen. Hetzelfde contractschema wordt gebruikt voor documentatie, fictieve voorbeelden en runtimevalidatie van payload.

Belangrijke regels:

• definition_code verwijst naar een actieve IntegrationDefinition;
• idempotency en correlation keys voorkomen dubbele verwerking;
• mappingfouten of domeinfouten worden als integratie-uitzondering zichtbaar;
• beheerders kunnen verwerking herstellen, opnieuw proberen of replayen via Integratiebeheer.

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
integrations.execute	Integratiepayloads indienen en verwerken

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.