> ## Documentation Index
> Fetch the complete documentation index at: https://www.finseed.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Identificador fiscal en Stripe Billing

> Proporciona el identificador fiscal del destinatario en las facturas de Stripe Billing mediante los campos estándar de Stripe o mediante metadatos, incluyendo el tipo y el país del documento para clientes sin NIF.

En Stripe Billing, Finseed obtiene el identificador fiscal del destinatario directamente de la factura de Stripe y lo incluye automáticamente al generar la factura Verifactu.

Los tipos de identificador fiscal que admite Stripe son limitados y no cubren todos los casos. No hay tipos pensados para el DNI de un particular ni para documentos extranjeros como el pasaporte. Para estos casos, puedes indicar el identificador fiscal mediante metadatos en la factura de Stripe.

## Proporcionar el identificador fiscal mediante los campos predeterminados

Stripe admite los siguientes tipos de identificador fiscal para clientes españoles a través de `customer_tax_ids`:

* **`es_cif`**: NIF o CIF español. Úsalo para empresas y autónomos españoles con número de identificación fiscal español.
* **`eu_vat`**: Número de IVA intracomunitario con prefijo de país (por ejemplo, `ESB12345678`). Úsalo para clientes con número de operador intracomunitario, incluidos los españoles.

Para clientes de otros países de la UE, el tipo de identificador sigue el patrón `xx_vat`, donde `xx` es el código de país ISO en minúsculas (por ejemplo, `de_vat` para Alemania, `fr_vat` para Francia).

```javascript theme={null}
await stripe.customers.createTaxId('cus_123', {
  type: 'es_cif',
  value: 'B12345678'
})
```

Cuando el cliente tiene un identificador asignado en Stripe, Finseed lo incluye automáticamente en la factura Verifactu sin necesidad de configuración adicional.

## Proporcionar el identificador fiscal mediante metadatos

Puedes añadir el campo `ev_recipient_tax_id` al objeto `metadata` de la **factura** de Stripe o al objeto `metadata` del **cliente** de Stripe. Su valor puede ser un NIF, DNI, NIE, CIF, un número de IVA intracomunitario o el número de un documento extranjero, como un pasaporte.

Para una factura concreta, añade el metadato a la factura:

```javascript theme={null}
const invoice = await stripe.invoices.create({
  customer: 'cus_123',
  metadata: {
    ev_recipient_tax_id: '46766201W'
  }
})
```

Para que se aplique a todas las facturas que genere un cliente, añade el metadato al cliente:

```javascript theme={null}
await stripe.customers.update('cus_123', {
  metadata: {
    ev_recipient_tax_id: '46766201W'
  }
})
```

Configurarlo en el cliente es especialmente útil con suscripciones y facturación recurrente: lo defines una sola vez y se aplica a todas las facturas que el cliente genere, incluidas las renovaciones que Stripe crea automáticamente, sin tener que indicarlo en cada factura.

Cuando este metadato está presente, lo usamos como identificador fiscal del destinatario en la factura Verifactu, **con prioridad sobre el identificador que Stripe guarda en la factura** (`customer_tax_ids`).

## Indicar el tipo y el país del documento

Cuando el identificador no es un documento español, Finseed necesita saber qué tipo de documento es y de qué país. El caso más habitual es un cliente extranjero sin NIF ni NIE, al que identificas en la factura con su pasaporte: el número de un pasaporte no sigue un formato que Finseed pueda reconocer automáticamente, así que hay que declararlo.

Junto a `ev_recipient_tax_id` puedes añadir dos metadatos que declaran el tipo y el país del documento:

* **`ev_recipient_tax_id_type`**: tipo de documento. Los valores no distinguen mayúsculas de minúsculas.
* **`ev_recipient_tax_id_country`**: país del documento, en código de dos letras ISO 3166-1 (por ejemplo, `FR` para Francia).

Los valores admitidos para `ev_recipient_tax_id_type` son los mismos que en la [API de Finseed](/docs/api-reference/creating-invoices):

* **`es_nif`**: NIF español, incluidos DNI y NIE.
* **`eu_vat`**: número de IVA intracomunitario.
* **`passport`**: pasaporte.
* **`official_document`**: documento oficial de identificación expedido por el país de residencia.
* **`residence_certificate`**: certificado de residencia.
* **`other`**: otro documento acreditativo.
* **`not_registered`**: cliente no censado en la Agencia Tributaria.

