Documentatie

Acht tools, synchrone aanroepen, een vaste reeks foutcodes.

Verbinden

De installatiegids per client staat op uw accountpagina, naast uw sleutel. Een aanvraag zonder sleutel krijgt 401 met een WWW-Authenticate-header; een sleutel boven de snelheidslimiet krijgt 429 met Retry-After.

Tools

Hoe lang een aanroep duurt

get_annual_accounts antwoordt in de aanroep zelf: een neerlegging ophalen betekent de Nationale Bank aanroepen, de neerlegging downloaden en XBRL verwerken, en dat gebeurt allemaal terwijl uw client wacht.

Een nieuwe neerlegging duurt meestal enkele seconden, af en toe tot een minuut wanneer de Nationale Bank traag is. Wacht op het antwoord in plaats van opnieuw te proberen — opnieuw proberen is een tweede aanrekenbare aanroep voor hetzelfde werk.

Een neerlegging die al eens is opgehaald, komt onmiddellijk terug met status: "completed" en cached: true. Resultaten worden per neerlegging bewaard en verlopen nooit, want een neergelegde jaarrekening verandert niet meer — een correctie is een nieuwe neerlegging met haar eigen referentie, en die pikt de server op.

Foutcodes

Een mislukte aanroep van get_annual_accounts draagt error.code, en die strings staan vast — een client mag erop vertakken.

Fouten die geen mislukte aanroep zijn

Verkeerde invoer en een opgebruikt quotum komen terug als tool-fout (MCP isError: true) met een verklarende boodschap, en niet als een failed-resultaat — er is geen vaste code om op te vertakken, alleen iets wat het model kan verbeteren of melden.

Limieten

Tijdens de alfa geldt er geen maandquotum: aanroepen worden geteld, nooit geweigerd. De rate limit per sleutel hierboven blijft, want die beschermt de gegevensbron en niet de omzet. Welke quota bij de start gelden, ligt nog niet vast.

De result-JSON

Elk afgerond resultaat van get_annual_accounts heeft dezelfde vorm:

Talen

language aanvaardt nl, fr, de en en, en staat standaard op nl. De labels komen uit de taxonomielabellinkbases van de Nationale Bank zelf, niet uit een vertaalmachine, zodat ze overeenkomen met de woorden op de officiële formulieren.

Ontbreekt een label in de gevraagde taal, dan valt het antwoord terug in deze orde: gevraagde taal → de taal waarin de neerlegging is ingediend → nl → fr → en. De cijfers veranderen nooit met de taal, en meta.response_language zegt wat u werkelijk gekregen hebt.

De website zelf verschijnt in het Nederlands, Frans en Engels. Hij volgt de taalvoorkeur van uw browser; de taalkiezer in de navigatie overschrijft die voor de pagina waar u op staat, en van die keuze wordt niets bewaard.

Gegevensbronnen en voorbehouden

meta.data_source zegt hoe een resultaat tot stand kwam, en dat is het veld dat u leest voor u een getal vertrouwt:

Bekende voorbehouden

• Alleen neerleggingen die de Nationale Bank aanvaard heeft, worden geleverd. Een neerlegging die later gecorrigeerd is, leidt naar de correctie en niet naar het origineel.
• Het zoeken op naam gebruikt het opendatabestand met benamingen van de KBO/BCE, dat maandelijks vernieuwd wordt. Een bedrijf dat de laatste weken is opgericht, is misschien eerder op nummer dan op naam te vinden.
• Verschillende bedrijven kunnen dezelfde naam hebben. search_company geeft kandidaten met een matchscore en verwacht dat de aanroeper kiest in plaats van dat wij gokken.
• Oudere neerleggingen gebruiken vroegere taxonomiegeneraties. Waar een generatie nog niet gekoppeld is, zegt het antwoord dat (pdf_fallback_required) in plaats van gedeeltelijke cijfers te geven.
• Deze dienst is niet verbonden met de Nationale Bank van België en voegt geen interpretatie toe: wat neergelegd is, is wat u krijgt, met inbegrip van de fouten die de neerlegger maakte.