{"openapi":"3.1.0","info":{"title":"Trailgun API","version":"1.0.0","description":"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`."},"servers":[{"url":"/api/v1"}],"security":[{"chiave":[]}],"tags":[{"name":"Pratiche","description":"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."},{"name":"Lotti","description":"Molte pratiche da un solo archivio: si crea il lotto, si carica lo zip (uno zip o una cartella per pratica), si avvia."},{"name":"Documenti e intake","description":"Altri documenti a una pratica o a un lotto già creati, e l'esito di ogni invio. Serve l'intake acceso per lo studio."},{"name":"Clienti e tipi","description":"I clienti visibili all'utente della chiave e i tipi di atto che si possono aprire."},{"name":"Audit","description":"Chi ha fatto che cosa nello studio, col valore prima e dopo, per il SIEM dello studio. Solo con la chiave di un amministratore."},{"name":"Webhook","description":"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."}],"components":{"securitySchemes":{"chiave":{"type":"http","scheme":"bearer","description":"La chiave API (`tg_live_…`)."}},"headers":{"RateLimitLimit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}},"IdempotentReplayed":{"description":"`true` quando la risposta è quella di un invio già ricevuto con la stessa Idempotency-Key.","schema":{"type":"string","const":"true"}}},"responses":{"Unauthorized":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"Forbidden":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"TooManyRequests":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"ServerError":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"ServerErrorIntake":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Errore":{"type":"object","properties":{"errore":{"type":"string"}},"required":["errore"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Intake":{"type":"object","description":"L'ingresso stabile di documenti di una pratica (`job`) o di un lotto (`batch`): un indirizzo email e, dall'API, le rotte `/documents`.","required":["id","address","target","jobId","batchId","clientId","name","enabled","senders","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"address":{"type":"string","format":"email","description":"L'indirizzo a cui mandare i documenti per mail."},"target":{"type":"string","enum":["job","batch"]},"jobId":{"type":["string","null"]},"batchId":{"type":["string","null"]},"clientId":{"type":"string"},"name":{"type":["string","null"]},"enabled":{"type":"boolean"},"senders":{"type":"array","items":{"type":"string","format":"email"},"description":"Indirizzi in più ammessi come mittenti delle mail."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"jobs":{"type":"array","description":"Solo per i lotti, nelle GET di /intakes: le pratiche del lotto visibili alla chiave, col `ref` da usare in POST /lotti/{id}/documents (o nell’indirizzo `address`).","items":{"type":"object","properties":{"jobId":{"type":"string"},"title":{"type":"string"},"ref":{"type":"string"},"address":{"type":"string","format":"email"}}}}}},"Arrival":{"type":"object","description":"Un invio di documenti a un intake (mail, API, caricamento dall’app) e il suo esito.","required":["id","channel","from","subject","ref","status","reason","jobId","documents","createdAt","deliveredAt"],"properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["email","api","upload","simulation"]},"from":{"type":["string","null"]},"subject":{"type":["string","null"]},"ref":{"type":["string","null"],"description":"La pratica del lotto indicata (solo per i lotti)."},"status":{"type":"string","enum":["received","waiting","quarantined","delivered","rejected","failed"],"description":"`received`: in lavorazione. `waiting`: la pratica è in lavorazione, i documenti entrano appena finisce. `quarantined`: mittente da verificare in app. `delivered`, `rejected`, `failed`: finali."},"reason":{"type":["string","null"]},"jobId":{"type":["string","null"],"description":"La pratica che ha ricevuto (o è nata da) i documenti."},"documents":{"type":"array","items":{"type":"object","required":["name","bytes"],"properties":{"name":{"type":"string"},"bytes":{"type":"integer"}}}},"createdAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"}}},"Pratica":{"type":"object","required":["id","numero","tipo","clienteId","lottoId","titolo","stato","fase","documenti","errore","origine","creataIl","completataIl","archived","link"],"properties":{"id":{"type":"string"},"numero":{"type":["integer","null"],"description":"Il numero della pratica nello studio (TRAIL-42)."},"tipo":{"type":"string","enum":["decreto_ingiuntivo","assessment","escussione_garanzia","insinuazione_passivo","remediation_datatape","affitto_ramo_azienda","analisi_faldone"]},"clienteId":{"type":"string"},"lottoId":{"type":["string","null"]},"titolo":{"type":["string","null"]},"stato":{"type":"string","enum":["in_coda","in_corso","completata","fallita"]},"fase":{"type":["string","null"],"description":"La fase in corso, mentre la pratica lavora."},"documenti":{"type":"object","required":["totali","lavorati"],"properties":{"totali":{"type":"integer"},"lavorati":{"type":"integer"}}},"errore":{"type":["string","null"]},"origine":{"type":"string","enum":["manuale","lotto","email","api"]},"creataIl":{"type":"string","format":"date-time"},"completataIl":{"type":["string","null"],"format":"date-time"},"archived":{"type":"boolean","description":"Archiviata nell'app: fuori dagli elenchi, nella sezione Archivio."},"link":{"type":"string","format":"uri","description":"La pagina della pratica nell'app."}}},"Lotto":{"type":"object","required":["id","numero","tipo","clienteId","titolo","stato","creatoIl","avviatoIl","conclusoIl","archived","link"],"properties":{"id":{"type":"string"},"numero":{"type":"integer"},"tipo":{"type":"string","enum":["decreto_ingiuntivo","assessment","escussione_garanzia","insinuazione_passivo","remediation_datatape","affitto_ramo_azienda","analisi_faldone"]},"clienteId":{"type":"string"},"titolo":{"type":"string"},"stato":{"type":"string","enum":["bozza","pronto","in_corso","in_pausa","concluso","annullato"]},"creatoIl":{"type":"string","format":"date-time"},"avviatoIl":{"type":["string","null"],"format":"date-time"},"conclusoIl":{"type":["string","null"],"format":"date-time"},"archived":{"type":"boolean","description":"Archiviato nell'app, con tutte le sue pratiche."},"link":{"type":"string","format":"uri","description":"La pagina del lotto nell'app."}}},"Conteggi":{"type":"object","description":"Le pratiche del lotto per stato.","required":["in_coda","in_corso","completato","fallito","totale"],"properties":{"in_coda":{"type":"integer"},"in_corso":{"type":"integer"},"completato":{"type":"integer"},"fallito":{"type":"integer"},"totale":{"type":"integer"}}},"Anteprima":{"type":["object","null"],"description":"Le pratiche trovate nell'archivio del lotto (`voci`) e quelle scartate, col motivo. `null` finché l'archivio non è caricato.","properties":{"voci":{"type":"array","items":{"type":"object","properties":{"n":{"type":"integer","description":"La posizione nella lista, da usare in `escludi` all’avvio."},"nome":{"type":"string"},"titolo":{"type":"string"},"fonte":{"type":"string","enum":["zip","cartella"]},"file":{"type":"string"},"bytes":{"type":"integer"},"documenti":{"type":"integer"},"fatti":{"type":"string"},"problema":{"type":"string","description":"Se c’è, la pratica non parte: il motivo."},"avviso":{"type":"string"},"annidati":{"type":"integer"}}}},"scartati":{"type":"array","items":{"type":"object","properties":{"nome":{"type":"string"},"motivo":{"type":"string"}}}},"csv":{"type":"integer","description":"Le righe di `lotto.csv` usate."},"bytesTotali":{"type":"integer"}}},"TipoAtto":{"type":"object","required":["tipo","nome","quando","fatti","template","opzioni"],"properties":{"tipo":{"type":"string","enum":["decreto_ingiuntivo","assessment","escussione_garanzia","insinuazione_passivo","remediation_datatape","affitto_ramo_azienda","analisi_faldone"]},"nome":{"type":"string"},"quando":{"type":"string","description":"Quando si usa."},"fatti":{"type":"string","enum":["obbligatori","facoltativi"]},"template":{"type":"boolean","description":"Serve un questionario (`templateId`) alla creazione."},"opzioni":{"type":"object","description":"Le opzioni che questo tipo accetta.","properties":{"qa":{"type":"boolean"},"raccoltaDati":{"type":"boolean"},"giurisprudenza":{"type":"boolean"}}}}},"Cliente":{"type":"object","required":["id","numero","nome","partitaIva","citta"],"properties":{"id":{"type":"string"},"numero":{"type":["integer","null"]},"nome":{"type":"string"},"partitaIva":{"type":["string","null"]},"citta":{"type":["string","null"]}}},"AuditEvent":{"type":"object","description":"Un evento del registro di audit dello studio: chi ha fatto che cosa, su quale entità, col valore prima e dopo (solo i campi cambiati; segreti e costi oscurati, testi lunghi come impronta `{ sha256, length }`). Un evento su un cliente che l'utente della chiave non vede ha `hidden: true` e niente `before`, `after`, `meta`.","required":["id","occurredAt","actor","action","entity","entityId","clientId","before","after","meta","ip","userAgent","hidden"],"properties":{"id":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"actor":{"type":"object","required":["kind","id","label"],"properties":{"kind":{"type":"string","enum":["user","api_key","platform_admin","system"]},"id":{"type":["string","null"],"description":"L'id dell'utente, della chiave o il componente di sistema."},"label":{"type":["string","null"],"description":"L'email o il nome della chiave al momento dell'evento."}}},"action":{"type":"string","enum":["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":{"type":"string","enum":["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":{"type":["string","null"]},"clientId":{"type":["string","null"]},"before":{"description":"Il valore prima (oggetto, o null)."},"after":{"description":"Il valore dopo (oggetto, o null)."},"meta":{"description":"Altri dettagli: canale, origine, righe esportate…"},"ip":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"hidden":{"type":"boolean"}}},"Opzioni":{"type":"object","description":"Assenti = le impostazioni dello studio e dell’utente della chiave.","properties":{"qaLevel":{"type":"string"},"giurisprudenza":{"type":"boolean"},"raccoltaDati":{"type":"boolean"},"comunicazioni":{"type":"string","enum":["spenta","semiautomatica","automatica"]},"archiviAnnidati":{"type":"boolean","description":"Apre anche gli zip dentro lo zip (fino a tre livelli). Default true."},"leaseDeed":{"type":"string","enum":["auto","preliminary","final"],"description":"Affitto di ramo d'azienda: il documento da redigere."},"materiali":{"type":"array","items":{"type":"string"},"description":"I materiali dello studio, del cliente o dell’avvocato da aggiungere a ogni pratica (id)."},"followedPeople":{"description":"Analisi del faldone: chi assiste l'avvocato, come elenco `[{ name, aliases }]` o come testo (una persona per riga, soprannomi dopo il punto e virgola).","oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}}}}}]},"templateOptions":{"type":"object","description":"Assessment: le opzioni del template (come nel modulo dell'app)."},"documentOptions":{"type":"object","description":"I componenti documentali (citazioni, coordinate, segmentazione, audio)."}}}}},"paths":{"/tipi":{"get":{"operationId":"listActTypes","tags":["Clienti e tipi"],"summary":"I tipi di atto e cosa chiedono","description":"Per ogni tipo: il nome, quando si usa, se i fatti sono obbligatori, se serve un questionario e quali opzioni accetta.","responses":{"200":{"description":"{ tipi: TipoAtto[] }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["tipi"],"properties":{"tipi":{"type":"array","items":{"$ref":"#/components/schemas/TipoAtto"}}}},"example":{"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}}]}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/clienti":{"get":{"operationId":"listClients","tags":["Clienti e tipi"],"summary":"I clienti visibili all'utente della chiave","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Ricerca per nome o partita IVA."}],"responses":{"200":{"description":"{ clienti: Cliente[] }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["clienti"],"properties":{"clienti":{"type":"array","items":{"$ref":"#/components/schemas/Cliente"}}}},"example":{"clienti":[{"id":"cli_4hd8s2","numero":12,"nome":"Servicer Beta S.p.A.","partitaIva":"01234567890","citta":"Milano"}]}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/pratiche":{"get":{"operationId":"listPractices","tags":["Pratiche"],"summary":"Le pratiche","parameters":[{"name":"clienteId","in":"query","schema":{"type":"string"},"description":"Solo le pratiche di questo cliente."},{"name":"lottoId","in":"query","schema":{"type":"string"},"description":"Solo le pratiche di questo lotto."},{"name":"stato","in":"query","schema":{"type":"string","enum":["in_coda","in_corso","completata","fallita"]}},{"name":"limite","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Quante pratiche, le più recenti per prime."},{"name":"archived","in":"query","schema":{"type":"string","enum":["true","all"]},"description":"Senza: le pratiche non archiviate, come gli elenchi dell'app (con `lottoId`: tutte le pratiche del lotto). `true`: solo le archiviate. `all`: tutte."}],"responses":{"200":{"description":"{ pratiche: Pratica[] }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["pratiche"],"properties":{"pratiche":{"type":"array","items":{"$ref":"#/components/schemas/Pratica"}}}},"example":{"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"}]}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}},"post":{"operationId":"createPractice","tags":["Pratiche"],"summary":"Apre una pratica (va in coda)","description":"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.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["clienteId","archivio"],"properties":{"clienteId":{"type":"string"},"tipo":{"type":"string","enum":["decreto_ingiuntivo","assessment","escussione_garanzia","insinuazione_passivo","remediation_datatape","affitto_ramo_azienda","analisi_faldone"],"description":"Default decreto_ingiuntivo."},"fatti":{"type":"string","description":"Le note per gli agenti (obbligatorie, tranne per l'assessment e l'analisi del faldone)."},"titolo":{"type":"string"},"templateId":{"type":"string","description":"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":{"type":"string","description":"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":{"type":"string","enum":["auto","preliminary","final"],"description":"Affitto di ramo d'azienda: il documento da redigere. Default auto (dalla proposta economica: rinnovo → definitivo, nuovo → preliminare)."},"followedPeople":{"type":"string","description":"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":{"type":"string"},"giurisprudenza":{"type":"string","enum":["true","false"]},"raccoltaDati":{"type":"string","enum":["true","false"]},"comunicazioni":{"type":"string","enum":["spenta","semiautomatica","automatica"]},"archiviAnnidati":{"type":"string","enum":["true","false"],"description":"Apre anche gli zip dentro lo zip (fino a tre livelli). Default true."},"archivio":{"type":"string","format":"binary","description":"I documenti, in uno .zip (fino a 4 GB)."}}}}}},"responses":{"202":{"description":"{ pratica: Pratica }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["pratica"],"properties":{"pratica":{"$ref":"#/components/schemas/Pratica"}}},"example":{"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"}}}}},"400":{"description":"Richiesta non valida: tipo, fatti, livello di controllo o archivio (.zip nel campo «archivio»)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"L'utente della chiave non è più nello studio, è disattivato, o il suo ruolo (operatore, sola lettura) non consente di creare pratiche","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Cliente o template non trovato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"413":{"description":"Archivio troppo grande","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto, troppe pratiche in coda per lo studio o troppe pratiche aperte da questa chiave nelle ultime 24 ore","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}},"headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/pratiche/{id}":{"get":{"operationId":"getPractice","tags":["Pratiche"],"summary":"Una pratica","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id della pratica."}],"responses":{"200":{"description":"{ pratica: Pratica }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["pratica"],"properties":{"pratica":{"$ref":"#/components/schemas/Pratica"}}},"example":{"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"}}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Pratica non trovata, o non visibile alla chiave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/pratiche/{id}/documento":{"get":{"operationId":"getPracticeDocument","tags":["Pratiche"],"summary":"Il documento prodotto (markdown)","description":"Il testo dell'atto, quando la pratica è completata.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id della pratica."}],"responses":{"200":{"description":"Il documento, in markdown","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"text/markdown":{"schema":{"type":"string"},"example":"# Ricorso per decreto ingiuntivo\n\n…"}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Pratica non trovata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"409":{"description":"Il documento non è ancora pronto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/pratiche/{id}/faldone":{"get":{"operationId":"getPracticeFile","tags":["Pratiche"],"summary":"Il faldone (zip): atto, allegati, deposito, dati","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id della pratica."}],"responses":{"200":{"description":"Il faldone, come allegato (`Content-Disposition: attachment`)","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Pratica non trovata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"409":{"description":"La pratica è ancora in lavorazione","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/pratiche/{id}/documents":{"post":{"operationId":"sendPracticeDocuments","tags":["Documenti e intake"],"summary":"Manda documenti a una pratica già creata","description":"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id della pratica."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"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."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"I documenti: uno o più file nel campo `files` (anche `files[]`). Al massimo 20, 25 MB ciascuno."},"text":{"type":"string","description":"Un testo che accompagna i documenti (da solo, senza file, diventa esso stesso un documento)."}}}}}},"responses":{"200":{"description":"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).","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}},"Idempotent-Replayed":{"description":"`true` quando la risposta è quella di un invio già ricevuto con la stessa Idempotency-Key.","schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"type":"object","required":["arrival","intake"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"},"intake":{"$ref":"#/components/schemas/Intake"}}}}}},"202":{"description":"Ricevuto (`status: received`): l'esito arriva col webhook `intake.*` o con GET /intakes/{id}/arrivals/{arrivalId}","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["arrival","intake"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"},"intake":{"$ref":"#/components/schemas/Intake"}}},"example":{"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"}}}}},"400":{"description":"Nessun file né testo, più di 20 file, `ref` non valido o Idempotency-Key oltre 200 caratteri","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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 }`)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/Errore"}]}}}},"404":{"description":"Pratica non trovato/a, o non visibile alla chiave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key già usata per un altro invio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Un file oltre il limite per file (25 MB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lotti":{"post":{"operationId":"createBatch","tags":["Lotti"],"summary":"Crea un lotto (bozza): un cliente, un tipo, le stesse opzioni per tutte le pratiche","description":"Poi si carica l'archivio (PUT /lotti/{id}/archivio) e si avvia (POST /lotti/{id}/avvia). Alla fine arriva il webhook `lotto.concluso`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clienteId"],"properties":{"clienteId":{"type":"string"},"tipo":{"type":"string","enum":["decreto_ingiuntivo","assessment","escussione_garanzia","insinuazione_passivo","remediation_datatape","affitto_ramo_azienda","analisi_faldone"],"description":"Default decreto_ingiuntivo."},"titolo":{"type":"string"},"fatti":{"type":"string","description":"Le note comuni a tutte le pratiche."},"templateId":{"type":"string"},"practiceTemplateId":{"type":"string","description":"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":{"type":"string","description":"La pratica dello studio (fascicolo) a cui legare le pratiche del lotto."},"opzioni":{"$ref":"#/components/schemas/Opzioni"}}},"example":{"clienteId":"cli_4hd8s2","tipo":"decreto_ingiuntivo","titolo":"Fatture insolute — ottobre 2026","fatti":"Fatture scadute e non pagate; nessuna contestazione."}}}},"responses":{"201":{"description":"{ lotto: Lotto }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["lotto"],"properties":{"lotto":{"$ref":"#/components/schemas/Lotto"}}},"example":{"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"}}}}},"400":{"description":"Richiesta non valida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Cliente o template non trovato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"409":{"description":"Troppi lotti in bozza per questo utente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/lotti/{id}":{"get":{"operationId":"getBatch","tags":["Lotti"],"summary":"Il lotto, i suoi numeri e le sue pratiche","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id del lotto."}],"responses":{"200":{"description":"{ lotto: Lotto & { conteggi, minutiRimanenti }, anteprima, pratiche: Pratica[] }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["lotto","anteprima","pratiche"],"properties":{"lotto":{"allOf":[{"$ref":"#/components/schemas/Lotto"},{"type":"object","required":["conteggi","minutiRimanenti"],"properties":{"conteggi":{"$ref":"#/components/schemas/Conteggi"},"minutiRimanenti":{"type":["integer","null"],"description":"La stima dei minuti che mancano alla fine."}}}]},"anteprima":{"$ref":"#/components/schemas/Anteprima"},"pratiche":{"type":"array","items":{"$ref":"#/components/schemas/Pratica"}}}},"example":{"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"}]}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Lotto non trovato, o non visibile alla chiave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/lotti/{id}/archivio":{"put":{"operationId":"uploadBatchArchive","tags":["Lotti"],"summary":"Carica l'archivio del lotto: uno zip con uno zip (o una cartella) per pratica","description":"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id del lotto."},{"name":"nome","in":"query","schema":{"type":"string"},"description":"Il nome del file, per riconoscerlo. Default `lotto.zip`."}],"requestBody":{"required":true,"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"{ lotto: Lotto, anteprima }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["lotto","anteprima"],"properties":{"lotto":{"$ref":"#/components/schemas/Lotto"},"anteprima":{"$ref":"#/components/schemas/Anteprima"}}}}}},"400":{"description":"Corpo assente o archivio non utilizzabile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Lotto non trovato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"409":{"description":"Il lotto è già avviato: non si cambia più il suo archivio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"413":{"description":"Troppo grande","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"507":{"description":"Spazio su disco insufficiente in questo momento: riprovare più tardi","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/lotti/{id}/avvia":{"post":{"operationId":"startBatch","tags":["Lotti"],"summary":"Avvia il lotto: le pratiche vanno in coda","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id del lotto."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"escludi":{"type":"array","items":{"type":"integer"},"description":"Le voci dell'anteprima (n) da non avviare."},"archiviAnnidati":{"type":"boolean","description":"Cambia la scelta del lotto sugli zip dentro lo zip prima di avviare."}}},"example":{"escludi":[3]}}}},"responses":{"200":{"description":"{ lotto: Lotto }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["lotto"],"properties":{"lotto":{"$ref":"#/components/schemas/Lotto"}}}}}},"400":{"description":"Nessuna pratica da avviare","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Lotto non trovato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"409":{"description":"Già avviato o senza archivio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"413":{"description":"Una pratica oltre il limite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/lotti/{id}/documents":{"post":{"operationId":"sendBatchDocuments","tags":["Documenti e intake"],"summary":"Manda documenti a un lotto già creato","description":"Con `ref` vanno alla pratica del lotto con quel riferimento; senza, il lotto decide (una pratica nuova del lotto).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id del lotto."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"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."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"I documenti: uno o più file nel campo `files` (anche `files[]`). Al massimo 20, 25 MB ciascuno."},"text":{"type":"string","description":"Un testo che accompagna i documenti (da solo, senza file, diventa esso stesso un documento)."},"ref":{"type":"string","pattern":"^[a-zA-Z0-9]{1,32}$","description":"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."}}}}}},"responses":{"200":{"description":"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).","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}},"Idempotent-Replayed":{"description":"`true` quando la risposta è quella di un invio già ricevuto con la stessa Idempotency-Key.","schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"type":"object","required":["arrival","intake"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"},"intake":{"$ref":"#/components/schemas/Intake"}}}}}},"202":{"description":"Ricevuto (`status: received`): l'esito arriva col webhook `intake.*` o con GET /intakes/{id}/arrivals/{arrivalId}","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["arrival","intake"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"},"intake":{"$ref":"#/components/schemas/Intake"}}},"example":{"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"}}}}},"400":{"description":"Nessun file né testo, più di 20 file, `ref` non valido o Idempotency-Key oltre 200 caratteri","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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 }`)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/Errore"}]}}}},"404":{"description":"Lotto non trovato/a, o non visibile alla chiave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key già usata per un altro invio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Un file oltre il limite per file (25 MB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/intakes":{"get":{"operationId":"listIntakes","tags":["Documenti e intake"],"summary":"Gli intake di un cliente, di una pratica o di un lotto","description":"Uno dei tre parametri è obbligatorio. Per i lotti, `jobs` elenca le pratiche del lotto col loro `ref`.","parameters":[{"name":"clientId","in":"query","schema":{"type":"string"}},{"name":"jobId","in":"query","schema":{"type":"string"}},{"name":"batchId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ intakes: Intake[], enabled }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["intakes","enabled"],"properties":{"intakes":{"type":"array","items":{"$ref":"#/components/schemas/Intake"}},"enabled":{"type":"boolean","description":"L'intake è acceso per lo studio."}}},"example":{"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}}}},"400":{"description":"Manca clientId, jobId o batchId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Cliente, pratica o lotto non trovato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/intakes/{id}":{"get":{"operationId":"getIntake","tags":["Documenti e intake"],"summary":"Un intake e i suoi arrivi più recenti","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id dell'intake."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":50},"description":"Quanti arrivi, i più recenti per primi."}],"responses":{"200":{"description":"{ intake, arrivals }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["intake","arrivals"],"properties":{"intake":{"$ref":"#/components/schemas/Intake"},"arrivals":{"type":"array","items":{"$ref":"#/components/schemas/Arrival"}}}},"example":{"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}]}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Non trovato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audit":{"get":{"operationId":"listAuditEvents","tags":["Audit"],"summary":"Il registro di audit dello studio (per il SIEM)","description":"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).","parameters":[{"name":"from","in":"query","schema":{"type":"string"},"description":"Dal (millisecondi o data ISO)."},{"name":"to","in":"query","schema":{"type":"string"},"description":"Al (millisecondi o data ISO)."},{"name":"action","in":"query","schema":{"type":"string","enum":["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"]}},{"name":"entity","in":"query","schema":{"type":"string","enum":["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"]}},{"name":"entityId","in":"query","schema":{"type":"string"}},{"name":"actor","in":"query","schema":{"type":"string"},"description":"L'id, l'email o il nome della chiave di chi ha agito."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"after","in":"query","schema":{"type":"string"},"description":"Il cursore `next` della pagina prima."}],"responses":{"200":{"description":"{ events: AuditEvent[], next }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["events","next"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}},"next":{"type":["string","null"]}}},"example":{"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}}}},"400":{"description":"Filtro o cursore non valido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"La chiave non è di un amministratore dello studio, o l'utente della chiave non è più nello studio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/intakes/{id}/arrivals/{arrivalId}":{"get":{"operationId":"getArrival","tags":["Documenti e intake"],"summary":"Lo stato di un arrivo (per chi non usa i webhook)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"L'id dell'intake."},{"name":"arrivalId","in":"path","required":true,"schema":{"type":"string"},"description":"L'id dell'arrivo."}],"responses":{"200":{"description":"{ arrival }","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["arrival"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"}}},"example":{"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"}}}}},"401":{"description":"Chiave assente, non valida o revocata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"403":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"Non trovato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Oltre 120 richieste al minuto per questa chiave.","headers":{"X-RateLimit-Limit":{"description":"Le richieste ammesse al minuto per questa chiave (120).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Le richieste che restano a questa chiave nel minuto in corso.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"Errore interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"intake.consegnato":{"post":{"summary":"intake.consegnato: i documenti sono entrati nella pratica","tags":["Webhook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","const":"intake.consegnato"},"creatoIl":{"type":"string","format":"date-time"},"dati":{"type":"object","required":["arrival","intake"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"},"intake":{"type":"object","properties":{"id":{"type":"string"},"target":{"type":"string","enum":["job","batch"]},"jobId":{"type":["string","null"]},"batchId":{"type":["string","null"]}}},"pratica":{"$ref":"#/components/schemas/Pratica","description":"La pratica che ha ricevuto (o è nata da) i documenti, se c’è."}}}}}}}},"responses":{"200":{"description":"Qualsiasi 2xx: consegnato. Altrimenti si riprova (dopo 30 s e dopo 5 min)."}}}},"intake.in_attesa":{"post":{"summary":"intake.in_attesa: la pratica è in lavorazione: i documenti entrano appena finisce","tags":["Webhook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","const":"intake.in_attesa"},"creatoIl":{"type":"string","format":"date-time"},"dati":{"type":"object","required":["arrival","intake"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"},"intake":{"type":"object","properties":{"id":{"type":"string"},"target":{"type":"string","enum":["job","batch"]},"jobId":{"type":["string","null"]},"batchId":{"type":["string","null"]}}},"pratica":{"$ref":"#/components/schemas/Pratica","description":"La pratica che ha ricevuto (o è nata da) i documenti, se c’è."}}}}}}}},"responses":{"200":{"description":"Qualsiasi 2xx: consegnato. Altrimenti si riprova (dopo 30 s e dopo 5 min)."}}}},"intake.da_verificare":{"post":{"summary":"intake.da_verificare: una mail da un mittente sconosciuto: l'avvocato approva o rifiuta in app","tags":["Webhook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","const":"intake.da_verificare"},"creatoIl":{"type":"string","format":"date-time"},"dati":{"type":"object","required":["arrival","intake"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"},"intake":{"type":"object","properties":{"id":{"type":"string"},"target":{"type":"string","enum":["job","batch"]},"jobId":{"type":["string","null"]},"batchId":{"type":["string","null"]}}},"pratica":{"$ref":"#/components/schemas/Pratica","description":"La pratica che ha ricevuto (o è nata da) i documenti, se c’è."}}}}}}}},"responses":{"200":{"description":"Qualsiasi 2xx: consegnato. Altrimenti si riprova (dopo 30 s e dopo 5 min)."}}}},"intake.rifiutato":{"post":{"summary":"intake.rifiutato: i documenti non sono stati accettati (motivo in `arrival.reason`)","tags":["Webhook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","const":"intake.rifiutato"},"creatoIl":{"type":"string","format":"date-time"},"dati":{"type":"object","required":["arrival","intake"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"},"intake":{"type":"object","properties":{"id":{"type":"string"},"target":{"type":"string","enum":["job","batch"]},"jobId":{"type":["string","null"]},"batchId":{"type":["string","null"]}}},"pratica":{"$ref":"#/components/schemas/Pratica","description":"La pratica che ha ricevuto (o è nata da) i documenti, se c’è."}}}}}}}},"responses":{"200":{"description":"Qualsiasi 2xx: consegnato. Altrimenti si riprova (dopo 30 s e dopo 5 min)."}}}},"intake.errore":{"post":{"summary":"intake.errore: la consegna non è riuscita (motivo in `arrival.reason`)","tags":["Webhook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","const":"intake.errore"},"creatoIl":{"type":"string","format":"date-time"},"dati":{"type":"object","required":["arrival","intake"],"properties":{"arrival":{"$ref":"#/components/schemas/Arrival"},"intake":{"type":"object","properties":{"id":{"type":"string"},"target":{"type":"string","enum":["job","batch"]},"jobId":{"type":["string","null"]},"batchId":{"type":["string","null"]}}},"pratica":{"$ref":"#/components/schemas/Pratica","description":"La pratica che ha ricevuto (o è nata da) i documenti, se c’è."}}}}}}}},"responses":{"200":{"description":"Qualsiasi 2xx: consegnato. Altrimenti si riprova (dopo 30 s e dopo 5 min)."}}}}},"x-webhook":{"events":{"pratica.completata":{"post":{"summary":"pratica.completata: una pratica creata dalla chiave (fuori da un lotto) è completata","tags":["Webhook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","const":"pratica.completata"},"creatoIl":{"type":"string","format":"date-time"},"dati":{"$ref":"#/components/schemas/Pratica"}}}}}},"responses":{"200":{"description":"Qualsiasi 2xx: consegnato. Altrimenti si riprova (dopo 30 s e dopo 5 min)."}}}},"pratica.fallita":{"post":{"summary":"pratica.fallita: una pratica creata dalla chiave (fuori da un lotto) non è riuscita","tags":["Webhook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","const":"pratica.fallita"},"creatoIl":{"type":"string","format":"date-time"},"dati":{"$ref":"#/components/schemas/Pratica"}}}}}},"responses":{"200":{"description":"Qualsiasi 2xx: consegnato. Altrimenti si riprova (dopo 30 s e dopo 5 min)."}}}},"lotto.concluso":{"post":{"summary":"lotto.concluso: un lotto creato dalla chiave è finito (le sue pratiche non mandano un evento ciascuna)","tags":["Webhook"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","const":"lotto.concluso"},"creatoIl":{"type":"string","format":"date-time"},"dati":{"allOf":[{"$ref":"#/components/schemas/Lotto"},{"type":"object","properties":{"conteggi":{"$ref":"#/components/schemas/Conteggi"}}}]}}}}}},"responses":{"200":{"description":"Qualsiasi 2xx: consegnato. Altrimenti si riprova (dopo 30 s e dopo 5 min)."}}}}},"description":"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."}}