Twinfield API uitgelegd: SOAP, OAuth en credits

De Twinfield API is geen REST-API: het is een verzameling SOAP-webservices met XML-berichten, bereikbaar op een clusterspecifieke URL. Inloggen gaat wel modern, via OAuth 2.0 en OpenID Connect bij Wolters Kluwer.

Dat onderscheid kost teams hun eerste sprint. Wie een REST-client pakt en voor elke klant op accounting.twinfield.com mikt, krijgt geen nette 404 maar stille authenticatiefouten (Apideck{target="_blank" rel="noopener noreferrer"}, 2026).

Hieronder de koppelvlakken in de volgorde waarin je ze tegenkomt: inloggen, het offices- en dimensiemodel, data ophalen, de creditlimieten en de fouten die pas onder productievolume zichtbaar worden. Het bredere plaatje staat in onze gids over maatwerk software; voor de vergelijking met het andere grote NL-pakket zie de Exact Online API uitgelegd.

Geen REST-endpoints, wel een rij SOAP-services#

De boekhoudkern van Twinfield is uitsluitend via SOAP bereikbaar; een native REST-API bestaat niet (Chift{target="_blank" rel="noopener noreferrer"}, 2026). Het officiele overzicht noemt alleen WSDL-endpoints, verdeeld over een generieke dienst en een reeks getypeerde diensten.

