Wat een ontwikkelaar ziet die deze API integreert
De marketingdocumentatie van een documentherkenningstool belooft altijd een perfecte extractie. Een ontwikkelaar die hem daadwerkelijk in productiesoftware moet integreren, stelt andere vragen: wat is de exacte vorm van het antwoord, hoe weet je of een veld betrouwbaar is, wat gebeurt er bij een onleesbaar document, en hoe lang moet je wachten op een antwoord onder echte belasting. Deze pagina beantwoordt die vragen, niet die van een verkoopfolder.
Het probleem dat deze engine oplost
Een echt financieel document — factuur, bankafschrift, bon — is geen gestructureerd formulier. De opmaak verschilt per afzender, de scankwaliteit verschilt per upload, en eenzelfde veld (het totaalbedrag bijvoorbeeld) kan op compleet verschillende plekken staan afhankelijk van het document. Een herkenningsengine moet generaliseren buiten een vaste set voorbeelden, iets wat een eenvoudige positiesjabloon niet kan zodra er een nieuwe opmaak opduikt.
Hoe de herkenning werkt
Het ingestuurde document wordt eerst geanalyseerd om de algemene structuur te herkennen — kop, body, regeltabel indien aanwezig — waarna elk veld wordt gelokaliseerd en geëxtraheerd met zijn eigen zekerheidsniveau. Deze aanpak per veld, in plaats van één score voor het hele document, is wat jouw integratie in staat stelt fijnmazige beslissingen te nemen: automatisch een bedrag overnemen dat met een score van 0,98 is geëxtraheerd, terwijl een factuurnummer met een score van 0,61 wordt gemarkeerd voor menselijke bevestiging.
De vorm van het antwoord
Een succesvolle call geeft een JSON-object terug met de kopvelden van het document (afzender, datum, documentnummer, totaalbedrag, valuta), een array line_items wanneer het document die bevat, en een object confidence dat elk veld individueel weerspiegelt. De volledige technische documentatie van de endpoints staat in de Engelstalige documentatie; het supportteam antwoordt in het Nederlands voor elke integratievraag.
De betrouwbaarheidsscore, veld voor veld
| Scorebereik | Aanbevolen gedrag |
|---|---|
| 0,90 – 1,00 | Automatisch overnemen zonder menselijke tussenkomst |
| 0,70 – 0,89 | Overnemen, maar het veld gemarkeerd tonen voor een snelle controle |
| Onder 0,70 | Doorsturen naar expliciete menselijke controle vóór verwerking |
Deze drempels zijn richtinggevend, niet opgelegd — elke integratie past haar eigen risicotolerantie aan naargelang hoe kritiek het betreffende veld is: een totaalbedrag verdient doorgaans een strengere drempel dan een ondergeschikte regelomschrijving.
Ondersteunde documentformaten
| Invoerformaat | Opmerking |
|---|---|
| Native pdf | Rechtstreeks verwerkt, ook meerpagina-documenten |
| Gescande pdf | Verwerkt als afbeelding, geen selecteerbare tekst nodig |
| JPEG / PNG | Foto genomen met de telefoon, ook licht scheefstaand |
| HEIC | Native iPhone-formaat, automatisch geconverteerd op de server |
Latency en asynchrone verwerking
Een kort document komt doorgaans binnen enkele seconden terug bij een synchrone call. Voor een batchimport — bijvoorbeeld enkele honderden historische documenten die in één keer moeten worden verwerkt tijdens een migratie — voorkomt een asynchrone modus dat er een open verbinding blijft bestaan: elk document wordt in een wachtrij verwerkt en er wordt een webhook-melding verstuurd zodra elk resultaat beschikbaar is, in plaats van de client in een blokkerende call te laten wachten.
Voor en na de integratie
Voor
Een gebruiker uploadt een document en typt daarna elk veld handmatig over in jouw software — een trage stap, gevoelig voor typefouten.
Na
Het document wordt geüpload, de velden verschijnen vooraf ingevuld met hun betrouwbaarheidsscore, en de gebruiker corrigeert alleen wat echt als onzeker gemarkeerd staat.
Concrete gebruikssituaties
Boekingen voorbereiden
Inkoopfactuur geüpload, velden geëxtraheerd, boeking voorgesteld vóór controle door de gebruiker.
Bankmatching
Meerpagina-bankafschrift omgezet in gestructureerde mutatieregels voor automatische matching.
Mobiele onkostennota
Foto van een bon genomen met de telefoon, gestructureerde onkostenregel binnen seconden beschikbaar.
Massale import bij een migratie
Enkele honderden historische documenten in batch verwerkt met webhook-melding per resultaat.
Meldingen en webhooks
Een document dat asynchroon wordt ingestuurd, activeert een melding naar een webhook-URL die jij zelf configureert, met het volledige extractieresultaat in de body van het verzoek. Dat voorkomt dat jouw integratie de API voortdurend moet bevragen om te weten of een document klaar is — jouw systeem ontvangt de melding zodra het resultaat bestaat.
Foutafhandeling en onleesbare documenten
Een echt onleesbaar document — te wazig, afgesneden, corrupt — geeft een expliciete foutstatus terug in plaats van een verzonnen waarde die plausibel lijkt. Geen enkel mislukt document wordt gefactureerd. Aan de integratiekant wordt dit geval doorgaans opgevangen door de gebruiker te vragen de foto opnieuw te maken of het document handmatig in te voeren, in plaats van stilzwijgend een onjuiste waarde in het systeem toe te laten.
Limieten en volume
Een standaard rate limit beschermt de infrastructuur die alle klanten delen; die wordt op verzoek verhoogd voor een productie-integratie met een hoog volume. Er bestaat geen harde limiet op het totale maandvolume — de prijs volgt simpelweg het aantal succesvol verwerkte pagina's, uitgewerkt op de pagina prijzen.
Authenticatie en beveiliging
Elke call wordt geauthenticeerd met een API-sleutel die aan jouw account is gekoppeld, onafhankelijk intrekbaar en opnieuw te genereren vanuit het dashboard. Documenten reizen versleuteld via TLS en worden verwerkt op servers binnen de Europese Unie — het volledige detail staat op de pagina beveiliging.
Vergeleken met een generieke OCR-engine
Een generieke OCR-engine geeft doorgaans ruwe tekst terug, regel voor regel, zonder te begrijpen dat een groep cijfers een totaalbedrag is en geen telefoonnummer. Deze engine gaat verder: hij herkent de structuur van het document — welke velden bij de kop horen, welke een regelniveau vormen — en geeft een reeds gestructureerd antwoord terug, klaar om naar jouw datamodel te mappen, zonder extra naverwerkingsstap aan jouw kant.
Testen en valideren vóór productie
De meest betrouwbare manier om een integratie te valideren voordat die aan echte gebruikers wordt blootgesteld, is een batch bekende historische documenten — waarvan je de verwachte waarde al kent — opnieuw te laten verwerken en veld voor veld het API-antwoord te vergelijken met die referentiewaarden. Deze vergelijking onthult direct de mapping-afwijkingen aan de integratiekant, voordat ze een echte gebruiker raken.
Een testomgeving die dezelfde credentials gebruikt als een productieaccount, maar met een gescheiden verbruiksregistratie, maakt deze validatie mogelijk zonder de testcijfers te vermengen met het werkelijk gefactureerde volume. De meeste teams bewaren deze testset als regressiesuite, opnieuw uitgevoerd bij elke belangrijke doorontwikkeling van hun eigen integratiecode.
Idempotentie en deduplicatie
Een document dat per ongeluk twee keer wordt ingestuurd — een dubbele klik, een verzoek dat na een netwerktimeout opnieuw wordt geprobeerd — mag geen twee uiteenlopende resultaten opleveren en het document niet twee keer factureren. Een verzoek-identifier die jij zelf genereert en bij elke call meestuurt, laat de API een duplicaat herkennen en het al berekende resultaat teruggeven in plaats van een volledige verwerking opnieuw te starten.
Deze bescherming is vooral belangrijk voor een integratie die een call automatisch opnieuw probeert bij een tijdelijke netwerkfout — een aanbevolen gedrag voor robuustheid, maar dat zonder idempotentie het risico loopt hetzelfde document meerdere keren te verwerken.
Aangepaste velden en bijzondere gevallen
Het standaard responsschema dekt de velden die het vaakst door boekhoudsoftware worden gebruikt — maar een specifieke sector kan een extra veld nodig hebben, bijvoorbeeld een intern dossiernummer dat op bepaalde documenten van een klant voorkomt. Dit type behoefte wordt doorgaans opgelost met een aangepaste mapping aan de integratiekant, in plaats van een wijziging van het standaardschema, wat dat laatste stabiel houdt voor de rest van de klanten.
Een document dat bij geen van de standaard ondersteunde types past — een zeldzaam maar reëel geval voor een leverancier met een zeer breed bereik — geeft de generieke velden terug die wel konden worden herkend, met een betrouwbaarheidsscore die die structurele onzekerheid weerspiegelt, in plaats van het document simpelweg te weigeren.
Prestaties op grote schaal
Een piek in uploads — het einde van de maand voor onkostensoftware, de jaarafsluiting voor boekhoudsoftware — vermenigvuldigt het dagvolume soms meerdere keren binnen een korte periode. De infrastructuur is gedimensioneerd om dat soort variatie op te vangen zonder merkbare vertraging, in tegenstelling tot een interne infrastructuur die op een gemiddeld volume is afgestemd en tijdens die pieken onder druk komt te staan.
| Situatie | Aanbevolen modus |
|---|---|
| Individuele upload door een gebruiker | Synchrone call |
| Import van enkele tientallen documenten | Synchrone calls achter elkaar |
| Import van enkele honderden tot duizenden documenten | Asynchrone modus met webhook |
| Onvoorspelbare seizoenspiek | Vereist geen aanpassing van jouw kant |
Versiebeheer en stabiliteit in de tijd
Het responsschema is expliciet geversioneerd, wat betekent dat een doorontwikkeling van de engine — de toevoeging van een nieuw veld, een precisieverbetering op een documenttype — nooit stilzwijgend de structuur verandert die jouw integratie al verwacht. Een structurele wijziging, veel zeldzamer, wordt vooraf aangekondigd in plaats van zonder waarschuwing te worden uitgerold over een integratie die al in productie draait.
De extractiekwaliteit in de tijd bewaken
Een integratie die de eerste maand goed werkt, garandeert niet dat ze in de twaalfde maand net zo goed blijft werken — een nieuwe factuuropmaak bij een leverancier, een nieuwe bank die een klant gebruikt, of gewoon een verschuiving in de mix van verwerkte documenten kan stilletjes het percentage velden met lage betrouwbaarheid doen oplopen. Dat percentage in de tijd volgen, ook al is het beknopt, laat je die verschuiving opmerken voordat die zichtbaar wordt voor eindgebruikers.
Een eenvoudig dashboard, wekelijks bijgewerkt — aantal verwerkte documenten, percentage automatisch geaccepteerde velden, percentage doorgestuurd voor menselijke controle — is voor de meeste integraties voldoende om een afwijking te ontdekken voordat een gebruiker die zelf meldt via support.
| Gevolgde indicator | Aanbevolen frequentie |
|---|---|
| Volume verwerkte documenten | Dagelijks of wekelijks |
| Percentage automatisch geaccepteerde velden | Wekelijks |
| Percentage doorgestuurd voor menselijke controle | Wekelijks |
| Totale mislukkingsgraad van de extractie | Wekelijks, met alarmering bij een abnormaal hoge waarde |
Ontwikkel-, test- en productieomgevingen
Een aparte sleutel per omgeving — ontwikkeling, test, productie — voorkomt dat een testcall de productiestatistieken beïnvloedt of in de echte facturatie terechtkomt. De meeste teams maken een dedicated sleutel per omgeving, onafhankelijk intrekbaar — nuttig als een sleutel per ongeluk in een coderepository of een gedeeld applicatielog terechtkomt, een incident dat vaker voorkomt dan gedacht.
Duidelijk vastleggen, binnen je eigen project, welke sleutel voor welke omgeving dient, voorkomt de klassieke fout van een ontwikkelaar die per ongeluk tegen de productiesleutel test — op zich een klein incident, maar het kan zorgvuldig opgebouwde monitoringcijfers vertekenen.
Grensgevallen uit de praktijk
Een samengesteld document met meerdere onderdelen
Een factuur en de bijbehorende pakbon samen in één bestand gescand, komen terug met de velden van elk onderdeel apart herkend waar mogelijk.
Een gedeeltelijk handgeschreven aantekening op een gedrukt document
Een handmatig gecorrigeerd bedrag op een gedrukte factuur kan de betrouwbaarheid op dat specifieke veld verlagen, wat de onzekerheid correct signaleert in plaats van willekeurig een waarde te kiezen.
Een document dat 90 graden gedraaid is
De oriëntatie wordt in de overgrote meerderheid van de gevallen automatisch gedetecteerd en gecorrigeerd vóór de extractie.
Een watermerk of stempel over de tekst
De onderliggende tekst blijft doorgaans leesbaar; een lagere betrouwbaarheidsscore signaleert de gevallen waarin de overlap te groot is.
Geen van deze grensgevallen wordt zomaar afgewezen: elk komt terug met de velden die de engine wel kon herkennen, samen met een betrouwbaarheidsscore die het echte onzekerheidsniveau eerlijk weergeeft, in plaats van een binaire keuze tussen perfect succes en volledige mislukking af te dwingen. Precies deze nuance, meer dan de afhandeling van één geïsoleerd grensgeval, onderscheidt een engine die voor productie is gebouwd van een prototype dat alleen met schone documenten is getest.
Clientbibliotheken en codevoorbeelden
Een ontwikkelaar heeft geen dedicated clientbibliotheek nodig om te beginnen: de API wordt aangeroepen met elke HTTP-client die een multipart-bestand kan uploaden en een JSON-antwoord kan lezen, wat in de praktijk elke backendtaal dekt die vandaag in boekhoudsoftware wordt gebruikt — Node.js, Python, PHP, Java, .NET, Ruby. De technische documentatie bevat voorbeelden van de minimale call in de meest gebruikte talen bij teams die de API vandaag integreren, genoeg om binnen enkele minuten een eerste antwoord te krijgen, niet dagen.
Voor een team dat liever niet zelf retry-, backoff- en webhook-handtekeningverificatielogica herschrijft, volstaat meestal een kleine interne wrapper — een paar tientallen regels rond de al gebruikte HTTP-client — zonder een extra externe dependency toe te voegen alleen voor deze integratie. Teams die al een generieke integratielaag hebben voor andere externe diensten — een betaalprovider, een e-mailprovider — passen deze API meestal zonder extra frictie in diezelfde laag in.
Migreren vanaf een andere OCR-leverancier
Software die al een andere documentherkenningsleverancier gebruikt, migreert zelden van de ene op de andere dag: het veiligste patroon laat beide engines gedurende enkele weken parallel draaien op dezelfde inkomende documentenstroom, waarbij veld voor veld de resultaten worden vergeleken zonder dat de eindgebruiker enig gedragsverschil merkt. Die vergelijking onthult snel of de nieuwe engine beter generaliseert op de opmaken die de vorige leverancier slechter dekte — bijna altijd de echte reden achter de migratie, meer dan een simpele kostenbesparing per pagina.
Het mappen van het uitvoerschema van je bestaande integratie naar het schema van deze API is meestal het langste werk van de migratie, niet de API-call zelf — een reden te meer om te testen met een representatieve batch echte documenten voordat je een definitieve overschakeldatum met de vertrekkende leverancier vastlegt. Eenmaal die mapping gevalideerd, is het uitschakelen van de vorige leverancier doorgaans een enkele configuratiewijziging, zonder extra deployment aan de kant van de eindklant.
Een respons in detail doorgenomen
Een goed voorbeelddocument doornemen helpt meer dan een abstracte beschrijving van het schema. Stuur een factuur van één pagina in, en het antwoord bevat naast de verwachte kopvelden ook een reeks metadata die makkelijk over het hoofd wordt gezien bij een eerste lezing: een uniek verwerkings-ID per document, een tijdstempel van wanneer de verwerking is gestart en afgerond, en een indicatie van het gedetecteerde documenttype vóór de veldextractie zelf begint. Die laatste indicatie is nuttig om vroeg in je pipeline te routeren — een factuur volgt een ander validatiepad dan een bankafschrift, ook al komen beide via dezelfde endpoint binnen.
Voor regelniveaus is het de moeite waard om te weten dat elke regel zijn eigen betrouwbaarheidsscore draagt, los van de score van de kopvelden. Een factuur kan dus een zeer betrouwbaar totaalbedrag hebben terwijl één specifieke regel — bijvoorbeeld een lange productomschrijving die half wordt afgesneden door een paginabreuk — een lagere score krijgt. Een integratie die alleen naar de documentbrede score kijkt, mist dat soort lokale onzekerheid; een integratie die per regel controleert, vangt het wél op voordat het een boekingsfout wordt.
Latency optimaliseren in de praktijk
De meeste vertraging die ontwikkelaars ervaren, zit niet in de extractie zelf maar in hoe het document wordt aangeleverd. Een pdf die clientside al is gecomprimeerd tot een redelijke bestandsgrootte, komt sneller aan en wordt sneller verwerkt dan een ongecomprimeerde scan van tientallen megabytes — een detail dat in een demo-omgeving met kleine testbestanden zelden opvalt, maar in productie met scans van klanten al snel merkbaar wordt.
Een tweede praktische tip: verzoeken bundelen waar mogelijk. Wanneer een gebruiker vijf bonnetjes tegelijk uploadt, is het sneller om vijf parallelle calls te doen dan vijf calls na elkaar te wachten — de infrastructuur is ontworpen om gelijktijdige verzoeken van eenzelfde account te verwerken zonder dat de een op de ander hoeft te wachten. Voor een importtaak met honderden documenten blijft de asynchrone modus met webhook echter de voorkeur, simpelweg omdat honderden parallelle synchrone verzoeken tegen de rate limit aanlopen die de gedeelde infrastructuur beschermt.