ISTANZA PROD

Collegare un’azienda a RENTRI

Come collegare un’azienda al gestionale tramite certificato P12, consultare l’esito e gestire il proprio accesso. La guida operativa è qui sotto.

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

Integrazione API — collegare un’azienda

Aggiornata il 20 novembre 2026. Le API richiedono abilitazioni esplicite sull’istanza e sul client. La pagina pubblica mostra le abilitazioni generali del server; non verifica i permessi di una specifica chiave. Contratto OpenAPI · Guida API FIR.

Prerequisiti

La SaaS abilita il client e rilascia una chiave con gli scope di onboarding richiesti, distinti dal canale management riservato al gestore. Le chiavi FIR esistenti non acquisiscono nuovi poteri. Per nuovi onboarding serve anche il flag dedicato del client; per consultare i propri metadati e auto-rimuoversi bastano client/chiave attivi e lo scope appropriato.

Il gestionale configura la base URL del gateway e la chiave dell’istanza scelta. Non passare ambiente, client, sedi, ruoli o richieste di rinnovo nel body: vengono rifiutati o non costituiscono selettori di deployment. Il servizio deduce azienda e sedi dal P12 e dalle letture RENTRI.

Avvio

POST /api/v1/onboarding, con Authorization: Bearer <API_KEY>, Content-Type: application/json e Idempotency-Key di 8–128 caratteri (A-Z a-z 0-9 . _ : -, primo carattere alfanumerico).

Body JSON con p12_base64 (P12 codificato base64 canonico) e password (stringa esatta, senza rimuovere eventuali spazi). Facoltativo expected_subject, ad esempio IT-12345678901, da confrontare con il certificato. Non inviare file multipart. Massimo 4 MiB di P12, 4096 byte di password e 6 MiB di body.

La risposta 200 contiene request_id, data.id, stato, ID pubblico operatore quando disponibile, contatori, esclusioni aggregate e replayed. Gli stati di successo sono completed e completed_with_exclusions. Header Location indica la risorsa del tentativo. Nessuna approvazione umana ordinaria viene richiesta e un P12 diverso non rinnova il certificato condiviso.

La POST è sincrona. Il 202 indica un tentativo già in corso; non implica la creazione di una nuova coda. Polling e retry non devono diventare un ciclo serrato.

Consultazione e ripetizione

GET /api/v1/onboarding/{onboardingId}, scope onboarding:read: soltanto propri tentativi, con stato e tempi UTC. historical=true significa che il risultato documenta il tentativo e non garantisce che gli accessi siano ancora attivi. Un running con lease scaduto appare abandoned.

Ripetere la stessa richiesta con la stessa Idempotency-Key e lo stesso materiale riconosce il tentativo; occorre comunque ripresentare P12/password per provare il possesso. Identità, certificato o intento differenti sulla stessa chiave producono conflitto. Non usare la GET o il solo fingerprint come prova per un nuovo onboarding.

Su 429/503 rispettare Retry-After, quando presente. Non esiste un retry automatico con segreti conservati: una nuova esecuzione richiede il materiale ripresentato. Dopo un errore di risposta successivo a un commit riuscito, usare idempotenza/consultazione prima di concludere che nulla sia stato salvato.

Accesso, auto-rimozione e rientro

GET /api/v1/operator-accesses/{operatorId}, scope onboarding:read: stato/revisione della propria associazione, finestre temporali e policy di riattivazione. Altri client/associazioni inesistenti danno 404.

DELETE sullo stesso percorso, scope operator-access:revoke: chiude il solo accesso del chiamante e restituisce stato/revisione. Ripetizioni non riaprono o declassano un blocco amministrativo. Non cancella azienda, sedi, certificato globale, storico o accessi degli altri gestionali.

Dopo auto-rimozione, recuperare la revisione corrente e inviare nuova POST con nuova Idempotency-Key, P12/password, reactivate=true ed expected_revision intero. administrative_action_required richiede invece intervento SaaS; non esiste un endpoint del gestionale per sbloccare il blocco. Le finestre temporali non vengono allungate automaticamente.

GET e DELETE sono locali, senza P12, keyring o contatto RENTRI, e restano disponibili con i rispettivi permessi anche se viene tolta la sola abilitazione ai nuovi onboarding.

Limiti ed errori

Cambiare chiave dello stesso client non moltiplica i limiti. GET/DELETE non aspettano il completamento di una POST lunga.

400 richiesta non valida; 401 chiave/client non attivi; 403 scope/abilitazione mancanti; 404 risorsa non propria/inesistente o gate chiuso; 409 conflitto/riattivazione non consentita; 413 dimensione; 415 formato; 422 onboarding non completato; 429 limite locale; 503 servizio temporaneamente non disponibile; 500 errore inatteso. I messaggi sono controllati e non contengono dettagli OpenSSL/SQL/RENTRI.

Usare X-Request-ID per assistenza. Non registrare API key, P12, password, body o dump di errori completi nei log del gestionale. Le letture anagrafiche non sono una promessa di validità futura del certificato o di disponibilità di ogni funzione FIR.

Abilitazione del servizio

Occorrono schema completo, tre gate espliciti per la POST, client abilitato e chiavi con scope dedicati. Il rilascio deve verificare limiti e buffering del web server, proxy fidati, worker HTTP massimo 150 secondi e timeout del proxy coerente con il budget remoto di 120 secondi e gli slot di 180 secondi. L’abilitazione è gestita dal fornitore del servizio: la sola esistenza della rotta non garantisce che l’onboarding sia disponibile sull’istanza.

Pannello e separazione degli ambienti

Il pannello web è un client delle stesse API. Il client SaaS è distinto dall’utente/email del pannello e può essere autorizzato a più operatori, con le relative sedi/ruoli. Due client distinti non condividono automaticamente gli archivi anche se collegano lo stesso P12. Le funzioni operative sono disponibili nel software per DEMO/PROD con abilitazioni separate: il collaudo reale PROD con certificato qualificato resta necessario e non è attestato dalla health. La rotazione del certificato condiviso dello stesso operatore va concordata con il gestore, non avviene automaticamente caricando un P12 diverso.

Configurazione di questa istanza

Nuovi collegamenti azienda tramite P12
Abilitato in configurazione
Consultazione e rimozione del proprio accesso
Abilitato 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 di onboarding

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à
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