Als documenten in een ander systeem beginnen

De vraag die in het tweede gesprek opduikt: «integreren jullie met ons systeem?». Tot nu toe was het eerlijke antwoord nee. Nu is het antwoord dit: je hebt een portaal, een CRM of een boekhoudsysteem waarin de transactie al bestaat, en DocuTract kan als onderdeel daarvan werken.

De zesde functie van deze golf is de weg naar buiten. Een token waarmee je systeem ons aanroept, een adres waarnaar we uit onszelf schrijven, en een openbare beschrijving van alles daartussen.

Een token dat we je geen twee keer kunnen tonen

Een token wordt aangemaakt op het scherm Integraties: een naam die je later herkent, zodat je weet welk systeem het gebruikt, en een lijst van wat het mag doen. Daarna wordt het één keer getoond.

Dat is geen vergeetachtigheid, zo hoort een product te werken dat de sleutel van iemand anders bewaart. We bewaren alleen een hash: het token een tweede keer tonen kunnen zelfs wij niet, en dat betekent dat het niet bij ons kan worden gestolen. De lijst bewaart de eerste tekens, de rechten en de datum van het laatste gebruik, zodat zichtbaar is welk token actief is en of iemand het nog gebruikt.

Intrekken schakelt het direct uit. De registratie ervan blijft: dat het bestond en wanneer het ophield te werken, hoort bij de geschiedenis van de werkruimte en is geen rommel.

Rechten worden per adres apart gecontroleerd. Een token dat alleen sjablonen mag lezen, krijgt een duidelijk «the documents:write scope is missing» als het een document probeert aan te maken, niet een leeg «not found». We gaan ervan uit dat er een echt mens de integratie aansluit, en een antwoord dat niets uitlegt, kost die persoon een avond.

Wat de API kan

Net zoveel als je op het scherm kunt, alleen zonder scherm: een dossier openen en er scans in uploaden, een document aanmaken vanuit een sjabloon met de waarden al ingevuld, vragen in welke fase het zit, alle waarden ophalen samen met de scan waaruit elke waarde is gelezen, en een kortlevende link naar het kant-en-klare bestand krijgen.

Dat laatste maakt deze integratie anders dan de andere. Je systeem ontvangt niet alleen een ingevuld bestand, maar elke waarde met haar herkomst: de scan, het veld, hoe zeker de lezing was. Dezelfde bron die een mens op het controlescherm ziet, is beschikbaar voor code.

De beschrijving van elk adres en veld wordt uit de code zelf gegenereerd en openbaar gepubliceerd, zonder token: /api/v1/openapi.json. Documentatie waar je eerst om moet vragen, is documentatie die niemand leest.

Webhooks en een eerlijk logboek

Je hoeft ons niet te vragen of een document klaar is. Geef ons een adres en vink de gebeurtenissen aan: document klaar, document mislukt, dossier klaar, een afwijking gevonden, een klant heeft een bestand gestuurd.

Elk verzoek is ondertekend, en het geheim waarmee je de handtekening verifieert, wordt net als het token één keer getoond. Antwoordde je server iets anders, of helemaal niet, dan proberen we het opnieuw: na een minuut, na vijf, na een halfuur, na twee uur en na tien. Daarna stoppen we, want een integratie die niemand onderhoudt, hoort niet eindeloos de middelen van iemand anders te verbruiken.

En dan het deel waarvoor dit allemaal is geschreven. Als de andere kant zegt «ons systeem heeft niets ontvangen», staat het antwoord op het scherm: de gebeurtenis, het tijdstip, hoeveel pogingen, welke responscode terugkwam en het begin van de responsinhoud. Je ziet dat het vijf keer met 500 antwoordde. Dat is geen hulpmiddel om voor ons te debuggen, het is een antwoord voor je engineer.

Daarnaast twee knoppen voor het uur waarin een integratie nog wordt ingericht. Test versturen stuurt nu meteen een proefverzoek, zonder op een echte gebeurtenis te wachten, zodat een ontvanger kan worden gecontroleerd voordat er echt werk doorheen gaat. Opnieuw proberen, naast een mislukte aflevering, doet direct nog een poging en wist de geschiedenis niet: de vier mislukte pogingen blijven vastgelegd, want dat is de waarheid over wat deze melding heeft gekost.

De grenzen die we onszelf opleggen

Een webhook gaat alleen naar https en alleen naar een openbaar adres: een adres binnen een privénetwerk wordt geweigerd, zowel bij het opslaan als vóór elke poging, want een hostnaam die gisteren naar buiten wees, kan vandaag naar binnen wijzen. De snelheidslimiet telt per token in plaats van per adres, zodat een buurman op dezelfde server jouw quotum niet opmaakt, en wie eroverheen gaat, krijgt een eerlijk «kom over zoveel seconden terug».

De API en webhooks zijn onderdeel van het Team-abonnement. Stapt een werkruimte over naar een ander abonnement, dan blijft wat al is aangemaakt zichtbaar en kan het worden ingetrokken: sleutels waar niemand bij kan, zijn erger dan een betaalde functie.

Wat niet in deze release zit

De opdracht voor deze fase beschreef nog twee onderdelen: een kant-en-klaar document exporteren naar Google Drive, OneDrive of Dropbox, en het ter ondertekening versturen via DocuSign of Dropbox Sign. Voor beide zijn inloggegevens van die aanbieders nodig, die we op dit moment niet hebben, en een integratie schrijven die nergens kan worden getest, betekent ongeschreven code als af presenteren. Ze blijven in de planning als eigen releases.

Wat er hierna komt

De zevende en laatste functie van deze golf is batchgeneratie: een lijst van vijftig rijen of een archief met scans in plaats van vijftig identieke invullingen met de hand, met zichtbare voortgang en de mogelijkheid om alleen de mislukte te herhalen.

De volledige lijst staat in wat we hierna bouwen, en de stap-voor-stapinstructies voor integraties staan in het helpcentrum.