-
Aanleveren Portaal maakt gebruik van de Oauth2 voor autorisatie. Softwareleveranciers kunnen via deze koppeling aan Aanleveren Portaal gebruikers toestemming vragen om namens hen te handelen. Zo kan je eenvoudig en veilig data delen met de uitvragende partij: Koppel je software aan met Oauth
- Onderaan deze pagina vind je een voorbeeld Postman-collectie (.json) met daarin de API-calls die ondersteund worden door Aanleveren Portaal.
- De Swagger definitie van de Aanleveren Portaal API is hier te vinden.
- Het gebruik van de API vereist een API token. Deze kunnen we aanmaken op de instellingen pagina van Aanleveren Portaal. Deze token geven we als header mee bij alle requests.
Een rapportage versturen naar de bank (via de BIV)
Het versturen van een rapportage naar de BIV, via Aanleveren Portaal, bestaat uit drie stappen/calls:
- Het XBRL-bestand uploaden (maximaal 25 MB)
- Bijlagen uploaden (maximaal 25 MB per bijlage met een maximum van 150 MB in totaal, incl. XBRL)
- De rapportage aanleveren aan de BIV
Het XBRL-bestand uploaden
Voor het uploaden van het XBRL-bestand doen we met een HTTP multipart POST .
| Request |
|
curl -i -X POST \ - H "x-api-key: $token" \ - H "Content-Type: multipart/form-data" \ - F "file=@valid.xbrl" \ https://acc-aanleverenapi.sbrnexus.nl/api/reports |
| Response |
|
{ "guid": "AMX5LQjUSyGhlFdIe71f-g", "filename": "valid.xbrl", "checksum": "14293581bf91d848a811708e7e120a9b87c389595e9752ded054fdc0c9b924e4", "cocNumber": 12345678, "cocOrganizationName": null, "entryPoint": { "guid": "XSCXnm5nShutabIKHbcaPQ", "uri": "https://www.sbrnexus.nl/ft15/frc/20201211/entrypoints/frc-rpt-nt-inrichtingsjaarrekening-2020.xsd", "name": "FT15 nt-inrichtingsjaarrekening-2020" }, "sizeInBytes": 184831, "version": 0 } |
Als resultaat krijgen we het aangemaakte report terug. Hierin staat het schemareferentie (entryPoint) van het bestand en het KVK-nummer (cocNumber) als deze automatisch gevonden kon worden. Bij het aanleveren kan naar deze rapportage verwezen worden door de guid uit het resultaat te gebruiken.
Bijlagen uploaden
Voor sommige berichtsoorten is het mogelijk of noodzakelijk om bijlagen mee te sturen als onderdeel van de aanlevering. Om te bepalen welke types en aantallen zijn toegestaan moeten de berichtsoorten worden opgehaald (zie "Rapportage aanleveren bij de BIV").
Net als voor de rapportage, gebruiken we voor het uploaden een HTTP multipart POST .
| Request |
|
curl -i -X POST \ -H "x-api-key: $token" \ -H "Content-Type: multipart/form-data" \ -F "file=@attachment.xbrl" \ https://acc-aanleverenapi.sbrnexus.nl/api/attachments |
| Response |
|
{ "guid": "--K3tyNmQ2mqEWZTWMMhiQ", "filename": "attachment.xbrl", "mimeType": "application/xml", "checksum": "14293581bf91d848a811708e7e120a9b87c389595e9752ded054fdc0c9b924e4", "version": 0, "sizeInBytes": 184831 } |
Bij het aanleveren kan naar deze bijlage verwezen worden door de guid uit het resultaat te gebruiken.
Rapportage aanleveren bij de BIV
Aanleveren Portaal gebruikt het berichtsoorten, message types, om aan te geven welk rapportage type naar welke ontvangende partij wordt verstuurd. Berichtsoorten zijn rapportage types en zijn gekoppeld aan toegestane schemareferenties (allowedEntryPoints), ontvangende partijen (allowedReceivers). Hierdoor kun je niet per ongeluk een rapportage type aanleveren bij een ontvangende partij die deze niet ondersteunt. Ook heeft elke berichtsoort een maximum aantal bijlages dat bij een aanlevering mag worden meegestuurd (maximumNumberOfAttachments), en zijn er restricties op de toegestane types en aantallen (all owedAttachments).
De beschikbare berichtsoorten halen we op met een GET.
| Request |
|
curl -i -H "x-api-key: $token" https://acc-aanleverenapi.sbrnexus.nl/api/message-types |
| Response |
|
[ { "guid": "fSXzCi52QrSWiwJv4DH7wg", "name": "Jaarrekening", "description": "Jaarrekening met OIN routering", "maximumNumberOfAttachments": 4, "allowedReceivers": [ { "receiver": { "guid": "AwvHWCDjQ3WmD7KCqRiZjA", "name": "Test Bank", "identityNumber": "00000000123456780000" }, "active": true }, (...) ], "allowedEntryPoints": [ { "entryPoint": { "guid": "XSCXnm5nShutabIKHbcaPQ", "uri": "https://www.sbrnexus.nl/ft15/frc/20201211/entrypoints/frc-rpt-nt-inrichtingsjaarrekening-2020.xsd", "name": "FT15 nt-inrichtingsjaarrekening-2020" }, "active": true }, (...) ], "allowedAttachments": [ { "dataType": "XBRL", "minimumNumberOfAttachments": 0, "maximumNumberOfAttachments": 4, "active": true }, (...) ], "active": true }, (...) ] |
Het resultaat bevat veel message types. Deze lijst zal maximaal één keer per dag geupdate worden en kan voor die periode gecached worden.
Nu kunnen we het bericht versturen. Dit doen we door een aanlevering, filing, aan te maken met een POST. Geef hierbij het aanleverkenmerk mee via filing Reference.
| Request |
|
curl -i -X POST -H "x-api-key: $token" -H "Content-Type: application/json" -d '{ "report": { "guid": "AMX5LQjUSyGhlFdIe71f-g" }, "attachment": [ { "guid": "--K3tyNmQ2mqEWZTWMMhiQ" } ], "filingReference": "Test aanlevering", "messageTypeGuid": "fSXzCi52QrSWiwJv4DH7wg", "receiver": { "guid": "AwvHWCDjQ3WmD7KCqRiZjA" } }' https://acc-aanleverenapi.sbrnexus.nl/api/filings |
| Response |
|
{ "guid": "mMeaU7cJR5C0LM8E80ZVKA", "report": { "guid": "AMX5LQjUSyGhlFdIe71f-g", "filename": "valid.xbrl", "checksum": "14293581bf91d848a811708e7e120a9b87c389595e9752ded054fdc0c9b924e4", "cocNumber": "30267975", "cocOrganizationName": null, "entryPoint": { "guid": "XSCXnm5nShutabIKHbcaPQ", "uri": "https://www.sbrnexus.nl/ft15/frc/20201211/entrypoints/frc-rpt-nt-inrichtingsjaarrekening-2020.xsd", "name": "FT15 nt-inrichtingsjaarrekening-2020" }, "sizeInBytes": 184831, "version": 1 }, "attachments": [ { "guid": "--K3tyNmQ2mqEWZTWMMhiQ", "filename": "attachment.xbrl", "mimeType": "application/xml", "checksum": "14293581bf91d848a811708e7e120a9b87c389595e9752ded054fdc0c9b924e4", "version": 0, "sizeInBytes": 184831 } ], "filingReference": "Test aanlevering", "receiver": { "guid": "AwvHWCDjQ3WmD7KCqRiZjA", "name": "Test Bank", "identityNumber": "00000000123456780000" }, "messageTypeGuid": "fSXzCi52QrSWiwJv4DH7wg", "createdBy": { "guid": "UZtTj1cATj6paTFfh0y1OQ", "organization": { "guid": "hX2SxdOaQpuFgbfPe9CLtg", "name": "Financiële Rapportages Coöperatief B.A.", "cocNumber": "34375187", "receiverGuid": null }, "firstName": "Test", "familyName": "Gebruiker", "email": "test.gebruiker@example.com", "termsAndConditionsAccepted": true, "receiveUpdates": false, "version": 0 }, "sentAt": "2021-02-24T09:24:29.107428Z", "externalReference": "BTA-210224-0000003", "bivFiledAt": "2021-02-24T10:24:28.986+01:00", "statusCode": "100", "statusType": "PENDING", "errorCode": null, "errorDescription": null, "version": 0 } |
Het veld externalReference bevat het aanleverkenmerk van de BIV en statusType geeft aan of de aanlevering succesvol is verwerkt. De velden errorCode en errorDescription worden gevuld als de BIV de aanlevering niet succesvol kan verwerken.
De aanlevering zal initieel de status PENDING terugkrijgen. Met onderstaande call kun je de actuele status ophalen. Het antwoord zal overeenkomen met het vorige antwoord.
| curl -i -H "x-api-key: $token" https://acc-aanleverenapi.sbrnexus.nl/api/filings/mMeaU7cJR5C0LM8E80ZVKA |
Hieronder vind je een voorbeeld Postman-collectie (.json) met daarin de API-calls die ondersteund worden door Aanleveren Portaal: