Formato canónico

El formato canónico es el JSON de factura de la API. Lo envías al guardar borradores, importar emitidas, registrar recibidas y validar. Las facturas que llegan en XML (FacturaE, UBL o CII) se convierten a este formato antes de validarse.

Estructura raíz

{
  "schema_version": "json_1_1",
  "meta": {},
  "invoice": {}
}

Campo	Obligatorio	Descripción
schema_version	Sí	Siempre "json_1_1". Otro valor se rechaza con unsupported_schema_version.
meta	Sí	Contexto de la integración
invoice	Sí	Contenido de la factura

Un campo que no está en este contrato se rechaza, en la raíz y dentro de cada bloque (schema.additional_properties).

Dónde se usa

Operación	Qué hace	invoice_number e issue_date	Qué pasa con los errores
PUT /api/v1.1/drafts	Guarda o actualiza un borrador	No se envían	Los de esquema impiden guardar (422). Los demás no: se guarda y la respuesta trae success: false y errors.
POST /api/v1.1/drafts/batch	Guarda varios borradores	No se envían	Igual, factura a factura
POST /api/v1.1/issued-invoices/{invoice_id}/issue	Emite un borrador ya guardado. El cuerpo solo admite invoice_number.	La fecha, la API. El número, la API o el invoice_number del cuerpo	Cualquier error impide emitir: 422 con validation_failed
POST /api/v1.1/issued-invoices/import	Registra una emitida expedida fuera de Faxtal	Obligatorios	No impiden registrarla: se devuelven en errors
PUT /api/v1.1/received-invoices	Registra o actualiza una recibida	Los del proveedor	No impiden registrarla: queda con errores hasta que la corriges
POST /api/v1.1/drafts/validate, /issued-invoices/validate, /received-invoices/validate	Valida sin guardar	Según el caso	Devuelve is_valid y errors

Reglas propias de cada operación:

• Borrador. invoice.header.invoice_series_code y meta.external_ref son obligatorios. Si envías invoice_number o issue_date, 422 con invoice_number_not_allowed o issue_date_not_allowed.
• Emisión. La API asigna la fecha del día y el siguiente número de la serie. Si tu programa numera, envía su número en el cuerpo de la emisión, no en el canónico (ver Facturas emitidas).
• Importación. invoice_series_code, invoice_number e issue_date son obligatorios. La fecha no puede ser futura (future_issue_date). Importar no genera registros VeriFactu.
• Validación sin guardar. Recalcula impuestos y totales desde las líneas, así que no detecta unos totales enviados que no cuadren.

meta

Campo	Obligatorio	Descripción
direction	Sí	"issued" o "received". En /received-invoices la API la fija a received.
source_system	Sí	Nombre libre de tu sistema, por ejemplo "mi-erp"
external_ref	Según operación	Tu referencia, máximo 60 caracteres. Obligatoria en PUT /drafts y POST /drafts/batch: si repites una referencia, se actualiza ese borrador. En la importación, si falta, se usa el número de factura.
batch_id	No	Referencia libre del lote
batch_item_id	No	Referencia libre del elemento dentro del lote
original_format	No	Formato de origen antes de convertir a canónico
original_document_id	No	Referencia al documento original

invoice

Bloques obligatorios: supplier, header, issue_data, totals y lines (al menos una línea).

Bloques opcionales:

Bloque	Descripción
customer	Receptor. Obligatorio en emitidas no simplificadas (customer_required).
taxes_outputs	Desglose de impuestos repercutidos. Si falta, se calcula desde las líneas.
taxes_withheld	Desglose de retenciones. Si falta, se calcula desde las líneas.
payment_terms	Condiciones de pago, en texto libre
payment_details	Vencimientos y formas de pago
legal_literals	Textos legales de la factura
additional_data	Factura relacionada e información adicional

invoice.supplier e invoice.customer

En una emitida, el emisor (supplier) es tu empresa. En una recibida, el receptor (customer) es tu empresa. Si no coincide con la empresa de la API key, la factura se rechaza.

