-
MDMB maakt gebruik van de Oauth2 voor autorisatie. Softwareleveranciers kunnen via deze koppeling aan MDMB 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 Mijn Data, Mijn Business (MDMB).
- De Swagger definitie van de MDMB API is hier te vinden.
- Het gebruik van de API vereist een API token. Deze kunnen we aanmaken op de instellingen pagina van MDMB. Deze token geven we als header mee bij alle requests.
Een rapportage versturen naar de BIV
Het versturen van een rapportage naar de BIV, via MDMB, bestaat uit drie stappen/calls:
- Het XBRL-bestand uploaden
- De rapportage updaten met het bijbehorende KVK-nummer
- Bijlagen uploaden
- 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.mijndatamijnbusiness.nl/api/reports |
| Response |
|
{ "guid": "AMX5LQjUSyGhlFdIe71f-g", "filename": "valid.xbrl", "checksum": "14293581bf91d848a811708e7e120a9b87c389595e9752ded054fdc0c9b924e4", "cocNumber": null, "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.
Rapportage bijwerken met KVK-nummer
Een KVK-nummer is verplicht als een rapportage aangeleverd wordt. Als het KVK-nummer nog niet bekend is kunnen we de rapportage bijwerken met een PUT call. Geef hierbij de guid van de report mee in de url.
| Request |
|
curl -i - X PUT - H "x-api-key: $token" - H "Content-Type: application/json" - d '{ "cocNumber": "30267975", "version": 0 }' https://acc.mijndatamijnbusiness.nl/api/reports/AMX5LQjUSyGhlFdIe71f-g |
In de body van het request geven we het KVK-nummer mee als cocNumber en het version veld vullen we met dezelfde waarde als die wij in de vorige stap terug hebben gekregen. Optioneel kan ook de organisatienaam worden aangepast via cocOrganizationName.
Met behulp van het version veld voorkomen we dat een entiteit door verschillende personen/processen gelijktijdig wordt aangepast.
| Response |
|
{ "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 } |
In het resultaat zien we dat het KVK-nummer is bijgewerkt. Ook is het versienummer opgehoogd.
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.mijndatamijnbusiness.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
MDMB 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.mijndatamijnbusiness.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" }, "attachments": [ { "guid": "--K3tyNmQ2mqEWZTWMMhiQ" } ], "filingReference": "Test aanlevering", "messageTypeGuid": "fSXzCi52QrSWiwJv4DH7wg", "receiver": { "guid": "AwvHWCDjQ3WmD7KCqRiZjA" } }' https://acc.mijndatamijnbusiness.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.mijndatamijnbusiness.nl/api/filings/mMeaU7cJR5C0LM8E80ZVKA |
Hieronder vind je een voorbeeld Postman-collectie (.json) met daarin de API-calls die ondersteund worden door Mijn Data, Mijn Business (MDMB):