Factuarea API

Clientes internacionales

Identificar a un destinatario no español con el catálogo AEAT de identificación alternativa, y el mapa de escenario a calificación para entregas intracomunitarias, inversión del sujeto pasivo, exportaciones y ventas por ventanilla única.

Facturar fuera de España plantea dos preguntas que el caso interior no plantea nunca: cómo identificas a un destinatario que no tiene NIF español y qué recibe la AEAT por una operación exenta, con inversión del sujeto pasivo o localizada en el extranjero. Son independientes, y esta página las responde en ese orden.

Cuándo aplica

Siempre que el destinatario no sea un obligado tributario español, o que la operación se localice fuera del territorio peninsular de aplicación del IVA. La identificación es una propiedad del cliente; la calificación es una propiedad de la operación, y un mismo cliente puede aparecer en operaciones de clases distintas.

Identificar al cliente

Un cliente no español se identifica con alternative_id, un objeto {type, value, country_code} mutuamente excluyente con el tax_id español (BR-CLI-017). El tipo pertenece al catálogo de identificación de la AEAT, lista L7, y cada caso tiene su propio código numérico, que viaja en la cadena VeriFactu:

typeCódigo AEATSignificado
nif_iva02Número de operador intracomunitario (NIF-IVA).
passport03Pasaporte.
country_id04Documento oficial de identificación del país de residencia.
residence_certificate05Certificado de residencia fiscal.
other_document06Otro documento probatorio.
not_registered07No censado.

La matriz de tipo y país es una invariante dura, no una sugerencia: nif_iva solo es legal para países de la UE, porque es el número de operador intracomunitario; los demás tipos valen para cualquier país que no sea España; y country_code: "ES" se rechaza siempre, porque España usa tax_id. Una combinación ilegal responde 422:

curl -X POST https://api.factuarea.com/v1/clients \
  -H "Authorization: Bearer fact_live_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Müller GmbH",
        "alternative_id": { "type": "nif_iva", "value": "DE811569869", "country_code": "DE" }
      }'

Los valores heredados tax_id_foreign y national_id se siguen aceptando para no romper las integraciones existentes. La normalización tiene en cuenta el país: national_id pasa a country_id sin condiciones, mientras que tax_id_foreign pasa a nif_iva en un país de la UE y a other_document en cualquier otro caso — porque un tax_id_foreign de fuera de la UE no puede ser un número intracomunitario, y la matriz lo rechazaría.

Si no envías alternative_id en absoluto —un cliente extranjero con solo un país y un identificador fiscal—, la cadena VeriFactu cae al tipo de identificación 02, el caso intracomunitario más frecuente. Enviar el campo de forma explícita es estrictamente mejor.

vat_id es texto libre, y no se verifica

El campo del número de IVA intracomunitario acepta cualquier cadena de hasta 20 caracteres. No se valida contra el registro VIES, no se comprueba su formato por país y no se contrasta con tax_id (BR-CLI-003). Un prefijo de país equivocado se acepta. Un cliente que debería estar en régimen intracomunitario pero no tiene vat_id no se bloquea ni se señala.

vat_id y tax_id son campos separados que conviven: una empresa española puede llevar su NIF nacional y ese mismo número con el prefijo de país como número de IVA intracomunitario.

Verificar a un destinatario español antes de facturar

Para los destinatarios que tienen NIF español, POST /v1/clients/census-verification (scope clients:read) comprueba el par de nombre y NIF contra el censo de la AEAT antes de que factures, anticipando el rechazo VeriFactu más frecuente: el del destinatario que el censo no identifica (BR-CLI-015).

Es informativa a propósito: no bloquea nunca el guardado de un cliente ni la emisión de una factura, no persiste nada y falla en abierto — una AEAT inaccesible responde 200 con estado de no disponible, nunca un 5xx. Está limitada por frecuencia, porque puede llegar a la red de la AEAT. Ver Verificación censal para el flujo completo.

El mapa de escenarios

Este es el mapa del escenario de negocio a lo que recibe la AEAT (BR-VFC-029):

EscenarioRégimen de operación de cabeceraQué llega a la AEAT
Entrega intracomunitaria de bienesintracomunitariaE5 — sujeta y exenta, art. 25 LIVA
Servicios con inversión del sujeto pasivoispS2 — sujeta y no exenta, cuota repercutida 0 (la autorrepercute el destinatario)
Exportación fuera de la UEimportacion_exportacionE2 — sujeta y exenta, art. 21 LIVA
Ventas a distancia por ventanilla única(general)regime_key: 17 — Capítulo XI del Título IX, OSS e IOSS

La inversión del sujeto pasivo no es una exención. Es una calificación derivada del régimen de cabecera — S2, sujeta y no exenta, con la cuota repercutida forzada a cero porque es el destinatario quien liquida el impuesto. No es una causa de exención de línea, y en particular no es E4: ese código es la exención de los arts. 23 y 24 LIVA, para depósitos aduaneros y regímenes suspensivos, que es una cosa completamente distinta. Una factura que declara la inversión del sujeto pasivo como operación exenta declara mal tanto la calificación como la cuota.

Las cuatro calificaciones alcanzables desde el régimen de cabecera son S1 (general), S2 (inversión del sujeto pasivo), E5 (intracomunitaria) y E2 (importación o exportación). Los demás códigos de exención —E1, E3, E4, E6— existen en el catálogo de la AEAT pero solo se alcanzan como causa de exención de línea.

