ISTANZA PROD

Il gestionale, collegato a RENTRI.

Un servizio API per creare e aggiornare i formulari dei rifiuti, seguirne lo stato e leggere le firme osservate in RENTRI. Il gestionale invia i dati via HTTPS e può ricevere notifiche sugli aggiornamenti.

Le firme si eseguono negli strumenti ufficiali RENTRI. Non sono attualmente esposti annullamento FIR, accettazione, download PDF/xFIR o conservazione a norma.

Configurazione di questa istanza

Validazione preliminare locale (senza invio)
Abilitato in configurazione
Ricerca RENTRI e importazione FIR esterni
Disabilitato in configurazione
Creazione e modifica FIR verso RENTRI
Disabilitato in configurazione
Annullamento FIR verso RENTRI
Disabilitato in configurazione
Nuovi collegamenti azienda tramite P12
Abilitato in configurazione
Documenti FIR PDF/xFIR e copie restituite
Disabilitato in configurazione
Sincronizzazione FIR richiesta dal gestionale
Disabilitato in configurazione
Controllo periodico dei FIR
Disabilitato in configurazione
Consegna notifiche al gestionale
Disabilitato in configurazione

Queste indicazioni descrivono le abilitazioni del server, non un collaudo in tempo reale. Chiave, permessi, collegamento azienda e disponibilità RENTRI vengono verificati sulle richieste. La configurazione generale non abilita automaticamente un singolo cliente.

API presenti nel software

I percorsi e gli scope di questa tabella sono ricavati dalle rotte dell’applicazione. Sono inclusi anche PATCH e DELETE; la disponibilità dipende dalla configurazione e dalle autorizzazioni.

MetodoPercorsoScopeDisponibilità
GET/api/v1/healthNessunoPubblico
GET/api/v1/contextscontexts:readRichiede chiave e autorizzazione
GET/api/v1/operators/{operatorId}/contropartirubrica:readRubrica disabilitata
POST/api/v1/operators/{operatorId}/contropartirubrica:writeRubrica disabilitata
GET/api/v1/operators/{operatorId}/controparti/{counterpartyId}/compilazionerubrica:readRubrica disabilitata
GET/api/v1/operators/{operatorId}/controparti/{counterpartyId}rubrica:readRubrica disabilitata
PATCH/api/v1/operators/{operatorId}/controparti/{counterpartyId}rubrica:writeRubrica disabilitata
GET/api/v1/contexts/{operatorId}/{localUnitId}/anagraficaanagrafiche:readRichiede chiave e autorizzazione
GET/api/v1/fir/{numeroFir}/documentifir:readDocumenti disabilitati
GET/api/v1/fir/{numeroFir}/documenti/copie/{token}fir:read + fir:downloadDocumenti disabilitati
GET/api/v1/fir/{numeroFir}/documenti/{tipo}fir:read + fir:downloadDocumenti disabilitati
POST/api/v1/fir/{numeroFir}/sincronizzazionefir:readSincronizzazione su richiesta disabilitata
GET/api/v1/fir/{numeroFir}/sincronizzazioni/{syncId}fir:readRichiede chiave e autorizzazione
POST/api/v1/fir/ricerca-rentrifir:readRicerca/importazione disabilitata
POST/api/v1/fir/importazionifir:read + fir:importRicerca/importazione disabilitata
GET/api/v1/fir/importazioni/{importId}fir:readStato locale; nessuna lettura RENTRI
GET/api/v1/fir/esternifir:readArchivio locale in sola lettura
GET/api/v1/fir/esterni/{externalId}fir:readArchivio locale in sola lettura
POST/api/v1/fir/validazionefir:writeControllo locale; richiede fir:write
GET/api/v1/firfir:readRichiede chiave e autorizzazione
POST/api/v1/firfir:writeInvio disabilitato
POST/api/v1/fir/{numeroFir}/annullamentofir:cancelAnnullamento disabilitato
PATCH/api/v1/fir/{numeroFir}fir:writeInvio disabilitato
GET/api/v1/fir/{numeroFir}fir:readRichiede chiave e autorizzazione
GET/api/v1/operationsfir:readRichiede chiave e autorizzazione
GET/api/v1/operations/{operationId}fir:readRichiede chiave e autorizzazione
GET/api/v1/operations/{operationId}/firfir:readRichiede chiave e autorizzazione
POST/api/v1/onboardingonboarding:writeAbilitato; richiede autorizzazione
GET/api/v1/onboarding/{onboardingId}onboarding:readAbilitato; richiede autorizzazione
GET/api/v1/operator-accesses/{operatorId}onboarding:readAbilitato; richiede autorizzazione
DELETE/api/v1/operator-accesses/{operatorId}operator-access:revokeAbilitato; richiede autorizzazione

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:

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:

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.

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.

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.

  1. POST /api/v1/fir/ricerca-rentri, con contesto, filtri facoltativi, limit 1–50 (default 25) e cursor facoltativo.
  2. Copia meta.selezione e scegli fino a dieci numero_fir restituiti dalla pagina.
  3. POST /api/v1/fir/importazioni, con lo stesso contesto, numeri_fir, selezione e una Idempotency-Key propria.
  4. Segui la Location restituita e consulta GET /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.

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.

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

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.