Όταν τα έγγραφα ξεκινούν σε άλλο σύστημα

Η ερώτηση που τίθεται στη δεύτερη συνάντηση: «συνεργάζεστε με το σύστημά μας;». Μέχρι τώρα η ειλικρινής απάντηση ήταν όχι. Τώρα η απάντηση είναι η εξής: έχετε μια πύλη, ένα CRM ή ένα λογιστικό σύστημα όπου η συναλλαγή υπάρχει ήδη, και το DocuTract μπορεί να λειτουργεί ως μέρος του.

Η έκτη λειτουργία του κύματος είναι η έξοδος προς τα έξω. Ένα token με το οποίο μας καλεί το σύστημά σας, μια διεύθυνση όπου γράφουμε από μόνοι μας, και μια ανοιχτή περιγραφή όλων όσων βρίσκονται ενδιάμεσα.

Ένα token που δεν μπορούμε να σας δείξουμε δύο φορές

Ένα token δημιουργείται στην οθόνη Ενσωματώσεις: ένα όνομα που θα αναγνωρίσετε αργότερα, ώστε να ξέρετε ποιο σύστημα το χρησιμοποιεί, και μια λίστα με όσα επιτρέπεται να κάνει. Έπειτα εμφανίζεται μία φορά.

Αυτό δεν είναι αφηρημάδα, είναι ο τρόπος που πρέπει να λειτουργεί ένα προϊόν που κρατά το κλειδί κάποιου άλλου. Κρατάμε μόνο ένα hash: το να δείξουμε το token δεύτερη φορά είναι κάτι που δεν μπορούμε να κάνουμε ούτε εμείς, που σημαίνει ότι δεν μπορεί να κλαπεί από εμάς. Η λίστα κρατά τους πρώτους χαρακτήρες, τα δικαιώματα και την ημερομηνία τελευταίας χρήσης, ώστε να φαίνεται ποιο token είναι ενεργό και αν το χρησιμοποιεί ακόμη κάποιος.

Η Ανάκληση το απενεργοποιεί αμέσως. Η εγγραφή του μένει: ότι υπήρξε και πότε σταμάτησε να λειτουργεί είναι μέρος του ιστορικού του χώρου εργασίας, όχι σκουπίδι.

Τα δικαιώματα ελέγχονται σε κάθε διεύθυνση χωριστά. Ένα token που επιτρέπεται μόνο να διαβάζει πρότυπα παίρνει ένα απλό «λείπει το scope documents:write» όταν προσπαθεί να δημιουργήσει ένα έγγραφο, όχι ένα κενό «δεν βρέθηκε». Υποθέτουμε ότι την ενσωμάτωση τη στήνει ένας ζωντανός άνθρωπος, και μια απάντηση που δεν εξηγεί τίποτα του κοστίζει ένα βράδυ.

Τι μπορεί να κάνει το API

Όσα μπορείτε στην οθόνη, μόνο χωρίς την οθόνη: να ανοίξετε μια υπόθεση και να ανεβάσετε σαρώσεις σε αυτήν, να δημιουργήσετε ένα έγγραφο από πρότυπο με τις τιμές ήδη συμπληρωμένες, να ρωτήσετε σε ποιο στάδιο έχει φτάσει, να πάρετε κάθε τιμή μαζί με τη σάρωση από την οποία διαβάστηκε, και να λάβετε έναν σύνδεσμο μικρής διάρκειας προς το ολοκληρωμένο αρχείο.

Αυτό το τελευταίο είναι που κάνει αυτή την ενσωμάτωση διαφορετική από τις άλλες. Το σύστημά σας λαμβάνει όχι απλώς ένα συμπληρωμένο αρχείο αλλά κάθε τιμή με την προέλευσή της: τη σάρωση, το πεδίο, πόσο βέβαιη ήταν η ανάγνωση. Η ίδια πηγή που βλέπει ένας άνθρωπος στην οθόνη ελέγχου είναι διαθέσιμη και στον κώδικα.

Η περιγραφή κάθε διεύθυνσης και κάθε πεδίου παράγεται από τον ίδιο τον κώδικα και δημοσιεύεται ανοιχτά, χωρίς token: /api/v1/openapi.json. Τεκμηρίωση που πρέπει πρώτα να τη ζητήσεις είναι τεκμηρίωση που δεν διαβάζει κανείς.

Webhooks και ένα ειλικρινές αρχείο καταγραφής

Δεν χρειάζεται να μας ρωτάτε αν ένα έγγραφο είναι έτοιμο. Δώστε μας μια διεύθυνση και επιλέξτε τα συμβάντα: έγγραφο έτοιμο, έγγραφο απέτυχε, υπόθεση έτοιμη, βρέθηκε απόκλιση, ένας πελάτης έστειλε αρχείο.