Campo	supplier	customer	Descripción
person_type_code	Obligatorio	Opcional	"F" persona física, "J" jurídica. En el receptor con NIF español se deduce si falta.
tax_id	Obligatorio	Opcional	NIF u otro identificador fiscal. El NIF español se valida.
name	Obligatorio	Obligatorio	Razón social o nombre completo, máximo 120 caracteres
country_code	No	No	País ISO 3166-1. Si falta, "ES".
party_country_code	No	No	País principal de la parte, si es distinto del de su dirección
telephone	No	No	Teléfono
electronic_mail	No	No	Correo electrónico
contact_persons	No	No	Persona de contacto
company	No	No	Datos de persona jurídica: legal_name, trade_name y address
person	No	No	Datos de persona física: first_name, first_surname, second_surname y address
electronic_address	No	No	Dirección electrónica: value y scheme_id, un código EAS de 4 dígitos (por ejemplo "0088", GLN)
identifiers[]	No	No	Identificadores adicionales: role, value, scheme_id (obligatorios), scheme_name e issuer_country_code
administrative_centres[]	No	No	Solo en customer. Centros administrativos (DIR3): centre_code (obligatorio), role_type_code y centre_description.

Dirección (company.address o person.address):

Campo	Descripción
address	Primera línea
address_2	Segunda línea (portal, piso…)
post_code	Código postal
town	Localidad
country_code	País ISO 3166-1
country_subdivision	Provincia o región: informa code (por ejemplo "ES-M") o name. La API completa el resto.

En una emitida completa a una persona jurídica establecida en España, la API tiene que poder determinar la provincia del receptor, por country_subdivision o por el código postal. Si no puede, customer_domicile_required.

invoice.header

Campo	Obligatorio	Descripción
invoice_type_code	Sí	Tipo de factura, del 01 al 05. Ver Catálogos.
invoice_series_code	En emitidas	Código de serie, máximo 60 caracteres. Si no existe, se crea. En recibidas es opcional.
invoice_number	Según operación	Solo en importaciones y recibidas, máximo 60 caracteres. En emitidas ya incluye la serie.
references	No	receiver_transaction_reference (pedido del cliente), receiver_contract_reference, issuer_contract_reference y file_reference (expediente)
corrective	En rectificativas	Datos de la factura rectificada

header.corrective. En una rectificativa emitida (03 o 04), la API exige la causa, la factura rectificada y el criterio:

Campo	Obligatorio	Descripción
reason_code	Sí	Causa de la rectificación, del 01 al 25. Ver Catálogos.
reason_description	No	Descripción de la causa
invoice_number	Sí	Número de la factura rectificada. En emitidas ya incluye la serie.
invoice_issue_date	Sí	Fecha de expedición de la factura rectificada (YYYY-MM-DD)
correction_type	Sí	"S" por sustitución o "D" por diferencias
corrected_taxable_base	Con S	Base imponible rectificada
corrected_tax_amount	Con S	Cuota rectificada
invoice_series_code	No	Serie de la factura rectificada
tax_period.start_date, tax_period.end_date	No	Periodo de la factura rectificada (YYYY-MM-DD)

Si falta alguno, la validación devuelve corrective_reason_required, corrective_reason_unknown, corrective_invoice_number_required, corrective_invoice_issue_date_required, corrective_correction_type_required o corrective_substitution_amounts_required. En recibidas no se exigen: esos datos los informa el proveedor.

invoice.issue_data

Campo	Obligatorio	Descripción
issue_date	Según operación	Fecha de expedición (YYYY-MM-DD). Obligatoria al importar y en recibidas. No se envía en borradores.
operation_date	No	Fecha de la operación, si es distinta
receipt_date	No	Fecha de recepción (recibidas)
invoicing_period_start_date, invoicing_period_end_date	No	Periodo de facturación
tax_group_code	No	"IVA", "IGIC" o "IPSI". Si falta, se usa el de la empresa. Una factura usa un solo grupo.
tax_country_code	No	País del impuesto. Si falta, "ES".
tax_currency_code	No	Moneda ISO 4217. Si falta, la del país del impuesto.
is_tai	No	true si la operación se realiza en el territorio de aplicación del IVA. Es un dato tuyo: si no lo envías, se deduce del domicilio del emisor.
is_dua	No	Importación de bienes con DUA. Solo en recibidas (is_dua_only_for_received).
invoice_description	No	Descripción general, máximo 500 caracteres
invoice_currency	No	Moneda original del documento: invoice_currency_code, exchange_rate (mayor que 0) y exchange_rate_date, los tres obligatorios

:::info IGIC aún no está disponible: una factura con tax_group_code: "IGIC" se rechaza con tax_group_not_available. :::

invoice.lines[]

Cada línea lleva item_description, quantity y uno solo de los dos precios unitarios: unit_price_without_tax (sin impuesto) o unit_price_with_tax (con impuesto incluido). Todas las líneas de una factura usan el mismo modo (line_price_mode_mixed).

