Guida API — collegare il gestionale alla SaaS RENTRI
Aggiornata il 20 novembre 2026. Contratto della SaaS /api/v1. Le pagine pubbliche leggono direttamente questo Markdown; la tabella pubblica delle rotte e le abilitazioni sono ricavate dall’istanza applicativa.
Questa guida descrive l’integrazione disponibile nel software. L’attivazione di invii, sincronizzazioni e onboarding dipende dalla configurazione della singola istanza e dalle autorizzazioni del cliente. Consultare il riepilogo della pagina pubblica o il gestore per l’ambiente richiesto. Una chiave API o una health positiva non attestano un collaudo PROD né autorizzano da sole un invio reale.
1. Cosa fa il servizio
Il gestionale invia richieste HTTPS JSON alla nostra SaaS, che gestisce autenticazione RENTRI, contesti autorizzati, invio e consultazione delle operazioni FIR. Non occorre installare Laravel o una libreria Composer. Qualsiasi linguaggio con un client HTTP può integrare il servizio. Non è ancora distribuito un SDK ufficiale.
Le funzionalità esposte sono: contesti autorizzati, creazione FIR come produttore o primo trasportatore nei casi ammessi, aggiornamento prudenziale dei FIR locali confermati, esito delle operazioni, lettura del FIR e fotografia remota sincronizzata, lettura anagrafiche osservate e webhook facoltativi.
Sono disponibili anche le API di onboarding per collegare un’azienda tramite P12, previa abilitazione. Non sono esposti pagamento, API di firma, presa in carico, accettazione o trasbordo. Download PDF/xFIR e ricerca/importazione selettiva dei FIR visibili sono disponibili con le abilitazioni e i limiti descritti sotto; non esiste un elenco universale di tutti i FIR RENTRI. Le firme e le altre operazioni non esposte si svolgono nei servizi ufficiali RENTRI. Un ruolo assegnato non implica che ogni funzione ufficiale di quel ruolo sia disponibile nella nostra API.
È disponibile nel software anche GET /api/v1/fir, l’elenco dei propri FIR confermati con filtri per emissione, primo trasporto e ultimo cambiamento. Si basa sui dati già salvati nella SaaS: non interroga RENTRI a ogni ricerca e non elenca automaticamente i FIR creati altrove. La disponibilità sul server richiede il rilascio del codice e la preparazione dell’indice da parte del gestore.
Il pannello web clienti è una webapp separata che usa queste stesse API per onboarding, rubriche, FIR, sincronizzazione e documenti. Non richiede di incorporarlo nel gestionale; bozze e autisti abituali gestiti dalla sua interfaccia non sono ulteriori API pubbliche della SaaS. Le funzioni amministrative di emissione chiavi e consultazione dei consumi usano un canale backend riservato, non accessibile con la normale chiave cliente. I conteggi sono informativi, senza limiti commerciali o addebiti automatici; restano i limiti tecnici di frequenza delle API.
2. Cosa riceverete e cosa ci dovete fornire
Il gestore consegna base URL, API key dell'ambiente con scadenza e scope, contesti autorizzati e contatto assistenza. Se si usano webhook, consegna anche un segreto separato di verifica firma.
Prima dell'attivazione occorrono i dati del gestionale/referente, dell'operatore e delle sedi, i site number RENTRI dell'ambiente richiesto, i ruoli autorizzati e la credenziale di interoperabilità appropriata. Il P12 e la sua password vengono acquisiti tramite la procedura di onboarding abilitata oppure tramite provisioning riservato concordato con il gestore: non si inviano nei body delle API FIR. Non servono credenziali personali SPID/CIE o PIN dell'app.
Glossario essenziale: client = gestionale chiamante; operatore = azienda per cui si opera; UL = sua unità locale/sede; contesto = operatore + UL + ruolo autorizzati; operazione = richiesta tecnica da seguire fino all'esito; FIR = formulario identificato dal numero assegnato.
3. Ambienti e autenticazione
| Ambiente | Base URL | Prefisso chiave |
|---|---|---|
| DEMO | https://rentri-demo.lorismenghi.com |
agw_demo_ |
| PROD | https://rentri.lorismenghi.com |
agw_prod_ |
Percorsi relativi a queste basi; non aggiungere un secondo /api/v1. L'ambiente è scelto da URL e chiave, non da un campo JSON/header/query. ID e chiavi di DEMO non vanno riutilizzati in PROD. Gli indirizzi demoapi.rentri.gov.it e api.rentri.gov.it appartengono al servizio upstream: non sono gli indirizzi a cui il gestionale deve chiamare questa API.
Header delle richieste autenticate:
Authorization: Bearer <API_KEY_SAAS>
Accept: application/json
Aggiungere Content-Type: application/json per POST/PATCH. Custodire la chiave lato server in un deposito segreti; non inserirla nel frontend, negli URL, nel repository o nei log. Non seguire redirect inoltrando il Bearer. Il segreto non viene recuperato in chiaro dal database: in caso di perdita o sospetta compromissione contattare il gestore per sostituzione/revoca.
Gli esempi cURL sono illustrativi: API_KEY, OPERATOR_ID, LOCAL_UNIT_ID, OPERATION_ID e FIR_SEGMENT devono essere valorizzati dal vostro ambiente applicativo, non incollando segreti in una chat. BASE_URL è una delle due basi sopra. Gli esempi di invio richiedono prima l'accordo sul collaudo e l'attivazione del servizio.
4. Endpoint e scope
| Metodo e percorso | Scope | Funzione |
|---|---|---|
GET /api/v1/health |
Nessuno | Stato applicativo e gate visibili |
GET /api/v1/contexts |
contexts:read |
Contesti attualmente autorizzati |
POST /api/v1/fir/ricerca-rentri |
fir:read |
Una pagina di FIR visibili in RENTRI alla sede autorizzata |
POST /api/v1/fir/importazioni |
fir:read + fir:import |
Registra un batch esplicito, nessuna creazione FIR |
GET /api/v1/fir/importazioni/{import_id} |
fir:read |
Esiti locali per numero e avanzamento |
GET /api/v1/fir/esterni |
fir:read |
Catalogo locale separato dei FIR importati |
GET /api/v1/fir/esterni/{external_id} |
fir:read |
Fotografia importata in sola lettura |
POST /api/v1/fir/validazione |
fir:write |
Controllo locale di dati e mapping; nessun FIR creato |
POST /api/v1/fir |
fir:write |
Avvia creazione |
POST /api/v1/fir/{numero_fir}/sincronizzazione |
fir:read |
Richiede una lettura accorpata e limitata; non attende RENTRI |
GET /api/v1/fir/{numero_fir}/sincronizzazioni/{sync_id} |
fir:read |
Stato locale della richiesta, senza chiamate remote |
GET /api/v1/fir/{numero_fir}/documenti |
fir:read |
Inventario su richiesta, senza scaricamenti automatici |
GET /api/v1/fir/{numero_fir}/documenti/{tipo} |
fir:read + fir:download |
Download esplicito del documento corrente |
GET /api/v1/fir/{numero_fir}/documenti/copie/{token} |
fir:read + fir:download |
Download protetto di una copia restituita |
POST /api/v1/fir/{numero_fir}/annullamento |
fir:cancel |
Annullamento controllato; gate dedicato, DEMO/PROD con abilitazione distinta |
PATCH /api/v1/fir/{numero_fir} |
fir:write |
Avvia aggiornamento a delta con If-Match |
GET /api/v1/operations?riferimento=… |
fir:read |
Ricerca locale delle operazioni per riferimento, senza polling |
GET /api/v1/operations/{operation_id} |
fir:read |
Esito; se pending può interrogare RENTRI |
GET /api/v1/operations/{operation_id}/fir |
fir:read |
FIR confermato; se pending può interrogare RENTRI |
GET /api/v1/fir |
fir:read |
Elenco locale filtrato e paginato dei propri FIR confermati |
GET /api/v1/fir/{numero_fir} |
fir:read |
Documento locale e ultima osservazione remota, senza nuova lettura RENTRI |
GET /api/v1/contexts/{operator_id}/{local_unit_id}/anagrafica |
anagrafiche:read |
Ultima osservazione anagrafica, senza nuova lettura RENTRI |
Le autorizzazioni dell'API key e quelle sul contesto devono entrambe consentire l'azione. Gli ID di risorse non autorizzate possono risultare 404. Non è previsto un endpoint pubblico per cambiare scope o autorizzazioni.
Health e contesti
curl --silent --show-error "$BASE_URL/api/v1/health"
curl --silent --show-error \
-H "Authorization: Bearer $API_KEY" \
-H 'Accept: application/json' "$BASE_URL/api/v1/contexts"
Esempio schematico di contesti; gli ID abbreviati non sono valori validi da inviare:
{
"request_id": "richiesta-di-esempio",
"data": [
{
"operator": {"id": "op_…", "name": "Azienda Esempio"},
"local_unit": {"id": "ul_…", "code": "SEDE_01"},
"role": "transporter"
}
]
}
Nel body delle mutation i campi diventano contesto.operator_id, contesto.local_unit_id e contesto.ruolo. Usare i valori restituiti, senza ricavarli dal CF o dal site number. Se l'elenco è vuoto, chiedere al gestore di verificare le autorizzazioni.
In PROD la health espone status, rentri_environment, live_sending, demo_gateway_enabled, prod_gateway_enabled, prod_reads_enabled. Un HTTP 200 dimostra che l'applicazione risponde, non che RENTRI abbia accettato un FIR o che tutti i prerequisiti operativi siano pronti. In DEMO i campi prod_* non sono presenti; live_sending=false non esclude traffico DEMO quando il relativo gateway è abilitato.
5. Creare un FIR
Prima di inviare, persistere nel gestionale riferimento univoco, chiave idempotenza e body esatto. Il riferimento è l'identità della richiesta nel gestionale, non il numero FIR. Il numero sarà restituito dopo il successo.
Body top-level obbligatorio:
{
"riferimento": "SPEDIZIONE-UNIVOCA-DEL-GESTIONALE",
"contesto": {
"operator_id": "op_ID_RESTITUITO_DAI_CONTESTI",
"local_unit_id": "ul_ID_RESTITUITO_DAI_CONTESTI",
"ruolo": "transporter"
},
"documento": {
"destinatario": {},
"trasportatori": [],
"rifiuto": {}
}
}
Questo blocco illustra solo la forma e non è un payload valido. Per un modello completo da compilare vedere fir-create.template.json. Contiene segnaposto e non è pronto per invii reali; dati delle aziende, autorizzazioni, EER, quantità e contesto vanno sostituiti con quelli verificati del caso. Non riutilizzare dati DEMO in PROD.
curl --silent --show-error --include \
-X POST "$BASE_URL/api/v1/fir" \
-H "Authorization: Bearer $API_KEY" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
--data-binary @fir-create.json
Non impostare retry automatici del client HTTP su questa chiamata. Il ruolo destination è rifiutato per la creazione iniziale. Il contesto di un trasportatore può riferirsi a un produttore diverso: non cambiare l'operatore esecutore per farlo coincidere artificialmente con il produttore. L'identità dell'esecutore e dei partecipanti viene verificata anche dal mapping/servizio remoto.
Campi del documento per il caso ordinario
Il JSON è tipizzato: numeri e booleani non sono stringhe. Oggetti e array non sono intercambiabili. Campi sconosciuti sono rifiutati; non inviare direttamente un body OpenAPI RENTRI al nostro endpoint.
| Campo | Tipo / indicazioni |
|---|---|
produttore |
Oggetto facoltativo/null nel contratto strutturale; quando presente richiede denominazione e CF. I requisiti operativi dipendono dal caso |
destinatario |
Oggetto obbligatorio con denominazione e CF |
trasportatori |
Array obbligatorio di almeno un oggetto; ciascun elemento richiede denominazione, CF e tipo trasporto |
intermediari |
Array facoltativo; ogni elemento richiede denominazione e CF |
rifiuto |
Oggetto obbligatorio con codice_eer, provenienza, stato_fisico |
trasporto |
Oggetto facoltativo/null: dati di partenza, conducente, targhe e percorso |
annotazioni |
Stringa/null, massimo 10.000 caratteri |
Per i soggetti: denominazione, codice_fiscale (5–20 caratteri), nazione_id (due caratteri), num_iscr_sito oppure sito: {"rentri_site_id":"…"}, numero_iscrizione_albo facoltativo/null. Usare un solo vocabolario sito per soggetto. Per produttore/destinatario privi di sito fornire indirizzo; ulteriori requisiti di autorizzazione e identificazione rimangono dipendenti dal caso. Non ricavare né inventare il site number di una controparte.
Indirizzo: {"citta":{"comune_id":"CODICE_COMUNE"},"indirizzo":"VIA","civico":"NUMERO"}. È supportata anche la forma codice_comune, via, numero, cap: non mescolare le due forme. L'oggetto produttore può avere luogo_produzione (indirizzo/null), detentore (boolean/null) e autorizzazione; destinatario può avere autorizzazione: {"numero":"…","tipo":"…"} e attivita (R1–R13 o D1–D15, oppure null). La legittimità e correttezza dei dati vanno verificate per il caso concreto.
trasportatori[].tipo_trasporto: terrestre, ferroviario, marittimo (minuscoli). Il supporto strutturale del valore non certifica ogni variante di trasporto o ogni ciclo multi-soggetto come già collaudato in PROD.
Campo sotto rifiuto |
Valori / tipo |
|---|---|
codice_eer |
Stringa; fornire il codice pertinente, non una descrizione |
provenienza |
U oppure S |
stato_fisico |
SP, S, FP, L, VS |
quantita |
Oggetto/null: valore numerico tra 0 e 9999999999.9999, unita_misura kg oppure l |
descrizione, caratteristiche_chimico_fisiche |
Stringhe/null |
caratteristiche_pericolo |
Array/null con codici HP01–HP15 |
verificato_in_partenza, trasporto_adr, rinfusa |
Booleani/null |
numero_colli |
Stringa/null |
dati_adr |
Oggetto/null; ammesso non-null solo con trasporto_adr=true. Figli facoltativi/null: numero_onu max 20, classe max 20, note max 500 |
analisi_classificazione |
Oggetto/null; se presente richiede tipo (Analisi o Classificazione) e numero (1–50 caratteri); data facoltativa/null RFC3339, data calendario tra 1980-01-01 e 2050-12-31 |
Sotto trasporto: data_ora_inizio in UTC (2026-11-02T08:30:00Z, esempio), conducente: {"nome":"…","cognome":"…"} (max 50 ciascuno), targa_automezzo/targa_rimorchio stringhe/null, percorso max 250/null e presa_in_carico_rimorchio_precedente boolean/null. Il servizio distingue la validità strutturale dai prerequisiti di firma/partenza: l'accettazione del JSON non certifica che il FIR sia pronto per tutte le fasi successive.
Idempotenza ed esiti
Idempotency-Key è obbligatorio sia su POST sia su PATCH. Generare una chiave opaca univoca per una nuova operazione (ad esempio UUID) e conservarla prima della chiamata. Il servizio verifica anche riferimento, contesto e contenuto: non riutilizzare una chiave per un'altra pratica o un body modificato.
Esempio schematico di risposta 202:
{
"request_id": "richiesta-di-esempio",
"data": {
"operation_id": "opr_…",
"riferimento": "SPEDIZIONE-UNIVOCA-DEL-GESTIONALE",
"kind": "fir_create",
"status": "pending",
"attempt": 1,
"numero_fir": null,
"retry_not_sent_allowed": false,
"status_url": "/api/v1/operations/opr_…",
"fir_url": null
}
}
Conservare operation_id, request_id, Location e Retry-After quando presenti. 202 non significa FIR creato definitivamente.
curl --silent --show-error \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
"$BASE_URL/api/v1/operations/$OPERATION_ID"
Seguire data.status: submitting/pending non conclusi, success riuscito, failed fallito, not_sent non inviato, unknown esito remoto incerto. Il GET di stato restituisce normalmente HTTP 200 anche per stati applicativi non riusciti: non basarsi solo sullo status HTTP. Se pending può fare polling RENTRI e aggiornare il risultato locale; rispettare indicazioni temporali quando presenti, evitare polling serrato e applicare un limite concordato con l'assistenza. Non impostare un GET a ciclo infinito.
Dopo success, recuperare il FIR da /api/v1/operations/{operation_id}/fir oppure usare numero_fir per il GET diretto. Anche se è presente un URL relativo, risolverlo sempre sulla base SaaS configurata, senza inoltrare il Bearer a host arbitrari.
Ritrovare le operazioni per riferimento
Se il gestionale ha perso la risposta della POST, può cercare le operazioni con il riferimento inviato nel body della creazione. Non è l’header Idempotency-Key, anche se negli esempi i due valori possono coincidere. Contratto: OpenAPI ricerca operazioni.
curl -sS --get "$BASE_URL/api/v1/operations" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
--data-urlencode 'riferimento=ORDINE-123' \
--data-urlencode 'limit=20' \
| python3 -m json.tool
Un PATCH che non cambia il documento (no-op) non crea un’operazione aggiuntiva e quindi non aggiunge una riga alla ricerca.
Il riferimento è obbligatorio, massimo 128 caratteri, corrispondenza binaria esatta senza trim o ricerca parziale. Riferimento inesistente → 200 con data: []; riferimento mancante/vuoto → 422 invalid_query. L’elenco include la creazione e le PATCH collegate al FIR che ha quel riferimento, senza cambiare i riferimenti tecnici interni o l’idempotenza esistenti. Se lo stesso riferimento è presente su operatori diversi del client, possono comparire più pratiche: controllare contesto, kind e operation_id, non scegliere automaticamente la prima.
Filtri facoltativi, combinati con AND: kind=fir_create|fir_update|fir_cancel, status=submitting|not_sent|pending|success|failed|unknown, operator_id=op_…, local_unit_id=ul_…. Si usa lo scope esistente fir:read; contesti esecutori ancora autorizzati, revoche e scadenze valgono anche per lo storico. Contesto esplicito incompatibile/non accessibile → 403. Parametri sconosciuti/duplicati/array/vuoti e body GET → 422; query massima 16.384 byte. Nessun filtro per cambiare ambiente.
Risposta: request_id, data, meta: {limit, next_cursor}. Ogni riga ha:
operation_id,riferimentocercato,kind,status,attempt(tentativo attuale, non una riga per ogni tentativo);numero_firdel FIR locale associato, se disponibile;status_url,fir_urlquando disponibili;contestoesecutore (operator_id,local_unit_id,ruolo) e date tecniche UTCcreated_at/updated_at.
success è il successo tecnico di quella richiesta, non una firma o l’accettazione del rifiuto. Su una PATCH failed/unknown può esserci comunque il numero del FIR già esistente: il numero non rende riuscita la PATCH. Pending/unknown/submitting possono non avere alcun numero FIR. retry_not_sent_allowed=true descrive lo stato not_sent, senza ampliare i permessi né eseguire un retry.
La ricerca è solo locale: non chiama RENTRI, non recupera automaticamente un pending, non invia nulla e non crea reservation o nuove pratiche. Il dettaglio già esistente GET /api/v1/operations/{operation_id} può invece interrogare RENTRI se pending. Il dettaglio restituisce il riferimento proprio dell’operazione, che nelle PATCH può essere tecnico; nella lista riferimento è il valore cercato dal gestionale.
Paginazione come per i FIR: limit 1–100, default 50; ripetere stessi filtri/limit con il next_cursor ricevuto fino a NULL. Cursore cifrato valido 24 ore, legato al client e a questa ricerca, non intercambiabile con quello dell’elenco FIR. Ordinamento fisso: operazioni prenotate più recentemente prima, con ID interno decrescente; nessun parametro sort/direction. Non è una fotografia immutabile: esiti o autorizzazioni possono cambiare fra pagine. Nessun totale obbligatorio, nessun dato tecnico upstream o documento completo nella lista.
Recupero corretto: ritrova l’ID → controlla tipo, contesto ed esito → consulta il dettaglio se necessario. Conserva chiave di idempotenza e payload originali. Una lista vuota, un timeout o un esito unknown non autorizzano a reinviare con una nuova chiave: verificare prima il caso, evitando duplicazioni.
6. Leggere il FIR e distinguere le versioni
Il numero FIR va codificato come un singolo segmento URL, per esempio gli spazi diventano %20. Non concatenare il numero grezzo. Nel seguente esempio FIR_SEGMENT è già codificato dal vostro client HTTP.
curl --silent --show-error --include \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
"$BASE_URL/api/v1/fir/$FIR_SEGMENT"
La risposta ha request_id e data, con:
documento,versione,document_hash: la copia locale confermata inviata tramite la SaaS.sync: stato di sincronizzazione dell'operazione locale e riferimenti a eventuali operazioni pending/unknown.rentri.stato: stato disponibile nel percorso locale delle operazioni; non sostituisce la fotografia remota periodica.remoto: ultima osservazione riletta da RENTRI, con stato/versione/revisione/freschezza e dati osservati quando disponibili.readiness: indicazioni locali sui dati mancanti; non attestazione ufficiale di firma o partenza.
ETag, ad esempio "v1", riguarda la versione locale, non remoto.versione. sync.stato=confirmed non significa che il FIR sia stato accettato dal destinatario. Per lo stato osservato leggere remoto.stato e controllarne sempre la freschezza.
remoto.stato_sincronizzazione: never_checked = nessuna osservazione; current = osservazione recente; stale = troppo vecchia; error = ultimo controllo fallito, con eventuali dati precedenti conservati. Campi come stato, versione e revisione possono essere assenti quando mai osservato: gestire questa possibilità. La lettura API restituisce la fotografia già presente e non forza un accesso RENTRI.
Se attivata, la sincronizzazione dei FIR avviene in background: normalmente circa cinque minuti per FIR attivi, un'ora per terminali, più jitter/backoff e limiti di elaborazione. Anagrafiche normalmente ogni sei ore. Non sono SLA né aggiornamenti istantanei; indisponibilità, rate limit, volume e gate possono aumentare la latenza. Sono seguiti i FIR gestiti e persistiti dalla SaaS, non scoperti automaticamente tutti i FIR esistenti nel portale RENTRI.
Riepilogo FIR: firme, conferimento, copia e azioni
Il GET del singolo FIR aggiunge data.riepilogo, mantenendo documento, versione locale, ETag, sync, rentri, remoto e readiness. Contratto: dettaglio FIR, schema del riepilogo. La GET legge soltanto dati salvati: non firma, non modifica e non chiama RENTRI.
| Campo del riepilogo | Cosa indica |
|---|---|
fase |
Codice RENTRI originale, categoria gestionale, descrizione e aperto true/false/NULL. Una fase che cita le firme non prova chi abbia firmato. |
osservazione |
Fonte RENTRI, ultima verifica, never_checked/current/stale/error, coerenza con la versione locale, versioni locale/remota e revisione dell’osservazione. |
firme.produttore e firme.destinatario |
stato presente/non_rilevata/non_disponibile, data firma UTC quando disponibile, fonte dell’evidenza. Nessuna verifica crittografica eseguita da questa GET. |
firme.trasportatori |
Stato aggregato e tratte, ognuna con indice, tipo, inizio compilato e propria firma/data. Tutte presenti → presente; almeno una non rilevata → non_rilevata; altrimenti non_disponibile. |
conferimento |
Esito osservato A = accettato per intero, P = accettato parzialmente, R = respinto; quantità accettata in kg, arrivo e attesa verifica analitica se disponibili. Esito assente resta non_disponibile, quantità assente resta NULL; zero resta zero. Non viene dedotto dal nome della fase. |
conferimenti_successivi |
Accettazioni e firme di eventuali destinazioni successive, separate dal primo destinatario. Indici di posizione, senza associazioni inventate con aziende non riconciliate. |
copia |
La proiezione attuale non attesta disponibilità/restituzione della copia completa. Riporta non_disponibile come informazione sconosciuta; download PDF/xFIR non disponibili via API. Un allegato, tre firme o una fase Accettato non dimostrano la copia disponibile. |
compilazione_locale |
Dati mancanti secondo le regole locali già usate da readiness. ready non certifica firmabilità, partenza o accettazione RENTRI. |
azioni |
Indicazioni, non autorizzazioni: modifica bloccata dai controlli locali oppure da verificare all’invio; firma soltanto negli strumenti ufficiali; annullamento con gate e permesso dedicati, documenti consultabili tramite l’endpoint dedicato, soggetti a configurazione e permessi. |
Le firme rappresentano metadati dell’ultima osservazione: non_rilevata non significa certamente assente quando l’osservazione è vecchia/in errore; non_disponibile non significa firma assente. Una data mancante/non interpretabile resta NULL anche con firma presente. Il destinatario non deve essere cliente della SaaS perché il produttore legga la firma osservata sul proprio FIR.
I motivi di blocco di azioni.modifica possono includere invii disabilitati, osservazione non corrente o non allineata, fase incompatibile, metadati firma, versione/vincoli da riconciliare e operazione locale ancora da risolvere. da_verificare_all_invio non è un permesso preventivo: servono scope fir:write, contesto autorizzato, If-Match, idempotenza e tutti i controlli finali del PATCH. L’osservazione può cambiare dopo la GET. La valutazione della policy è locale al momento della GET, non un lock RENTRI.
Esempio di lettura (numero codificato nel percorso):
curl -sS "$BASE_URL/api/v1/fir/XLPRB%20000017%20ST" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
| python3 -m json.tool
Prima delle firme, il nome della fase può già essere FirmaProduttoreTrasportatoreIniziale mentre le firme sono non_rilevata o non_disponibile. Dopo la firma del produttore, solo il suo metadato deve passare a presente; dopo il conferimento si leggono separatamente esito, quantità e firma del destinatario. Anche dopo accettazione e tre firme, copia e chiusura documentale non vengono presunte: il contratto attuale non fornisce quella prova; il futuro inventario/download sarà uno step separato.
Anche ogni riga dell’elenco FIR contiene un riepilogo compatto con fase, conferimento, copia e indicazioni generali. Date delle firme, tratte e motivi della policy si leggono nel dettaglio; per la freschezza della sintesi usare osservazione già presente sulla riga. La sintesi non carica documenti completi o snapshot per ogni FIR.
Elenco FIR e filtri
Contratto scaricabile: OpenAPI elenco FIR. Stesso Bearer delle altre GET, scope fir:read. Nessun body: parametri nella query string. Sono visibili solo i FIR del client e del contesto esecutore ancora autorizzato, con numero e ultima versione locale confermati. Un operatore condiviso con altri client non rende comuni le pratiche. Una PATCH pending/unknown conserva nella lista l’ultima versione confermata; una creazione senza numero confermato non compare.
Esempio: FIR emessi a novembre, ordinati per emissione:
curl --get "$BASE_URL/api/v1/fir" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
--data-urlencode 'emissione_da=2026-11-01T00:00:00+01:00' \
--data-urlencode 'emissione_a=2026-12-01T00:00:00+01:00' \
--data-urlencode 'sort=emissione' --data-urlencode 'limit=50'
Altri esempi di filtri da passare con --data-urlencode:
| Ricerca | Parametri di esempio |
|---|---|
| Primo trasporto del 2 novembre italiano | inizio_trasporto_da=2026-11-02T00:00:00+01:00, inizio_trasporto_a=2026-11-03T00:00:00+01:00 |
| Cambiati dall’ultimo controllo del gestionale | aggiornamento_da=2026-11-02T08:00:00Z |
| Produttore non ancora firmato nell’osservazione corrente e coerente | firma_produttore=non_rilevata |
| Solo una sede autorizzata | operator_id=op_…, local_unit_id=ul_… (ID completi, non segnaposto) |
| Riferimento preciso | riferimento=ORDINE-123 |
I tre intervalli sono indipendenti e combinati con AND, come tutti gli altri filtri. RFC3339 con offset obbligatorio, fino a 6 decimali; iniziale incluso e finale escluso ([da,a)). Si può fornire un solo estremo; entrambi presenti richiedono da < a. Una data mancante non soddisfa un intervallo. Usare il fuso del gestionale per le mezzanotti, considerando il cambio ora; --data-urlencode preserva il segno + dell’offset.
Altri filtri: numero_fir, stato (fase originale), categoria (preparazione, firme_iniziali, in_corso, conferimento, annullamento_in_corso, annullato, indeterminato), aperto=true|false|unknown, firma_trasportatore e firma_destinatario. Riferimento e numero richiedono corrispondenza esatta, anche per maiuscole/spazi; massimo 128 caratteri. Parametri sconosciuti, duplicati, array, vuoti e body GET sono rifiutati con 422; query massima 16.384 byte.
La risposta contiene request_id, data e meta: {limit, next_cursor}. Ogni elemento riporta numero/riferimento, operatore/UL esecutori, versione locale confermata, tre date e provenienza, fase/categoria/aperto, firme e osservazione. Nessun documento completo o segreto nella lista. Non è previsto il conteggio totale.
data_emissione: data ufficiale osservata, altrimenti NULL; non la creazione nella SaaS.inizio_trasporto: dato del primo trasporto, osservato se compatibile oppure compilato nel documento confermato. Non prova da solo che il mezzo sia partito.ultimo_aggiornamento: conferma locale o rilevazione di una variazione significativa, comprese le firme. Una rilettura identica non lo modifica.osservazione.ultima_verifica: ultima lettura riuscita;aggiornamento_datiènever_checked,current,staleoerror.coerente_con_versione_localeè distinto dalla freschezza: dati coerenti possono comunque essere vecchi.
Le firme espongono l’evidenza dell’ultima osservazione: presente, non_rilevata, non_disponibile. I filtri presente/non_rilevata richiedono dati current e coerenti; non_disponibile include anche dati vecchi, in errore o non coerenti. Pertanto una riga selezionata da firma_produttore=non_disponibile può mostrare una firma storicamente presente: leggere sempre osservazione. Per i trasportatori: tutte le firme osservate presenti → presente; almeno una esplicitamente non rilevata → non_rilevata; altrimenti informazione non disponibile.
aperto può essere NULL (unknown nel filtro). Accettato non significa automaticamente concluso: disponibilità/restituzione della copia e adempimenti sono separati. FirmaProduttoreTrasportatoreIniziale indica una fase, non chi ha firmato. La lista non autorizza modifiche, annullamenti o firme.
Paginazione: limit da 1 a 100 (default 50), sort=emissione|inizio_trasporto|aggiornamento (default aggiornamento), direction=asc|desc (default desc). Date mancanti sempre in fondo; parità risolte stabilmente. Per la pagina successiva ripetere gli stessi filtri, ordinamento e limit, aggiungendo cursor con il valore di meta.next_cursor tramite URL encoding. NULL significa fine. Il cursore è valido 24 ore e non è trasferibile a un altro client o ad altri filtri (422 invalid_cursor). Le revoche vengono ricontrollate a ogni pagina.
Non è una fotografia immutabile tra pagine: aggiornamenti concorrenti possono spostare un FIR, producendo ripetizioni o salti. Per acquisizioni incrementali usare finestre temporali sovrapposte e deduplicare per numero/versione; non considerare la pagina un registro immutabile. 503 search_index_unavailable indica che l’indice deve essere allineato dal gestore; non creare di nuovo i FIR per risolverlo.
Validare prima di creare un FIR
Contratto: OpenAPI validazione preliminare. Il gestionale può controllare lo stesso JSON della creazione (riferimento, contesto, documento) prima di inviarlo. Serve fir:write, senza nuovi permessi. Non serve Idempotency-Key: se presente viene ignorata, senza prenotare il riferimento o consumare l’idempotenza dell’invio futuro.
# payload-fir.json contiene il corpo completo previsto da POST /api/v1/fir.
curl -sS -X POST "$BASE_URL/api/v1/fir/validazione" \
-H "Authorization: Bearer $API_KEY" \
-H 'Accept: application/json' -H 'Content-Type: application/json' \
--data-binary @payload-fir.json | python3 -m json.tool
La risposta contiene data.valido, data.esito, data.controlli, data.errori e data.avvisi. Gli elementi indicano campo, codice, messaggio; ad esempio documento.rifiuto.quantita.valore oppure documento.trasportatori.0. I valori inviati e i nomi di proprietà sconosciute non vengono ripetuti negli errori.
- HTTP 200,
valido: true,esito: "valido": struttura, contesto, metadati del certificato e mapping locale controllati. Gli avvisi possono segnalare dati completabili successivamente, come trasporto o quantità assenti. La creazione parziale può essere ammessa. - HTTP 422,
valido: false,esito: "non_valido": correggere i campi indata.errorie ripetere il controllo. Se si fornisce l’oggettotrasporto, il mapping richiede almeno data/ora iniziale e conducente; ometterlo o impostarlo a null per la creazione parziale. - HTTP 200,
valido: null,esito: "incompleto": il controllo non ha potuto verificare tutto, ad esempio certificato o sede non pronti. Non equivale a payload valido né a errore nei dati: consultarecontrollieavvisi.
Chiave non valida: 401; permesso, contesto o ruolo non autorizzato: 403. Nessuna verifica di aziende non autorizzate. Limite specifico del controllo: 256 KiB, profondità JSON massima 64, massimo 100 errori. Corpo troppo grande: 413; query string non ammesse: 422. Questi errori generali usano error, mentre le diagnosi del payload usano data. Risposte private senza cache.
Il controllo è interamente locale, disponibile anche se gli invii sono disabilitati. Non interroga RENTRI, non apre il materiale privato P12, non firma, non assegna numeri, non crea operazioni né FIR. Rimane il normale aggiornamento del metadato di ultimo utilizzo della chiave API. invii_abilitati_in_configurazione descrive la configurazione dell’istanza, senza cambiarla; non attesta la disponibilità del servizio remoto.
garantisce_accettazione_rentri è sempre false: codifiche correnti, regole di servizio e autorizzazioni ambientali non sono certificate dal controllo. Anche readiness descrive solo i pochi requisiti locali già previsti per conducente e targa: non prova la possibilità di firmare o partire. Il controllo non è una validazione PATCH; l’aggiornamento continua a validare il documento risultante secondo le sue regole.
Dopo aver corretto i dati, il gestionale invia lo stesso file a POST /api/v1/fir con una propria Idempotency-Key. Solo questa seconda chiamata avvia la creazione. L’invio applica nuovamente i controlli: autorizzazioni e prerequisiti possono cambiare fra le due richieste.
Ricercare e importare FIR già presenti in RENTRI
Contratto: OpenAPI ricerca/importazione. Capacità DEMO/PROD con abilitazioni separate. PROD richiede anche opt-in del modulo, letture abilitate e certificato qualificato. Il pilota Flusia usa soltanto DEMO; il collaudo operativo PROD con P12 reale è ancora da eseguire. Non si tratta di un elenco universale: RENTRI restituisce i FIR digitali visibili alla sede autorizzata scelta nel contesto. Non ricerca le copie cartacee tramite i servizi separati di caricamento/conferma. Non accettiamo un codice fiscale o un sito arbitrario per allargare la ricerca.
La ricerca richiede fir:read. L’importazione richiede sia fir:read sia il nuovo fir:import: la vecchia chiave non acquista automaticamente il permesso di importare. Non serve creare un nuovo client o ricaricare il P12 se l’azienda è già collegata: l’amministratore può emettere una nuova chiave dello stesso client con i permessi necessari.
Il flusso è cerca → scegli i numeri → importa → leggi l’esito. Ogni ricerca legge una sola pagina remota; il POST di importazione registra soltanto un lavoro locale. Nessuna chiamata crea, firma, modifica o annulla un FIR su RENTRI.
POST /api/v1/fir/ricerca-rentri, concontesto,filtrifacoltativi,limit1–50 (default 25) ecursorfacoltativo.- Copia
meta.selezionee scegli fino a diecinumero_firrestituiti dalla pagina. POST /api/v1/fir/importazioni, con lo stessocontesto,numeri_fir,selezionee unaIdempotency-Keypropria.- Segui la
Locationrestituita e consultaGET /api/v1/fir/importazioni/{import_id}. La GET non fa nuove letture RENTRI.
Esempio di ricerca: sostituire gli ID con quelli reali ottenuti da /contexts. Le date devono comprendere ora e fuso; vengono normalizzate in UTC.
{
"contesto": {
"operator_id": "op_ID_COMPLETO",
"local_unit_id": "ul_ID_COMPLETO",
"ruolo": "producer"
},
"filtri": {
"data_creazione_da": "2026-10-01T00:00:00Z",
"data_creazione_a": "2026-11-03T23:59:59Z"
},
"limit": 25
}
Salva il corpo in ricerca-fir.json e invialo:
curl -sS -X POST "$BASE_URL/api/v1/fir/ricerca-rentri" \
-H "Authorization: Bearer $API_KEY" \
-H 'Accept: application/json' -H 'Content-Type: application/json' \
--data-binary @ricerca-fir.json | python3 -m json.tool
Le date degli elenchi sono normalizzate in UTC a microsecondi. La fotografia importata conserva la precisione originale RENTRI, anche a sette cifre decimali. Per i filtri usa i campi normalizzati dell’elenco/dettaglio: sono ammesse fino a sei cifre decimali.
I filtri iniziali ammessi sono numero_fir, codice_eer (sei cifre, eventualmente seguite da *), data_creazione_da/a, data_emissione_da/a. Non sono esposti tutti i filtri nativi. data_creazione e data_emissione restano concetti distinti; non si sostituisce la seconda con la prima quando manca. La lista contiene un sottoinsieme dei dati disponibili, non il dettaglio completo.
Per la pagina successiva ripeti il POST con stessi contesto, filtri e limite, aggiungendo cursor uguale a meta.next_cursor. Null significa fine della continuazione disponibile. Se limite_pagine_raggiunto:true, è stato raggiunto il limite di 100 pagine: restringi la ricerca. Ogni cursore e selezione dura 15 minuti ed è legato a client, istanza, contesto e metadati del certificato. Non è una fotografia congelata: una variazione dei dati RENTRI può produrre spostamenti/duplicati tra pagine. Una ricerca interrotta riprende dal cursore valido, senza importazioni implicite.
Il campo di creazione num_iscr_sito del singolo FIR può riferirsi a una sede diversa da quella che ne ha acquisito visibilità: non lo usiamo da solo per concedere accesso. Prima di importare ogni elemento, il worker verifica di nuovo la presenza del numero nella ricerca limitata alla sede e controlla l’identità del soggetto nel ruolo richiesto. In questo primo flusso sono supportati produttore e trasportatori presenti nei dati iniziali; altri casi richiedono verifica dedicata e non vengono abilitati implicitamente. Il dettaglio deve contenere numero coerente, versione remota positiva e dati sufficienti a verificare il ruolo; se mancano, l’elemento non viene acquisito e non si inventano versioni.
Esempio di richiesta di importazione (ID, numero e selezione da sostituire con i propri):
{
"contesto": {
"operator_id": "op_ID_COMPLETO",
"local_unit_id": "ul_ID_COMPLETO",
"ruolo": "producer"
},
"numeri_fir": ["XLPRB 000013 LP"],
"selezione": "TOKEN_RESTITUITO_DALLA_RICERCA"
}
curl -sS -X POST "$BASE_URL/api/v1/fir/importazioni" \
-H "Authorization: Bearer $API_KEY" \
-H 'Idempotency-Key: importazione-gestionale-001' \
-H 'Accept: application/json' -H 'Content-Type: application/json' \
--data-binary @importazione-fir.json | python3 -m json.tool
La risposta 202 indica lavoro registrato, non importazione conclusa. Il worker automatico, pianificato ogni minuto, elabora fino a cinque elementi per esecuzione, dopo i controlli dei FIR esistenti; non è uno SLA. Può attendere se quei controlli hanno già consumato il budget condiviso. Retry-After: 5 guida il polling di stato, non promette completamento entro cinque secondi. Ripetere stessa chiave e stessi numeri normalizzati recupera lo stesso lavoro anche dopo la scadenza della selezione; stessa chiave con richiesta diversa riceve 409. I separatori ammessi nel numero vengono normalizzati. Lo stesso numero duplicato nel batch viene rifiutato.
Lo stato complessivo è pending, completed o completed_with_errors. Ogni elemento può essere:
| Stato | Significato |
|---|---|
queued / running |
In attesa o in elaborazione; non ripetere l’importazione per controllare l’avanzamento |
imported |
Prima fotografia importata |
unchanged / updated |
Fotografia già presente, invariata o aggiornata con versione remota coerente |
already_managed |
Numero già gestito localmente dallo stesso client: nessuna copia o riscrittura, nessun nuovo permesso |
failed / cancelled |
Elemento non importato o lavoro interrotto; non significa FIR annullato |
Una versione remota inferiore, oppure stesso numero/versione con contenuti incoerenti, non sovrascrive l’archivio. Creazioni locali in corso possono rinviare l’importazione finché non sono riconciliate. Un batch scade dopo 24 ore; al massimo sei errori transitori per elemento, con attese crescenti. Revoca della chiave originaria, del grant o variazione del certificato/sede interrompono gli elementi interessati. Emettere una nuova chiave non trasferisce automaticamente un lavoro alla nuova credenziale: consulta l’esito e avvia, se necessario, una nuova richiesta esplicita con nuova idempotenza.
Limiti condivisi tra le chiavi: ammissione ricerca/importazione 20 richieste/minuto per client e 100 per istanza; letture remote FIR 10/minuto per client e 20 per istanza, condivise con sincronizzazione e controlli che usano lo stesso sincronizzatore. Ogni elemento riserva due letture (verifica visibilità + dettaglio), anche se la prima fallisce. Il cooldown upstream è condiviso e non viene abbreviato da un altro lavoro; anche le letture di sincronizzazione soggette a quel budget lo rispettano. Il POST di coda non consuma letture remote. Massimo 100 elementi attivi per client e 1.000 per istanza. Oltre quota: 429 con Retry-After; il worker rinvia. Corpo POST massimo 64 KiB, profondità JSON 32; query sui POST e parametri non previsti sono rifiutati.
Dove si trovano gli importati: in un archivio distinto da GET /api/v1/fir, che continua a elencare i FIR locali confermati creati dalla SaaS. Non inventiamo una create/PATCH o una versione locale per far comparire un documento esterno nello storico delle operazioni.
curl -sS --get "$BASE_URL/api/v1/fir/esterni" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
--data-urlencode "operator_id=$OPERATOR_ID" \
--data-urlencode "local_unit_id=$LOCAL_UNIT_ID" \
--data-urlencode 'ruolo=producer' \
--data-urlencode 'limit=25' | python3 -m json.tool
Il catalogo richiede tutti e tre i campi del contesto; supporta emissione_da/a, creazione_da/a, lettura_da/a inclusivi, limit e cursor. Ordinamento ID crescente, cursore cifrato valido 24 ore, legato a contesto/filtri/limite. Non è intercambiabile con il cursore remoto o con quello dell’elenco FIR locale. La chiave next_cursor si usa ripetendo gli stessi parametri. Le date non disponibili non corrispondono a un filtro di intervallo.
GET /api/v1/fir/esterni/{external_id} restituisce fotografia tipizzata, versione remota reale, revisione della fotografia, provenienza, prima importazione e ultima lettura. Un record appartiene al solo client e al contesto operatore/sede/ruolo che l’ha importato; un altro client con lo stesso operatore deve effettuare la propria ricerca e importazione, senza accedere allo storico SaaS altrui.
Gli importati sono in sola lettura: nessuna modifica, annullamento, firma, download, sincronizzazione periodica o notifica automatica. Il loro dettaglio non attesta un aggiornamento istantaneo: fa fede ultima_lettura. Una nuova importazione esplicita può rileggere il documento. Consultazione dell’archivio e dello stato dei lavori rimangono possibili se il flag di importazione viene disabilitato, purché chiave e contesto siano ancora autorizzati. I vecchi endpoint di mutation non vengono abilitati per gli importati.
7. Aggiornare un FIR
Prima leggere il FIR e il suo ETag. Inviare un nuovo Idempotency-Key, lo stesso contesto autorizzato originario e solo il delta sotto documento. Non inserire riferimento nel PATCH. È disponibile anche il modello PATCH.
{
"contesto": {
"operator_id": "op_ID_RESTITUITO_DAI_CONTESTI",
"local_unit_id": "ul_ID_RESTITUITO_DAI_CONTESTI",
"ruolo": "transporter"
},
"documento": {
"annotazioni": "TESTO_CONCORDATO_DA_SOSTITUIRE"
}
}
curl --silent --show-error --include \
-X PATCH "$BASE_URL/api/v1/fir/$FIR_SEGMENT" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $UPDATE_IDEMPOTENCY_KEY" \
-H "If-Match: $ETAG" --data-binary @fir-patch.json
ETAG deve contenere il valore ricevuto, incluse le virgolette, per esempio "v1". Header assente o * → 428; versione superata → 412. Rileggere prima di proporre un nuovo aggiornamento; non forzare una versione.
Merge: campi omessi rimangono invariati; oggetti sono uniti ricorsivamente; array sostituiscono l'intero array, quindi gli elementi devono essere completi. null è accettato solo nei campi nullable e non è un comando universale di cancellazione; un oggetto vuoto non cancella automaticamente i figli esistenti. Viene validato il documento completo risultante.
L'API non modifica identità del contesto né numero FIR. L'aggiornamento può essere rifiutato anche con ETag corretto se il FIR è in una fase non modificabile, ci sono firme/modifiche esterne, osservazione vecchia/in errore o versioni non riconciliate (remote_reconciliation_required). Non copiare automaticamente il documento remoto dentro il PATCH e non aggirare il rifiuto cambiando chiave. La protezione locale non costituisce un lock remoto contro modifiche concorrenti nell'app ufficiale.
Un delta che non cambia nulla può restituire 200 con il documento e l'ETag, senza nuova operazione. Altrimenti seguire l'operazione di aggiornamento come per la creazione.
Sincronizzazione richiesta dal gestionale
Contratto: OpenAPI sincronizzazione. Questa funzione registra una richiesta locale di lettura, non modifica né firma il FIR. Capacità DEMO/PROD con abilitazioni distinte e sincronizzazione remota attiva; PROD richiede anche letture, opt-in e certificato approvato. Il pilota Flusia resta DEMO. Serve fir:read, già usato per consultare il FIR: non occorre cambiare la chiave se possiede questo scope. Quote e controlli impediscono che il permesso di lettura diventi un accesso remoto illimitato.
# Stesso FIR scelto per la consultazione; spazi codificati automaticamente.
FIR='XLPRB 000013 LP'
FIR_URL="$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FIR")"
# Nessun body richiesto; è ammesso anche un oggetto JSON vuoto {}.
curl -sS -X POST "$BASE_URL/api/v1/fir/$FIR_URL/sincronizzazione" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
| python3 -m json.tool
La risposta contiene sync_id (syn_…), status_url, fir_url, stato, prossimo tentativo e Retry-After. 202 significa richiesta registrata, non dati già aggiornati. Non è una mutation opr_…: non cercarla in /operations.
queued: in attesa dello scheduler, dei limiti o del backoff upstream.running: un worker sta elaborando; una lease scaduta viene recuperata da un worker successivo.completed: lettura riuscita (changed/unchanged) oppure osservazione recente riutilizzata (reused). Non significa firma o chiusura del FIR.failed: scadenza della richiesta (24 ore) o sei tentativi di lettura non riusciti.cancelled: richiedente/contesto non più autorizzati o lavoro interrotto dai controlli. Revoca della chiave originaria annulla il lavoro ancora da completare; una nuova chiave non trasferisce automaticamente una richiesta già accorpata.
Ripetizioni per lo stesso FIR condividono la richiesta attiva (accorpata=true); un risultato corrente può essere riutilizzato senza creare un’altra risorsa. La deduplica è legata al lavoro attivo/all’osservazione recente, non è un’idempotenza perpetua tramite Idempotency-Key. Se l’ultima lettura valida ha meno di 60 secondi, il POST può rispondere direttamente 200 con quel risultato: non ogni POST interroga RENTRI. Un nuovo POST dopo quella finestra può registrare un nuovo controllo.
# Usa sync_id restituito dal POST: questa GET legge soltanto lo stato locale.
SYNC_ID='syn_ID_COMPLETO'
curl -sS "$BASE_URL/api/v1/fir/$FIR_URL/sincronizzazioni/$SYNC_ID" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
| python3 -m json.tool
# Quando completed, consulta la fotografia aggiornata del FIR.
curl -sS "$BASE_URL/api/v1/fir/$FIR_URL" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
| python3 -m json.tool
Rispetta Retry-After; la GET di stato non esegue polling upstream e non avvia worker. Il comando trusted rentri:process-fir-sync-requests --limit=10 è pianificato ogni minuto prima del controllo periodico dei FIR. Se scheduler/cron sono fermi, la richiesta rimane in coda: non c’è promessa di aggiornamento istantaneo. Errori, budget e backoff possono ritardarla ulteriormente.
Limiti condivisi su DB in finestre fisse di 60 secondi: POST 20 per client e 100 per istanza, anche se accorpati; nuove letture di sincronizzazione FIR 10 per client, 20 per istanza e una per FIR. Il budget remoto è condiviso con sincronizzazione periodica, controllo amministrativo e riconciliazione tramite lo stesso sincronizzatore quando le relative capacità sono attive nell’ambiente selezionato. Chiavi aggiuntive non moltiplicano le quote. Un POST oltre quota riceve 429 e Retry-After; il worker oltre budget rimane in attesa senza produrre un falso aggiornamento. Le attese upstream (anche Retry-After) non vengono aggirate dal POST.
Nessun corpo con opzioni force, scelta ambiente o contesto, né query string. Non vengono create versioni FIR fittizie e non cambiano i dati locali confermati da create/PATCH: si aggiorna l’osservazione remota. Una versione remota precedente non sostituisce una più recente.
Le notifiche mantengono lo stesso contratto esistente: una variazione significativa genera un evento durevole, una lettura identica no. Una firma può cambiare anche senza cambiare fase: l’evento invita il gestionale a rileggere il FIR. Il campo notifiche della risorsa mostra se consegna e endpoint sono abilitati e l’eventuale evento della revisione osservata; quell’evento può precedere questa richiesta, non è la promessa di una nuova notifica a ogni POST.
La consegna webhook ha attivazione separata. Non viene abilitata dal POST, né inviata direttamente dal worker di lettura. Se il cliente non ha un endpoint configurato non c’è consegna; se il gate globale è spento, eventuali eventi pending attendono. Riconfigurare/disabilitare l’endpoint annulla le vecchie consegne pending secondo le regole esistenti. Per una richiesta cancellata dopo una revoca non si salva una nuova osservazione non autorizzata.
Consegne duplicate o fuori ordine sono possibili: verificare HMAC sul body originale, deduplicare per ID evento e applicare solo revisioni successive all’ultima gestita per quel FIR. Conservare prima l’evento e rispondere 2xx, poi lavorarlo; se un evento è vecchio/duplicato, confermarne la ricezione senza far retrocedere lo stato. Integrare comunque una riconciliazione tramite GET FIR.
Documenti disponibili e chiusura documentale
Contratto: OpenAPI documenti. Capacità DEMO/PROD con abilitazioni distinte; su PROD servono opt-in del modulo, letture autorizzate e certificato approvato. La disponibilità dell’istanza non attesta il collaudo operativo reale PROD, ancora da eseguire.
# Numero FIR codificato come segmento URL, per esempio XLPRB%20000013%20LP.
curl -sS "$BASE_URL/api/v1/fir/$FIR_SEGMENT/documenti" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
| python3 -m json.tool
Serve fir:read. L’inventario interroga RENTRI per le copie digitali e cartacee restituite, con contesto originale del FIR e filtri su soggetto, sede, ruolo e numero. Una lista vuota completa significa copie non rilevate in quella lettura; errore o paginazione incompleta restituiscono 503. Non scarica PDF, xFIR o copie e non modifica il formulario.
documenti: link per stampa PDF e xFIR corrente.disponibilita=da_verificare_al_downloadnon promette un file già pronto: RENTRI ne verifica l’effettiva disponibilità al download.copie_restituite: copie effettivamente osservate, data caricamento, eventuale esito A/P/R e presa visione del soggetto/ruolo del contesto. I link sono cifrati e durano 10 minuti; restano necessari API key, scope e autorizzazione attuale. Un link scaduto si rinnova rileggendo l’inventario.chiusura_documentale: restituzione osservata distinta dalla presa visione. Non attesta conclusione di tutti gli adempimenti o conservazione a norma. Un’accettazione parziale o un respingimento non diventa un conferimento concluso.
Per scaricare serve anche il nuovo scope fir:download, assegnato esplicitamente. Le chiavi esistenti non cambiano. Le prossime chiavi operative DEMO vanno preparate con fir:cancel secondo l’indicazione concordata; aggiungere fir:download se devono recuperare file, oltre ai normali scope necessari al gestionale.
# Stampa PDF leggibile del FIR: non equivale alla copia restituita.
curl --fail-with-body -sS "$BASE_URL/api/v1/fir/$FIR_SEGMENT/documenti/pdf" \
-H "Authorization: Bearer $API_KEY" -o formulario.pdf
# File xFIR corrente: scaricamento esplicito, byte originali senza riconfezionamento.
curl --fail-with-body -sS "$BASE_URL/api/v1/fir/$FIR_SEGMENT/documenti/xfir" \
-H "Authorization: Bearer $API_KEY" -o formulario.xfir
Il download xFIR può impedire un successivo rollback di firma in RENTRI. Non usarlo come controllo automatico di disponibilità o per un’anteprima. La stampa PDF non dimostra da sola firme valide, restituzione o presa visione. L’xFIR è il contenitore originale restituito da RENTRI; questa API non certifica crittograficamente le firme contenute.
Per una copia restituita usare esattamente copie_restituite[].download_url dell’inventario, sempre con Authorization: il gateway ne ricontrolla numero FIR, soggetto, sede/ruolo e permessi prima di chiedere il file. Non costruire URL upstream o passare identificativi di altre pratiche. La copia digitale restituisce xFIR; la cartacea può essere PDF, PNG o JPEG.
I download restituiscono byte, Content-Disposition: attachment, nome generato dal gateway, Content-Length, X-Content-SHA256 e Cache-Control: no-store, private. L’hash serve per controllare l’integrità dei byte ricevuti, non certifica firme o adempimenti. Il gateway non archivia file, non li estrae e non invia il loro contenuto a log. Per errori il body resta JSON: verificare HTTP e Content-Type prima di aprire il file salvato con curl.
Limiti: PDF fino a 10 MiB, xFIR fino a 3 MiB, copia cartacea fino a 5 MiB; massimo 500 copie per tipo, con lettura completa o errore. Una consultazione/download per client e due simultanei per istanza, condivisi tra tutte le chiavi dello stesso client; se occupati, 429. Non sono quote per minuto. Un budget di 60 secondi è verificato tra le letture: una chiamata già in corso può aggiungere fino a 20 secondi; oltre il budget la risposta è 503, senza inventario parziale. Nessun redirect, retry automatico, Range, risposta condizionale 304 o HEAD che scarichi file. Query string e body GET non ammessi. Un file non disponibile restituisce 404, indisponibilità/risposta non valida 503.
Le operazioni di caricamento/restituzione copia, conferma di presa visione, firma, cambio formato e trasmissione restano negli strumenti ufficiali RENTRI: non sono eseguite da una GET o da un download, né esposte come nuove mutation in questo step.
Annullamento FIR controllato
Contratto: OpenAPI annullamento. Funzione DEMO/PROD disabilitata per default, con opt-in e gate separati. Le mutazioni PROD richiedono letture, gateway/invii abilitati e certificato approvato; il collaudo reale PROD resta distinto e ancora da eseguire. Gli esempi del pilota Flusia operano soltanto in DEMO.
Serve una chiave con fir:cancel, assegnato esplicitamente: fir:write non basta. Per seguire l’esito serve anche fir:read. Nessun permesso viene aggiunto alle chiavi esistenti. Si mantiene il contesto esecutore originale del FIR: produttore o primo trasportatore, corrispondente al titolare della vidimazione osservato. RENTRI verifica definitivamente incarichi, copie già consegnate e trasmissioni per rifiuti pericolosi.
Flusso: leggi FIR/ETag → invia motivo locale, If-Match e Idempotency-Key → conserva operation_id → consulta l’operazione fino alla conferma. Esempio operativo da usare solo dopo accordo sul collaudo: annullare il FIR annulla anche la relativa vidimazione.
curl -sS -X POST "$BASE_URL/api/v1/fir/$FIR_SEGMENT/annullamento" \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "If-Match: $ETAG" \
-H 'Idempotency-Key: annullamento-prova-001' \
--data-binary '{"motivo":"Formulario creato per errore"}' \
| python3 -m json.tool
ETAG include le virgolette ("v2"); FIR_SEGMENT è il numero codificato come segmento URL. motivo richiesto, massimo 1.024 caratteri, conservato soltanto nello storico locale: non è una nota RENTRI. L’endpoint ufficiale attuale annulla-fir non richiede body; note-annullamento è distinto e non viene eseguito automaticamente. Nessuna firma proprietaria o rollback di firme.
La SaaS rilegge il FIR prima della preparazione e dopo la firma tecnica della richiesta HTTP. Cambiamenti di versione, credenziale o autorizzazione bloccano l’invio. La firma tecnica autentica la chiamata, non firma il formulario. Solo la firma del titolare della vidimazione può essere presente; se produttore e trasportatore hanno firmato entrambi, l’invio è bloccato. Metadati mancanti non provano l’assenza di firme: controlli finali e rifiuto RENTRI restano determinanti, anche per cambiamenti concorrenti. Il contratto upstream non espone If-Match o lock remoto per questa richiesta.
Lo stato tecnico dell’operazione è separato da annullamento.stato:
| Stato annullamento | Significato |
|---|---|
| submitting / pending | Registrazione o elaborazione in corso; non conferma Annullato. |
| not_sent | Invio certamente non avvenuto; eventuale blocco_preinvio, nessun retry automatico. |
| unknown | Invio/esito incerto: non cambiare chiave per ripeterlo. |
| rejected | Rifiuto definitivo; conservare lo storico e riconciliare il caso. |
| awaiting_confirmation | Successo tecnico, ma nessuna osservazione di conferma ancora acquisita. |
| awaiting_signature | Osservata FirmaAnnullamento: eventuale firma nei servizi ufficiali. |
| confirmed | Una lettura RENTRI salvata riporta Annullato; confermato_il è l’istante di acquisizione della prova. |
202 non significa Annullato. Anche status=success riguarda l’operazione tecnica: leggere annullamento.stato. La conferma può arrivare dallo scheduler prima del result, o dopo un esito tecnico incerto: i due indicatori rimangono distinti. Non si promuovono le operazioni unknown inventando un successo tecnico. Letture fallite/obsolete non confermano; osservazioni remote precedenti non cancellano una conferma valida. Se il FIR era già annullato, non viene inviato un altro POST; si verifica la conferma per lettura.
Stessi dati/idempotenza recuperano la richiesta senza altro invio; cambiare chiave non aggira pending/unknown. Una sola pratica locale di annullamento per FIR; motivo/versione diversi causano conflitto. X-Retry-Not-Sent: true recupera solo not_sent con stessi dati e versione ancora corrente. Failed/unknown richiedono riconciliazione, non nuova idempotenza o eliminazione dello storico.
Annullamento in corso/incerto/confermato blocca le PATCH. Una PATCH candidate/unknown già registrata blocca invece la nuova reservation di annullamento. Nessuna versione FIR fittizia: numero, documento, versioni e firme precedenti rimangono nello storico. Non è un DELETE della pratica né una revoca dell’accesso all’azienda.
Lo stato compare nei riepiloghi di dettaglio/lista e nella ricerca per riferimento kind=fir_cancel. Le liste rimangono locali. Il dettaglio dell’operazione può leggere status/result e sincronizzare il solo FIR per confermare. Nessun polling delle mutation dall’elenco e nessun reinvio automatico.
8. Anagrafiche
curl --silent --show-error \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json' \
"$BASE_URL/api/v1/contexts/$OPERATOR_ID/$LOCAL_UNIT_ID/anagrafica"
Restituisce data.contesto e data.remoto. La fotografia riguarda l'operatore e la sede già autorizzata: non è una ricerca generale di aziende, Albo, autorizzazioni o tutte le sedi. Non crea nuove UL né modifica permessi o documenti FIR. Gestire never_checked, current, stale, error come per i FIR. L'endpoint è in sola lettura locale.
9. Webhook facoltativo
Comunicate al gestore un URL HTTPS pubblico su porta 443 e se desiderate anche gli avvisi anagrafici. L'attivazione è amministrativa. Non ci sono webhook disponibili automaticamente per il solo fatto di aver creato una API key.
Eventi FIR fir.observed (prima osservazione) e fir.updated (cambiamento osservato). Esempio schematico:
{
"id": "evt_…",
"type": "fir.updated",
"numero_fir": "NUMERO FIR",
"revisione": 2,
"versione_rentri": 4,
"stato_precedente": "STATO_PRECEDENTE",
"stato": "STATO_OSSERVATO",
"rilevato_il": "2026-11-02T08:30:00+00:00",
"fir_url": "/api/v1/fir/NUMERO%20FIR"
}
Eventi anagrafici, se richiesti: anagrafica.observed, anagrafica.updated, con id, operatore_id, unita_locale_id, revisione, rilevato_il, anagrafica_url. Il webhook segnala una nuova osservazione: non include tutti i dettagli né attesta da solo una variazione di stato (possono cambiare altri dati).
Header: X-Webhook-ID, X-Webhook-Timestamp (secondi Unix), X-Webhook-Signature nel formato v1=<hex>. Usare il segreto webhook, non l'API key, per calcolare:
HMAC-SHA256(segreto, timestamp + "." + event_id + "." + raw_body)
Verificare la firma con confronto a tempo costante prima di elaborare il JSON, sui byte originali (non JSON ricodificato). Verificare timestamp con orologio sincronizzato e finestra ragionevole, ad esempio ±5 minuti; verificare anche coerenza tra ID header e id del body. Ogni retry mantiene ID e body ma può avere timestamp/firma nuovi.
Dopo verifica, salvare l'evento in modo durevole e rispondere rapidamente 2xx; elaborare poi in modo idempotente. Deduplicare per ID, usare la revisione per risorsa per gestire eventi fuori ordine e rileggere i dettagli dalla SaaS con la propria API key. Non applicare ciecamente un evento vecchio sullo stato nuovo.
La consegna prevede duplicati e ritentativi; non garantisce una consegna unica o indefinita. Fino a otto tentativi con backoff, poi gestione amministrativa di eventuale replay. Un evento può non arrivare in caso di endpoint disabilitato, assenza configurazione, cambio generazione, revoca autorizzazioni o esaurimento tentativi. Mantenere una rilettura periodica di riconciliazione nel gestionale. Non rispondere 2xx prima di aver salvato durevolmente l'evento.
Niente redirect, endpoint localhost o indirizzi privati. Timeout di consegna limitato: non attendere l'elaborazione completa prima dell'ack. Il segreto webhook viene ruotato alla riconfigurazione: coordinare il cambio con il gestore.
10. Errori, timeout e assistenza
Gli errori applicativi sono JSON con request_id e error.code/error.message; un'infrastruttura intermedia può invece restituire una pagina non JSON. Registrare status HTTP, request ID e risposta sanificata, senza chiavi o dati riservati. Nelle risposte positive di operazione controllare sempre data.status.
| Esito | Comportamento richiesto |
|---|---|
| 401 | Verificare ambiente, chiave, scadenza e revoca; non riprovare in ciclo |
| 403 | Scope/ruolo/autorizzazione insufficienti; chiedere verifica al gestore |
| 404 | Risorsa inesistente o non visibile; controllare ID e contesto |
| 409 | Conflitto/risorsa non pronta/riconciliazione necessaria; distinguere il codice e lo stato operazione |
| 412 | ETag superato: rileggere e rivalutare la modifica |
| 428 | Manca If-Match valido sul PATCH |
| 422 | Payload invalido oppure mutation con stato failed; distinguere errore e data.status |
| 503 | Servizio/gateway/configurazione indisponibile oppure mutation con stato not_sent; non equiparare tutti i 503 a mancato invio certo |
| 429, se restituito | Rispettare Retry-After quando presente; evitare raffiche di richieste |
| Timeout, interruzione o 5xx senza esito certo | Conservare identità e body originali; verificare l'operazione e contattare assistenza, senza creare un nuovo invio |
Un replay idempotente coerente della stessa richiesta non deve essere sostituito con una nuova chiave per superare un errore. Per not_sent, solo dopo verifica esplicita, il servizio prevede il recupero con X-Retry-Not-Sent: true, stessa chiave, stesso body e stessa identità. Non impostare questo header sempre; il server ricontrolla le condizioni. Per unknown non forzare alcun reinvio: il FIR potrebbe già esistere in RENTRI.
Conservare almeno: ambiente, riferimento, chiave idempotenza, body originale in archivio protetto, ID operazione, numero FIR, versione/ETag, esiti e request ID. All'assistenza inviare solo gli identificativi e i dati sanificati necessari: mai API key completa, P12, password o PIN.
11. Checklist prima dell'uso reale
- Ambiente e chiave corretti, scadenza gestita, contesti verificati.
- Scelta del ruolo coerente con l'operatore e il caso FIR.
- Idempotenza persistita prima dell'invio, retry automatici mutation disabilitati.
- Gestiti pending, failed, not_sent, unknown e timeout senza duplicare pratiche.
- Gestiti ETag/412 e blocchi di riconciliazione esterna.
- Distinti documento locale, stato remoto e freschezza dell'osservazione.
- Se usati, webhook firmati, deduplicati, durevoli e con riconciliazione periodica.
- Prova DEMO concordata e conferma separata del gestore prima delle prove reali PROD.
L'integrazione v1 copre il perimetro indicato; non è una promessa di copertura di tutti i servizi RENTRI, di aggiornamento istantaneo, di conservazione a norma o di firma proprietaria.
Onboarding — collegare un’azienda
Gli endpoint di onboarding sono documentati nella guida dedicata e nel contratto OpenAPI. Richiedono scope separati dai FIR e abilitazioni dedicate, disabilitate per default. La pagina pubblica riporta la configurazione dell’istanza visitata. Le chiavi esistenti non acquisiscono automaticamente nuovi permessi.
Rubrica privata delle controparti
Salva le aziende produttrici, trasportatrici, destinatarie e intermediarie abituali per selezionarle quando prepari un FIR. La rubrica è privata per client e operatore: le sedi della stessa azienda la condividono; altri client o altri operatori non la vedono. Serve almeno un contesto producer/transporter attivo sull’operatore. Non serve caricare il P12 della controparte e non le viene assegnato alcun accesso SaaS.
Contratto rubrica. Nuovi scope rubrica:read per lettura/compilazione e rubrica:write per creazione/modifica. Le chiavi già emesse non li acquisiscono automaticamente. Funzione locale DEMO/PROD, con abilitazione distinta per ambiente e opt-in PROD aggiuntivo. Non effettua chiamate RENTRI.
| Metodo e percorso | Scope | Risultato |
|---|---|---|
GET /api/v1/operators/{operator_id}/controparti |
rubrica:read | Elenco privato e paginato |
| POST stesso percorso | rubrica:write | Crea una scheda locale, HTTP 201 |
GET /api/v1/operators/{operator_id}/controparti/{counterparty_id} |
rubrica:read | Scheda, anche disattivata |
| PATCH stesso percorso | rubrica:write | Modifica o disattiva con versione corrente |
GET /api/v1/operators/{operator_id}/controparti/{counterparty_id}/compilazione |
rubrica:read | Frammento da copiare nel nuovo FIR |
Esempio di POST per salvare un trasportatore (dati inventati):
{
"codice": "TRASPORTATORE-001",
"tipo": "transporter",
"etichetta": "Trasportatore abituale",
"dati": {
"denominazione": "Trasporti Esempio Srl",
"codice_fiscale": "99999999999",
"nazione_id": "IT",
"tipo_trasporto": "terrestre",
"numero_iscrizione_albo": "XX/000001"
}
}
La risposta contiene data.id (ctp_…) e data.versione (inizialmente 1). codice è il riferimento stabile del gestionale: massimo80 caratteri, lettere/cifre e . _ : -, inizio alfanumerico. Tipo e codice restano immutabili. tipo può essere transporter, destination o intermediary; la stessa azienda può avere schede diverse per funzione o sede. Non basta il CF per distinguere due impianti destinatari.
I dati usano i campi anagrafici del documento FIR: per transporter quelli di un elemento trasportatori, per destination quelli di destinatario, per intermediary quelli di un elemento intermediari, per producer quelli di produttore. Non sono ammessi dati arbitrari o segreti. Corpo massimo16KiB, testi massimo250 caratteri, denominazione/etichetta massimo150; valgono anche i vincoli più stretti del vocabolario FIR (CF5–20, nazione2 ecc.). Oggetti annidati vuoti o identificativi/indirizzi contraddittori sono rifiutati. Spazi esterni rimossi, CF/nazione/sito in maiuscolo.
Puoi salvare una bozza con la sola denominazione. /compilazione restituisce HTTP200 con utilizzabile:false, motivo dati_incompleti_o_non_validi e frammento null se mancano dati strutturali. Un produttore richiede CF e una sede/indirizzo coerente; un trasportatore richiede anche CF e tipo trasporto; un intermediario CF; un destinatario CF e sede/indirizzo coerente.
Quando utilizzabile:true, frammento_documento contiene ad esempio {"trasportatori":[{…}]}: copia l’elemento nel documento della nuova pratica, preservando eventuali altri trasportatori già selezionati. Per il destinatario copia l’oggetto; per intermediari aggiungi l’elemento alla lista. Gli endpoint FIR non accettano ctp_… al posto dei dati e non caricano automaticamente la rubrica. Completa il resto del documento e invialo prima a POST /api/v1/fir/validazione, poi al normale POST FIR. La compilazione della rubrica verifica soltanto la struttura del frammento: non attesta autorizzazioni, iscrizioni, coerenza con l’operatore esecutore o accettazione RENTRI.
Per modificare una scheda:
{"versione":1,"etichetta":"Alias aggiornato"}
Per disattivarla: {"versione":2,"attiva":false} usando la versione effettivamente restituita dall’ultima modifica. dati, se presente nel PATCH, sostituisce interamente i dati precedenti: non è una modifica dei soli campi trasmessi. Una modifica effettiva incrementa versione e conserva uno storico interno; un PATCH identico con versione corrente non la incrementa. Una versione superata produce409 counterparty_version_conflict: rileggi prima di riprovare. Nessuna DELETE fisica. Una scheda inattiva resta consultabile, ma la compilazione restituisce409 counterparty_inactive; si può riattivare con PATCH e versione corrente.
Codice duplicato →409 counterparty_code_exists; stessa identità tipo/nazione/CF/sede (nome se manca CF) →409 counterparty_identity_exists. Nessuna fusione automatica. La verifica usa dati normalizzati, non certifica che due descrizioni diverse rappresentino davvero aziende diverse. Le schede inattive conservano codice/identità: recuperale e riattivale. Un POST ripetuto non è un replay: dopo un timeout cerca per codice prima di riprovare a creare.
Filtri GET: tipo, attiva=true|false|tutte (default true), codice esatto, q (denominazione/CF/etichetta, sottostringa letterale), limit=1..100 (default25), cursor. Segui meta.next_cursor senza cambiare filtri/limite/operatore/client; scade dopo un’ora. Ordine crescente di inserimento, nessuno snapshot immutabile fra pagine. Massimo5.000 schede per coppia client/operatore, comprese disattivate.
Aggiornare o disattivare la rubrica non cambia alcun FIR esistente: ogni pratica conserva i dati copiati al momento della compilazione. Non vengono importate automaticamente controparti da FIR o rubriche di altri gestionali.