Qué envía la API

Aquí viene la parte que decide cómo construyes el payload, y es una restricción real más que una preferencia de estilo.

El régimen de operación de cabecera es de solo lectura en la v1. Ni POST /v1/invoices ni PUT /v1/invoices/{id} aceptan operation_regime; el objeto factura lo devuelve, y toda factura creada por la API pública nace bajo el régimen general. La causa de exención a nivel de documento es de solo lectura por el mismo motivo.

El preferred_operation_regime del cliente —aceptado en POST /v1/clients con los valores general, intracomunitaria, importacion_exportacion e isp— se guarda y se devuelve, pero no fija el régimen de las facturas que creas. Es una preferencia declarativa para tu propio uso.

Lo que puedes expresar por línea es la causa de exención. Así que:

EscenarioCómo lo expresas en la v1
Entrega intracomunitaria de bienestax_rate: 0 + exemption_reason: "E5" por línea.
Exportación fuera de la UEtax_rate: 0 + exemption_reason: "E2", normalmente con regime_key: "02".
Ventas a distancia por ventanilla únicaregime_key: "17" por línea, con el tipo del país de destino.
Inversión del sujeto pasivoNo expresable. S2 deriva del régimen de cabecera, y el catálogo de línea no contiene códigos S por diseño.

Esa última fila es la respuesta honesta, y tiene consecuencias: una factura con inversión del sujeto pasivo creada por la API pública quedará calificada como S1 y con cuota repercutida, que no es lo que quieres decir. Hasta que el régimen de cabecera sea escribible, emite esas facturas desde el panel. Queda recogido en Alcance y limitaciones.

El ejemplo publicado intracomunitario_bienes de la operación de creación tiene exactamente esta forma —tipo cero, más E5, más una clave de régimen explícita— en lugar de un régimen de cabecera que no podría fijar:

{
  "client_id": "0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42",
  "series_id": "019e5584-7a72-7038-a8f6-561ed180b699",
  "issued_on": "2026-06-01",
  "due_on": "2026-07-01",
  "notes": "Entrega intracomunitaria de bienes exenta (art. 25 LIVA)",
  "lines": [
    {
      "description": "Suministro de maquinaria a cliente UE (DE)",
      "quantity": 1,
      "unit_price": 5000,
      "tax_rate": 0,
      "exemption_reason": "E5",
      "regime_key": "01"
    }
  ]
}

La factura simplificada no es opción en ninguno de estos escenarios: la comprobación de admisibilidad bloquea las operaciones intracomunitarias, la inversión del sujeto pasivo y cualquier destinatario fuera de España antes siquiera de mirar el importe. Ver Facturas simplificadas o completas.

Qué sale en el PDF

El bloque de destinatario imprime la identificación alternativa exactamente como se suministró, congelada en el momento de emitir igual que el resto del snapshot del destinatario (BR-INV-024).

La mención legal —art. 25 LIVA en una entrega intracomunitaria, art. 21 en una operación con terceros países, art. 84.Uno.2 en la inversión del sujeto pasivo— deriva del régimen de cabecera, y por tanto no aparece automáticamente en una factura creada por la v1 (BR-TAX-024). Dos opciones: poner el texto en notes, o usar el exemption_reason_text de línea, que se imprime bajo la descripción de la línea y es solo de presentación.

Qué llega a la AEAT

En el registro VeriFactu, el tipo de identificación del destinatario viaja como el código AEAT de la tabla L7 de arriba, y el desglose lleva la calificación descrita en El mapa de escenarios — códigos de operación exenta para E5 y E2, y S2 con cuota cero en la inversión del sujeto pasivo.

En la declaración anual de operaciones con terceras personas (Modelo 347), las operaciones intracomunitarias y las importaciones o exportaciones quedan excluidas (BR-TXR-022): se declaran por sus propias vías —la declaración recapitulativa para las operaciones intracomunitarias, y la documentación aduanera para el resto— y declararlas dos veces produciría un descuadre en la declaración cruzada.

La inversión del sujeto pasivo se comporta al revés: es una operación interior y sí aparece en esa declaración. La clasificación usa el régimen de cabecera de la factura, así que una factura mixta se clasifica en bloque.

Trazabilidad

Derivado de las reglas de dominio del backend de Factuarea:

  • BR-CLI-003vat_id como texto libre, sin validación VIES, independiente de tax_id.
  • BR-CLI-015 — verificación censal del destinatario: informativa, con fallo en abierto y sin estado.
  • BR-CLI-017 — el catálogo AEAT L7 de identificación alternativa, la matriz de tipo y país, y los alias heredados que se aceptan.
  • BR-INV-024 — el snapshot inmutable del destinatario.
  • BR-INV-031 — el catálogo cerrado de claves de régimen usado en las líneas de ventanilla única y de exportación.
  • BR-INV-032 — las causas de exención de línea y su caída al valor de la cabecera.
  • BR-TAX-024 — la causa de exención a nivel de documento y su mención legal automática.
  • BR-VFC-029 — el mapa de calificaciones: S1, S2, E5 y E2 derivadas del régimen de cabecera, y la inversión del sujeto pasivo como calificación y no como exención.
  • BR-TXR-022 — exclusión de las operaciones intracomunitarias y de importación o exportación de la declaración anual de operaciones con terceros, y la inclusión de la inversión del sujeto pasivo interior.

En esta página