API e webhook

Dove trovarli

Se nel tuo ufficio i documenti nascono altrove e non in DocuTract, quel sistema può parlare direttamente con noi. Apri il menu con il tuo indirizzo nell'angolo in alto a destra e scegli Integrazioni: lì si emette il token con cui il tuo sistema ci chiama e si aggiunge l'indirizzo a cui lo avvisiamo dei documenti finiti.

La schermata comincia con i collegamenti pronti ai CRM (Integrazioni CRM); i token e i webhook descritti qui stanno sotto, nella sezione API e webhook.

Il token

Premi Crea un token, dagli un nome che riconoscerai in seguito (così saprai quale sistema lo usa) e spunta cosa gli è consentito fare: leggere i modelli, creare documenti, lavorare con le pratiche.

Il token viene mostrato una sola volta, subito dopo la creazione: ne conserviamo solo un hash, quindi mostrarlo una seconda volta è impossibile perfino per noi. Copialo subito nelle impostazioni del tuo sistema.

L'elenco mostra i primi caratteri di ogni token, cosa può fare e quando è stato usato l'ultima volta. Revoca disattiva un token all'istante; la sua traccia resta, così si vede che è esistito e quando ha smesso di funzionare.

Cosa può fare l'API

Il tuo sistema può:

• aprire una pratica e caricarvi le scansioni;
• creare un documento da un modello con i valori già compilati;
• chiedere a che punto si trova un documento;
• ricevere tutti i valori insieme alla scansione da cui ciascuno è stato letto;
• ottenere un link di breve durata al file finito.

La descrizione completa di ogni indirizzo e campo è generata dal codice stesso ed è pubblicata apertamente: la descrizione dell'API.

Webhook

Invece di chiederci se un documento è pronto, dacci un indirizzo e ti scriveremo noi. Aggiungilo in Webhook e spunta gli eventi: documento pronto, documento non riuscito, pratica pronta, discrepanza trovata, un cliente ha inviato un file.

Ogni richiesta è firmata con l'intestazione X-DocuTract-Signature e il segreto che verifica la firma viene mostrato una sola volta, come il token. Il tuo sistema deve verificare la firma e rispondere con un codice 2xx. Se risponde con qualsiasi altro codice, o non risponde affatto, riproviamo: dopo un minuto, dopo cinque, dopo mezz'ora, dopo due ore e dopo dieci, poi ci fermiamo.

Quando qualcosa non è arrivato

Il pulsante Consegne mostra il registro: quale evento abbiamo inviato, quando, quante volte, quale codice di risposta è tornato e l'inizio del corpo della risposta. È la risposta a «il nostro sistema non ha ricevuto nulla»: c'è scritto nero su bianco che alle 14:12 ha risposto 500 per quattro volte.

Invia una prova invia subito un ping all'indirizzo, senza attendere un evento reale, così il ricevitore può essere configurato prima che ci passi del lavoro vero. Riprova, accanto a una consegna non riuscita, fa subito un altro tentativo.

Zapier, Make e n8n

Le piattaforme no-code (servizi in cui un'integrazione si costruisce senza programmare) si iscrivono da sole ai nostri eventi, tramite la parte REST hooks dell'API, così nessuno deve copiare i loro indirizzi in DocuTract. Dai alla piattaforma un token con i permessi webhooks:read e webhooks:write, più quelli che servono alle sue azioni (per esempio templates:read e documents:write).

• POST /api/v1/hooks con {"event": "document.ready", "target_url": "https://…"} iscrive un indirizzo a un evento. La risposta contiene l'id dell'iscrizione e, una sola volta, il suo secret di firma.
• GET /api/v1/hooks elenca le iscrizioni create così; DELETE /api/v1/hooks/{id} ne elimina una.
• GET /api/v1/hooks/events elenca gli eventi: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} restituisce un esempio di contenuto, che la piattaforma mostra nel suo «trigger di prova» prima che accada un evento reale.

Un'iscrizione è un normale indirizzo webhook: firmato, ritentato e registrato allo stesso modo, e visibile nell'elenco Webhook. Smette di funzionare quando il token che l'ha creata viene revocato o scade, oppure quando la piattaforma risponde a una consegna con 410 Gone.

Ecco document.ready:

{
  "document_id": "00000000-0000-4000-8000-000000000001",
  "reference": "DOC-26-0001",
  "template_id": "00000000-0000-4000-8000-000000000002",
  "template_version": 1,
  "event": "document.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

e case.ready:

{
  "case_id": "00000000-0000-4000-8000-000000000003",
  "title": "Sample case",
  "documents": [
    { "id": "00000000-0000-4000-8000-000000000001", "reference": "DOC-26-0001" }
  ],
  "event": "case.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

I campi di un modello

GET /api/v1/templates/{id}/fields (permesso templates:read) elenca ciò che serve a un modello: la key di ogni campo (quella con cui sono indicizzati i values di POST /api/v1/documents), la sua label, da dove viene compilato e fillable, che vale false per un campo che DocuTract compila da sé, come una data. Un modulo in Zapier o Make si costruisce da questo elenco, quindi corrisponde sempre al modello com'è adesso.

Ricerche

Alcune chiamate esistono perché un sistema, o una piattaforma no-code, trovi ciò che gli serve senza tirare a indovinare:

• GET /api/v1/me (nessun permesso) restituisce lo spazio di lavoro a cui appartiene il token, il suo piano e il nome e i permessi del token stesso. È il modo più semplice per verificare che un token funzioni.
• GET /api/v1/documents (permesso documents:read) elenca i documenti, i più recenti per primi. Restringi con reference (il riferimento DOC-… esatto), status o template_id; limit arriva fino a 100, 25 di default.
• GET /api/v1/cases (permesso cases:read) elenca le pratiche più recenti, se vuoi solo quelle con un certo status, con lo stesso limit. Ogni pratica ora riporta anche il suo created_at.
• GET /api/v1/case-types (permesso cases:read) elenca i tipi di pratica da cui si può aprire una pratica.
• GET /api/v1/templates?name=… tiene solo i modelli il cui nome contiene il testo, senza badare alle maiuscole.

Non c'è paginazione di proposito: questi elenchi servono a trovare gli elementi più recenti, non a esportare un intero spazio di lavoro.

Con quale piano

API e webhook fanno parte del piano Team. Con qualsiasi altro piano i token e gli indirizzi già creati restano visibili e si possono revocare, ma non se ne emettono di nuovi e le chiamate fatte con un token non vengono più servite. Confronta i piani nella pagina dei prezzi.