Teruglezen is makkelijk, wegschrijven is werk

Wie via de API een verkooporder in Exact Online aanmaakt, vindt in de documentatie van het SalesOrders-eindpunt twee velden die als verplicht zijn gemarkeerd: OrderedBy, de klant die bestelt, en SalesOrderLines, de orderregels. Dat leest als een middag werk, en die twee velden zijn ook niet het probleem. Het probleem is alles wat er niet bij staat: of de klant al bestaat, of de order al eens is aangemaakt, en wie er iets van merkt als het om drie uur 's nachts misgaat.

Lezen uit een pakket is vergevingsgezind: een verkeerde filter geeft hooguit een lege of verkeerde lijst, en niets verandert er in de administratie. Schrijven is dat niet. Elke aanroep die slaagt, staat in de administratie, en wat erin staat, wordt gebruikt: ingepland, gefactureerd, geboekt. Hieronder staan de zeven dingen die geregeld moeten zijn voordat een koppeling mag schrijven.

1. Verplichte velden

De documentatie noemt per eindpunt wat verplicht is. Bij Exact Online is dat weinig: een verkoopfactuur vraagt een dagboek, een klant en regels; een inkoopboeking een dagboek, een leverancier en regels; een relatie alleen een naam. Een orderregel vraagt een artikel en het ordernummer; het aantal is niet eens verplicht.

Dat is de verplichting van de API. De verplichting van de administratie is groter. Een relatie met alleen een naam bestaat, maar of er een factuur naartoe kan, hangt af van wat uw administratie daarvoor eist: een adres, een betalingstermijn, een btw-code. Een orderregel zonder aantal wordt aangemaakt; welk aantal er dan staat, bepaalt het pakket, niet u. Bij AFAS geldt hetzelfde: de UpdateConnector accepteert wat de business rules toelaten, en welke velden uw inrichting daarbovenop eist, staat niet in de algemene documentatie maar in de metainfo van de connector en in uw eigen Profit-omgeving. Welke connectoren dat precies zijn en welke velden erin gaan, staat in de AFAS-connectoren die u in de praktijk nodig heeft; dit stuk gaat over wat er vóór elke schrijfaanroep geregeld moet zijn, ongeacht het pakket.

De lijst die u nodig heeft, is dus niet de kolom "mandatory" uit de documentatie, maar de lijst van velden zonder welke het record in uw administratie onbruikbaar is. Die lijst maakt u zelf, met de persoon die de records nu met de hand invoert en met de accountant. Wat de invoerder nooit leeg laat, is het begin van die lijst; wat de accountant later nodig heeft, maakt hem af.

2. Validatie vóór de aanroep

Een pakket controleert wat het binnenkrijgt, maar pas op het moment van schrijven, en het zegt niet altijd duidelijk wat er mis was. AFAS meldt inhoudelijke afkeuringen als een HTTP 500 die "in de AFAS business rules" ontstaat, met de foutmelding in Base64 in een responseheader en de details in het logboek van de omgeving (REST API voor ontwikkelaars, responscodes). Dat volstaat voor een ontwikkelaar die ernaast zit, niet voor een koppeling die 's nachts draait.

Daarom controleert een koppeling zelf, voordat ze iets verstuurt: bestaat de relatie, bestaat het artikel, is het bedrag een getal, valt de datum in een open periode, is de btw-code er een die het pakket kent. Wat niet door die controle komt, wordt niet verstuurd maar apart gezet, met de reden erbij. Het pakket is de laatste controle, niet de eerste.

Er is nog een reden. Exact Online begrenst het aantal aanroepen per administratie: zestig per minuut, en voor apps die sinds 1 juli 2021 zijn geregistreerd vijfduizend per dag, waarna de API met een HTTP 429 antwoordt. Die cijfers komen uit de samenvatting die Brixxs van de limietenpagina van Exact geeft, geraadpleegd op 29 augustus 2026. Wat vooraf is tegengehouden, hoeft niet uit dat budget.

3. Dubbele records

Lezen kan tien keer; schrijven maar één keer. Een koppeling die een order aanmaakt en de bevestiging niet ontvangt, omdat de verbinding wegviel, weet niet of de order bestaat. Opnieuw proberen geeft misschien een dubbele order; niet proberen misschien geen. Bij AFAS antwoordt een geslaagde UpdateConnector met een 201 en het ID van de aangemaakte regel (responscodes), maar alleen als dat antwoord ook aankomt.

De oplossing is dat elk record dat de koppeling schrijft, een kenmerk meekrijgt waarmee het terug te vinden is: het ordernummer van de klant in het referentieveld, het factuurnummer van de leverancier, een eigen kenmerk in een vrij veld. Voordat de koppeling schrijft, zoekt ze op dat kenmerk. Staat het er al, dan schrijft ze niet. Dat is alleen sluitend als er niet twee runs tegelijk lopen; daarom verwerkt een koppeling records één voor één, of zet ze het kenmerk in een veld dat het pakket uniek houdt.

Hetzelfde geldt voor relaties. Een order van "Bakkerij De Vries" en een van "De Vries Bakkerij B.V." zijn van dezelfde klant; een koppeling die op naam zoekt, maakt er twee van. Zoeken op KVK-nummer, btw-nummer of het klantnummer dat de klant zelf in zijn order zet, is betrouwbaarder dan zoeken op naam, al kunnen ook die nummers ontbreken of verkeerd zijn overgetypt. Wat niet eenduidig gevonden wordt, gaat niet automatisch het pakket in; het wacht op iemand die het herkent.

