Când documentele pornesc din alt sistem

Întrebarea care apare la a doua întâlnire: „vă integrați cu sistemul nostru?”. Până acum, răspunsul onest era nu. Acum răspunsul este acesta: aveți un portal, un CRM sau un sistem de contabilitate în care tranzacția există deja, iar DocuTract poate funcționa ca parte a acestuia.

A șasea funcție a valului este calea de ieșire. Un token cu care sistemul dvs. ne apelează, o adresă la care scriem din proprie inițiativă și o descriere deschisă a tot ce se află între ele.

Un token pe care nu vi-l putem arăta de două ori

Un token se creează pe ecranul Integrări: un nume pe care îl veți recunoaște mai târziu, ca să știți ce sistem îl folosește, și o listă cu ce are voie să facă. Apoi este afișat o singură dată.

Nu este o scăpare, ci modul în care trebuie să funcționeze un produs care deține cheia altcuiva. Păstrăm doar un hash: nici măcar noi nu putem afișa tokenul a doua oară, ceea ce înseamnă că nu poate fi furat de la noi. Lista păstrează primele caractere, permisiunile și data ultimei utilizări, astfel încât se vede ce token este activ și dacă îl mai folosește cineva.

Revocați îl dezactivează instantaneu. Înregistrarea lui rămâne: faptul că a existat și momentul în care a încetat să funcționeze fac parte din istoricul spațiului de lucru, nu sunt gunoi.

Permisiunile sunt verificate separat pentru fiecare adresă. Un token care are voie doar să citească șabloane primește un simplu „lipsește permisiunea documents:write” când încearcă să creeze un document, nu un „nu a fost găsit” gol. Pornim de la premisa că integrarea este configurată de un om real, iar un răspuns care nu explică nimic îl costă o seară.

Ce poate face API-ul

Cât puteți face pe ecran, doar că fără ecran: să deschideți un dosar și să încărcați scanări în el, să creați un document dintr-un șablon cu valorile deja completate, să întrebați în ce stadiu a ajuns, să preluați fiecare valoare împreună cu scanarea din care a fost citită și să obțineți un link cu durată scurtă către fișierul finalizat.

Această ultimă parte face ca integrarea să nu semene cu celelalte. Sistemul dvs. primește nu doar un fișier completat, ci fiecare valoare cu proveniența ei: scanarea, câmpul, cât de sigură a fost citirea. Aceeași sursă pe care o vede un om pe ecranul de verificare este disponibilă și pentru cod.

Descrierea fiecărei adrese și a fiecărui câmp este generată din codul însuși și publicată deschis, fără token: /api/v1/openapi.json. O documentație pe care trebuie s-o ceri mai întâi este o documentație pe care nu o citește nimeni.

Webhookuri și un jurnal onest

Nu trebuie să ne întrebați dacă un document este gata. Dați-ne o adresă și bifați evenimentele: document gata, document eșuat, dosar gata, neconcordanță găsită, un client a trimis un fișier.

Fiecare cerere este semnată, iar secretul care verifică semnătura este afișat o singură dată, ca și tokenul. Dacă serverul dvs. a răspuns altceva sau nu a răspuns deloc, încercăm din nou: după un minut, după cinci, după o jumătate de oră, după două ore și după zece. Apoi ne oprim, pentru că o integrare pe care nu o mai întreține nimeni nu ar trebui să consume la nesfârșit resursele cuiva.

Și apoi partea pentru care a fost scris totul. Când cealaltă parte spune „sistemul nostru nu a primit nimic”, răspunsul este pe ecran: evenimentul, ora, câte încercări, ce cod de răspuns a venit înapoi și începutul corpului răspunsului. Se vede că a răspuns 500 de cinci ori. Nu este un instrument de depanare pentru noi, ci un răspuns pentru inginerul dvs.

Alături, două butoane pentru ora în care o integrare încă se configurează. Trimiteți un test trimite chiar acum o cerere de probă, fără să aștepte un eveniment real, astfel încât un receptor să poată fi verificat înainte să treacă vreo lucrare prin el. Reîncercați, lângă o livrare eșuată, face imediat încă o încercare și nu resetează istoricul: cele patru încercări eșuate rămân înregistrate, pentru că acesta este adevărul despre cât a costat această notificare.

Limitele pe care ni le impunem

Un webhook merge doar la https și doar la o adresă publică: o adresă dintr-o rețea privată este refuzată atât la salvare, cât și înaintea fiecărei încercări, pentru că un nume de host care ieri indica spre exterior poate indica azi spre interior. Limita de frecvență se calculează per token, nu per adresă, astfel încât un vecin de pe același server să nu vă consume cota, iar depășirea ei aduce un onest „reveniți peste atâtea secunde”.

API-ul și webhookurile fac parte din planul Team. Dacă un spațiu de lucru trece la alt plan, ce a fost deja creat rămâne vizibil și poate fi revocat: cheile la care nu mai poate ajunge nimeni sunt mai rele decât o funcție plătită.

Ce nu este în această versiune

Specificația acestei etape descria încă două părți: exportul unui document finalizat în Google Drive, OneDrive sau Dropbox și trimiterea lui spre semnare prin DocuSign sau Dropbox Sign. Ambele necesită credențiale de la acești furnizori, pe care momentan nu le avem, iar a scrie o integrare care nu poate fi testată nicăieri înseamnă a prezenta cod nescris drept finalizat. Ele rămân în plan, ca versiuni separate.

Ce urmează

A șaptea și ultima funcție a valului este generarea în lot: o listă de cincizeci de rânduri sau o arhivă de scanări în loc de cincizeci de completări identice de mână, cu progres vizibil și posibilitatea de a repeta doar ce nu a funcționat.

Lista completă se află în ce construim în continuare, iar instrucțiunile pas cu pas pentru integrări, în centrul de ajutor.