Campo	Obligatorio	Descripción
item_description	Sí	Concepto
quantity	Sí	Cantidad
unit_price_without_tax	Uno de los dos	Precio unitario sin impuesto
unit_price_with_tax	Uno de los dos	Precio unitario con impuesto incluido
sequence_number	No	Número de línea. Si falta, se numeran 1..n.
item_type	No	"goods", "service" o "investment_good"
unit_of_measure	No	Código de unidad del catálogo, del 01 al 36. Ver Catálogos.
article_code	No	Referencia interna del producto o servicio
discount_rate, discount_amount	No	Descuento de línea. No se admite con precio con impuesto incluido.
charge_rate, charge_amount	No	Recargo de línea. No se admite con precio con impuesto incluido.
tax_output_rate	No	Tipo del impuesto repercutido (%). Tiene que existir en el catálogo del grupo (tax_rate_unknown).
tax_withheld_rate	No	Tipo de retención (%)
tax_treatment_code	No	Tratamiento fiscal. Ver Catálogos. Si falta, se deduce del tipo, de reverse_charge y de la causa de exención.
reverse_charge	No	true si hay inversión del sujeto pasivo
exemption_reason_code, exemption_reason_text	No	Causa de exención, del catálogo del grupo del impuesto
non_taxable_reason	No	Motivo de no sujeción. En operaciones fuera del TAI, si falta, se usa LOCATION_RULES.
tax_regime_key, tax_regime_description	No	Clave de régimen especial. Ver Clave de régimen.
consumption_country_code, consumption_tax_rate, consumption_tax_amount, consumption_rate_type, supply_type	No	Ventanilla única (clave 17): IVA del Estado de consumo. Ver Ventas con el IVA de otro Estado.
purchase_price_incl	No	IVA por margen: precio de compra con IVA incluido
deduction_rate, non_deductible_reason	No	Solo en recibidas: porcentaje deducible y motivo de no deducibilidad
line_item_period_start_date, line_item_period_end_date	No	Periodo del servicio de la línea
transaction_date	No	Fecha de la operación de la línea
additional_line_item_information	No	Texto adicional
references	No	issuer_contract_reference, issuer_contract_date, receiver_contract_reference, receiver_transaction_reference, file_reference y delivery_notes[] (albaranes, con number y date)
legal_literals	No	Textos legales propios de la línea
invoice_currency	No	Importes de la línea en la moneda original

Importes que calcula la API si no los envías: gross_amount_without_tax (neto, ya con el descuento o recargo de línea), total_cost_without_tax, gross_amount_with_tax, total_cost_with_tax, tax_output_base, tax_output_amount, tax_withheld_base, tax_withheld_amount y consumption_tax_amount (base × tipo del Estado de consumo).

invoice.taxes_outputs[]

Opcional. Si falta, la API agrupa las líneas por tipo. Si lo envías, tiene que ser coherente con las líneas.

Campo	Obligatorio	Descripción
tax_rate	Sí	Tipo (%)
taxable_base	Sí	Base imponible
tax_amount	Sí	Cuota
tax_treatment_code	No	Tratamiento fiscal
reverse_charge	No	Inversión del sujeto pasivo
exemption_reason_code, exemption_reason_text	No	Causa de exención. Obligatoria si la operación es exenta (exemption_reason_required).
non_taxable_reason	No	Motivo de no sujeción
tax_regime_key, tax_regime_description	No	Clave de régimen especial
equivalence_surcharge, equivalence_surcharge_amount	No	Recargo de equivalencia: tipo (%) y cuota
consumption_country_code, consumption_tax_rate, consumption_tax_amount, consumption_rate_type, supply_type	No	Ventanilla única (clave 17): IVA del Estado de consumo. Ver Ventas con el IVA de otro Estado.
invoice_currency	No	taxable_base, tax_amount y equivalence_surcharge_amount en la moneda original

invoice.taxes_withheld[]

Opcional. Si falta, se calcula desde las líneas.

Campo	Obligatorio	Descripción
tax_rate	Sí	Tipo de retención (%)
taxable_base	Sí	Base de la retención
tax_amount	Sí	Importe retenido

invoice.totals

