Wenn Dokumente in einem anderen System entstehen

Die Frage, die beim zweiten Termin kommt: „Haben Sie eine Integration mit unserem System?“ Bisher war die ehrliche Antwort Nein. Jetzt lautet die Antwort so: Sie haben ein Portal, ein CRM oder ein Buchhaltungssystem, in dem das Geschäft bereits existiert, und DocuTract kann als Teil davon arbeiten.

Die sechste Funktion der Welle ist der Weg nach draußen. Ein Token, mit dem Ihr System uns aufruft, eine Adresse, an die wir von uns aus schreiben, und eine offene Beschreibung von allem dazwischen.

Ein Token, den wir Ihnen nicht zweimal zeigen können

Ein Token wird auf dem Bildschirm Integrationen erstellt: ein Name, den Sie später wiedererkennen, damit Sie wissen, welches System ihn nutzt, und eine Liste dessen, was er darf. Dann wird er einmal angezeigt.

Das ist keine Vergesslichkeit, sondern so muss ein Produkt arbeiten, das den Schlüssel eines anderen verwahrt. Wir speichern nur einen Hash: Den Token ein zweites Mal anzuzeigen, können nicht einmal wir, und das heißt, er kann uns nicht gestohlen werden. Die Liste behält die ersten Zeichen, die Berechtigungen und das Datum der letzten Verwendung, sodass sichtbar ist, welcher Token aktiv ist und ob ihn noch jemand nutzt.

Widerrufen schaltet ihn sofort ab. Der Eintrag bleibt: Dass es ihn gab und wann er aufgehört hat zu funktionieren, gehört zur Geschichte des Arbeitsbereichs und ist kein Müll.

Berechtigungen werden für jede Adresse einzeln geprüft. Ein Token, der nur Vorlagen lesen darf, erhält beim Versuch, ein Dokument zu erstellen, ein klares „der Scope documents:write fehlt“ statt eines leeren „nicht gefunden“. Wir gehen davon aus, dass ein echter Mensch die Integration einrichtet, und eine Antwort, die nichts erklärt, kostet ihn einen Abend.

Was die API kann

So viel wie auf dem Bildschirm, nur ohne Bildschirm: einen Vorgang eröffnen und Scans hineinladen, ein Dokument aus einer Vorlage mit bereits ausgefüllten Werten erstellen, abfragen, in welchem Stadium es sich befindet, alle Werte zusammen mit dem Scan abrufen, aus dem jeder gelesen wurde, und einen kurzlebigen Link zur fertigen Datei erhalten.

Dieser letzte Teil unterscheidet diese Integration von anderen. Ihr System erhält nicht nur eine ausgefüllte Datei, sondern jeden Wert mit seiner Herkunft: den Scan, das Feld, wie sicher das Lesen war. Dieselbe Quelle, die ein Mensch auf dem Prüfbildschirm sieht, steht dem Code zur Verfügung.

Die Beschreibung aller Adressen und Felder wird direkt aus dem Code erzeugt und offen veröffentlicht, ohne Token: /api/v1/openapi.json. Eine Dokumentation, nach der man erst fragen muss, liest niemand.

Webhooks und ein ehrliches Protokoll

Sie müssen uns nicht fragen, ob ein Dokument fertig ist. Geben Sie uns eine Adresse und haken Sie die Ereignisse an: Dokument fertig, Dokument fehlgeschlagen, Vorgang fertig, eine Abweichung gefunden, ein Kunde hat eine Datei gesendet.

Jede Anfrage ist signiert, und das Secret zur Prüfung der Signatur wird wie der Token einmal angezeigt. Hat Ihr Server anders oder gar nicht geantwortet, versuchen wir es erneut: nach einer Minute, nach fünf, nach einer halben Stunde, nach zwei Stunden und nach zehn. Dann hören wir auf, denn eine Integration, die niemand pflegt, sollte nicht ewig fremde Ressourcen verbrauchen.

Und dann der Teil, für den all das geschrieben wurde. Wenn die andere Seite sagt: „Unser System hat nichts erhalten“, steht die Antwort auf dem Bildschirm: das Ereignis, die Uhrzeit, wie viele Versuche, welcher Antwortcode zurückkam und der Anfang des Antworttexts. Es ist sichtbar, dass fünfmal mit 500 geantwortet wurde. Das ist keine Debugging-Hilfe für uns, sondern eine Antwort für Ihren Entwickler.

Daneben zwei Schaltflächen für die Stunde, in der eine Integration noch eingerichtet wird. Test senden schickt sofort eine Probeanfrage, ohne auf ein echtes Ereignis zu warten, damit ein Empfänger geprüft werden kann, bevor echte Arbeit darüber läuft. Erneut versuchen neben einer fehlgeschlagenen Zustellung unternimmt sofort einen weiteren Versuch und setzt den Verlauf nicht zurück: Die vier fehlgeschlagenen Versuche bleiben im Protokoll, denn das ist die Wahrheit darüber, was diese Benachrichtigung gekostet hat.

Die Grenzen, die wir uns selbst setzen

Ein Webhook geht nur an https und nur an eine öffentliche Adresse: Eine Adresse in einem privaten Netzwerk wird sowohl beim Speichern als auch vor jedem Versuch abgelehnt, denn ein Hostname, der gestern nach außen zeigte, kann heute nach innen zeigen. Die Ratenbegrenzung zählt pro Token statt pro Adresse, damit ein Nachbar auf demselben Server nicht Ihr Kontingent verbraucht, und wer sie überschreitet, erhält ein ehrliches „Versuchen Sie es in so vielen Sekunden wieder“.

API und Webhooks gehören zum Tarif Team. Wechselt ein Arbeitsbereich in einen anderen Tarif, bleibt das bereits Erstellte sichtbar und kann widerrufen werden: Schlüssel, an die niemand mehr herankommt, sind schlimmer als eine kostenpflichtige Funktion.

Was nicht in diesem Release ist

Die Vorgabe für diese Phase beschrieb zwei weitere Teile: den Export eines fertigen Dokuments nach Google Drive, OneDrive oder Dropbox und das Versenden zur Unterschrift über DocuSign oder Dropbox Sign. Beide brauchen Zugangsdaten dieser Anbieter, die wir derzeit nicht haben, und eine Integration zu schreiben, die sich nirgends testen lässt, hieße, ungeschriebenen Code als fertig auszugeben. Sie bleiben als eigene Releases im Plan.

Wie es weitergeht

Die siebte und letzte Funktion der Welle ist die Stapelerstellung: eine Liste mit fünfzig Zeilen oder ein Archiv mit Scans statt fünfzig gleicher Ausfüllvorgänge von Hand, mit sichtbarem Fortschritt und der Möglichkeit, nur die zu wiederholen, die nicht geklappt haben.

Die vollständige Liste steht in Woran wir als Nächstes arbeiten, und die Schritt-für-Schritt-Anleitung zu Integrationen im Hilfecenter.