Integrare il gestionale con FttEl
Invia fatture elettroniche, ricevi i documenti e segui gli esiti SdI dal tuo gestionale, con una chiave API per ogni azienda.
FttEl gestisce il trasporto verso il Sistema di Interscambio, la memorizzazione dei documenti e le notifiche. Il tuo software prepara il file FatturaPA e usa le API REST; non deve implementare un client SOAP verso SdI.
| Pagina | Cosa trovi |
|---|---|
| Questa pagina | Risorse, autenticazione ed endpoint principali. |
| Inviare fatture | XML e firme, risposta di invio, stati ed esiti incerti. |
| Ricevere e consultare | Filtri, paginazione, documenti XML/PDF e importazione storica. |
| Webhook | Configurazione, payload, test e riconciliazione. |
| Ambienti ed errori | Base URL, codici HTTP e limiti delle richieste. |
Il riferimento API interattivo e il documento OpenAPI JSON descrivono rotte, campi e risposte della versione in esecuzione. Questa guida spiega come combinarli. Verifica sempre il contratto dell’ambiente a cui ti colleghi.
I concetti da conoscere#
| Termine | Significato |
|---|---|
| Account | L’azienda titolare delle fatture, identificata dalla propria anagrafica fiscale. |
| Chiave API | Credenziale di un solo account. L’account viene ricavato dalla chiave: non si passa un accountId nelle richieste macchina. |
| Fattura | Record con un id interno, direzione OUTBOUND o INBOUND e stato corrente. |
| Documento | File associato alla fattura: XML, metadati o notifica. Ha un proprio documentId. |
| Notifica SdI | Evento che descrive un esito; è disponibile in notifications[], con il relativo XML Base64. |
| Identificativo SdI | sdiIdentifier è assegnato da SdI; può essere nullo e non sostituisce l’id FttEl. |
Autenticazione#
Ogni chiave API identifica un account attivo e il relativo perimetro di accesso. La credenziale viene restituita in chiaro alla creazione o rotazione; il servizio ne memorizza solo l’impronta. Conserva una chiave distinta per ogni azienda nel backend del gestionale, senza esporla nel browser o nei log.
Le rotte /machine usano l’header x-api-key. Le sessioni della console usano invece un token Bearer JWT. Il token di sessione non sostituisce la chiave nelle API macchina.
Per ruotarla via API usa POST /auth/api-keys/rotate con il JWT dell’account: restituisce { "apiKey": "…" }. La nuova chiave invalida subito la precedente; coordina l’aggiornamento dei servizi che la usano. Un 401 può indicare anche un account disattivato.
Endpoint principali#
I percorsi sono relativi alla base URL dell’ambiente, senza prefisso /api. Tutte le rotte macchina richiedono x-api-key.
| Metodo e percorso | Contratto |
|---|---|
GET /machine/accounts/me | Anagrafica e configurazione dell’account associato alla chiave. |
PATCH /machine/accounts/me | Aggiornamento dell’account, inclusi gli URL dei webhook. |
POST /machine/invoices/outbound | Invio fattura: JSON con filename e xmlBase64; risposta con id e stato. |
GET /machine/invoices | Elenco fatture con filtri e paginazione. |
GET /machine/invoices/{id} | Dettaglio fattura, stato corrente, documenti e notifiche SdI. |
GET /machine/invoices/{id}/documents/{documentId}/xml | XML estratto dal documento, anche se l’originale è una busta CAdES. |
GET /machine/invoices/{id}/documents/{documentId}/pdf | Rappresentazione PDF della fattura. |
POST /machine/invoices/import/inboundPOST /machine/invoices/import/outbound | Importazione storica da ZIP multipart, senza trasmissione a SdI. |
DELETE /machine/invoices/{id}POST /machine/invoices/deletions | Eliminazione singola o multipla delle sole fatture importate. |
Esempio di richiesta autenticata
GET /machine/accounts/me HTTP/1.1
Host: api.sandbox.fttel.com
x-api-key: <API_KEY>Le richieste JSON usano Content-Type: application/json. Schemi completi, campi obbligatori e risposte di ogni endpoint sono nel riferimento API.