Campo	Obligatorio	Descripción
total_gross_amount_before_taxes	Sí	Base imponible total
total_tax_outputs	Sí	Suma de cuotas repercutidas
invoice_total	Sí	Total de la factura
total_gross_amount	No	Suma de las líneas
total_consumption_taxes	No	Suma del IVA de los Estados de consumo (ventanilla única). Se incluye en invoice_total y no en total_tax_outputs.
general_discounts[]	No	Descuentos de documento: discount_reason, discount_rate, discount_amount
general_surcharges[]	No	Recargos de documento: charge_reason, charge_rate, charge_amount
total_general_discounts, total_general_surcharges	No	Suma de descuentos y recargos de documento
total_non_taxable_amount	No	Importe no sujeto
total_taxes_withheld	No	Suma de retenciones
payments_on_account[]	No	Anticipos: payment_on_account_date y payment_on_account_amount (obligatorios) y description
total_payments_on_account	No	Suma de anticipos
reimbursable_expenses[]	No	Suplidos: issue_date, invoice_number, invoice_series_code, reimbursable_expenses_amount y description
total_reimbursable_expenses	No	Suma de suplidos
total_executable_amount	No	Importe a pagar
rounding_amount	No	Ajuste de redondeo para absorber diferencias legítimas entre la suma de componentes y el total
invoice_currency	No	Totales en la moneda original

• Los campos opcionales que faltan se calculan desde las líneas y los impuestos.
• Los descuentos y recargos de documento entran en la base imponible. Los de línea ya van en el importe de cada línea: no los repitas aquí.

invoice.payment_details[]

Campo	Descripción
installment_due_date	Fecha de vencimiento (YYYY-MM-DD)
installment_amount	Importe del vencimiento
payment_method_code	Forma de pago, dos dígitos. Ver Catálogos.
payment_method_label	Etiqueta de la forma de pago
iban_account_to_be_credited	IBAN de abono
iban_account_to_be_debited	IBAN de cargo
payment_reconciliation_reference	Referencia de conciliación
collection_additional_information	Información adicional de cobro

Con varios vencimientos, cada uno necesita fecha e importe (installment_due_date_required, installment_amount_required). Con uno o ninguno, la API completa el vencimiento único con el total a pagar.

invoice.legal_literals[] e invoice.additional_data

Campo	Descripción
legal_literals[].legal_reference	Texto legal (obligatorio)
legal_literals[].code	Código del literal
additional_data.related_invoice	Factura relacionada: number, series e issue_date
additional_data.invoice_additional_information	Información adicional

Campos que calcula la API

No los envíes: la API los deduce y, si llegan en el payload, responde 422 con inferred_fields_not_allowed y la lista de rutas en fields.

Campo	Se deduce de
header.is_simplified, header.is_corrective	invoice_type_code
lines[].taxable, lines[].exempt	tax_treatment_code
lines[].tax_category_code	Tratamiento, tipo y grupo del impuesto
lines[].tax_output_code, lines[].tax_withheld_code	El tipo (%) y el grupo del impuesto
taxes_outputs[].taxable, taxes_outputs[].exempt, taxes_outputs[].tax_category_code, taxes_outputs[].tax_type_code	Ídem, en el desglose
taxes_withheld[].tax_type_code	El tipo de retención (%)
country_subdivision.subdivision_type	code o name de la subdivisión

Normalizaciones automáticas

Campo	Qué hace la API
country_code, tax_country_code	Normaliza a ISO alpha-2. Si falta, "ES".
tax_currency_code	Si falta, la moneda del país del impuesto
tax_group_code	Si falta, el grupo de impuesto de la empresa
customer.person_type_code	Si falta y hay NIF español, se deduce del NIF
country_subdivision	Completa code, name y el tipo a partir de uno de los dos
is_tai	Si falta, se deduce del domicilio del emisor
lines[].sequence_number	Si falta, numera 1..n
lines[].tax_treatment_code	Si falta, se deduce del tipo, de reverse_charge y de la causa de exención
unit_of_measure	"ud", "uds" o "unidades" pasan a "01"
Importes de línea, taxes_outputs, taxes_withheld y totales opcionales	Si faltan, se calculan

Ejemplo completo

Borrador de factura emitida con IVA general, una línea de servicio y pago por transferencia. Se envía tal cual a PUT /api/v1.1/drafts. El emisor tiene que ser la empresa de tu API key.