Κάθε αίτημα είναι υπογεγραμμένο, και το μυστικό που επαληθεύει την υπογραφή εμφανίζεται μία φορά, όπως το token. Αν ο διακομιστής σας απάντησε κάτι άλλο ή δεν απάντησε καθόλου, ξαναπροσπαθούμε: μετά από ένα λεπτό, μετά από πέντε, μετά από μισή ώρα, μετά από δύο ώρες και μετά από δέκα. Έπειτα σταματάμε, γιατί μια ενσωμάτωση που δεν συντηρεί κανείς δεν πρέπει να ξοδεύει τους πόρους κάποιου για πάντα.

Και μετά το κομμάτι για το οποίο γράφτηκαν όλα αυτά. Όταν η άλλη πλευρά λέει «το σύστημά μας δεν έλαβε τίποτα», η απάντηση είναι στην οθόνη: το συμβάν, η ώρα, πόσες προσπάθειες, ποιος κωδικός απόκρισης επέστρεψε και η αρχή του σώματος της απόκρισης. Φαίνεται ότι απάντησε 500 πέντε φορές. Αυτό δεν είναι βοήθημα αποσφαλμάτωσης για εμάς, είναι απάντηση για τον μηχανικό σας.

Δίπλα του, δύο κουμπιά για την ώρα που μια ενσωμάτωση ακόμη στήνεται. Η Δοκιμαστική αποστολή στέλνει ένα δοκιμαστικό αίτημα αμέσως, χωρίς να περιμένει πραγματικό συμβάν, ώστε ένας παραλήπτης να μπορεί να ελεγχθεί πριν περάσει από αυτόν οποιαδήποτε δουλειά. Η Επανάληψη, δίπλα σε μια αποτυχημένη παράδοση, κάνει αμέσως άλλη μία προσπάθεια και δεν μηδενίζει το ιστορικό: οι τέσσερις αποτυχημένες προσπάθειες μένουν καταγεγραμμένες, γιατί αυτή είναι η αλήθεια για το πόσο κόστισε αυτή η ειδοποίηση.

Τα όρια που θέσαμε στον εαυτό μας

Ένα webhook πηγαίνει μόνο σε https και μόνο σε δημόσια διεύθυνση: μια διεύθυνση μέσα σε ιδιωτικό δίκτυο απορρίπτεται τόσο όταν αποθηκεύεται όσο και πριν από κάθε προσπάθεια, γιατί ένα όνομα κεντρικού υπολογιστή που χθες έδειχνε προς τα έξω μπορεί σήμερα να δείχνει προς τα μέσα. Το όριο ρυθμού μετρά ανά token και όχι ανά διεύθυνση, ώστε ένας γείτονας στον ίδιο διακομιστή να μην ξοδεύει το δικό σας όριο, και η υπέρβασή του φέρνει ένα ειλικρινές «ελάτε ξανά σε τόσα δευτερόλεπτα».

Το API και τα webhooks είναι μέρος του προγράμματος Team. Αν ένας χώρος εργασίας μεταβεί σε άλλο πρόγραμμα, ό,τι έχει ήδη δημιουργηθεί παραμένει ορατό και μπορεί να ανακληθεί: κλειδιά που δεν μπορεί να φτάσει κανείς είναι χειρότερα από μια λειτουργία επί πληρωμή.

Τι δεν περιλαμβάνεται σε αυτή την έκδοση

Ο σχεδιασμός αυτής της φάσης περιέγραφε δύο ακόμη μέρη: εξαγωγή ενός ολοκληρωμένου εγγράφου στο Google Drive, στο OneDrive ή στο Dropbox, και αποστολή του για υπογραφή μέσω DocuSign ή Dropbox Sign. Και τα δύο χρειάζονται διαπιστευτήρια από αυτούς τους παρόχους, που δεν έχουμε αυτή τη στιγμή, και το να γράψεις μια ενσωμάτωση που δεν μπορεί να δοκιμαστεί πουθενά σημαίνει να παρουσιάζεις άγραφο κώδικα ως ολοκληρωμένο. Παραμένουν στο σχέδιο ως ξεχωριστές εκδόσεις.

Τι ακολουθεί

Η έβδομη και τελευταία λειτουργία του κύματος είναι η μαζική δημιουργία: μια λίστα πενήντα γραμμών ή ένα αρχείο σαρώσεων αντί για πενήντα πανομοιότυπες συμπληρώσεις με το χέρι, με ορατή πρόοδο και τη δυνατότητα να επαναλάβετε μόνο όσες δεν πέτυχαν.

Η πλήρης λίστα βρίσκεται στο τι φτιάχνουμε στη συνέχεια, και οι οδηγίες βήμα προς βήμα για τις ενσωματώσεις στο κέντρο βοήθειας.