4. De volgorde van aanmaken

Een order kan niet bestaan zonder klant, een orderregel niet zonder order en niet zonder artikel, een factuur niet zonder dagboek. Bij Exact Online dragen alle regels van een order hetzelfde OrderID (SalesOrderLines), en bij POST moeten de regels in dezelfde aanroep mee (SalesOrders). Bij AFAS kan één UpdateConnector een hoofdrecord met subrecords in één aanroep aanmaken en wijzigen (UpdateConnector via REST).

De volgorde ligt daarmee vast: eerst kijken of de klant bestaat, zo nodig de klant aanmaken, het artikel controleren, en pas dan de order met zijn regels. De order wacht op de klant, want hij heeft diens ID nodig. Een koppeling die dat niet afwacht, werkt in de test, waar de klant al bestaat, en kan falen bij de eerste nieuwe klant.

5. Foutafhandeling die iemand ziet

Een fout bij het lezen is meestal onschuldig: de lijst is leeg of de run stopt, en er is niets veranderd. Een fout bij het schrijven is een order die niet is aangemaakt terwijl de klant een bevestiging kreeg, of een factuur die wel is aangemaakt maar niet verstuurd. Zo'n fout mag niet verdwijnen in een logbestand dat niemand opent; per soort fout hoort er een bestemming te zijn. Een tijdelijke fout, zoals een 503 bij onderhoud of een 429 bij te veel aanroepen, wacht en probeert opnieuw, met een oplopende pauze. Een inhoudelijke fout, zoals een onbekend artikel of een gesloten boekperiode, probeert niet blind opnieuw, want dezelfde aanroep geeft meestal dezelfde afkeuring; die gaat naar de persoon die het kan beoordelen, met het oorspronkelijke bericht erbij. En een fout waarbij niet vaststaat wat er is gebeurd, de verbroken verbinding uit punt 3, wordt eerst opgezocht voordat er iets wordt herhaald. Hoe die meldingen eruitzien en waar ze terug te vinden zijn, hoort bij de documentatie die u bij een koppeling meekrijgt.

6. Terugdraaien

Een order met zes regels, waarvan de vierde wordt afgekeurd. Verwerkt het pakket de aanroep in één keer of weigert het hem in één keer, dan staat er niets. Bij een koppeling die regel voor regel schrijft, staat er een order met drie regels, en die is voor de planning en de facturatie gewoon een order. De koppeling moet dan weten dat ze half is, en de order verwijderen of blokkeren voordat iemand ermee aan de slag gaat.

Dat terugdraaien is niet altijd mogelijk. Bij AFAS kan de kostprijs van een orderregel alleen nog gewijzigd worden "zolang de regel nog actief is. Dus niet bij deellevering, geleverd of afgehandeld" (UpdateConnector FbSales). Een verstuurde factuur wordt in de regel niet verwijderd maar gecorrigeerd, met een creditnota. Daarom schrijft een koppeling records waar het kan eerst in een toestand waarin ze nog geen gevolg hebben: een order als concept, een inkoopfactuur als boekingsvoorstel, een factuur klaar voor controle in plaats van verstuurd. Niet elk pakket en niet elk eindpunt kent zo'n tussenstand; waar die er is, zet een mens de stap naar definitief, of de koppeling zet hem pas als alles ervoor is geslaagd.

7. Rechten

Een schrijvende koppeling krijgt in de test vaak een beheerdersaccount, omdat dat het snelst werkt. Als niemand daarop terugkomt, is dat ook het account waarmee ze twee jaar later nog draait, met dezelfde sleutel, en met meer rechten dan het proces nodig heeft.

Bij AFAS bepaalt de app connector welke connectoren aangeroepen mogen worden en de filterautorisatie welke records die connector ziet en wijzigt; KnSubject bijvoorbeeld wijzigt alleen dossieritems waar de gebruiker rechten op heeft (UpdateConnector KnSubject). Een schrijvend account hoort precies de connectoren te mogen aanroepen die het proces nodig heeft, op de records die het proces raakt, en verder niets. Een eigen account maakt in het logboek ook zichtbaar welke wijziging van de koppeling kwam. Hoe wij accounts, sleutels en eigendom regelen, staat op techniek en eigendom.

Wat u zelf kunt nagaan

Open de documentatie van het eindpunt waar de koppeling naar schrijft en tel de verplichte velden. Zet daarnaast de velden die de collega die dit werk nu doet, nooit leeg laat. Het verschil is de omvang van het werk aan de schrijfkant. Vraag daarna aan wie de koppeling bouwt hoe hij een dubbele order voorkomt, wat er gebeurt als regel vier van zes wordt afgekeurd, en onder welk account hij schrijft. Wie daar antwoord op heeft, heeft over de schrijfkant nagedacht.

Deze lijst is geen reden om te bouwen. Bestaat er voor uw combinatie een abonnementskoppeling die deze zeven punten al voor haar rekening neemt, dan is die in de regel goedkoper dan maatwerk en wordt ze door meer mensen onderhouden. Wat er voor uw pakket overblijft, en wanneer we afraden om iets te bouwen, staat bij de Exact Online-koppeling en de AFAS-koppeling.