Twinfield API: inloggen, browse codes en data ophalen

Wat kun je met de Twinfield API?

Met de Twinfield API lees je grootboekrekeningen, relaties, kostenplaatsen, projecten, boekingen en openstaande posten, en kun je facturen en boekingen aanmaken. Ontwikkelaars gebruiken hem om facturatie, webshops en kassasystemen te koppelen, en om boekhouddata naar een datawarehouse of rapportagetool te halen.

DigiData gebruikt deze API dagelijks om Twinfield-administraties te synchroniseren. Dit artikel beschrijft hoe dat in de praktijk werkt. De officiële bron is de documentatie van de Twinfield-webservices.

SOAP en XML, geen moderne REST-API

Wie gewend is aan JSON en REST, moet bij Twinfield even omschakelen. Het grootste deel van de API bestaat uit SOAP-webservices die XML-berichten ontvangen en terugsturen. De belangrijkste:

Stap 1: inloggen met OAuth 2.0

Twinfield gebruikt OAuth 2.0 via de inlogdienst van Wolters Kluwer. Je registreert een app bij Twinfield, stuurt de gebruiker naar het inlogscherm en wisselt de code in bij https://login.twinfield.com/auth/authentication/connect/token voor een access token en refresh token.

Daarna komt een stap die veel ontwikkelaars missen: Twinfield draait op meerdere clusters. Met het access token roep je het validatie-endpoint aan, en het antwoord bevat het cluster-adres van de gebruiker. Alle webservices roep je daarna aan op dat adres, bijvoorbeeld {cluster}/webservices/processxml.asmx. Bij het verversen van het token kan het cluster-adres veranderen; haal het dus opnieuw op.

Stap 2: kies de administratie

In Twinfield heet een administratie een office. Een gebruiker heeft vaak toegang tot meerdere offices, en een accountantskantoor tot honderden. Bij elke opdracht geef je de office-code mee. Een lijst van offices haal je op via de Finder.

Stap 3: boekingen ophalen met browse codes

Boekingen en openstaande posten haal je niet per record op, maar met een browse: een vooraf gedefinieerd overzicht met een code, kolommen en filters. Voor transactieregels is dat browse code 030_3. Je geeft aan welke kolommen je wilt en filtert bijvoorbeeld op periode:

<columns code="030_3">
  <column><field>fin.trs.head.yearperiod</field><operator>between</operator><from>2026/01</from><to>2026/12</to></column>
  <column><field>fin.trs.head.code</field><visible>true</visible></column>
  <column><field>fin.trs.head.number</field><visible>true</visible></column>
  <column><field>fin.trs.line.dim1</field><visible>true</visible></column>
  <column><field>fin.trs.line.valuesigned</field><visible>true</visible></column>
</columns>

Dit bericht stuur je via ProcessXml. Het antwoord is een XML-tabel met de gevraagde kolommen. Voor incrementeel bijwerken filter je op de wijzigingsdatum van de boeking (fin.trs.head.modified), zodat je niet elke keer het hele jaar opnieuw ophaalt.

Stamgegevens, zoals grootboekrekeningen (dimensietype BAS en PNL), relaties (DEB en CRD) en kostenplaatsen (KPL), lees je met een <read>-opdracht per code of zoek je eerst op met de Finder.

Waar je op moet letten

• Grote antwoorden. Een browse over een heel jaar in een grote administratie kan veel regels opleveren. Splits op periode.
• Per office. Alles gaat per administratie. Bij veel offices loopt het aantal calls snel op.
• Datatypes in XML. Bedragen en datums komen als tekst terug; let op het decimaalteken en het datumformaat bij het omzetten.
• Rechten van de gebruiker. De API ziet alleen wat de ingelogde gebruiker in Twinfield mag zien.

Wanneer je de API niet zelf hoeft te bouwen

Voor een eenmalige export is de API prima te gebruiken. Een koppeling die elke dag betrouwbaar alle boekingen, relaties en grootboekstructuren bijhoudt, kost meer werk dan het lijkt. Wil je de data alleen voor rapportages of AI gebruiken, dan zijn er kortere routes:

• Power BI of Excel: met de Twinfield connector van DigiData staat je data als OData-feed klaar. Zie Twinfield aan Power BI koppelen via OData en Twinfield in Power Query en Excel.
• ChatGPT of Claude: zie Twinfield met Claude via read-only MCP.
• Alle opties naast elkaar: Twinfield koppelingen vergelijken.

Werk je ook met Exact Online, lees dan hoe de Exact Online API werkt.