De generieke dienst is ProcessXml. Die verwerkt XML-berichten voor stamgegevens en transacties: gebruikers, dimensies, facturen en boekingen lopen er allemaal doorheen (Twinfield, Web services overview{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026).

Daarnaast staan er getypeerde services voor werk waar ProcessXml hooguit een beperkte variant voor kent: perioden openen en sluiten, bankafschriften en verwijderde transacties. Afletteren en periodevalidatie kun je ook via ProcessXml doen, met match en period als rootelement.

https://api.<cluster>.twinfield.com/webservices/processxml.asmx?wsdl
https://api.<cluster>.twinfield.com/webservices/finder.asmx?wsdl
https://api.<cluster>.twinfield.com/webservices/matching.asmx?wsdl
https://api.<cluster>.twinfield.com/webservices/periodservice.svc?wsdl
https://api.<cluster>.twinfield.com/webservices/bankstatementservice.svc?wsdl

Praktisch gevolg: je bouwt tegen XML-schema's, niet tegen JSON-modellen. Reken op een XML-serialisatielaag en op handwerk voor foutafhandeling, want SOAP-fouten komen terug als exceptie met een detailblok, niet als statuscode met een body.

Inloggen bij Wolters Kluwer, en daarna pas je eigen cluster#

Twinfield draait OpenID Connect op OAuth 2.0 en ondersteunt twee flows: implicit en authorization code (Twinfield, OpenID Connect authentication{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026). Voor een koppeling met een server-backend is authorization code de juiste keuze.

De tokenlevensduur verschilt per flow, en dat verschil is groter dan je zou verwachten.

Die refresh token van 25 jaar is een valkuil in vermomming. Hij verloopt praktisch nooit, maar wordt wel stil ingetrokken zodra een gebruiker wordt gedeactiveerd of zijn wachtwoord roteert — zonder waarschuwing vooraf (Apideck, 2026).

Na het inloggen komt de stap die de meeste integraties overslaan. Je valideert het access token en leest daaruit de claim twf.clusterUrl; dat is de basis-URL voor al je SOAP-calls.

# 1. Token ophalen (authorization code flow)
curl -s https://login.twinfield.com/auth/authentication/connect/token \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" \
  -d redirect_uri="$REDIRECT_URI"

# 2. Cluster bepalen — deze URL is per klant anders
curl -s "https://login.twinfield.com/auth/authentication/connect/accesstokenvalidation?token=$ACCESS_TOKEN"
# -> { "twf.clusterUrl": "https://api.<cluster>.twinfield.com", ... }

Loopt het toch mis, dan helpen de foutcodes: 354 betekent een ongeldig token, 351 tot 353 een ontbrekende claim, en 360 dat je een access token en een session-ID tegelijk meestuurt (Twinfield, Guidelines{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026).

Een klant is geen klant, maar een DEB-dimensie#

Twinfield kent geen aparte objecten voor debiteuren en crediteuren. Alles wat je in een boeking als tegenpartij of kostendrager gebruikt, is een dimensie met een type-code binnen een office — de Twinfield-term voor een administratie.

Elk dimensietype hoort bij een office en draagt een mask die het formaat van de codes vastlegt, bijvoorbeeld 1#### voor debiteuren (Twinfield, Dimension types{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026). Verzin je zelf een code die buiten dat mask valt, dan weigert Twinfield hem.

Een debiteur uitlezen is daarmee een dimensie-read met vier velden.

<read>
  <type>dimensions</type>
  <office>001</office>
  <dimtype>DEB</dimtype>
  <code>EXAMPLE</code>
</read>

Aanmaken en bijwerken lopen via hetzelfde bericht: wordt de dimensie niet gevonden, dan maakt Twinfield hem aan, anders werkt hij hem bij. De code die je meestuurt moet voldoen aan het mask van het DEB-dimensietype (Twinfield, Customers{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026).

Het office-veld keert in vrijwel elk bericht terug. Een verkoopfactuur draagt naast office ook customer, invoicetype en een periode in YYYY/PP-notatie, plus minstens een regel (Twinfield, Sales invoices{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026).

<salesinvoice>
  <header>
    <office>001</office>
    <invoicetype>FACTUUR</invoicetype>
    <customer>1000</customer>
    <period>2021/4</period>
    <status>concept</status>
  </header>
  <lines>
    <line id="1">
      <article>510</article>
      <quantity>2.00</quantity>
      <unitspriceexcl>83.94</unitspriceexcl>
    </line>
  </lines>
</salesinvoice>

Data eruit halen gaat via browse-codes, niet via een query-taal#

Voor financiele data gebruik je browse data: een set voorgedefinieerde browse-codes die elk een dataset ontsluiten, van grootboekmutaties (030-reeks) tot debiteuren- en crediteurentransacties (100 en 200) en kas en bank (400 en 410) (Twinfield, Browse data{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026).

Je kiest per code welke kolommen je wilt en filtert met operatoren als equal en between.

<column>
  <field>fin.trs.head.yearperiod</field>
  <operator>between</operator>
  <from>2021/01</from>
  <to>2021/12</to>
  <visible>true</visible>
</column>

Twinfield adviseert zelf om transacties per periode op te halen en alleen kolommen op te nemen waarvan je de waarden echt nodig hebt. Dat is geen stijladvies: brede uitvragen over een heel boekjaar lopen op technische fouten stuk.

Credits in plaats van calls: certificering bepaalt je doorvoer#

Twinfield rekent niet in calls maar in credits: een query-verzoek kost 1 credit, elk ander verzoek 3 credits. Query's zijn GET- en OPTIONS-calls, SOAP-acties die met Get, Query, Search of Load beginnen, en ProcessXml-berichten met list, read, columns, accountcode of accountcodes als root (Twinfield, Fair use policy{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026).

De limieten lopen per minuut over vier emmers tegelijk. De sterretjes zijn het hele verhaal: alleen de ClientId-emmers zakken naar 5 procent zolang je integratie niet gecertificeerd is.

Daarnaast geldt een gelijktijdigheidslimiet: 20 parallelle verzoeken per ClientId en 10 per combinatie van ClientId en organisatie. Boven een limiet volgt een 429 Too Many Requests, met Retry-After en X-RateLimit-*-headers in de response.

Op dat laatste punt spreken de integratieblogs elkaar tegen. Apideck volgt de documentatie — "a non-certified Client ID is capped at 50 credits per minute, and 25 credits per minute against a single organisation" — terwijl Chift de korting over alle emmers uitsmeert: "5% of those limits across all buckets: 50 credits/min per IP, per ClientId, and per OrganisationId".

Het verschil is niet academisch. In Chifts lezing is een tweede klant op dezelfde server een probleem; volgens de officiele pagina is dat het niet, en is jouw ClientId de rem in plaats van je infrastructuur.

Reken je scenario door voordat je bouwt. Bij 3 credits per schrijfactie haal je ongecertificeerd ongeveer 16 boekingen per minuut; een eenmalige historie-import van 10.000 boekingen kost 30.000 credits en dus zo'n tien uur doorlooptijd.

Certificering is daarmee geen keurmerk maar een capaciteitsbeslissing. Reken op enkele weken tussen indienen en goedkeuring (Apideck, 2026) en plan die doorlooptijd voor je go-live-datum in.

Wat er misgaat zodra het echt draait#

Vier dingen die je niet uit de schema's haalt, maar wel je incidenten bepalen.

De periode-valkuil verdient toelichting, want hij slaat maandelijks toe. De PeriodService kent OpenPeriod en ClosePeriod plus een IsOpen-vlag per periode, met foutcodes PeriodCanNotBeOpened en PeriodCanNotBeClosed (Twinfield, Periods{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026).

Een koppeling die op de derde van de maand nog naar de vorige periode boekt, valt om op het moment dat iemand die periode sluit.

Los dat op in je koppeling, niet in een procedure: lees de periodestatus voor je boekt en wijk uit naar de eerstvolgende open periode, met een melding.

De breaking-changes-kalender is de zachte variant van wat Nmbrs doet. Twinfield gaf het general-rootelement end-of-life op 01-07-2025 en ProcessXmlCompressed op 31-07-2025, telkens met jaren aankondiging (Twinfield, Breaking changes{target="_blank" rel="noopener noreferrer"}, geraadpleegd september 2026).

Bij Nmbrs stopt de complete SOAP-API in een keer op een datum, wat een heel ander migratieproject is — zie de Nmbrs API-migratie.

Grootboeksuggesties en afwijkingsdetectie op de boekingsstroom#

De koppeling zelf is transport. De winst zit in het model dat je ertussen zet, en Twinfield leent zich daar beter voor dan gemiddeld.

Grootboekcodesuggestie werkt omdat je historie in dezelfde structuur staat als je nieuwe boeking. Een model dat op je eigen boekingsverleden per CRD-dimensie is afgestemd, stelt bij een nieuwe inkoopfactuur een grootboekrekening en kostenplaats voor.

Het veiligheidsventiel zit in Twinfield zelf: je levert de boeking aan met <status>concept</status>, zodat een mens hem bevestigt voordat hij definitief wordt. Suggereren mag automatisch, definitief boeken niet.

Afwijkingsdetectie draait de vraag om. Je vergelijkt een nieuwe boeking met het patroon van dezelfde dimensie over de voorgaande perioden en signaleert een bedrag, btw-code of tegenrekening die eruit springt — precies de historie die de browse-codes voor grootboekmutaties je leveren.

Beide zijn classificatietaken, geen chatbot. Wij bouwen ze als aparte laag naast de koppeling; wat dat kost staat op AI software laten maken, waar een ingebouwde AI-feature start bij €8.500.

Een kanttekening die je vooraf regelt: zodra declaraties, uren of salarisboekingen in de stroom zitten, verwerk je persoonsgegevens en hoort er een verwerkersovereenkomst met je modelleverancier bij.

Wanneer de koppeling van je accountant volstaat#

Draait je Twinfield onder het kantoor van je accountant, dan is er vaak al een koppeling of connector actief. Voor een enkele administratie met standaard facturatie is dat de goedkoopste route, en blijft de API buiten beeld.

Zelf bouwen wordt pas de betere keuze bij een van deze drie signalen.

• Je boekt in meerdere offices en wilt een autorisatie die alle administraties dekt.
• Je volume past niet in 50 credits per minuut, dus je hebt certificering nodig.
• Je wilt iets dat geen connector doet, zoals afletteren via de matching-service of een eigen dimensiestructuur.

Werk je vanuit een kantoor en koppel je voor meerdere klanten tegelijk, dan speelt er meer dan techniek — daarover schrijven we op software voor accountants en adviseurs.

Qua kosten: de standaardstroom van webshop naar boekhouding bouwen wij als boekhoudkoppeling vanaf €2.000 eenmalig plus €150 tot €350 per maand. Een eigen integratie op de API valt onder API-koppelingen: vanaf €5.000 in een richting, €7.500 tot €15.000 bidirectioneel met datatransformatie.

Twijfel je aan welke kant van die streep je zit, leg je scenario kort aan ons voor — je krijgt een eerlijk oordeel over connector versus maatwerk, inclusief kostenindicatie.