En Italia, la facturación electrónica es obligatoria, está regulada por la Agenzia delle Entrate y es exigible por ley desde enero de 2019. Toda factura, B2B y B2C, se intercambia a través del SDI (Sistema di Interscambio) en formato XML FatturaPA y debe conservarse a largo plazo mediante archivado certificado (conservazione a norma).
E-INVOICE IT gestiona ese intercambio por ti. Envías los datos de la factura a través de la Unified API; fiskaly genera el XML FatturaPA, lo transmite al SDI, hace el seguimiento del resultado y conserva la factura durante los 10 años exigidos por ley.
fiskaly emite la Factura estándar (Fattura ordinaria, TD01) y la Nota de crédito (Nota di credito, TD04), que juntas cubren la facturación ordinaria y las correcciones. El tipo de documento no lo estableces tú: se deriva de la operación de la Unified API que llamas. La Factura simplificada (Fattura semplificata, TD07) está en la hoja de ruta.
Tipos de documento fuera del alcance actual
Las facturas de anticipo (TD02), las facturas diferidas (TD24, TD25) y las facturas a administraciones públicas (B2G, la variante FatturaPA FPA12) no se emiten. recipients[].type acepta BUSINESS y CONSUMER.
Esta página cubre los requisitos específicos para Italia que complementan la Guía de integración general paso a paso para dar de alta un Taxpayer en la facturación electrónica.
fiskaly gestiona ambas direcciones del intercambio con el SDI, y las dos funcionan de forma diferente:
Envío — B2B y B2C
fiskaly genera la FatturaPA y la envía al SDI, que la valida y la reenvía al destinatario de forma asíncrona. No se requiere registro en la red. Los destinatarios empresa y los consumidores requieren campos distintos.
Recepción — solo B2B
Opcional, y se habilita por Taxpayer. Requiere un registro único para recibir las facturas de tus proveedores.
Además del intercambio en ambas direcciones, fiskaly archiva automáticamente cada factura que envías y recibes. Esto supone la conservación certificada a largo plazo (conservazione a norma) durante los 10 años exigidos por ley, sin ninguna configuración por tu parte.
Si ya tienes una integración de SIGN IT, no empiezas desde cero — amplías tu Taxpayer existente con los datos de registro adicionales y pones en servicio un System E_INVOICE_SERVICE. Consulta E-INVOICE IT para clientes de SIGN IT para ver todos los pasos.
Requisitos previos
Sección titulada «Requisitos previos»Estos requisitos se aplican a cualquier Taxpayer que des de alta para la facturación electrónica en Italia, ya sea que envíes, recibas o hagas ambas cosas. Asegúrate de tener disponible la siguiente información del Taxpayer antes de continuar.
E-INVOICE IT admite actualmente Taxpayers de tipo COMPANY. Dar de alta un Taxpayer INDIVIDUAL — un autónomo o empresario individual que emite con su propio codice fiscale en lugar de un NIF de empresa — llegará próximamente.
Datos de registro específicos para Italia — enviados en content.fiscalization.registration:
company_id— Numero Registro Imprese (número del Registro Mercantil)office— código de provincia de la Camera di Commercio que emitió el número REA, p. ej.MI,RMentry— número REA (6 o 7 dígitos)legal_form— forma jurídica de la entidad (p. ej.LIMITED_LIABILITY_COMPANY,JOINT_STOCK_COMPANY)capital— capital social registrado en EUR (p. ej."10000.00")shareholder_status—SOLE_SHAREHOLDERoMULTIPLE_SHAREHOLDERSliquidation_status—IN_LIQUIDATIONoNOT_IN_LIQUIDATIONtax_regime— opcional,ORDINARY(predeterminado) oFLAT_RATE_SCHEME(Regime Forfettario)
Campos estándar del Taxpayer — parte del propio Taxpayer (compartidos con SIGN IT si lo utiliza):
content.name— denominación legal registrada de la empresa o del individuocontent.address— dirección legal registradacontent.address.region— Provincia (código de provincia, p. ej.MI,RM); obligatorio en el Taxpayer y validado al poner en servicio
Para la facturación electrónica en Italia, content.fiscalization.registration y content.address.region (Provincia) son campos obligatorios en el Taxpayer. Se validan al poner en servicio el System E_INVOICE_SERVICE — la puesta en servicio falla si faltan. Asegúrate de que ambos campos estén establecidos o actualizados en el Taxpayer de antemano.
Envío de facturas electrónicas: requisitos del destinatario
Sección titulada «Envío de facturas electrónicas: requisitos del destinatario»Para enviar una factura electrónica, indica su destinatario y sus datos de enrutamiento directamente en el Record de la factura. Cuando crees la factura (TRANSACTION::INVOICE) con createRecord, en el System E_INVOICE_SERVICE o, si el Taxpayer también usa SIGN IT, en su FISCAL_DEVICE, añade el destinatario a su array recipients. Los campos que debes rellenar dependen de a quién facturas:
Destinatarios empresa (B2B)
Se enrutan mediante el código de destinatario SDI. Las empresas en el extranjero se comunican con XXXXXXX.
Destinatarios consumidores (B2C)
Los residentes en Italia se identifican por el codice fiscale; los consumidores en el extranjero, por un identificador extranjero.
Todo destinatario lleva invoicing.type = SDI. Lo que cambia entre los tres casos es la identificación, el código de destinatario y si interviene o no una PEC:
| Empresa | Consumidor en Italia | Consumidor en el extranjero | |
|---|---|---|---|
type | BUSINESS | CONSUMER | CONSUMER |
identification | VAT — validado | TAX — codice fiscale, validado | cualquier tipo; sin validar |
invoicing.destination_code | el código de 7 caracteres del destinatario, o "0000000"; en el extranjero "XXXXXXX" | "0000000" | "XXXXXXX" |
invoicing.pec | obligatoria con "0000000" | opcional | no se utiliza |
address.region | obligatoria cuando la dirección está en Italia | obligatoria | no obligatoria |
name | nombre de la empresa | gender, forename, surname | gender, forename, surname |
- El código de 7 caracteres que te haya facilitado el destinatario (p. ej.
ABC1234): solo letras mayúsculas y dígitos. "0000000": el destinatario no tiene buzón SDI, como los consumidores residentes en Italia y las empresas sin código SDI."XXXXXXX": el destinatario está en el extranjero (empresa o consumidor).
Destinatarios empresa (B2B)
Sección titulada «Destinatarios empresa (B2B)»Cada destinatario empresa es de tipo BUSINESS con el bloque invoicing cumplimentado, como explica la integración general paso a paso. Además de los datos estándar que requiere toda factura electrónica (nombre del destinatario, dirección, identificación fiscal, líneas de factura, etc.), Italia añade los campos de enrutamiento SDI indicados arriba.
Los valores que toman destination_code y pec dependen del destinatario:
| Escenario | destination_code | pec |
|---|---|---|
| El destinatario tiene un buzón SDI registrado | su código de 7 caracteres (p. ej. ABC1234) | opcional |
| El destinatario no está registrado en el SDI | "0000000" | obligatorio |
| El destinatario es una empresa fuera de Italia | "XXXXXXX" | no se usa |
Una pec es una dirección de Posta Elettronica Certificata, el correo electrónico certificado de Italia. Es obligatoria para un destinatario empresa con "0000000". Envíe siempre la pec junto con destination_code: "0000000": fiskaly incluye la PEC en la FatturaPA como PECDestinatario, por lo que nunca tiene que rellenar ese elemento usted mismo.
recipients[].address.region (la Provincia del destinatario) no está marcada como obligatoria en el esquema compartido de la Unified API, pero Italia la exige siempre que la dirección esté en Italia. Si falta, no se devuelve una respuesta de error: el registro vuelve como COMPLETED con una entrada ERROR en logs y sin used_in, y no se crea ninguna factura. Envíala en dos letras mayúsculas, por ejemplo RM. Otras formas, como IT-RM, rm o Roma, se aceptan pero no se incluyen en la factura.
Destinatarios empresa fuera de Italia
Sección titulada «Destinatarios empresa fuera de Italia»Una factura a una empresa en el extranjero se comunica al SDI, pero no se entrega a través de él. Envíela con destination_code: "XXXXXXX" y el número de IVA extranjero del destinatario:
| Campo | Valor |
|---|---|
recipients[].identification | VAT: el número de IVA extranjero del destinatario |
recipients[].address.country | el país del destinatario como código ISO 3166-1 alfa-2 (no IT) |
recipients[].address.code | el código postal real del destinatario. fiskaly escribe "00000" en la FatturaPA, que solo admite códigos postales italianos; la copia en PDF muestra el real |
recipients[].invoicing.destination_code | "XXXXXXX" |
region no es obligatorio y pec no se usa. Una empresa establecida en Italia sigue siempre el flujo nacional descrito arriba.
El SDI no tiene ningún canal para llegar a una empresa en el extranjero: "XXXXXXX" solo comunica la factura. Envíe al destinatario su copia (por ejemplo, por correo electrónico o Peppol) por separado, fuera del SDI. La comprobación del número de IVA extranjero en VIES le corresponde a usted; fiskaly no lo comprueba allí.
Destinatarios consumidores (B2C)
Sección titulada «Destinatarios consumidores (B2C)»La ley italiana prohíbe emitir facturas electrónicas a través del Sistema de Intercambio (SDI) por servicios sanitarios prestados a consumidores finales (personas físicas). Por tanto, estas facturas no deben emitirse con E-INVOICE IT. Te recomendamos consultar con tu asesor fiscal si la prohibición se aplica a tus facturas.
Cuando tu cliente es un particular y no una empresa, establece recipients[].type en CONSUMER. La factura circula por el SDI como documento FatturaPA (TD01), igual que una factura B2B.
Los consumidores normalmente no tienen buzón SDI, así que el enrutamiento funciona de otra manera. Cómo identifiques al consumidor depende de si reside en Italia:
- Residente en Italia — se identifica por su codice fiscale y se enruta con el código de destinatario
"0000000". - Fuera de Italia — no existe codice fiscale, por lo que un identificador extranjero ocupa su lugar y la factura se enruta con
"XXXXXXX".
Además de los campos de la tabla anterior, un destinatario consumidor lleva siempre name.gender, name.forename y name.surname, junto con su dirección.
Consumidores residentes en Italia
Sección titulada «Consumidores residentes en Italia»Envía el codice fiscale como identificación de tipo TAX (16 caracteres), el domicilio de residencia incluida la region (Provincia) en dos letras mayúsculas, por ejemplo RM, y el código de destinatario "0000000". La pec es opcional.
Para un consumidor residente en Italia la identificación es obligatoria, debe ser de tipo TAX y el codice fiscale se comprueba al crear el registro. Si falta o tiene un formato incorrecto, no se devuelve una respuesta de error: el registro vuelve como COMPLETED con una entrada ERROR en logs y sin used_in, y no se crea ninguna factura. Comprueba siempre logs y used_in antes de dar una factura por emitida. El SDI lo valida de nuevo contra el registro tributario, por lo que un código bien formado pero desconocido se rechaza en esa fase.
Consumidores fuera de Italia
Sección titulada «Consumidores fuera de Italia»Un consumidor que no reside en Italia no tiene codice fiscale, así que envía en su lugar un identificador extranjero, normalmente un número fiscal o de IVA extranjero.
| Campo | Valor |
|---|---|
recipients[].identification | obligatoria; VAT, TAX, PASSPORT, DOCUMENT u OTHER, según el identificador del que dispongas |
recipients[].address.country | el país del consumidor como código ISO 3166-1 alfa-2 |
recipients[].address.code | el código postal real del destinatario. fiskaly escribe "00000" en la FatturaPA, que solo admite códigos postales italianos; la copia en PDF muestra el real |
recipients[].invoicing.destination_code | "XXXXXXX" |
El identificador viaja al SDI como IdCodice; ni fiskaly ni el SDI comprueban su validez en cuanto el país de la dirección no es Italia. La region no es obligatoria para una dirección no italiana.
"XXXXXXX" indica al SDI que se solicita el despacho pero que la entrega a través del sistema de intercambio no procede: el SDI no tiene ningún canal para llegar a un destinatario en el extranjero. Envía al consumidor su copia de la factura (PDF o equivalente) por separado, fuera del SDI.
gender lo exige la Unified API, no el SDI: la factura FatturaPA no incluye ese campo. Envía DIVERSE cuando no tengas el dato.
Para un consumidor residente en Italia, el SDI deposita la factura original en su área reservada en el portal de la AdE (Fatture e Corrispettivi).
Una nota de crédito para una factura a un consumidor sigue los mismos pasos que para una factura a una empresa: una INTENTION::TRANSACTION y, a continuación, una TRANSACTION::CORRECTION que hace referencia a la factura original.
Cuando el cliente necesita una factura en lugar de un documento commerciale
Sección titulada «Cuando el cliente necesita una factura en lugar de un documento commerciale»Italia declara los dos documentos por canales separados —el documento commerciale por los corrispettivi, la factura por el SDI— y nada los vincula automáticamente.
Recoge la petición antes de cerrar la venta. Cuando el cliente te indique que necesita una fattura, emite una TRANSACTION::INVOICE en lugar de una TRANSACTION::RECEIPT. Preguntar «¿necesitas factura?» como parte del cobro es el flujo que fiskaly admite de principio a fin hoy, tanto si el cliente lo pide antes como durante la venta.
Gestión de las respuestas del SDI
Sección titulada «Gestión de las respuestas del SDI»A diferencia de una llamada de API síncrona, el resultado del SDI es asíncrono. Tras crear la factura (TRANSACTION::INVOICE) con createRecord, consulta periódicamente el Record E_INVOICE::TRANSMISSION para saber si el SDI la ha aceptado. No existe ningún webhook.
Los resultados del SDI suelen llegar en pocos minutos, pero el SDI puede tardar hasta 5 días en devolver un rechazo, así que sigue consultando hasta que el Record alcance mode=FINISHED. Mientras el estado sea ACCEPTED y el modo PROCESSING, consulta aproximadamente cada 15 segundos.
Si la factura se transmite, los tres Records alcanzan su estado final de forma conjunta:
| Record | Estado final |
|---|---|
E_INVOICE::TRANSMISSION | COMPLETED o FAILED, mode=FINISHED |
TRANSACTION::INVOICE | COMPLETED o FAILED, mode=FINISHED |
INTENTION::TRANSACTION | COMPLETED o FAILED, mode=FINISHED |
En caso de fallo, lee logs[].message: un fallo antes de que la factura llegue al SDI se registra en el Record TRANSACTION::INVOICE, y un rechazo del SDI en el Record E_INVOICE::TRANSMISSION, desde donde también se copia en los logs de los Records TRANSACTION::INVOICE e INTENTION::TRANSACTION. Para más detalles, consulta How to check the status of an e-invoice en nuestra página de Soporte.
Leer el resultado
Sección titulada «Leer el resultado»state te indica en qué punto está una factura y logs[] te indica por qué. Léelos juntos y actúa según lo que encuentres:
| Qué ves | Qué significa | Qué hacer |
|---|---|---|
4xx de createRecord, ningún Record creado | El payload se rechazó. No se creó nada y no se envió nada. | Corrige el payload y reinténtalo en el mismo INTENTION::TRANSACTION. |
state=ACCEPTED | Todavía en curso. | Consulta el Record E_INVOICE::TRANSMISSION aproximadamente cada 15 segundos hasta mode=FINISHED. Los resultados suelen llegar en cuestión de minutos; un rechazo puede tardar hasta 5 días. |
state=FAILED | Finalizada, y la factura no es legalmente válida. O se detuvo camino al SDI o el SDI la rechazó con NS. | Lee logs[].message para conocer el motivo, corrige los datos e inicia una nueva cadena — consulta Fallos y reenvío. |
state=COMPLETED con una entrada ERROR en logs[] | Algo salió mal por el camino sin detener la factura. | Lee logs[].message antes de dar la factura por enviada. |
state=COMPLETED, sin entradas ERROR | El SDI aceptó la factura. | Nada más. |
Cada entrada de logs[] es un ERROR o un WARNING. Un WARNING es informativo y nunca bloquea una factura — recibes uno cuando algo de tu payload se ajustó o no cuadraba, por ejemplo si enviaste varios pagos pendientes y solo se usó el primero, o si los totales de IVA de tu payload difieren de los totales calculados a partir de las líneas de la factura.
No significa que el destinatario la haya recibido. El SDI notifica como éxito tanto la entrega (RC) como la no entrega (MC, que sigue siendo legalmente válida), y la API no distingue entre ambos casos.
Dónde se manifiestan los fallos de validación
Sección titulada «Dónde se manifiestan los fallos de validación»No todo rechazo parece un rechazo. Los datos de la factura se comprueban en tres puntos distintos, y cada uno falla de una forma diferente:
| Dónde falla | Ejemplo | Qué ves |
|---|---|---|
| Restricciones de esquema | identification.number fuera de AlphaNumerical28; document.number fuera de ^[0-9A-Z_/\-\.]{1,20}$ | 400 de createRecord. No se crea nada. |
| Validación de campo | Un codice fiscale con formato incorrecto o dígito de control erróneo; un recipients[].address.region ausente | createRecord funciona. El Record se cierra en COMPLETED / FINISHED, pero content.used_in está ausente y no se transmite nada. El motivo aparece únicamente como entrada de content.logs con severidad ERROR. |
| Aguas abajo | El SDI rechaza la factura con NS, o la transmisión falla camino al SDI | createRecord funciona y la cadena pasa después a FAILED. FAILED cubre cualquier transmisión fallida, no solo un NS — el motivo está en logs[].message. |
La fila central es la que sorprende a los integradores: un Record COMPLETED / FINISHED sin factura detrás es idéntico a uno correcto si lees state y te detienes ahí. Lee siempre content.logs en busca de entradas ERROR y comprueba que content.used_in está presente antes de dar una factura por emitida.
Fallos y reenvío
Sección titulada «Fallos y reenvío»Si el SDI devuelve NS (Notifica di Scarto), la factura es legalmente inexistente:
- Lee
logs[].messagepara obtener el motivo de rechazo del SDI. Está en el RecordE_INVOICE::TRANSMISSIONy también se copia en loslogsde los RecordsTRANSACTION::INVOICEeINTENTION::TRANSACTION - Crea una nueva
INTENTION::TRANSACTIONy una nuevaTRANSACTION::INVOICEcon los datos corregidos - Con el rechazo
NSempieza un nuevo plazo de 5 días. Dentro de ese plazo puedes reenviar la factura con el mismodocument.number, como Records nuevos con una nueva clave de idempotencia. - La cadena fallida permanece
FAILEDde forma permanente — se conserva con fines de auditoría
Cada reenvío inicia una nueva cadena de transacción — UAPI la trata como un envío completamente nuevo.
Recepción de facturas electrónicas
Sección titulada «Recepción de facturas electrónicas»Un System E_INVOICE_SERVICE puede tanto enviar como recibir facturas electrónicas. La recepción es opcional — un Taxpayer que solo envía puede omitir esta sección.
Intervienen dos cosas separadas e independientes:
- Disponibilidad para recibir — fiskaly la configura automáticamente cuando pones en servicio el System.
- Registro del código de destinatario SDI (manual, realizado por ti) — en tu portal de la Agenzia delle Entrate (AdE), establece el código de destinatario SDI de fiskaly
JKKZDGRcomo el destino SDI de tu empresa, de modo que el SDI enrute tus facturas entrantes a fiskaly.
La respuesta de la puesta en servicio muestra compliance.state como TRANSMISSION_ONLY. Luego pasa a TRANSMISSION_RECEPTION automáticamente una vez que se completa el registro del Taxpayer — lo cual normalmente ocurre, independientemente de si ha realizado el registro en la AdE o de si tiene previsto recibir.
TRANSMISSION_RECEPTION significa que el System puede recibir, pero no que las facturas entrantes se entreguen realmente al Taxpayer. Esa entrega requiere el registro en la AdE: mientras este no se complete, el Taxpayer no recibe ninguna factura, aunque el System esté listo. Puedes completar el registro en la AdE en cualquier momento — por ejemplo, para habilitar la recepción en un Taxpayer que anteriormente estaba configurado solo para enviar.
Llama a retrieveSystem en cualquier momento para leer el compliance.state actual, que refleja únicamente la disponibilidad — no el registro en la AdE:
TRANSMISSION_RECEPTION— fiskaly ha configurado el System para recibir.TRANSMISSION_ONLY— esa configuración no se ha completado.
Si retrieveSystem sigue devolviendo compliance.state = TRANSMISSION_ONLY tras la puesta en servicio, el registro del Taxpayer no se completó. Trátalo como una transición bloqueada y ponte en contacto con el soporte de fiskaly en dev-support@fiskaly.com con el VAT ID del Taxpayer para que podamos investigar.
No hay nada adicional que configurar para el enrutamiento: fiskaly asocia automáticamente cada factura entrante al Taxpayer correcto mediante su tax ID — razón por la cual cada tax ID debe pertenecer a un único Taxpayer registrado. No necesitas configurar ni almacenar un código de enrutamiento aparte.
Cuando llega una factura
Sección titulada «Cuando llega una factura»Cuando se te envía una factura a través del SDI, fiskaly la recibe automáticamente:
- la entrega entrante se procesa automáticamente por nuestra parte
- se crea un Record de recepción para la factura
- el XML firmado, el PDF y los metadatos se almacenan asociados al Record
- las entregas duplicadas se deduplican
En la práctica, la primera factura que te llega de esta forma es también tu confirmación de que la recepción está configurada correctamente.
Recuperar las facturas recibidas
Sección titulada «Recuperar las facturas recibidas»Cada factura dirigida a tu Taxpayer se recibe, valida y almacena automáticamente como Record — no existe ningún webhook, por lo que debes consultar la API para detectar las nuevas:
- Llama a
listRecordsy filtra porE_INVOICE::RECEPTION. - Para cada Record nuevo, llama a
retrieveRecordconcompliance-artifactpara obtener el XML firmado.
listRecords devuelve los Records más recientes (limit es 10 por defecto, del más reciente al más antiguo), así que lleve un registro de los que ya ha procesado.
E-INVOICE IT comparte su Taxpayer con SIGN IT, por lo que las credenciales de Fisconline son necesarias aunque solo utilices E-INVOICE IT. Así funciona hoy; dejará de ser necesario cuando esté disponible la versión completa de SIGN IT.
Las credenciales solo tienen que ser válidas en dos momentos: cuando se pone en servicio el Taxpayer y cada vez que pasa de SUSPENDED de nuevo a OPERATIVE. Crear una factura (TRANSACTION::INVOICE) no las comprueba, así que unas credenciales caducadas no interrumpen la facturación diaria.
Vuelven a importar la próxima vez que necesites ese paso SUSPENDED → OPERATIVE por otro motivo —por ejemplo, al actualizar la dirección del Taxpayer—, ya que la reactivación falla si las credenciales han caducado. La contraseña caduca cada 90 días, así que comprueba que sigue siendo válida antes de hacer ese tipo de actualización.
Consulta Credenciales de Fisconline para saber cómo obtenerlas y renovarlas.
Archivado
Sección titulada «Archivado»La ley italiana exige que las facturas electrónicas se conserven a largo plazo mediante archivado digital certificado (conservazione a norma): deben conservarse durante al menos 10 años y almacenarse de modo que permanezcan inmutables, auténticas y fácilmente recuperables, con firmas digitales y sellos de tiempo (marca temporale). Conservar tu propia copia del XML no es suficiente — fiskaly se encarga de ello por ti.
Para Italia, el archivado es automático y siempre está activo: cada factura que envías y cada factura que recibes a través del SDI se conserva legalmente, sin configuración adicional ni llamada a la API por tu parte. Solo depende del tax ID italiano del Taxpayer, que ya forma parte del alta. Cada factura conservada obtiene un recibo de conservación como prueba de la conservazione a norma, adjuntado automáticamente en cuanto está listo — no se requiere nada por tu parte. En lugar de un plazo fijo, usa state y mode del Record para saber si el recibo se ha asentado; consulta Cuándo están disponibles los artefactos más abajo.
Recupera los artefactos de una factura electrónica desde su Record con retrieveRecord, seleccionando el artefacto mediante un parámetro de consulta:
compliance-artifact— el documento legalmente vinculante. Para Italia, el XML FatturaPA validado por el SDI.archive-artifact— el recibo de conservación que atestigua la conservación legal (conservazione a norma), devuelto como XML firmado.
Ambos artefactos se devuelven dentro de la respuesta JSON del Record, como un objeto con type y data:
"compliance": { "artifact": { "type": "application/xml", "data": "<base64>" }}Para Italia, type es siempre application/xml — no existe una respuesta XML sin procesar independiente ni una variante en PDF de ninguno de los dos artefactos. La cabecera Accept no tiene ningún efecto sobre esto.
Cuándo están disponibles los artefactos
Sección titulada «Cuándo están disponibles los artefactos»compliance-artifact y archive-artifact no existen durante toda la vida de un Record. Ninguno se produce al crear el Record: ambos se escriben una vez que la transmisión se completa, es decir, una vez que el SDI ha respondido, lo que puede tardar hasta 5 días. Ambos quedan fijados en el mismo momento, porque el paso de archivado se ejecuta antes de que cambie el estado del Record.
De ahí sale una regla basada únicamente en el estado, sin nada que cronometrar:
| Estado del Record | Qué indica sobre los artefactos |
|---|---|
state: ACCEPTED, mode: PROCESSING | No es terminal. Los artefactos pueden faltar todavía, y que falten significa aún no: siguen en camino. |
state: COMPLETED / FAILED / REJECTED, mode: FINISHED | Terminal. Lo que haya es todo lo que va a haber; un artefacto ausente ya no aparecerá. |
Pedir un artefacto que todavía no existe devuelve 200 con el Record sin más: ningún error y ninguna señal de «aún no está listo». Decide a partir del state y el mode del Record si un artefacto ausente significa aún no o nunca, y no a partir de la respuesta a la petición del artefacto.
El recibo de conservación pertenece al Record E_INVOICE::TRANSMISSION y no a la TRANSACTION::INVOICE. Toma content.used_in.id del Record de la factura y, a continuación:
GET /records/{transmissionId}?archive-artifactEl recibo se devuelve codificado en Base64 en content.compliance.archive.data. Las facturas que envías y las que recibes tienen cada una su propio recibo. Mientras el artefacto no esté disponible, el campo está ausente de la respuesta en lugar de presente y vacío.
file-artifact devuelve el sobre firmado del Record tal como se envió: un envoltorio genérico que se usa para todos los tipos de Record, fijado en el momento de crear el Record y sin relación con la generación de la FatturaPA. Es XML bien formado, pero no es la FatturaPA y no debe registrarse como la factura. Para la FatturaPA, usa compliance-artifact.
Ni el recibo de conservación ni file-artifact son una representación de la factura. Para obtener una versión legible por personas, descarga el paquete de archivos de la transmisión — un ZIP con el XML FatturaPA (el documento jurídicamente vinculante), una representación en PDF de la factura en italiano y un JSON de metadatos — desde su propio endpoint:
GET /files/{transmissionId}.zipEn el entorno de test el archivado se ejecuta de principio a fin, pero el resultado no tiene validez legal — es solo para pruebas de integración. Únicamente las facturas procesadas en live se certifican como legalmente conservadas.
En una factura pendiente de pago (payments[].type = OUTSTANDING), el objeto instruction es opcional. Sin él, la factura se acepta y se transmite, pero la forma de pago figura como transferencia bancaria sin ningún dato de la cuenta, así que tu cliente recibe una factura electrónica sin IBAN al que pagar.
Si la factura debe pagarse por transferencia bancaria, envía instruction.type = CREDIT_TRANSFER con:
account: tu IBANname: el titular de la cuenta, es decir, tú como emisor de la facturapayment_service_provider: el código BIC/SWIFT de tu banco (no se acepta el nombre del banco)
Para ver un ejemplo completo y la variante con domiciliación bancaria, consulta Cómo representar los pagos en una factura.
Impuesto de timbre (imposta di bollo)
Sección titulada «Impuesto de timbre (imposta di bollo)»La legislación italiana exige un impuesto de timbre (imposta di bollo) de 2,00 € en las facturas cuyas líneas exentas de IVA superen en conjunto los 77,47 €. fiskaly lo aplica automáticamente: cuando el total de las líneas exentas de IVA correspondientes supera ese umbral, el impuesto de timbre se añade a la FatturaPA transmitida.
No existe ningún campo para el impuesto de timbre ni en la solicitud ni en la respuesta: no hay nada que establecer al crear la factura y no se devuelve nada en el Record. El único lugar donde aparece el valor aplicado es el elemento DatiBollo del XML FatturaPA, que puedes leer desde el documento transmitido:
GET /records/{transmissionId}?compliance-artifactEl XML llega codificado en Base64, así que descodifícalo antes de buscar DatiBollo.
Espera dos avisos de descuadre en los totales
Sección titulada «Espera dos avisos de descuadre en los totales»Los 2,00 € se añaden después de calcular los totales de la factura, de modo que en toda factura que supera el umbral los totales transmitidos son 2,00 € más altos que los que enviaste. El Record registra esa diferencia como dos entradas WARNING en content.logs, por ejemplo:
provided '100.00000000', calculated '102.00'Es lo esperado, y es la señal de que se aplicó el impuesto de timbre. Sigue enviando tus totales sin el impuesto: no existe ninguna carga útil que incluya el impuesto de timbre y a la vez evite los avisos. Trata estas dos entradas WARNING como informativas y no hagas fallar tu integración por ellas.
Abonar una factura emitida fuera de fiskaly
Sección titulada «Abonar una factura emitida fuera de fiskaly»En Italia el tipo de documento es el identificador de tipo FatturaPA: una CORRECTION se transmite como TD04 (Nota di credito) y una INVOICE como TD01 (Fattura). Como el tipo se deriva de la operación, una factura que fiskaly no transmitió no puede abonarse: emitir una TD01 que referencie la factura anterior incrementa el importe adeudado en lugar de cancelarlo. Consulta Nota de crédito para la regla general.
Para casos puntuales, el SdI concede acceso al portal a todos los comerciantes, donde puede emitirse una nota de crédito manualmente. Esto no escala y no es un patrón de integración: trátalo como alternativa de migración y mantén disponible el sistema de facturación electrónica anterior hasta que todo lo emitido en él esté liquidado o abonado.