E-INVOICE IT para clientes de SIGN IT

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 B2B italiana (E-INVOICE IT). Ambos productos se ejecutan sobre la misma API Unificada y comparten la misma estructura de Taxpayer y Location — solo se necesitan unas pocas adiciones.

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 para recibos fiscales

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

Paso 1 — Ampliar los datos de alta del Taxpayer

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. tax_regime es opcional (valor predeterminado ORDINARY). Este bloque es opcional a nivel de API, pero el SDI lo exige para entidades registradas y debe proporcionarse en el momento del alta.

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

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

📘Note

Solo se necesita un System E_INVOICE_SERVICE por Taxpayer, vinculado a la Location HEAD_OFFICE, que se crea automáticamente al crear el Taxpayer. Esto es independiente de los Systems FISCAL_DEVICE utilizados para la fiscalización de recibos, que están vinculados a Locations BRANCH individuales y pueden existir en cualquier número junto a él.

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

SIGN IT utiliza TRANSACTION::RECEIPT. E-INVOICE IT utiliza un tipo de transacción diferente en el mismo contenedor INTENTION::TRANSACTION:

• Factura B2B → cree una TRANSACTION::INVOICE vinculada al System E_INVOICE_SERVICE
• Nota de crédito → cree una TRANSACTION::CORRECTION con data.type=INVOICE, que haga referencia a la factura original mediante record.id

📘Solo B2B

Solo se admiten destinatarios de tipo BUSINESS. El destinatario debe tener un bloque invoicing de tipo SDI con un destination_code válido. Las facturas B2C están actualmente fuera del alcance.

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.

📘Note

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

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

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 de Invopop (asíncrona)	Invopop 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:

1. Lea logs[].message en cualquiera de los tres Records para obtener el motivo de rechazo del SDI
2. Cree una nueva INTENTION::TRANSACTION y una nueva TRANSACTION::INVOICE con los datos corregidos
3. El mismo document.number puede reutilizarse dentro de los 5 días posteriores al rechazo NS
4. 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 existente