{
  "schema_version": "json_1_1",
  "meta": {
    "direction": "issued",
    "source_system": "mi-erp",
    "external_ref": "PEDIDO-2026-001"
  },
  "invoice": {
    "supplier": {
      "person_type_code": "J",
      "tax_id": "B10000008",
      "name": "Empresa Demo S.L.",
      "electronic_mail": "facturacion@empresa-demo.es",
      "company": {
        "legal_name": "Empresa Demo S.L.",
        "address": {
          "address": "Calle Mayor 1, 3º A",
          "post_code": "28001",
          "town": "Madrid",
          "country_subdivision": { "code": "ES-M" },
          "country_code": "ES"
        }
      }
    },
    "customer": {
      "person_type_code": "J",
      "tax_id": "B10000016",
      "name": "Cliente Prueba S.L.",
      "company": {
        "legal_name": "Cliente Prueba S.L.",
        "address": {
          "address": "Avenida Diagonal 5",
          "post_code": "08001",
          "town": "Barcelona",
          "country_subdivision": { "code": "ES-B" },
          "country_code": "ES"
        }
      }
    },
    "header": {
      "invoice_series_code": "A",
      "invoice_type_code": "01",
      "references": {
        "receiver_transaction_reference": "PED-2026-0001"
      }
    },
    "issue_data": {
      "invoice_description": "Servicios de consultoría de noviembre de 2026"
    },
    "lines": [
      {
        "item_type": "service",
        "item_description": "Consultoría senior, noviembre de 2026",
        "quantity": 10,
        "unit_of_measure": "02",
        "unit_price_without_tax": 100.0,
        "tax_output_rate": 21.0,
        "tax_treatment_code": "TAXABLE_NON_EXEMPT",
        "article_code": "CONSULT-SENIOR"
      }
    ],
    "taxes_outputs": [
      {
        "tax_rate": 21.0,
        "taxable_base": 1000.0,
        "tax_amount": 210.0
      }
    ],
    "totals": {
      "total_gross_amount_before_taxes": 1000.0,
      "total_tax_outputs": 210.0,
      "invoice_total": 1210.0
    },
    "payment_terms": "Pago a 30 días desde la fecha de factura",
    "payment_details": [
      {
        "installment_due_date": "2026-12-15",
        "installment_amount": 1210.0,
        "payment_method_code": "04",
        "iban_account_to_be_credited": "ES6621000418401234567891"
      }
    ]
  }
}

curl -s -X PUT https://app.faxtal.com/api/v1.1/drafts \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY" \
  -H "Content-Type: application/json" \
  -d @borrador.json

Respuesta 201:

{
  "success": true,
  "id": "3f1c9a52-8e7b-4d1a-9c0e-2b6f4a7d8e91",
  "errors": []
}

Para importar la misma factura como ya emitida (POST /api/v1.1/issued-invoices/import), añade header.invoice_number (por ejemplo "A-15") e issue_data.issue_date.

Ventas con el IVA de otro Estado (ventanilla única)

Una venta a distancia a un consumidor de otro Estado miembro lleva el IVA de ese Estado, que no es un impuesto español: no se declara a la AEAT ni entra en la base ni en la cuota del desglose. Por eso viaja en campos propios de la línea (o de la entrada de taxes_outputs), junto a la clave de régimen 17:

Campo	Descripción
consumption_country_code	Estado miembro de consumo (ISO 3166-1 alfa-2). No puede ser ES ni un país de fuera de la UE.
consumption_tax_rate	Tipo del Estado de consumo, en porcentaje.
consumption_tax_amount	Cuota. Si no la envías, la calcula la API (base × tipo).
consumption_rate_type	standard, reduced, super_reduced o parking. La pide el modelo 369 y no se deduce del porcentaje.
supply_type	goods o services, como los distingue el 369.

Reglas:

• Solo en emitidas de IVA, en operaciones con tax_regime_key 17 y no sujetas por reglas de localización (tax_treatment_code: NON_TAXABLE, non_taxable_reason: LOCATION_RULES). Una venta con IOSS consumida en España va sujeta con tipo español y sin estos campos.
• invoice_total incluye la cuota extranjera (la paga el cliente) y totals.total_consumption_taxes la resume; total_tax_outputs y total_gross_amount_before_taxes siguen siendo solo españoles.
• Al registrar la factura en VERI*FACTU y en el SII se declara la base no sujeta, sin ese impuesto, así que el importe del registro (y el del código QR) no coincide con el total de la factura.
• El tipo se comprueba contra el catálogo de tipos por Estado (tomado de la base de datos TEDB de la Comisión): si no figura, se devuelve un aviso, nunca un rechazo.

{
  "tax_regime_key": "17",
  "tax_treatment_code": "NON_TAXABLE",
  "non_taxable_reason": "LOCATION_RULES",
  "gross_amount_without_tax": 100.0,
  "consumption_country_code": "DE",
  "consumption_tax_rate": 19.0,
  "consumption_tax_amount": 19.0,
  "consumption_rate_type": "standard",
  "supply_type": "goods"
}

