Ricevere e consultare le fatture

Sincronizza fatture ricevute e inviate, recupera i file e collega ogni documento ai dati del gestionale.

Ricevere una fattura#

FttEl acquisisce i documenti dai listener SdI e li associa all’account attraverso l’anagrafica fiscale del destinatario. Il gestionale riceve l’evento invoice.received e può recuperare il dettaglio per invoice.id.

Per recuperare eventi persi, consulta anche GET /machine/invoices?direction=INBOUND. Lo stato di una nuova fattura ricevuta è RECEIVED.

Filtri e paginazione#

http

GET /machine/invoices?direction=INBOUND&receivedFrom=2026-10-01T00%3A00%3A00%2B02%3A00&receivedTo=2026-10-20T23%3A59%3A59.999%2B02%3A00&limit=50&offset=0 HTTP/1.1
x-api-key: <API_KEY>

json

{ "items": [], "total": 0, "limit": 50, "offset": 0, "hasMore": false }

I valori dei filtri nella query vanno codificati come parametri URL; nell’esempio %2B rappresenta il segno + del fuso orario. La risposta mostra una pagina vuota. Leggi items e, finché hasMore è vero, incrementa offset del limit. Il valore predefinito è 50, il massimo per le API macchina è 500. I risultati sono ordinati per data documento decrescente.

Filtro	Significato
`direction`, `status`	Direzione e stato, usando gli enum del riferimento API.
`counterpartyVat`, `senderFilename`	Corrispondenza esatta su partita IVA controparte o nome originale.
`search`	Ricerca su numero fattura, nome controparte e partita IVA.
`documentType`, `source`	Tipo FatturaPA, per esempio TD01, e origine del record.
`issuedFrom` / `issuedTo`	Intervallo inclusivo sulla data documento, `issuedAt`.
`sentFrom` / `sentTo`	Intervallo inclusivo su `createdAt`, non sull’istante di conferma SdI.
`receivedFrom` / `receivedTo`	Intervallo inclusivo su `receivedAt`, data di ricezione SdI.

Passa timestamp ISO 8601 con fuso orario; i limiti sono inclusivi. La paginazione a offset non fornisce una fotografia immutabile: durante una sincronizzazione possono arrivare nuovi record. Usa finestre sovrapposte e aggiorna per id. Le date non filtrano per ultima modifica: per gli stati delle fatture già note, combina webhook e rilettura per id.

Leggere XML, notifiche e PDF#

Le risposte macchina includono documents[].xml e notifications[].xml in Base64. Per un documento P7M, il contenuto memorizzato può essere la busta firmata: decodificare Base64 non equivale a estrarre l’XML. Usa la rotta /xml per ottenere l’XML senza busta CAdES.

Seleziona il documentId dal documento di tipo XML_INVOICE della fattura; non usare l’id di una notifica.

http

GET /machine/invoices/{id}/documents/{documentId}/xml HTTP/1.1
x-api-key: <API_KEY>
Accept: application/xml

GET /machine/invoices/{id}/documents/{documentId}/pdf HTTP/1.1
x-api-key: <API_KEY>
Accept: application/pdf

Le risposte sono rispettivamente application/xml e application/pdf. Il PDF è una rappresentazione leggibile del documento; conserva anche il file originale. Le liste includono i payload: scegli pagine contenute per limitare memoria e traffico.

Importare uno storico#

Per caricare fatture già emesse o ricevute, usa le rotte di importazione. Non vengono ritrasmesse a SdI. La direzione dipende dalla rotta scelta, non viene dedotta dall’XML.

http

POST /machine/invoices/import/inbound HTTP/1.1
x-api-key: <API_KEY>
Content-Type: multipart/form-data; boundary=fttel-boundary

--fttel-boundary
Content-Disposition: form-data; name="file"; filename="storico-ricevute.zip"
Content-Type: application/zip

<BYTE_DELL_ARCHIVIO_ZIP>
--fttel-boundary--

Il corpo multipart nell’esempio è schematico: <BYTE_DELL_ARCHIVIO_ZIP> rappresenta il contenuto binario dell’archivio.

Per le emesse usa /machine/invoices/import/outbound. Il multipart deve contenere un solo campo file chiamato file. Il limite è 50 MiB e 400 file fattura per archivio; sono accettati XML e .xml.p7m, mentre i sidecar *_metaDato.xml vengono ignorati. Controlla sempre imported, skipped e failed nella risposta: un archivio può avere esiti parziali.

I duplicati storici vengono saltati in base a direzione, tipo documento, controparte, numero e data. I record importati hanno source: HISTORICAL_IMPORT. Solo questi record sono eliminabili con DELETE /machine/invoices/{id} (risposta 204) o POST /machine/invoices/deletions con { "invoiceIds": ["…"] }. L’eliminazione rimuove anche i documenti associati; nella richiesta multipla controlla i conteggi deleted e skipped.