Hoe sluit ik mijn software aan op Aanleveren Portaal?

Introductie

Softwarepartners kunnen op verschillende manieren aansluiten op de infrastructuur van SBR Nexus via het Aanleveren Portaal (voorheen Mijn Data, Mijn Business).

Deze handleiding beschrijft de stappen die nodig zijn om een aansluiting te realiseren. We onderscheiden hierbij twee hoofdprocessen:

1. XBRL-creatie: het genereren van een rapportage in het juiste XBRL-formaat.
2. XBRL-verzending: het versturen van de rapportage naar de juiste ontvangende partij via het Aanleveren Portaal.

Daarnaast beschrijven we de beschikbare authenticatiemethoden, de testmogelijkheden en de verwerking van aanleveringen.

1. Authenticatie en toegang

Voor het gebruik van Aanleveren Portaal zijn verschillende authenticatiemethoden beschikbaar. Welke methode nodig is, hangt af van de manier waarop je het portaal gebruikt.

We onderscheiden handmatige toegang via de gebruikersinterface en geautomatiseerde communicatie via de API.

1.1 Handmatige toegang via eHerkenning

Voor het inloggen op de productieomgeving van Aanleveren Portaal is eHerkenning vereist. Het eHerkenningsmiddel wordt op organisatieniveau uitgegeven door een erkende leverancier.

Meer informatie vind je in het overzicht van erkende eHerkenningsleveranciers.

Via de gebruikersinterface kun je onder andere handmatig XBRL-rapportages uploaden en verzenden.

Voor de acceptatieomgeving gelden afwijkende inloggegevens. Zie hoofdstuk 7 voor meer informatie.

1.2 API-authenticatie via OAuth 2.0 met eHerkenning

Softwarepartners kunnen OAuth 2.0 gebruiken om hun software te koppelen aan Aanleveren Portaal. In combinatie met eHerkenning kan de authenticatie en uitwisseling van API-tokens worden geautomatiseerd.

Deze methode is geschikt voor softwareoplossingen die namens een organisatie rapportages willen aanleveren zonder dat een gebruiker iedere verzending handmatig hoeft uit te voeren.

Voor het realiseren van deze koppeling moeten de OAuth-configuratie, de benodigde autorisaties en de tokenuitwisseling correct worden ingericht.

De technische stappen en configuratieparameters zijn beschreven in de documentatie voor de OAuth-koppeling.

1.3 API-authenticatie via een PKIoverheid-certificaat

Softwarepartners kunnen ook een PKIoverheid-certificaat gebruiken voor de authenticatie van API-verzoeken.

Bij deze methode wordt een PKIoverheid-certificaat gebruikt om de identiteit van de aanroepende software te verifiëren. 

Voor de implementatie moet de softwarepartner onder andere rekening houden met:

• Het verkrijgen en configureren van een geschikt PKIoverheid-certificaat.
• Het veilig beheren van het certificaat en de bijbehorende privésleutel.
• Het correct aanbieden van het certificaat bij API-verzoeken.
• De technische aansluitvoorwaarden van de betreffende API.

Raadpleeg de actuele API-documentatie voor de vereiste certificaatconfiguratie en de technische implementatie .

Let op: OAuth 2.0 en authenticatie met een PKIoverheid-certificaat zijn verschillende authenticatiemethoden. Controleer vooraf welke methode voor jou vereist is. 

2. Gebruik van Aanleveren Portaal

Aanleveren Portaal ondersteunt zowel handmatige als system-to-system communicatie.

Handmatige verzending

Na het inloggen op het portaal kun je via de gebruikersinterface een rapportage in XBRL-formaat verzenden naar de juiste ontvangende partij.

Selecteer hiervoor de tegel 'SBR Jaarrekening' of de relevante functionaliteit voor het gewenste rapportagetype.

System-to-system verzending

Wil je vanuit je eigen software automatisch rapportages aanleveren? Dan kun je gebruikmaken van de REST API van Aanleveren Portaal.

Afhankelijk van de gekozen authenticatiemethode wordt de toegang tot de API geregeld via OAuth 2.0 met eHerkenning of via een PKIoverheid-certificaat.

Meer informatie vind je in de API-documentatie van Aanleveren Portaal.

3. API-koppeling configureren

Voor het versturen van rapportages via de API moet de softwarepartner de verbinding met Aanleveren Portaal configureren.

Afhankelijk van de gekozen authenticatiemethode moeten de benodigde authenticatiegegevens en configuratieparameters worden ingericht.