Por ejemplo, para un cliente con dirección de facturación en España identificado con un pasaporte francés:

```javascript theme={null}
const invoice = await stripe.invoices.create({
  customer: 'cus_123',
  metadata: {
    ev_recipient_tax_id: '18AB12345',
    ev_recipient_tax_id_type: 'passport',
    ev_recipient_tax_id_country: 'FR'
  }
})
```

Igual que con `ev_recipient_tax_id`, también puedes definir estos metadatos en el cliente de Stripe para que se apliquen a todas sus facturas. La validación censal (la comprobación del NIF contra el censo de la Agencia Tributaria) solo se aplica a los NIF españoles, así que no interviene con el tipo `passport`.

Estos metadatos siguen estas reglas:

* **Los tres metadatos van juntos.** Solo leemos `ev_recipient_tax_id_type` y `ev_recipient_tax_id_country` del mismo objeto `metadata` que aporta `ev_recipient_tax_id`. Un tipo o país declarado sin `ev_recipient_tax_id` a su lado se ignora.
* **Tipo y país se indican juntos, o se omiten los dos.** Si solo indicas uno, el pedido (el registro que Finseed crea a partir de la factura de Stripe) aparece como "Bloqueado" con un mensaje que explica el problema, antes de emitir ninguna factura. Puedes resolverlo desde la página de detalle del pedido, sobrescribiendo los datos del destinatario y reprocesando, o corrigiendo los metadatos en Stripe y reprocesando el pedido.
* **Si omites los dos**, Finseed detecta automáticamente el tipo y el país a partir del formato del identificador y del país del cliente. Si no puede determinarlos, el pedido queda bloqueado con un mensaje que lo explica.
* **Si `ev_recipient_tax_id_type` contiene un valor no reconocido**, lo tratamos como si no estuviera presente. Si además indicaste el país, se aplica la regla anterior y el pedido queda bloqueado.

Estos metadatos funcionan igual en Stripe Payments: se leen del objeto `metadata` del PaymentIntent y, en su defecto, del cliente. Consulta la [configuración de Stripe Payments](/docs/stripe/stripe-payments-configuracion).

## Cómo se determina el identificador fiscal

Al generar la factura Verifactu resolvemos el identificador fiscal en este orden, y usamos el primer valor no vacío que encontramos:

1. **Metadato `ev_recipient_tax_id`** de la factura de Stripe, si está presente y no está vacío.
2. **Metadato `ev_recipient_tax_id`** del cliente de Stripe, en caso contrario.
3. **Identificador fiscal de la factura de Stripe** (`customer_tax_ids`, la copia de los identificadores del cliente que Stripe guarda en la factura al finalizarla), si no hay ninguno de los metadatos anteriores.

Si un metadato está vacío o solo contiene espacios, lo ignoramos y pasamos a la siguiente fuente. Si no hay ninguna de las tres, la factura se emite sin identificador fiscal.

El tipo y el país declarados (`ev_recipient_tax_id_type` y `ev_recipient_tax_id_country`) acompañan a la fuente que gana: solo los leemos del mismo objeto `metadata` que aporta el identificador. Si el identificador procede de `customer_tax_ids`, el tipo y el país se detectan automáticamente.

En Stripe Billing, el resto de los datos del destinatario (nombre, dirección, país) se toman automáticamente de la factura de Stripe. Los metadatos `ev_recipient_tax_id*` solo afectan al identificador fiscal.

Para entender cuándo es obligatorio incluir el identificador fiscal y cuándo puedes emitir una factura simplificada, consulta [Facturas simplificadas y completas](/docs/verifactu/facturas-simplificadas-completas).

## Solución de problemas

Si el identificador o el tipo declarado no llegan a la factura Verifactu:

* **Para suscripciones y renovaciones, define los metadatos en el cliente.** Stripe finaliza las facturas de renovación automáticamente, sin intervención manual, por lo que es fácil que la factura se finalice antes de que llegues a editarla. Los metadatos del cliente se aplican a todas las facturas que genere.