Come faccio scrivere l'integrazione a un agente AI?

Questa API è pensata per essere integrata da Claude Code, Codex, Cursor o qualunque altro strumento tu abbia aperto. Per questo esistono due file, e un pulsante che scrive il prompt al posto tuo.

I due file

File	Che cosa contiene
`/llms.txt`	Un indice breve: che cos'è questo servizio, e una riga per ogni pagina della documentazione. Costa poco scaricarlo e basta per decidere che cosa leggere dopo.
`/llms-full.txt`	Tutto, in un solo download: ogni endpoint, ogni impostazione, la struttura della risposta, ogni codice di esito con il suo numero e l'indicazione se è ritentabile, e poi l'intera guida in formato testo. Circa 100 KB.

Entrambi sono generati dal servizio in esecuzione. Le impostazioni vengono dal modello della richiesta, i numeri degli esiti dal catalogo degli errori, la forma della risposta dal codice che la costruisce. Non possono descrivere una versione dell'API che non esiste, ed è proprio per questo che conviene indicarli a un agente invece di lasciargli dedurre il contratto da un esempio.

Il pulsante

Nella console ogni modello ha un pulsante Integra con l'AI. Scrive un prompt che contiene già l'id del modello, i campi che quel modello legge e un payload della forma giusta — le tre cose che un agente non può trovare da solo — e lo rimanda a /llms-full.txt per tutto il resto.

Il prompt non contiene mai la tua chiave API, ed è voluto. Dice di leggere la chiave dalla variabile d'ambiente DOCONURE_API_KEY. Un prompt viene incollato nella trascrizione di una chat, conservato da chi fa girare il modello e spesso finisce in un file che viene committato: una chiave che arriva in tutti e tre i posti è di fatto pubblicata. Leggerla dall'ambiente è comunque l'integrazione che vorresti avere, quindi non c'è nessun compromesso da fare.

Migrare un'integrazione esistente

Se arrivi da un altro prodotto, il lavoro dell'agente è una traduzione, e l'ordine che la rende sicura è: prima i modelli, poi le chiamate, niente caricato finché non hai letto i report. I modelli Carbone e Docmosis vengono riscritti da una sola chiamata che elenca ogni tag che non è riuscita a convertire: Arrivi da Carbone o Docmosis ha un prompt pronto per questo. Poi chiedi all'agente di sostituire le vecchie chiamate con POST /api/v1/compose/documents/generate con "isTest": true, e di confrontare un PDF di ogni modello con quello che il tuo sistema produce oggi prima di togliere il flag.

Regole per un agente

Se scrivi tu il prompt, queste sono le cinque che contano. Sono quelle che costa poco enunciare e molto sbagliare.

Leggi /llms-full.txt prima di scrivere codice. Non dedurre la forma della richiesta da un esempio. Le chiavi sconosciute in qualsiasi punto del corpo fuori da data vengono rifiutate, non ignorate, quindi un'impostazione inventata ma plausibile fa fallire l'intera chiamata (data è tuo, e ha forma libera).
Leggi la chiave API dall'ambiente (DOCONURE_API_KEY). Non scriverla mai in un file sorgente, in una configurazione committata o in una riga di log.
Decidi in base a code, mai a message. Ogni errore porta un code stabile e un number di quattro cifre; il messaggio è un'indicazione per chi legge un log e può essere riformulato in qualsiasi momento.
Ritenta solo quando il corpo dice "retryable": true. Un TEMPLATE_DATA_MISMATCH ritentato cento volte fallisce cento volte, e ogni tentativo viene addebitato come lavoro svolto.
Mostra output.warnings. Una chiamata può riuscire avendo fatto meno di quanto le era stato chiesto. TEMPLATE_FIELDS_MISSING significa che il PDF è stato prodotto con degli spazi vuoti e indica quali campi; ignorare quell'avviso è il modo in cui un cliente lo scopre dal proprio cliente.

Altre due che riguardano questa API in particolare: la generazione è sincrona, quindi usa un timeout del client di almeno 120 secondi; e invia "responseFormat": "json" dentro settings se vuoi gli id, gli avvisi e il documento in un unico corpo JSON invece dei byte grezzi del PDF con gli identificativi negli header.

Model Context Protocol

Un server MCP ufficiale è previsto e non è ancora stato realizzato, e questa pagina non ne promette uno. Quando esisterà esporrà le operazioni di cui un agente ha davvero bisogno — elencare i modelli, leggere i campi attesi da un modello, validare un payload prima di spenderci un credito, generare un documento, leggere i consumi — e verrà annunciato qui e in /llms.txt.

Fino ad allora, /llms-full.txt più un agente in grado di fare richieste HTTP è l'intera integrazione, e basta: c'è un solo endpoint da imparare e nessun SDK da installare.

Prosegui con: Il primo documento · Esiti e codici di errore · Generare un documento