Catálogos

Las tablas de abajo son la referencia rápida de los valores más usados. La lista viva se consulta por API, así que no hace falta copiarla en tu integración:

GET /api/v1.1/catalogs/{nombre} con tax-rates, tax-groups, tax-treatments, exemption-reasons, non-taxable-reasons, non-deductible-reasons, tax-regimes, invoice-types, payment-methods, correction-reasons, countries, subdivisions o units.

Se piden con tu API key y no exigen ningún permiso: no son datos de tu empresa, sino listas fijas. Cada entrada trae al menos code y name.

curl "https://app.faxtal.com/api/v1.1/catalogs/tax-rates" \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY"

Provincias (country_subdivision.code)

GET /api/v1.1/catalogs/subdivisions devuelve las provincias y ciudades autónomas de España:

{ "code": "ES-BI", "ine": 48, "name": "Bizkaia", "name_secondary": "Vizcaya", "is_tai": false }

En country_subdivision.code puedes mandar el ISO 3166-2 (ES-BI) o el código INE (48): la API acepta los dos. name va en la lengua propia y name_secondary en castellano. is_tai indica si la provincia está en el Territorio de Aplicación del IVA (Canarias, Ceuta y Melilla no lo están).

Unidades de medida (unit_of_measure)

GET /api/v1.1/catalogs/units devuelve el catálogo por código (02 Horas, 03 Kilogramos, 04 Litros…).

:::warning Manda el código, no el texto Envía el código del catálogo. Los alias de texto (KG, L, HORAS) tienen una incidencia abierta y pueden resolverse a una unidad equivocada. :::

Tipo de factura (header.invoice_type_code)

Código	Nombre	Simplificada	Rectificativa
01	Factura ordinaria	No	No
02	Factura simplificada	Sí	No
03	Factura rectificativa	No	Sí
04	Factura rectificativa simplificada	Sí	Sí
05	Autofactura (la emite el destinatario en nombre del proveedor)	No	No

Tratamiento fiscal (tax_treatment_code)

Código	Significado
TAXABLE_NON_EXEMPT	Sujeta y no exenta
TAXABLE_EXEMPT	Sujeta y exenta (requiere causa de exención)
TAXABLE_NON_EXEMPT_RC	Sujeta y no exenta, con inversión del sujeto pasivo
NON_TAXABLE	No sujeta

Tipos de impuesto (tax_output_rate, tax_withheld_rate, tax_rate)

Se informa solo el porcentaje. La API deduce el código del impuesto a partir del tipo y del grupo de la factura.

Grupo	Tipos (%)
IVA	21, 10, 4, 0
IGIC	0, 3, 7, 9,5, 13,5, 20, 35
IRPF (retención)	15, 7, 19

Causas de exención de IVA (exemption_reason_code)

Código	Descripción
E1	Artículo 20 LIVA. Operaciones interiores.
E2	Artículo 21 LIVA. Exportaciones y operaciones asimiladas.
E3	Artículo 22 LIVA. Importaciones.
E4	Artículos 23 y 24 LIVA. Operaciones en zonas francas.
E5	Artículo 25 LIVA. Entregas intracomunitarias.
E6	Exenta por otros motivos.

Una causa de otro grupo de impuesto se rechaza con exemption_reason_not_valid_for_tax_group.

Clave de régimen (tax_regime_key)

La clave de régimen especial o trascendencia de la operación (la de VeriFactu y el SII). La lista completa está en GET /api/v1.1/catalogs/tax-regimes; una clave que no está en el catálogo se rechaza con invalid_tax_regime_key.