Bij gebruik van de bestaande API-tokenfunctionaliteit kan een token via het portaal worden aangemaakt en in de software worden geconfigureerd.

Wil je de tokenuitwisseling automatiseren via OAuth? Volg dan de instructies in de OAuth-koppeldocumentatie.

Voor nieuwe aansluitingen is het belangrijk om vooraf vast te stellen welke authenticatiemethode van toepassing is. Volg hiervoor de actuele technische documentatie en aansluitvoorwaarden.

4. Een XBRL-bestand genereren

De gegevens uit een softwarepakket moeten worden omgezet naar het XBRL-formaat voordat ze via de infrastructuur van SBR Nexus kunnen worden verzonden.

XBRL is een internationale standaard voor het digitaal uitwisselen van financiële en bedrijfsrapportages. Meer informatie over de standaard vind je op de website van XBRL International.

Softwarepartners kunnen XBRL-bestanden op verschillende manieren genereren:

• Door zelf tooling te ontwikkelen.
• Door gebruik te maken van tooling van derden, bijvoorbeeld:
  • Accept: https://www.acc.nl
  • Batavia: https://www.batavia-xbrl.com
  • Semansys: https://semansys.com
  • ParsePort: https://parseport.com/nl/

Beschik je over gegevens in een ander bestandsformaat, zoals XML? Dan kun je mogelijk gebruikmaken van de converter-API om deze gegevens om te zetten naar het vereiste XBRL-formaat.

4.1 Ondersteuning van de Financieren Taxonomie of Vastgoedtaxonomie

Het softwarepakket moet een actuele versie van de relevante taxonomie ondersteunen: de Financieren Taxonomie of de Vastgoedtaxonomie.

De actuele versies van de taxonomieën en de bijbehorende documentatie zijn beschikbaar via de SBR Nexus-taxonomiepagina.

4.2 Voldoen aan het Bancair Kwaliteitsraamwerk

Voor SBR Jaarrekeningen (kredietrapportages) gelden kwaliteitsnormen en standaarden die zijn vastgelegd in het Bancair Kwaliteitsraamwerk voor Kredietrapportages.

Het is de verantwoordelijkheid van de softwarepartner om ervoor te zorgen dat de gegenereerde rapportages aan de toepasselijke kwaliteitsnormen voldoen: SBR Nexus-taxonomiepagina.

4.3 SBR Nexus-testbeleid voor XBRL

SBR Nexus publiceert datastandaarden in de vorm van dataproducten voor zakelijk gebruik in Nederland. Deze producten worden periodiek bijgewerkt.

Het testbeleid beschrijft hoe softwarepartners de dataproducten en de bijbehorende aanleverketen kunnen testen. Het uitvoeren van ketentests helpt om de kwaliteit van rapportages te waarborgen en ongewenste afkeuringen te voorkomen. Onze partnermanager gaat in gesprek met je om een ketentest te plannen. 

5. Een XBRL-rapport naar de ontvangende partij verzenden

Voor de verzending van een XBRL-bestand zijn er twee mogelijkheden.

5.1 Geautomatiseerde verzending via de REST API

Softwarepartners kunnen zelf een koppeling ontwikkelen met de REST API van Aanleveren Portaal.

Hiervoor zijn de volgende hulpmiddelen beschikbaar:

• API-documentatie
• Swagger-documentatie voor de acceptatieomgeving

De software moet de juiste API-aanroepen uitvoeren om de rapportage te registreren, te verzenden en de verwerkingsstatus op te vragen.

5.2 Handmatige verzending via het portaal

Het is ook mogelijk om een XBRL-bestand handmatig te uploaden via het Aanleveren Portaal.

Voor testdoeleinden kun je gebruikmaken van de acceptatieomgeving:

Aanleveren Portaal – Acceptatieomgeving.

6. Verwerking, statussen en foutcodes

Aanleveren Portaal stuurt het XBRL-bestand door naar de Bancaire Infrastructurele Voorziening (BIV) van SBR Nexus.

De BIV verzorgt de validatie van berichten en de routering naar de juiste ontvangende partij. Wanneer een bericht niet aan de gestelde eisen voldoet, kan het worden afgekeurd.

De technische documentatie van de BIV beschrijft de beschikbare status- en foutmeldingen, waaronder de meldingen in Appendix A: Status and fault codes.

Raadpleeg de technische documentatie van BIV 2.0.

Elke foutcode heeft een drieletterige prefix die aangeeft bij welke service de fout is opgetreden. Voorbeelden zijn:

