DoConure

Come faccio a sapere quando qualcosa è terminato?

In due modi, e potete usare l'uno o l'altro. Il polling è descritto sotto e funziona sempre. Una callback di solito è meglio, se potete accettare una richiesta in ingresso: impostate callbackUrl (in signature per un flusso, in settings per una busta) e ve lo diciamo noi; conta soprattutto su una piattaforma con un budget giornaliero di chiamate: una busta lasciata aperta tre giorni, interrogata ogni cinque minuti, costa circa 860 chiamate per non sapere nulla 859 volte. Se il vostro ricevitore vuole che ci autentichiamo (un token, una chiave API, OAuth2 come fa Salesforce), configura un ambiente di callback e invia {"env": "prod", "onSuccess": "/hooks/ok"}. Per sapere anche quando un firmatario viene sostituito, aggiungete l'indirizzo facoltativo onEvent: riceve recipient.replaced, mentre onSuccess e onError continuano a dire soltanto come si è conclusa la richiesta (dettagli).

Per il polling, chiedete GET /api/v1/flow/{flowId} (oppure GET /api/v1/sign/envelopes/{id} se avete usato il percorso in due passaggi) e decidete in base a output.status, non in base alla specifica stringa di stato:

curl https://your-host/api/v1/flow/FLOW_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
{ "output": { "status": "pending",
              "flow": { "status": "awaiting_signature", "closed": false },
              "...": "..." } }

"status": "pending" significa: continua a chiedere. "succeeded" e "failed" significano entrambi: fermatevi. Insieme coprono tutti i modi in cui un flusso smette di cambiare — signed, declined, expired, cancelled — quindi il codice che controlla output.status continua a funzionare il giorno in cui viene aggiunto un nuovo stato, invece di ciclare all'infinito su quello. Quando vi serve distinguere i tre modi di fallire, output.flow.status è sempre lì.

Le stesse due parole funzionano su una busta: GET /api/v1/sign/envelopes/{id} risponde con la stessa identica forma, con output.sign al posto di output.flow. Un solo poller, per entrambi i percorsi.

Vedere, reinviare e provare i vostri webhook

Nella console, Webhook elenca ogni notifica che abbiamo inviato al vostro sistema — l'evento, l'URL, i nostri tentativi, cosa ha risposto il vostro server — e il corpo esatto. Cosa potete fare lì:

  • Invia di nuovo. Mette in coda una nuova consegna con lo stesso corpo memorizzato: gli stessi byte e lo stesso event.id, così un ricevitore che deduplica lo riconosce e uno che non lo fa riceve esattamente ciò che gli era stato inviato la prima volta. Segue la normale pianificazione e i normali tentativi; l'originale conserva la sua cronologia. Attenzione: un ricevitore che deduplica su event.id (come dovrebbe) risponde 200 e non fa nulla, quindi la riga dice "consegnato" e dalla vostra parte non cambia niente.
  • Invia di nuovo come nuovo evento. Per provare il vostro ricevitore: lo stesso corpo con un event.id e un occurredAt nuovi, e event.replayOf che nomina l'evento ripetuto, dentro il corpo firmato. La vostra deduplicazione lo lascia passare.
  • La loro risposta. Ogni consegna conserva cosa ha risposto il vostro server all'ultimo tentativo: la riga di stato, qualche intestazione e i primi 500 caratteri del corpo — così si vede un 200 che contiene un rifiuto. Un reinvio è una riga a sé con la sua risposta; l'originale non cambia mai.
  • Invia di nuovo tutti gli abbandonati. Dopo che il vostro server è rimasto giù più a lungo dei nostri tentativi (44 ore), una pressione rimette in coda ogni evento abbandonato, dal più vecchio, ciascuno esattamente come farebbe Invia di nuovo; un evento già reinviato non viene mai messo in coda due volte, e ne partono al massimo 200 per pressione.
  • Invia un evento di esempio. Un evento inventato nella forma reale, firmato con il vostro segreto, inviato subito con lo stesso codice di uno vero (solo https, solo indirizzi pubblici, nessun redirect). Riportate event.simulated: true dentro il corpo firmato e non viene mai ritentato, così potete scrivere il vostro handler prima di avere una busta reale.
  • Tutte queste azioni sono registrate nell'audit e limitate per organizzazione.

Tabella completa degli stati: Componi e firma, in una chiamata.