Section navigation

E-INVOICE IT para clientes de SIGN IT

Está viendo la documentación de la versión de API 2026-06-01.

Esta guía está dirigida a clientes que ya tienen una integración de SIGN IT en funcionamiento y desean añadir la facturación electrónica italiana (E-INVOICE IT) — B2B y B2C —. Ambos productos se ejecutan sobre la misma API Unificada y comparten la misma estructura de Taxpayer y Location — solo se necesitan unas pocas adiciones.

¿Vienes de SIGN IT 2024-10-31 o 2025-08-12? Expande y lee esto primero.

Después de la versión 2025-08-12, algunos recursos se renombraron y se añadieron otros nuevos para la facturación electrónica. Los endpoints actualizados pueden llamarse con los mismos {id} que ya se están usando.

Hasta la versión 2025-08-12	Después de la versión 2025-08-12	Notas
`ASSET` — `/assets`	`ORGANIZATION` — `/organizations`	Solo un cambio de nombre — mismo ID que antes.
`ENTITY` (`COMPANY`/`INDIVIDUAL`) — `/entities`	`TAXPAYER` (`COMPANY`/`INDIVIDUAL`) — `/taxpayers`	Solo un cambio de nombre — mismo ID que antes.
`ENTITY` (`LOCATION`) — `/entities`	`LOCATION` — `/locations`	Este recurso ahora se divide en dos tipos: `HEAD_OFFICE` location: se crea automáticamente al crear el Taxpayer — mismo ID que su antiguo `ENTITY` (`COMPANY`/`INDIVIDUAL`) `BRANCH` location: cualquier ubicación adicional. Se crea mediante el endpoint `createLocation` — mismo ID que su antiguo `ENTITY` (`LOCATION`)
`SYSTEM` que hace referencia a `entity: {id}`	`SYSTEM` que hace referencia a `location: {id}`	Solo un cambio de nombre — mismo ID que antes.

Antes de continuar:

Actualice su encabezado X-Api-Version a la versión indicada en el banner de arriba.
Asegúrese de usar las URL base correctas: test.api.fiskaly.com (TEST) y live.api.fiskaly.com (LIVE).
Añada fiscalization.credentials.tax_id_number a sus credenciales FISCONLINE, si aún no está presente. Este campo no era obligatorio en 2024-10-31, era opcional en 2025-08-12, pero ahora es obligatorio.
Revise los principales cambios en la estructura de los records en la documentación de la API — esta FAQ puede ayudarle. Para cualquier duda, contacte con dev-support@fiskaly.com.

Lo que su integración de SIGN IT ya cubre

Antes de empezar, se asume que su integración cuenta con:

Un Taxpayer creado con datos de fiscalización italianos (fiscalization.type=IT, tax_id_number, vat_id_number, credentials)
El Taxpayer puesto en servicio (state=COMMISSIONED, mode=OPERATIVE)
Un System FISCAL_DEVICE puesto en servicio en la Location del Taxpayer
Un flujo INTENTION::TRANSACTION → TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION para recibos fiscales

Nada de esto necesita cambiar. Los pasos siguientes añaden E-INVOICE IT junto a la configuración existente.

Ampliar los datos de alta del Taxpayer

Añada los datos adicionales de registro de la empresa que exige la facturación electrónica italiana.

Poner en servicio un System adicional

Habilite el servicio de facturación electrónica en su Taxpayer — esto cubre el envío y, opcionalmente, la recepción.

Añadir el flujo de transacción de factura

Comience a emitir facturas y notas de crédito a empresas y consumidores.

Paso 1 — Ampliar los datos de alta del Taxpayer

📘Por ahora solo Taxpayers COMPANY

E-INVOICE IT admite actualmente Taxpayers de tipo COMPANY. Un Taxpayer INDIVIDUAL — un autónomo o empresario individual que emite con su propio codice fiscale en lugar de un NIF de empresa — todavía no puede ampliarse; la compatibilidad llegará próximamente.

Se requieren dos adiciones en el Taxpayer que SIGN IT por sí solo no necesita:

address.region — el código de Provincia italiano (p. ej. MI, RM) es obligatorio para el envío al SDI. Si aún no está establecido en el Taxpayer, añádalo mediante updateTaxpayer.
fiscalization.registration — un nuevo bloque que contiene los datos del Registro delle Imprese / REA.

Campos obligatorios: company_id, office, entry, legal_form, capital, shareholder_status, liquidation_status. El campo tax_regime toma ORDINARY de forma predeterminada si no lo indica.