• Se informa en cada línea (lines[].tax_regime_key) o en taxes_outputs[]. Una línea sin clave toma la del documento. Si taxes_outputs falta, la API lo agrupa por impuesto, tipo y clave, así que dos líneas al mismo tipo con claves distintas dan dos desgloses.
• Sin clave, la operación es de régimen general (01).
• La clave 07 es el régimen especial del criterio de caja: el IVA se declara al cobrar (ver Cobros y pagos). Si la empresa está acogida al criterio de caja en el ejercicio de la operación, sus emitidas llevan la 07 en las operaciones a las que se aplica; una emitida con una clave que no cuadra con el régimen de la empresa se rechaza con recc_key_mismatch. No se admite junto con los regímenes de margen (03, 05): recc_margin_regime_not_supported. La factura con 07 lleva la mención «Régimen especial del criterio de caja» (literal 007; 107 en IGIC).
• En una recibida, la 07 indica que el proveedor está en el criterio de caja: el IVA se deduce al pagar.
• La clave 17 es la ventanilla única (OSS/IOSS). En una emitida de IVA con destinatario de otro país de la UE, o sin destinatario, la operación va como no sujeta por reglas de localización (tax_treatment_code: NON_TAXABLE; si falta non_taxable_reason, se toma LOCATION_RULES) y se declara con la 17 y la calificación N2, sin el IVA del país del cliente. Con destinatario español solo cabe como sujeta y no exenta con IVA español (venta de bienes importados con IOSS). Lo más seguro es informar la 17 en cada línea: si solo viene en taxes_outputs y al recalcular desde las líneas no se puede saber a cuáles corresponde, se rechaza con oss_regime_key_ambiguous. No admite destinatarios de fuera de la UE, inversión del sujeto pasivo ni fechas anteriores al 1 de julio de 2021, y una factura con la 17 no puede llevar operaciones con otra clave. El país que cuenta es el del destinatario (country_code, ES si no se informa). La empresa debe tener el alta en la ventanilla única en la fecha de la operación (se configura en la app, en Configuración → Empresa → Impuestos): sin alta, oss_regime_not_registered; con el alta aún sin efecto o en trámite, el aviso oss_regime_not_effective.

Causas de rectificación (header.corrective.reason_code)

Código	Causa	Código	Causa
01	Número de la factura	14	Clase de factura
02	Serie de la factura	15	Literales legales
03	Fecha de expedición	16	Base imponible
04	Nombre o razón social del emisor	17	Cálculo de cuotas repercutidas
05	Nombre o razón social del receptor	18	Cálculo de cuotas retenidas
06	Identificación fiscal del emisor	19	Devolución de envases y embalajes
07	Identificación fiscal del receptor	20	Descuentos y bonificaciones posteriores a la operación
08	Domicilio del emisor	21	Resolución firme judicial o administrativa
09	Domicilio del receptor	22	Concurso de acreedores
10	Detalle de la operación	23	Créditos total o parcialmente incobrables
11	Porcentaje impositivo aplicado	24	Contraprestación fijada provisionalmente
12	Cuota tributaria aplicada	25	Resto de causas
13	Fecha o periodo de la operación

Formas de pago (payment_details[].payment_method_code)

Código	Descripción	Código	Descripción
01	Al contado	11	Cheque
02	Recibo domiciliado	12	Reposición
03	Recibo	13	Especiales
04	Transferencia	14	Compensación
05	Letra aceptada	15	Giro postal
06	Crédito documentario	16	Cheque conformado
07	Contrato de adjudicación	17	Cheque bancario
08	Letra de cambio	18	Contra reembolso
09	Pagaré a la orden	19	Tarjeta
10	Pagaré no a la orden

Unidades de medida (lines[].unit_of_measure)

Código	Unidad	Código	Unidad	Código	Unidad
01	Unidades	13	Botes	25	Metros
02	Horas	14	Tetra briks	26	Milímetros
03	Kilogramos	15	Centilitros	27	Packs de 6
04	Litros	16	Centímetros	28	Paquetes
05	Otros	17	Cubos	29	Raciones
06	Cajas	18	Docenas	30	Rollos
07	Bandejas	19	Estuches	31	Sobres
08	Barriles	20	Garrafas	32	Tarrinas
09	Bidones	21	Gramos	33	Metro cúbico
10	Bolsas	22	Kilómetros	34	Segundo
11	Bombonas	23	Latas	35	Vatio
12	Botellas	24	Manojos	36	Kilovatio hora

Un código que no está en el catálogo devuelve invalid_unit_of_measure.

Esquemas de identificador (identifiers[].scheme_id)

Código	Descripción
ES:VAT	NIF-IVA español (operaciones intracomunitarias)
ES:NIF	NIF español
EU:VAT	Número de IVA de otro país de la UE
GLN	Global Location Number
DUNS	Número D-U-N-S
VF:SUPPLIER	Identificador de proveedor en Faxtal
VF:CUSTOMER	Identificador de cliente en Faxtal
LOCAL:ERP	Identificador de tu ERP
LOCAL:CRM	Identificador de tu CRM
OTHER	Otros identificadores

identifiers[].role admite "tax", "vat", "legal", "local" y "other".

Errores de validación

Errores que impiden la operación:

