Twinfield koppeling met je webshop: verkopen, debiteuren en betalingen in Twinfield

Wat is Twinfield en wie gebruikt het?

Twinfield is het online boekhoudpakket van Wolters Kluwer, gebruikt in Nederland en België. Veel administraties in Twinfield worden gevoerd door een accountantskantoor, dat onder één organisatie de administraties van veel klanten beheert. Een webshop die in Twinfield boekt, heeft dus vaak een boekhouder die de inrichting bepaalt: dagboeken, grootboekrekeningen, btw-codes en factuurtypen.

Twinfield kent geen orders en geen voorraad. Een Twinfield koppeling is een stroom van verkoop en betalingen naar de boekhouding. Heb je voorraad uit een centraal systeem nodig, kijk dan op ERP koppeling met je webshop.

Wat je met Twinfield koppelt

Twinfield maakt een scherp onderscheid tussen een verkoopfactuur, het document voor de klant, en een verkooptransactie, de boeking in de administratie. Een definitieve factuur maakt zelf een transactie aan. Verstuurt de webshop de factuur al, dan zet de koppeling alleen de transactie. Welke velden bij een order horen staat op orders, klanten en verzending.

Hoe Twinfield data vrijgeeft

SOAP-webservices en ProcessXml

Twinfield heeft SOAP-webservices. Het meeste werk loopt via één ervan, ProcessXml, die XML-berichten verwerkt met een root als transaction, salesinvoice, dimension, match of read. Elk verzoek draagt in de SOAP-header een access token en de administratie:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:twin="http://www.twinfield.com/">
  <soapenv:Header><twin:Header>
    <twin:AccessToken>eyJ0eXAi...</twin:AccessToken>
    <twin:CompanyCode>BAKKER01</twin:CompanyCode>
  </twin:Header></soapenv:Header>
  <soapenv:Body><twin:ProcessXmlString><twin:xmlRequest><![CDATA[
    <read><type>dimensions</type><office>BAKKER01</office>
      <dimtype>DEB</dimtype><code>10482</code></read>
  ]]></twin:xmlRequest></twin:ProcessXmlString></soapenv:Body>
</soapenv:Envelope>

Het adres van de webservice verschilt per organisatie: https://api.<cluster>.twinfield.com. Het cluster staat in de claim twf.clusterUrl van het token. Een koppeling met een vast adres werkt voor de ene administratie en niet voor de andere.

OpenID Connect en tokens

Toegang loopt via OpenID Connect en OAuth 2.0 op login.twinfield.com. De koppeling registreert een client in het ontwikkelaarsportaal van Twinfield en gebruikt de authorization code flow. Een access token is 3.600 seconden geldig. Een refresh token krijg je alleen met de scope offline_access, en is 25 jaar geldig. Zonder die scope moet iemand elk uur opnieuw inloggen. De scope twf.organisationUser is verplicht om in te loggen.

Limieten in API-credits

Sinds december 2024 gelden er limieten. Een leesverzoek kost 1 credit, elk ander verzoek 3. Een ProcessXml-bericht met root read of list telt als lezen; een factuur, transactie, dimensie of match kost 3.

De bron is het fair use policy van Twinfield, nagelezen op 3 oktober 2026. Hogere limieten geeft Twinfield niet.

Een order kost bij een bestaande klant 7 credits: de klant lezen (1), de verkooptransactie of factuur (3) en het afletteren van de betaling (3). Na een storing staan er 1.200 orders klaar: 1.200 x 7 = 8.400 credits. Met 500 per minuut is de koppeling in 16,8 minuten bij. Zonder certificering, met 25 per minuut, duurt het 336 minuten. Daarom laten we een koppeling certificeren voordat hij live gaat, en doseert hij zelf op de headers X-RateLimit-Remaining en X-RateLimit-Credited in plaats van te wachten op de eerste 429. Hoe je zo'n som maakt staat in doorvoer berekenen.

Waar het bij Twinfield op vastloopt

Factuur of verkooptransactie

Een factuur via de API komt in de klassieke facturatiemodule. Met status concept blijft hij voorlopig en wijzigbaar; met final is hij definitief, wordt er een transactie geboekt en kan er niets meer aan veranderen. Het factuurnummer is een getal dat Twinfield uitgeeft op basis van het factuurtype. Een verkooptransactie is vrijer: invoicenumber is tekst van maximaal 40 tekens, dus WEB-10482 past, en met destiny="final" staat hij direct in de boekhouding. Twinfield kan waarschuwen bij een dubbel factuurnummer, via het attribuut raisewarning. De koppeling zet die waarschuwing niet uit, zodat een herhaald verzoek na een time-out opvalt in plaats van een tweede boeking te worden.

Dimensies en het factuurtype

Twinfield noemt alles waarop je boekt een dimensie. Niveau 1 is de grootboekrekening, niveau 2 de debiteur of kostenplaats, niveau 3 het project. Op een verkooptransactie heeft de totaalregel de debiteurenrekening in dim1 en de klant in dim2; de detailregels hebben de omzetrekening in dim1. Op een factuur bepaalt het factuurtype welke omzetrekening wordt gebruikt, en een andere rekening op de regel mag alleen als het factuurtype dat toestaat. Een debiteurcode moet passen in het masker van het dimensietype DEB; een klantnummer als WC-311 past daar niet altijd in.

Btw-afronding per regel

Twinfield rekent btw per regel en neemt het afrondingsverschil mee naar de volgende regel. Drie regels van € 3,50 tegen 21% geven per regel € 0,735. Een webshop die per regel afrondt komt op 3 x € 0,74 = € 2,22. Twinfield rondt de eerste af op € 0,74, draagt -0,005 over, maakt van de tweede € 0,73 en van de derde € 0,74: samen € 2,21. De factuur wijkt 1 cent af van de betaling. Twinfield biedt twee oplossingen: autobalancevat="true", dat kleine afrondingsverschillen bij de grootste regel optelt, of de btw per regel meesturen in vatvalue. Twinfield raadt het tweede aan, en dat doet de koppeling ook: de btw uit de webshop gaat ongewijzigd mee. Meer in bedragen en btw mappen.

Leveringen binnen de EU

Bij een btw-code voor intracommunautaire levering zijn performancetype (goederen of diensten) en het land verplicht. Ontbreekt het type, dan weigert Twinfield de regel. Het btw-nummer van een klant staat in field4 van het adres, en daar accepteert Twinfield alleen een geldig btw-nummer. Een zakelijke klant uit België met een fout in zijn btw-nummer komt dus niet als debiteur binnen; de koppeling zet de order op de controlelijst in plaats van hem als particulier te boeken.

Platformen die we aan Twinfield koppelen

De koppeling wordt gebouwd op jouw administratie en de inrichting van je boekhouder: dagboeken, factuurtypen, btw-codes en het masker voor debiteuren. Per platform:

• WooCommerce koppeling met je boekhoudpakket, met Twinfield naast Exact Online, Moneybird en Yuki
• WooCommerce koppeling en Shopify koppeling voor de platformkant

Andere pakketten: Exact Online koppeling, Yuki koppeling en Moneybird koppeling. Het overzicht van alle stromen staat op koppelingen.

Wij bouwen de koppeling voor een vaste prijs en hosten, draaien en bewaken hem daarna voor een vast bedrag per maand. Voor de livegang draait hij als dry run: je ziet per order welke debiteur, dagboekregels en btw-bedragen er in Twinfield zouden ontstaan. Vertel welke webshop je hebt en wie je Twinfield inricht.