• ALS – Aanleverservice: fouten tijdens de aanlevering van informatie.
• AFS – Afleverservice: fouten tijdens de aflevering van informatie.

Bij nieuwe services en verwerkingsprocessen kunnen aanvullende status- en foutmeldingen worden geïntroduceerd. Raadpleeg daarom altijd de actuele technische documentatie.

6.1 Procesverloop van een API-aanlevering

Een aanlevering via Aanleveren Portaal kan uit de volgende API-aanroepen bestaan:

1. XBRL-conversie: de software roept de converter aan via /api/converter en ontvangt het XBRL-bestand.
2. Ontvangers en berichtsoorten ophalen: de software vraagt beschikbare berichtsoorten op via /api/messagetypes.
3. Rapportage registreren: de software verstuurt het XBRL-bestand naar /api/reports.
4. KvK-nummer bijwerken: indien nodig wordt het KvK-nummer in de rapportage bijgewerkt via /api/reports/{GUID}.
5. Rapportage verzenden: de software verstuurt het bericht naar de ontvangende partij via /api/filings.
6. Verwerkingsstatus opvragen: de software vraagt de status van de aanlevering op via /api/filing.

Niet iedere aanlevering vereist alle bovenstaande stappen. De precieze volgorde en benodigde API-aanroepen zijn afhankelijk van het proces en de actuele API-specificatie.

Bekijk het schema van de API-flow.

7. Testen op de acceptatieomgeving

De acceptatieomgeving van Aanleveren Portaal kan worden gebruikt om de aansluiting, authenticatie en verzending van rapportages te testen voordat de software in productie wordt genomen.

7.1 Toegang tot de acceptatieomgeving

Voor de acceptatieomgeving wordt gebruikgemaakt van een gebruikersnaam en wachtwoord. Dit wijkt af van de productieomgeving, waar voor handmatige toegang eHerkenning wordt gebruikt.

Na het inloggen kun je via de daarvoor beschikbare functionaliteit een API-token aanmaken, indien deze methode voor jouw aansluiting wordt gebruikt.

Voor het aanvragen van een testaccount kun je contact opnemen met SBR Nexus via support@sbrnexus.nl.

Vermeld daarbij de volgende gegevens:

• Voornaam en achternaam.
• E-mailadres.
• Bedrijfsnaam.
• KvK-nummer.

7.2 Testparameters

Gebruik bij het uitvoeren van tests de juiste berichtsoort, entrypoint en ontvangende partij.

De beschikbare berichtsoorten en entrypoints kunnen worden opgevraagd via de berichtsoortenservice-API. Controleer vooraf of de gekozen waarden passen bij het scenario dat je wilt testen.

Let op: testaanleveringen aan 'Test bank' kunnen niet door SBR Nexus worden ingezien of beoordeeld.

7.3 Testscenario's

Het is raadzaam verschillende testscenario's uit te voeren om te controleren of de gegenereerde XBRL-rapportages voldoen aan de relevante kwaliteitsnormen.

Denk hierbij aan:

• Het succesvol aanleveren van een geldig XBRL-bestand.
• Het testen van verschillende rapportagevarianten.
• Het controleren van validatie- en foutmeldingen.
• Het controleren van de verwerkingsstatus van een aanlevering.
• Het testen van relevante uitzonderingssituaties.

Na het uitvoeren van tests die door SBR Nexus moeten worden beoordeeld, kun je de resultaten per e-mail delen met je partnermanager. Vermeld daarbij per scenario het BIV-kenmerk, bijvoorbeeld BTA-220805-0000007.

8. Checklist voor aansluiting

Gebruik onderstaande checklist om te controleren of de belangrijkste stappen zijn uitgevoerd.

• De gewenste authenticatiemethode is vastgesteld.
• De benodigde toegangsgegevens, autorisaties of certificaten zijn geregeld.
• De API-koppeling is geconfigureerd.
• Het softwarepakket genereert geldige XBRL-bestanden.
• De juiste taxonomie wordt ondersteund.
• De API-aanroepen zijn volgens de specificatie geïmplementeerd.
• De aansluiting is getest op de acceptatieomgeving.
• De relevante testscenario's zijn uitgevoerd.
• De verwerkingsstatussen en foutmeldingen worden correct verwerkt.
• De overgang naar de productieomgeving is voorbereid.

Door deze stappen te doorlopen, kan de softwarepartner de aansluiting op Aanleveren Portaal voorbereiden en de kwaliteit van de rapportage en verzending controleren.