API
Il gestionale dello studio, di una banca o di un servicer apre pratiche e lotti, manda documenti e riceve gli esiti senza passare dall’interfaccia. Ogni operazione, con i suoi parametri, le risposte e un esempio pronto da copiare.
- Una chiave per ogni sistema: la crea l’amministratore dello studio in Organizzazione → API e agisce per conto di un membro dello studio.
- Le pratiche vanno in coda e si seguono con una GET o col webhook firmato della chiave.
- Al massimo 120 richieste al minuto per chiave; su richiesta, l’accesso solo con certificato client (mTLS) per i deployment dedicati.
Le pratiche di Trailgun dai sistemi dello studio. Ogni richiesta porta Authorization: Bearer tg_live_…, una chiave creata dall'amministratore dello studio (Organizzazione → API) che agisce per conto di un membro dello studio: vede i suoi clienti e crea a nome suo. Le pratiche vanno in coda e si seguono con GET o col webhook della chiave. A una pratica o a un lotto già creati si mandano altri documenti con POST …/documents (con l'intake acceso per lo studio). Al massimo 120 richieste al minuto per chiave: ogni risposta porta X-RateLimit-Limit e X-RateLimit-Remaining.
Indirizzo https://app.trailgun.ai/api/v1 · Scarica la specifica OpenAPI
Pratiche
Una pratica è una chiamata: il cliente, il tipo di atto, i fatti e lo zip dei documenti. Va in coda e si segue con GET o col webhook.
GET /pratiche
Le pratiche
Parametri
clienteId query | string Solo le pratiche di questo cliente. |
|---|---|
lottoId query | string Solo le pratiche di questo lotto. |
stato query | in_coda | in_corso | completata | fallita |
limite query | integer Quante pratiche, le più recenti per prime. |
archived query | true | all Senza: le pratiche non archiviate, come gli elenchi dell'app (con lottoId: tutte le pratiche del lotto). true: solo le archiviate. all: tutte. |
Risposte
- 200 { pratiche: Pratica[] }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"pratiche": [
{
"id": "job_8f2kq1x9",
"numero": 42,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"lottoId": null,
"titolo": "Alfa S.r.l. — fattura 128/2026",
"stato": "in_coda",
"fase": null,
"documenti": {
"totali": 0,
"lavorati": 0
},
"errore": null,
"origine": "api",
"creataIl": "2026-11-08T09:30:00.000Z",
"completataIl": null,
"archived": false,
"link": "https://app.trailgun.ai/jobs/job_8f2kq1x9"
}
]
}
curl https://app.trailgun.ai/api/v1/pratiche \
-H "Authorization: Bearer tg_live_…"
POST /pratiche
Apre una pratica (va in coda)
Multipart: il cliente, il tipo di atto, i fatti e lo zip dei documenti. La pratica va in coda (stato: in_coda) e si segue con GET /pratiche/{id} o col webhook della chiave (pratica.completata, pratica.fallita). L'utente della chiave deve poter creare pratiche: un operatore o un utente in sola lettura ricevono 403.
Corpo multipart/form-data
clienteId obbligatorio | string |
|---|---|
tipo | decreto_ingiuntivo | assessment | escussione_garanzia | insinuazione_passivo | remediation_datatape | affitto_ramo_azienda | analisi_faldone Default decreto_ingiuntivo. |
fatti | string Le note per gli agenti (obbligatorie, tranne per l'assessment e l'analisi del faldone). |
titolo | string |
templateId | string Il questionario, per l'assessment; il template del centro, per l'affitto di ramo d'azienda (facoltativo: senza, si riconosce dal nome del centro in fatti e titolo). |
practiceTemplateId | string Solo per analisi_faldone: il template di pratica (libreria Trailgun, dello studio, o personale di chi possiede la chiave). Dà materia, funzioni e opzioni documentali, i template atto e il workflow proposti sulla pratica. Si congela sulla pratica. |
leaseDeed | auto | preliminary | final Affitto di ramo d'azienda: il documento da redigere. Default auto (dalla proposta economica: rinnovo → definitivo, nuovo → preliminare). |
followedPeople | string Analisi del faldone: chi assiste l'avvocato, una persona per riga coi soprannomi dopo il punto e virgola («Mario Rossi; il biondo»), o il JSON [{ "name": "…", "aliases": ["…"] }]. Le domande potranno leggere solo le pagine che le nominano. |
qaLevel | string |
giurisprudenza | true | false |
raccoltaDati | true | false |
comunicazioni | spenta | semiautomatica | automatica |
archiviAnnidati | true | false Apre anche gli zip dentro lo zip (fino a tre livelli). Default true. |
archivio obbligatorio | file I documenti, in uno .zip (fino a 4 GB). |
Risposte
- 202 { pratica: Pratica }
- 400 Richiesta non valida: tipo, fatti, livello di controllo o archivio (.zip nel campo «archivio»)
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio, è disattivato, o il suo ruolo (operatore, sola lettura) non consente di creare pratiche
- 404 Cliente o template non trovato
- 413 Archivio troppo grande
- 429 Oltre 120 richieste al minuto, troppe pratiche in coda per lo studio o troppe pratiche aperte da questa chiave nelle ultime 24 ore
- 500 Errore interno.
Esempio di risposta
{
"pratica": {
"id": "job_8f2kq1x9",
"numero": 42,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"lottoId": null,
"titolo": "Alfa S.r.l. — fattura 128/2026",
"stato": "in_coda",
"fase": null,
"documenti": {
"totali": 0,
"lavorati": 0
},
"errore": null,
"origine": "api",
"creataIl": "2026-11-08T09:30:00.000Z",
"completataIl": null,
"archived": false,
"link": "https://app.trailgun.ai/jobs/job_8f2kq1x9"
}
}
curl -X POST https://app.trailgun.ai/api/v1/pratiche \
-H "Authorization: Bearer tg_live_…" \
-F clienteId=<clienteId> \
-F tipo=<tipo> \
-F fatti=<fatti> \
-F archivio=@pratica.zip
GET /pratiche/{id}
Una pratica
Parametri
id obbligatorio path | string L'id della pratica. |
|---|
Risposte
- 200 { pratica: Pratica }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Pratica non trovata, o non visibile alla chiave
- 429 Oltre 120 richieste al minuto per questa chiave.
Esempio di risposta
{
"pratica": {
"id": "job_8f2kq1x9",
"numero": 42,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"lottoId": null,
"titolo": "Alfa S.r.l. — fattura 128/2026",
"stato": "completata",
"fase": null,
"documenti": {
"totali": 14,
"lavorati": 14
},
"errore": null,
"origine": "api",
"creataIl": "2026-11-08T09:30:00.000Z",
"completataIl": "2026-11-08T10:12:00.000Z",
"archived": false,
"link": "https://app.trailgun.ai/jobs/job_8f2kq1x9"
}
}
curl https://app.trailgun.ai/api/v1/pratiche/<id> \
-H "Authorization: Bearer tg_live_…"
GET /pratiche/{id}/documento
Il documento prodotto (markdown)
Il testo dell'atto, quando la pratica è completata.
Parametri
id obbligatorio path | string L'id della pratica. |
|---|
Risposte
- 200 Il documento, in markdown
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Pratica non trovata
- 409 Il documento non è ancora pronto
- 429 Oltre 120 richieste al minuto per questa chiave.
Esempio di risposta
# Ricorso per decreto ingiuntivo
…
curl https://app.trailgun.ai/api/v1/pratiche/<id>/documento \
-H "Authorization: Bearer tg_live_…" \
-o documento.md
GET /pratiche/{id}/faldone
Il faldone (zip): atto, allegati, deposito, dati
Parametri
id obbligatorio path | string L'id della pratica. |
|---|
Risposte
- 200 Il faldone, come allegato (
Content-Disposition: attachment) - 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Pratica non trovata
- 409 La pratica è ancora in lavorazione
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
curl https://app.trailgun.ai/api/v1/pratiche/<id>/faldone \
-H "Authorization: Bearer tg_live_…" \
-o faldone.zip
Lotti
Molte pratiche da un solo archivio: si crea il lotto, si carica lo zip (uno zip o una cartella per pratica), si avvia.
POST /lotti
Crea un lotto (bozza): un cliente, un tipo, le stesse opzioni per tutte le pratiche
Poi si carica l'archivio (PUT /lotti/{id}/archivio) e si avvia (POST /lotti/{id}/avvia). Alla fine arriva il webhook lotto.concluso.
Corpo application/json
clienteId obbligatorio | string |
|---|---|
tipo | decreto_ingiuntivo | assessment | escussione_garanzia | insinuazione_passivo | remediation_datatape | affitto_ramo_azienda | analisi_faldone Default decreto_ingiuntivo. |
titolo | string |
fatti | string Le note comuni a tutte le pratiche. |
templateId | string |
practiceTemplateId | string Solo per analisi_faldone: il template di pratica (libreria Trailgun, dello studio, o personale di chi possiede la chiave). Dà materia, funzioni e opzioni documentali, i template atto e il workflow proposti sulla pratica. Si congela sulla pratica. |
matterId | string La pratica dello studio (fascicolo) a cui legare le pratiche del lotto. |
opzioni | Opzioni Assenti = le impostazioni dello studio e dell’utente della chiave. |
Esempio di corpo
{
"clienteId": "cli_4hd8s2",
"tipo": "decreto_ingiuntivo",
"titolo": "Fatture insolute — ottobre 2026",
"fatti": "Fatture scadute e non pagate; nessuna contestazione."
}
Risposte
- 201 { lotto: Lotto }
- 400 Richiesta non valida
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Cliente o template non trovato
- 409 Troppi lotti in bozza per questo utente
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"lotto": {
"id": "lot_3m9x2a",
"numero": 7,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"titolo": "Fatture insolute — ottobre 2026",
"stato": "bozza",
"creatoIl": "2026-11-08T09:30:00.000Z",
"avviatoIl": null,
"conclusoIl": null,
"archived": false,
"link": "https://app.trailgun.ai/batches/lot_3m9x2a"
}
}
curl -X POST https://app.trailgun.ai/api/v1/lotti \
-H "Authorization: Bearer tg_live_…" \
-H "Content-Type: application/json" \
-d '{"clienteId":"cli_4hd8s2","tipo":"decreto_ingiuntivo","titolo":"Fatture insolute — ottobre 2026","fatti":"Fatture scadute e non pagate; nessuna contestazione."}'
GET /lotti/{id}
Il lotto, i suoi numeri e le sue pratiche
Parametri
id obbligatorio path | string L'id del lotto. |
|---|
Risposte
- 200 { lotto: Lotto & { conteggi, minutiRimanenti }, anteprima, pratiche: Pratica[] }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Lotto non trovato, o non visibile alla chiave
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"lotto": {
"id": "lot_3m9x2a",
"numero": 7,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"titolo": "Fatture insolute — ottobre 2026",
"stato": "in_corso",
"creatoIl": "2026-11-08T09:30:00.000Z",
"avviatoIl": "2026-11-08T09:40:00.000Z",
"conclusoIl": null,
"archived": false,
"link": "https://app.trailgun.ai/batches/lot_3m9x2a",
"conteggi": {
"in_coda": 3,
"in_corso": 2,
"completato": 5,
"fallito": 0,
"totale": 10
},
"minutiRimanenti": 24
},
"anteprima": null,
"pratiche": [
{
"id": "job_8f2kq1x9",
"numero": 42,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"lottoId": "lot_3m9x2a",
"titolo": "Alfa S.r.l. — fattura 128/2026",
"stato": "in_coda",
"fase": null,
"documenti": {
"totali": 0,
"lavorati": 0
},
"errore": null,
"origine": "lotto",
"creataIl": "2026-11-08T09:30:00.000Z",
"completataIl": null,
"archived": false,
"link": "https://app.trailgun.ai/jobs/job_8f2kq1x9"
}
]
}
curl https://app.trailgun.ai/api/v1/lotti/<id> \
-H "Authorization: Bearer tg_live_…"
PUT /lotti/{id}/archivio
Carica l'archivio del lotto: uno zip con uno zip (o una cartella) per pratica
Il corpo è lo zip, grezzo. Facoltativi: lotto.csv alla radice (archivio;titolo;fatti) e fatti.txt dentro ogni pratica. La risposta contiene l’anteprima: le pratiche trovate e quelle scartate, col motivo.
Parametri
id obbligatorio path | string L'id del lotto. |
|---|---|
nome query | string Il nome del file, per riconoscerlo. Default lotto.zip. |
Corpo application/zip
Risposte
- 200 { lotto: Lotto, anteprima }
- 400 Corpo assente o archivio non utilizzabile
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Lotto non trovato
- 409 Il lotto è già avviato: non si cambia più il suo archivio
- 413 Troppo grande
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
- 507 Spazio su disco insufficiente in questo momento: riprovare più tardi
curl -X PUT https://app.trailgun.ai/api/v1/lotti/<id>/archivio \
-H "Authorization: Bearer tg_live_…" \
-H "Content-Type: application/zip" \
--data-binary @lotto.zip
POST /lotti/{id}/avvia
Avvia il lotto: le pratiche vanno in coda
Parametri
id obbligatorio path | string L'id del lotto. |
|---|
Corpo application/json
escludi | integer[] Le voci dell'anteprima (n) da non avviare. |
|---|---|
archiviAnnidati | boolean Cambia la scelta del lotto sugli zip dentro lo zip prima di avviare. |
Esempio di corpo
{
"escludi": [
3
]
}
Risposte
- 200 { lotto: Lotto }
- 400 Nessuna pratica da avviare
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Lotto non trovato
- 409 Già avviato o senza archivio
- 413 Una pratica oltre il limite
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
curl -X POST https://app.trailgun.ai/api/v1/lotti/<id>/avvia \
-H "Authorization: Bearer tg_live_…" \
-H "Content-Type: application/json" \
-d '{"escludi":[3]}'
Documenti e intake
Altri documenti a una pratica o a un lotto già creati, e l'esito di ogni invio. Serve l'intake acceso per lo studio.
POST /pratiche/{id}/documents
Manda documenti a una pratica già creata
I documenti entrano nella pratica dall'intake (lo stesso dell'indirizzo email della pratica, creato al primo invio). Una pratica conclusa li riceve subito; una in lavorazione li tiene in attesa (waiting) e li prende appena finisce. Serve l'intake acceso per lo studio.
Parametri
id obbligatorio path | string L'id della pratica. |
|---|---|
Idempotency-Key header | string La stessa chiave due volte (con la stessa chiave API) dà un arrivo solo: la seconda risposta (200, header Idempotent-Replayed: true) è il primo arrivo. |
Corpo multipart/form-data
files | file[] I documenti: uno o più file nel campo files (anche files[]). Al massimo 20, 25 MB ciascuno. |
|---|---|
text | string Un testo che accompagna i documenti (da solo, senza file, diventa esso stesso un documento). |
Risposte
- 200 Stessa Idempotency-Key: lo stesso arrivo di prima. Eccezione: un arrivo finito in errore senza documenti salvati (es. un riavvio) libera la chiave, e la ripetizione è un invio nuovo (202).
- 202 Ricevuto (
status: received): l'esito arriva col webhookintake.*o con GET /intakes/{id}/arrivals/{arrivalId} - 400 Nessun file né testo, più di 20 file,
refnon valido o Idempotency-Key oltre 200 caratteri - 401 Chiave assente, non valida o revocata.
- 403 L'intake non è attivo per lo studio (lo accende il backoffice di Trailgun) o è disattivato (
{ error }); oppure, dal controllo della chiave, l'utente non è più nello studio o il suo ruolo non lo consente ({ errore }) - 404 Pratica non trovato/a, o non visibile alla chiave
- 409 Idempotency-Key già usata per un altro invio
- 413 Un file oltre il limite per file (25 MB)
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"arrival": {
"id": "arr_7d1q8z",
"channel": "api",
"from": null,
"subject": null,
"ref": null,
"status": "received",
"reason": null,
"jobId": null,
"documents": [
{
"name": "estratto-conto.pdf",
"bytes": 182344
}
],
"createdAt": "2026-11-08T09:31:00.000Z",
"deliveredAt": null
},
"intake": {
"id": "int_5k2p9w",
"address": "intake-a8f3k2@mail.trailgun.ai",
"target": "job",
"jobId": "job_8f2kq1x9",
"batchId": null,
"clientId": "cli_4hd8s2",
"name": null,
"enabled": true,
"senders": [],
"createdAt": "2026-11-08T09:31:00.000Z",
"updatedAt": "2026-11-08T09:31:00.000Z"
}
}
curl -X POST https://app.trailgun.ai/api/v1/pratiche/<id>/documents \
-H "Authorization: Bearer tg_live_…" \
-H "Idempotency-Key: <idempotency-key>" \
-F files=@documento.pdf
POST /lotti/{id}/documents
Manda documenti a un lotto già creato
Con ref vanno alla pratica del lotto con quel riferimento; senza, il lotto decide (una pratica nuova del lotto).
Parametri
id obbligatorio path | string L'id del lotto. |
|---|---|
Idempotency-Key header | string La stessa chiave due volte (con la stessa chiave API) dà un arrivo solo: la seconda risposta (200, header Idempotent-Replayed: true) è il primo arrivo. |
Corpo multipart/form-data
files | file[] I documenti: uno o più file nel campo files (anche files[]). Al massimo 20, 25 MB ciascuno. |
|---|---|
text | string Un testo che accompagna i documenti (da solo, senza file, diventa esso stesso un documento). |
ref | string Il riferimento di una pratica già esistente del lotto, cioè il suo numero (42 o trail42 per TRAIL-42; li elenca jobs in GET /intakes): i documenti vanno a quella pratica invece di aprirne una nuova. |
Risposte
- 200 Stessa Idempotency-Key: lo stesso arrivo di prima. Eccezione: un arrivo finito in errore senza documenti salvati (es. un riavvio) libera la chiave, e la ripetizione è un invio nuovo (202).
- 202 Ricevuto (
status: received): l'esito arriva col webhookintake.*o con GET /intakes/{id}/arrivals/{arrivalId} - 400 Nessun file né testo, più di 20 file,
refnon valido o Idempotency-Key oltre 200 caratteri - 401 Chiave assente, non valida o revocata.
- 403 L'intake non è attivo per lo studio (lo accende il backoffice di Trailgun) o è disattivato (
{ error }); oppure, dal controllo della chiave, l'utente non è più nello studio o il suo ruolo non lo consente ({ errore }) - 404 Lotto non trovato/a, o non visibile alla chiave
- 409 Idempotency-Key già usata per un altro invio
- 413 Un file oltre il limite per file (25 MB)
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"arrival": {
"id": "arr_7d1q8z",
"channel": "api",
"from": null,
"subject": null,
"ref": null,
"status": "received",
"reason": null,
"jobId": null,
"documents": [
{
"name": "estratto-conto.pdf",
"bytes": 182344
}
],
"createdAt": "2026-11-08T09:31:00.000Z",
"deliveredAt": null
},
"intake": {
"id": "int_5k2p9w",
"address": "intake-a8f3k2@mail.trailgun.ai",
"target": "job",
"jobId": "job_8f2kq1x9",
"batchId": null,
"clientId": "cli_4hd8s2",
"name": null,
"enabled": true,
"senders": [],
"createdAt": "2026-11-08T09:31:00.000Z",
"updatedAt": "2026-11-08T09:31:00.000Z"
}
}
curl -X POST https://app.trailgun.ai/api/v1/lotti/<id>/documents \
-H "Authorization: Bearer tg_live_…" \
-H "Idempotency-Key: <idempotency-key>" \
-F files=@documento.pdf
GET /intakes
Gli intake di un cliente, di una pratica o di un lotto
Uno dei tre parametri è obbligatorio. Per i lotti, jobs elenca le pratiche del lotto col loro ref.
Parametri
clientId query | string |
|---|---|
jobId query | string |
batchId query | string |
Risposte
- 200 { intakes: Intake[], enabled }
- 400 Manca clientId, jobId o batchId
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Cliente, pratica o lotto non trovato
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"intakes": [
{
"id": "int_5k2p9w",
"address": "intake-a8f3k2@mail.trailgun.ai",
"target": "job",
"jobId": "job_8f2kq1x9",
"batchId": null,
"clientId": "cli_4hd8s2",
"name": null,
"enabled": true,
"senders": [],
"createdAt": "2026-11-08T09:31:00.000Z",
"updatedAt": "2026-11-08T09:31:00.000Z"
}
],
"enabled": true
}
curl https://app.trailgun.ai/api/v1/intakes \
-H "Authorization: Bearer tg_live_…"
GET /intakes/{id}
Un intake e i suoi arrivi più recenti
Parametri
id obbligatorio path | string L'id dell'intake. |
|---|---|
limit query | integer Quanti arrivi, i più recenti per primi. |
Risposte
- 200 { intake, arrivals }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Non trovato
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"intake": {
"id": "int_5k2p9w",
"address": "intake-a8f3k2@mail.trailgun.ai",
"target": "job",
"jobId": "job_8f2kq1x9",
"batchId": null,
"clientId": "cli_4hd8s2",
"name": null,
"enabled": true,
"senders": [],
"createdAt": "2026-11-08T09:31:00.000Z",
"updatedAt": "2026-11-08T09:31:00.000Z"
},
"arrivals": [
{
"id": "arr_7d1q8z",
"channel": "api",
"from": null,
"subject": null,
"ref": null,
"status": "received",
"reason": null,
"jobId": null,
"documents": [
{
"name": "estratto-conto.pdf",
"bytes": 182344
}
],
"createdAt": "2026-11-08T09:31:00.000Z",
"deliveredAt": null
}
]
}
curl https://app.trailgun.ai/api/v1/intakes/<id> \
-H "Authorization: Bearer tg_live_…"
GET /intakes/{id}/arrivals/{arrivalId}
Lo stato di un arrivo (per chi non usa i webhook)
Parametri
id obbligatorio path | string L'id dell'intake. |
|---|---|
arrivalId obbligatorio path | string L'id dell'arrivo. |
Risposte
- 200 { arrival }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Non trovato
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"arrival": {
"id": "arr_7d1q8z",
"channel": "api",
"from": null,
"subject": null,
"ref": null,
"status": "delivered",
"reason": null,
"jobId": "job_8f2kq1x9",
"documents": [
{
"name": "estratto-conto.pdf",
"bytes": 182344
}
],
"createdAt": "2026-11-08T09:31:00.000Z",
"deliveredAt": "2026-11-08T09:32:10.000Z"
}
}
curl https://app.trailgun.ai/api/v1/intakes/<id>/arrivals/<arrivalId> \
-H "Authorization: Bearer tg_live_…"
Clienti e tipi
I clienti visibili all'utente della chiave e i tipi di atto che si possono aprire.
GET /tipi
I tipi di atto e cosa chiedono
Per ogni tipo: il nome, quando si usa, se i fatti sono obbligatori, se serve un questionario e quali opzioni accetta.
Risposte
- 200 { tipi: TipoAtto[] }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 429 Oltre 120 richieste al minuto per questa chiave.
Esempio di risposta
{
"tipi": [
{
"tipo": "decreto_ingiuntivo",
"nome": "Decreto ingiuntivo",
"quando": "Recupero di un credito con prova scritta verso un debitore in bonis: ricorso per decreto ingiuntivo.",
"fatti": "obbligatori",
"template": false,
"opzioni": {
"qa": true,
"raccoltaDati": true,
"giurisprudenza": true
}
}
]
}
curl https://app.trailgun.ai/api/v1/tipi \
-H "Authorization: Bearer tg_live_…"
GET /clienti
I clienti visibili all'utente della chiave
Parametri
q query | string Ricerca per nome o partita IVA. |
|---|
Risposte
- 200 { clienti: Cliente[] }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"clienti": [
{
"id": "cli_4hd8s2",
"numero": 12,
"nome": "Servicer Beta S.p.A.",
"partitaIva": "01234567890",
"citta": "Milano"
}
]
}
curl https://app.trailgun.ai/api/v1/clienti \
-H "Authorization: Bearer tg_live_…"
Audit
Chi ha fatto che cosa nello studio, col valore prima e dopo, per il SIEM dello studio. Solo con la chiave di un amministratore.
GET /audit
Il registro di audit dello studio (per il SIEM)
Gli eventi dello studio della chiave, dal più recente, a pagine con cursore: passa next come after per la pagina dopo. Solo con la chiave di un amministratore dello studio (403 altrimenti).
Parametri
from query | string Dal (millisecondi o data ISO). |
|---|---|
to query | string Al (millisecondi o data ISO). |
action query | auth.session.start | client.create | client.update | client.delete | client.visibility.update | client.members.update | matter.create | act.create | act.delete | act.archive | act.restore | act.redraft | act.text.update | act.playbook.update | act.actors.update | act.document.sign | external.request.open | external.request.download | external.request.move | external.request.comment | external.request.resend | external.account.register | external.account.login | external.account.delete | external.account.whatsapp.verify | external.account.whatsapp.remove | act.spending_limit.update | act.space.update | document.add | document.restore | user.invite | user.disable | user.enable | user.resend_invite | user.role.update | user.admin.update | user.permissions.update | org.update | settings.studio.update | settings.user.update | settings.platform.update | prompt.platform.update | prompt.studio_addition.update | api_key.create | api_key.update | api_key.revoke | platform.org.create | platform.org.update | platform.feature.update | platform.limits.update | platform.users.add | platform.site.update | platform.compliance_document.update | platform.audit.purge | outlook.connection.updated | outlook.connection.enabled | outlook.connection.disabled | outlook.connection.deleted | outlook.connection.secret_rotated | platform.outlook.enabled | platform.outlook.disabled | governance.owner_changed | document.injection_suspected | export.download | audit.export | data_export.requested | data_export.completed | data_export.failed | data_export.downloaded | data_export.deleted | data_export.expired | sso.connection.create | sso.connection.update | sso.connection.delete | sso.domain.add | sso.domain.remove | sso.sso_only.update | sso.jit_user_created | sso.jit_refused | sso.first_login | sso.login_refused | scim.enabled_changed | scim.token_created | scim.token_revoked | scim.default_role_changed | scim.group_role_changed | scim.user_created | scim.user_updated | scim.user_disabled | scim.user_enabled | scim.user_deleted | scim.group_created | scim.group_updated | scim.group_deleted | scim.group_members_changed | scim.role_changed | scim.role_change_blocked | scim.request_refused | regulatory_topic.create | regulatory_topic.update | regulatory_topic.delete | platform.regulatory_source.update | actor.create | actor.update | actor.archive | actor.restore | actor.person.erase | voice_note.create | voice_note.view | voice_note.audio_access | voice_note.update | voice_note.link | voice_note.delete | dictation.transcribe | space.create | space.rename | space.members.update | space.delete | transfer.settings.update | transfer.quota.update | transfer.sender.block | transfer.sender.unblock | transfer.revoke | transfer.abuse.update |
entity query | client | matter | act | document | user | org | settings | api_key | prompt | session | export | site | compliance_document | audit | data_export | sso | outlook_connection | agent | scim | regulatory_topic | regulatory_source | actor | space | external_request | external_account | voice_note | dictation | transfer | transfer_sender | transfer_abuse_report |
entityId query | string |
actor query | string L'id, l'email o il nome della chiave di chi ha agito. |
limit query | integer |
after query | string Il cursore next della pagina prima. |
Risposte
- 200 { events: AuditEvent[], next }
- 400 Filtro o cursore non valido
- 401 Chiave assente, non valida o revocata.
- 403 La chiave non è di un amministratore dello studio, o l'utente della chiave non è più nello studio
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Esempio di risposta
{
"events": [
{
"id": "aud_7Qp2x9",
"occurredAt": "2026-11-08T10:15:00.000Z",
"actor": {
"kind": "user",
"id": "usr_3kd9",
"label": "avvocato@studio.it"
},
"action": "client.visibility.update",
"entity": "client",
"entityId": "cli_4hd8s2",
"clientId": "cli_4hd8s2",
"before": {
"visibility": "org"
},
"after": {
"visibility": "privato"
},
"meta": null,
"ip": "203.0.113.5",
"userAgent": "Mozilla/5.0",
"hidden": false
}
],
"next": null
}
curl https://app.trailgun.ai/api/v1/audit \
-H "Authorization: Bearer tg_live_…"
Webhook
Se la chiave ha un webhook, Trailgun manda un POST firmato alla fine di ciò che la chiave ha creato e a ogni esito dell'intake.
Eventi
pratica.completatauna pratica creata dalla chiave (fuori da un lotto) è completatapratica.fallitauna pratica creata dalla chiave (fuori da un lotto) non è riuscitalotto.conclusoun lotto creato dalla chiave è finito (le sue pratiche non mandano un evento ciascuna)intake.consegnatoi documenti sono entrati nella praticaintake.in_attesala pratica è in lavorazione: i documenti entrano appena finisceintake.da_verificareuna mail da un mittente sconosciuto: l'avvocato approva o rifiuta in appintake.rifiutatoi documenti non sono stati accettati (motivo inarrival.reason)intake.errorela consegna non è riuscita (motivo inarrival.reason)
Firma e tentativi
Se la chiave ha un webhook, Trailgun manda un POST JSON { tipo, creatoIl, dati } con tipo = pratica.completata | pratica.fallita (pratiche fuori da un lotto) | lotto.concluso | intake.consegnato | intake.in_attesa | intake.da_verificare | intake.rifiutato | intake.errore. Gli eventi intake.* (dati: { arrival, intake, pratica? }) vanno alla chiave che ha creato la pratica o il lotto e a quella che ha mandato i documenti. Header Trailgun-Signature: t=<secondi>,v1=<hex>: HMAC-SHA256, col segreto del webhook, di <t>.<corpo>. Tre tentativi.