El SDI exige este bloque para las entidades registradas, así que proporciónelo al dar de alta el Taxpayer.

Ejemplo: PATCH /taxpayers/{taxpayer_id}

{
  "content": {
    "address": {
      "region": "MI"
    },
    "fiscalization": {
      "type": "IT",
      "registration": {
        "company_id": "MI12345678901234567",
        "office": "MI",
        "entry": "1234567",
        "legal_form": "LIMITED_LIABILITY_COMPANY",
        "capital": "10000.00",
        "shareholder_status": "MULTIPLE_SHAREHOLDERS",
        "liquidation_status": "NOT_IN_LIQUIDATION"
      }
    }
  }
}

💡¿Ya tiene address.region?

Si su integración de SIGN IT ya recopila la dirección completa del Taxpayer, incluida region, no es necesario ningún cambio aquí — solo añada el bloque registration.

Paso 2 — Poner en servicio un System adicional

El System E_INVOICE_SERVICE es el único System que crea y transmite facturas electrónicas (y recibe las entrantes). No reemplaza a sus Systems FISCAL_DEVICE: usted sigue creando el Record de la factura (TRANSACTION::INVOICE) en un System FISCAL_DEVICE (cualquiera del mismo Taxpayer), y el System E_INVOICE_SERVICE convierte esos datos en la factura electrónica.

📘¿Quiere recibir también?

La recepción es opcional. Si la desea, establezca el código de destinatario SDI de fiskaly JKKZDGR como el destino SDI de su empresa en su portal de la Agenzia delle Entrate (AdE) — en cualquier momento, antes o después de la puesta en servicio. Sin ello, el Taxpayer no recibirá facturas, incluso una vez que el System esté listo. Omítalo si el Taxpayer solo enviará.

Utilice createSystem para crear un System E_INVOICE_SERVICE en la Location HEAD_OFFICE del Taxpayer y, a continuación, póngalo en servicio mediante updateSystem estableciendo su state en COMMISSIONED.

⚠️Caution

Por cada Taxpayer solo se puede poner en servicio un System E_INVOICE_SERVICE, en la Location HEAD_OFFICE (creada automáticamente junto con el Taxpayer) — poner en servicio un segundo falla. Permanece separado de los Systems FISCAL_DEVICE utilizados para la fiscalización de recibos, que no se ven afectados sin importar cuántos tenga.

📘Si el System permanece en TRANSMISSION_ONLY

La respuesta de la puesta en servicio siempre muestra TRANSMISSION_ONLY; llame a retrieveSystem después para leer el compliance.state real del System. Si permanece en TRANSMISSION_ONLY en lugar de pasar a TRANSMISSION_RECEPTION, el registro del Taxpayer no se completó — trátelo como una transición bloqueada y póngase en contacto con el soporte de fiskaly en dev-support@fiskaly.com con el VAT ID del Taxpayer para que podamos investigar.

Para el flujo completo de recepción, consulte Recepción de facturas electrónicas en la página de Italia.

Paso 3 — Añadir el flujo de transacción de factura

SIGN IT utiliza TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION.

E-INVOICE IT utiliza tipos de transacción diferentes en el mismo contenedor INTENTION::TRANSACTION:

Factura (B2B o B2C) → cree una TRANSACTION::INVOICE en un System FISCAL_DEVICE (como en el Paso 2)
Nota de crédito → cree una TRANSACTION::CORRECTION con data.type=INVOICE, que haga referencia a la factura original mediante record.id

Se admiten destinatarios de tipo BUSINESS y CONSUMER. Para un destinatario empresa, la entrada del array recipients de la factura necesita un bloque invoicing de tipo SDI, además de la Provincia del destinatario:

recipients[].type = BUSINESS
recipients[].invoicing.type = SDI
recipients[].invoicing.destination_code — el código de buzón SDI de 7 caracteres del destinatario
recipients[].invoicing.pec — (cuando sea obligatorio) la dirección PEC del destinatario
recipients[].address.region — la Provincia del destinatario (p. ej. MI, RM)

Escenario	`destination_code`	`pec`
El destinatario tiene un buzón SDI registrado	su código de 7 caracteres, solo letras mayúsculas y dígitos (p. ej. `ABC1234`)	opcional
El destinatario no está registrado en el SDI	`"0000000"`	obligatorio
El destinatario está fuera de Italia	`"XXXXXXX"`	no se utiliza

⚠️Incluya la region (Provincia) del destinatario