Código HTTP	code	Causa
422	inferred_fields_not_allowed	El payload trae campos que calcula la API (lista en fields)
422	missing_required_fields	Falta un campo obligatorio de la operación, como invoice_series_code o meta.external_ref (lista en missing)
422	invoice_number_not_allowed	invoice_number en un borrador
422	issue_date_not_allowed	issue_date en un borrador
422	future_issue_date	issue_date futura al importar
422	schema_validation_failed	El payload no cumple el esquema. Cada error de errors trae su code (schema.required, schema.type, schema.enum, schema.additional_properties…) y su path.
422	validation_failed	Al emitir un borrador que tiene errores
409	invoice_update_not_allowed	La factura que corresponde a esa referencia ya no admite cambios (por ejemplo, ya está emitida)
409	invoice_race_condition	Otra petición está modificando la misma factura
409	received_invoice_fiscally_locked	La recibida tiene datos fiscales que ya no se pueden cambiar

Errores de contenido: al guardar un borrador o registrar una factura vuelven en errors, y al emitir impiden la emisión. Cada uno trae source, code, message y path. Algunos habituales:

code	Causa
customer_required	Emitida no simplificada sin receptor
customer_domicile_required	No se puede determinar la provincia de un receptor persona jurídica en España
tax_rate_unknown	El tipo no existe en el catálogo del grupo
exemption_reason_required	Operación exenta sin causa de exención
exemption_reason_unknown	Causa de exención que no está en el catálogo
tax_treatment_code_unknown	Tratamiento fiscal que no está en el catálogo
line_price_mode_mixed	Líneas con precio con y sin impuesto en la misma factura
invalid_unit_of_measure	Unidad de medida que no está en el catálogo
corrective_reason_required	Rectificativa emitida sin causa
corrective_substitution_amounts_required	Rectificación por sustitución sin base o cuota rectificada
invalid_tax_regime_key	Clave de régimen que no está en el catálogo
recc_key_mismatch	La clave 07 no cuadra con el criterio de caja de la empresa en el ejercicio de la operación (falta en una operación acogida o sobra en una que no lo está)
recc_margin_regime_not_supported	Criterio de caja (07) junto con un régimen de margen (03, 05)
oss_customer_outside_eu	Clave 17 con un destinatario de fuera de la UE
oss_foreign_consumption_must_be_non_subject	Clave 17 con destinatario de otro país de la UE (o sin destinatario) en una operación que no es no sujeta
oss_non_subject_reason_must_be_location_rules	Clave 17 no sujeta por un motivo distinto de LOCATION_RULES
oss_spanish_consumption_must_be_subject	Clave 17 con destinatario español en una operación no sujeta o exenta
oss_reverse_charge_not_allowed	Clave 17 con inversión del sujeto pasivo
oss_before_regime_start	Clave 17 con fecha de expedición u operación anterior al 1 de julio de 2021
oss_mixed_with_other_regimes	Factura con la clave 17 que incluye operaciones con otra clave
oss_regime_key_ambiguous	La clave 17 viene solo en taxes_outputs y no se puede asignar a las líneas no sujetas
consumption_tax_requires_oss_regime	Campos de IVA de consumo en una operación sin la clave 17
consumption_tax_requires_non_subject	IVA de otro Estado en una operación que no es no sujeta
consumption_country_required	Falta el Estado de consumo
consumption_country_must_not_be_es	El Estado de consumo es España
consumption_country_not_eu	El Estado de consumo no es de la Unión Europea
consumption_tax_rate_required	Cuota del Estado de consumo sin su tipo
consumption_tax_rate_invalid	Tipo fuera del rango 0-100
consumption_tax_amount_mismatch	La cuota no cuadra con la base por el tipo
oss_regime_not_registered	Emitida con la clave 17 sin un alta de la empresa en la ventanilla única que cubra la fecha de la operación, en el régimen que le corresponde (no sujeta: de la Unión o exterior; sujeta: de importación)

Avisos: vuelven en errors con severity: "warning" y no impiden guardar ni emitir.

code	Causa
oss_regime_not_effective	Emitida con la clave 17 cuya operación es anterior a la fecha de efecto del alta en la ventanilla única, o con el alta en trámite (modelo 035 sin presentar)
consumption_country_differs_from_customer	El Estado de consumo no coincide con el país del destinatario
consumption_tax_rate_unknown_for_country	El tipo no figura en el catálogo de ese Estado
consumption_rate_type_missing	Falta la clase del tipo, que el modelo 369 necesita
supply_type_missing	Falta indicar bienes o servicios, que el modelo 369 necesita

Ver también

• Conceptos: estados, series y numeración, idempotencia.
• Borradores
• Facturas emitidas
• Facturas recibidas
• Importación
• Referencia interactiva