Vai al contenuto
Trailgun
ITEN Accedi

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 querystring Solo le pratiche di questo cliente.
lottoId querystring Solo le pratiche di questo lotto.
stato queryin_coda | in_corso | completata | fallita
limite queryinteger Quante pratiche, le più recenti per prime.
archived querytrue | 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 obbligatoriostring
tipodecreto_ingiuntivo | assessment | escussione_garanzia | insinuazione_passivo | remediation_datatape | affitto_ramo_azienda | analisi_faldone Default decreto_ingiuntivo.
fattistring Le note per gli agenti (obbligatorie, tranne per l'assessment e l'analisi del faldone).
titolostring
templateIdstring 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).
practiceTemplateIdstring 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.
leaseDeedauto | preliminary | final Affitto di ramo d'azienda: il documento da redigere. Default auto (dalla proposta economica: rinnovo → definitivo, nuovo → preliminare).
followedPeoplestring 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.
qaLevelstring
giurisprudenzatrue | false
raccoltaDatitrue | false
comunicazionispenta | semiautomatica | automatica
archiviAnnidatitrue | false Apre anche gli zip dentro lo zip (fino a tre livelli). Default true.
archivio obbligatoriofile 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 pathstring 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 pathstring 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 pathstring 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 obbligatoriostring
tipodecreto_ingiuntivo | assessment | escussione_garanzia | insinuazione_passivo | remediation_datatape | affitto_ramo_azienda | analisi_faldone Default decreto_ingiuntivo.
titolostring
fattistring Le note comuni a tutte le pratiche.
templateIdstring
practiceTemplateIdstring 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.
matterIdstring La pratica dello studio (fascicolo) a cui legare le pratiche del lotto.
opzioniOpzioni 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 pathstring 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 pathstring L'id del lotto.
nome querystring 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 pathstring L'id del lotto.

Corpo application/json

escludiinteger[] Le voci dell'anteprima (n) da non avviare.
archiviAnnidatiboolean 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 pathstring L'id della pratica.
Idempotency-Key headerstring 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

filesfile[] I documenti: uno o più file nel campo files (anche files[]). Al massimo 20, 25 MB ciascuno.
textstring 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 webhook intake.* o con GET /intakes/{id}/arrivals/{arrivalId}
  • 400 Nessun file né testo, più di 20 file, ref non 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 pathstring L'id del lotto.
Idempotency-Key headerstring 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

filesfile[] I documenti: uno o più file nel campo files (anche files[]). Al massimo 20, 25 MB ciascuno.
textstring Un testo che accompagna i documenti (da solo, senza file, diventa esso stesso un documento).
refstring 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 webhook intake.* o con GET /intakes/{id}/arrivals/{arrivalId}
  • 400 Nessun file né testo, più di 20 file, ref non 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 querystring
jobId querystring
batchId querystring

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 pathstring L'id dell'intake.
limit queryinteger 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 pathstring L'id dell'intake.
arrivalId obbligatorio pathstring 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 querystring 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 querystring Dal (millisecondi o data ISO).
to querystring Al (millisecondi o data ISO).
action queryauth.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 queryclient | 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 querystring
actor querystring L'id, l'email o il nome della chiave di chi ha agito.
limit queryinteger
after querystring 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.completata una pratica creata dalla chiave (fuori da un lotto) è completata
  • pratica.fallita una pratica creata dalla chiave (fuori da un lotto) non è riuscita
  • lotto.concluso un lotto creato dalla chiave è finito (le sue pratiche non mandano un evento ciascuna)
  • intake.consegnato i documenti sono entrati nella pratica
  • intake.in_attesa la pratica è in lavorazione: i documenti entrano appena finisce
  • intake.da_verificare una mail da un mittente sconosciuto: l'avvocato approva o rifiuta in app
  • intake.rifiutato i documenti non sono stati accettati (motivo in arrival.reason)
  • intake.errore la consegna non è riuscita (motivo in arrival.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.