Establezca la Provincia del destinatario en recipients[].address.region. 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. No se comprueba al crear el registro: createRecord responde correctamente y la transmisión falla más tarde, llevando toda la cadena a FAILED.

Para un destinatario consumidor (B2C), los campos son distintos: no hay un destination_code a elección del destinatario ni número de IVA, pero el codice fiscale es obligatorio:

recipients[].type = CONSUMER
recipients[].identification.type = TAX, con number como el codice fiscale del consumidor
recipients[].name — gender, forename y surname
recipients[].address — el domicilio de residencia del consumidor, incluida la region (Provincia)
recipients[].invoicing.destination_code = "0000000", con pec opcional

📘Si no dispone del sexo del consumidor

gender lo exige la Unified API, no el SDI: la factura FatturaPA no incluye ese campo. Envíe DIVERSE cuando no tenga el dato.

Para los requisitos completos del destinatario, consulte Envío de facturas electrónicas en la página de Italia.

Cuando el cliente necesita una factura en lugar de un documento commerciale

Sus dos flujos declaran en lugares distintos —el documento commerciale a la AdE, la factura al SDI— y nada los vincula automáticamente.

Recoja la petición antes de cerrar la venta. Cuando el cliente le indique que necesita una fattura, emita una TRANSACTION::INVOICE en el System E_INVOICE_SERVICE en lugar del documento commerciale. Es el flujo que fiskaly admite de principio a fin hoy, tanto si el cliente lo pide antes como durante la venta.

📘La conversión de documento commerciale a factura está en desarrollo

Estamos construyendo un camino compatible que vincule entre sí un documento commerciale fiscalizado y una factura electrónica, de modo que una misma operación tenga una sola factura y un solo rastro de auditoría. Hasta que esté disponible, recoja la petición de factura antes de cerrar la transacción.

Gestión de las respuestas del SDI

Resultado asíncrono

A diferencia de los flujos de recibos, el resultado del SDI es asíncrono. Tras crear la TRANSACTION::INVOICE, consulte periódicamente o escuche las actualizaciones del Record E_INVOICE::TRANSMISSION.

💡Tip

Los resultados del SDI suelen llegar en pocos minutos. Sin embargo, la especificación del SDI permite hasta 48 horas.

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, el motivo de rechazo del SDI está disponible en logs[].message en los tres Records.

Para más detalles, consulte How to check the status of an e-invoice en nuestra página de Soporte.

Las facturas electrónicas enviadas y recibidas se conservan automáticamente a largo plazo (conservazione a norma, al menos 10 años), con un recibo de conservación disponible desde el archive-artifact del Record. No se requiere ninguna configuración. Consulte Archivado en la página de Italia para más detalles.

📘Note

El artefacto de cumplimiento para la facturación electrónica italiana es el XML FatturaPA, accesible en el Record E_INVOICE::TRANSMISSION.

Fases de error

Los errores pueden producirse en tres fases distintas, cada una con un comportamiento diferente:

Fase	Cuándo	Comportamiento
Validación de UAPI (síncrona)	Payload inválido	Se devuelve `4xx` de inmediato — no se crea ningún Record. Corrija el payload y reinténtelo en el mismo `INTENTION::TRANSACTION`.
Validación previa al SDI (asíncrona)	La factura se rechaza antes de llegar al SDI	Toda la cadena alcanza `state=FAILED` — se requiere una nueva cadena para reintentar.
Rechazo del SDI (asíncrono)	El SDI devuelve `NS`	Toda la cadena alcanza `state=FAILED` — se requiere una nueva cadena para reintentar.

Fallos y reenvío

Si el SDI devuelve NS (Notifica di Scarto), la factura es legalmente inexistente:

Lea logs[].message en cualquiera de los tres Records para obtener el motivo de rechazo del SDI
Cree una nueva INTENTION::TRANSACTION y una nueva TRANSACTION::INVOICE con los datos corregidos
El mismo document.number puede reutilizarse dentro de los 5 días posteriores al rechazo NS
La cadena fallida permanece FAILED de forma permanente — se conserva con fines de auditoría

⚠️Sin reintento automático

Cada reenvío inicia una nueva cadena de transacción — UAPI la trata como un envío completamente nuevo.

Lo que no cambia

Lo siguiente permanece totalmente intacto:

El flujo de puesta en servicio del Taxpayer y las credenciales de Fisconline
Todos los Systems FISCAL_DEVICE y las Locations BRANCH
Su flujo de recibos INTENTION::TRANSACTION → TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION existente