Esquemas

Esta guía tiene como objetivo proporcionar una visión clara y completa de los distintos esquemas de identificación (scheme) que rigen los códigos de empresa a través de la API de B2Brouter. Explica los conceptos de TIN, CIN, PIN y taxcode, así como los esquemas EAS e ICD y el campo country, para que cualquier integrador sepa exactamente qué información debe suministrar en cada escenario.

Cada número de identificación oficial de una empresa tiene un scheme correspondiente para indicar el tipo de TIN, CIN o PIN que representa.

Puedes revisar cada identificador usando el endpoint GET /schemes, que devuelve el número de scheme, si es un identificador fiscal y si está incluido en las listas de identificadores válidos de EAS e ICD.

Ejemplo de respuesta del endpoint /schemes:

{
  "code": "9914",
  "name": "UID",
  "country": "at",
  "eas": true,
  "icd": false,
  "taxcode": true
}

code: Número de identificación del scheme (en este caso 9914).
name: Nombre oficial del identificador (en este caso UID).
country: País correspondiente al identificador (at para Austria).
eas: Indica si pertenece a la lista EAS (en este caso true).
icd: Indica si pertenece a la lista ICD (en este caso false).
taxcode: Indica si el identificador es un TIN (true) o un CIN (false). Aquí, true significa que es un TIN (Tax Identification Number).

Definiciones básicas

TIN (Tax Identifier Number)

El identificador fiscal principal de una empresa, válido tanto para la facturación nacional como internacional. Para verificar si un identificador es el Tax Identifier Number de un país determinado, usa el endpoint de schemes de B2Brouter.

Para Europa, el portal VIES valida los identificadores de los estados miembros de la UE. Todos los TIN europeos comienzan con el código ISO del país.

Si "taxcode": true, el identificador se considera un TIN y puede usarse para la facturación fiscal.

Ejemplos:

NIF alemán (VAT ID):

"tin_scheme": 9930,
"tin_value": "DE123456789"

NIF español:

"tin_scheme": 9920,
"tin_value": "ESB12345678"

Número de IVA francés:

"tin_scheme": 9957,
"tin_value": "FR12345678901"

Partita IVA italiana:

"tin_scheme": 9906,
"tin_value": "IT12345678901"

Nota: Si el código de país ISO 3166-1 alpha-2 no está ya incluido en tin_value, se añadirá automáticamente al inicio al guardar un TIN.

CIN (Company Identifier Number)

Cualquier identificador de empresa válido que no sea el Tax Identifier Number, como identificadores de subdivisiones, administraciones públicas, cuentas bancarias, etc. Para crear una cuenta o un contact sin especificar un TIN, establece "taxcode": false. Todos los schemes con taxcode: false se tratan como CIN. Una empresa puede tener múltiples CIN.

Ejemplos:

SIRET francés:

"cin_scheme": 0009,
"cin_value": "1234567890"

Global Location Number (GLN):

"cin_scheme": 0088,
"cin_value": "1234567890"

Organisationsnummer sueco:

"cin_scheme": 0007,
"cin_value": "1234567890"

Nota: En Suecia, para facturar a nivel fiscal debes activar el booleano registered_for_empl_tax una vez aprobado para el F-tax.

PIN (Peppol Identifier Number)

Se usa para los términos de negocio “ID de dirección electrónica del vendedor” (BT‑34) y “ID de dirección electrónica del comprador” (BT‑49), donde scheme indica el scheme de identificación (p. ej., KVK con código 0088).

El identificador de empresa usado como dirección de buzón Peppol. Un PIN puede ser un TIN o un CIN, siempre que aparezca en la lista EAS. Puedes obtener los PIN a través del endpoint de schemes. Una empresa puede tener múltiples PIN y conectarse a Peppol a través de múltiples softwares de facturación.

Implementación:

Transporte Peppol: Añade tu PIN en la configuración de Transportes habilitando tu conexión Peppol. Referencia de la API - POST create-transport
Contacts y Facturas: Especifica un PIN al crear el contact o directamente en la factura. Referencia de la API - POST create-contact Ejemplo:

"pin_scheme": 0208,
"pin_value": "BCE/KBO/ZDU"

Schemes admitidos

EAS (EN 16931 – Electronic Address Scheme) Lista oficial de schemes de identificación de direcciones electrónicas reconocidos por el estándar europeo de facturación electrónica (EN 16931). Mantenida por Digital Europe (sucesora de CEF desde enero de 2022) y actualizada dos veces al año para añadir nuevos schemes o códigos ICD ISO 6523 relevantes para el direccionamiento electrónico. Esta lista habilita nuevos identificadores Peppol.
ICD (ISO 6523 – International Code Designator) Registro global de schemes de identificación de entidades mantenido por ISO. Cada autoridad de asignación (p. ej., registros gubernamentales o servicios de codificación) tiene un código numérico único (ICD). Sirve de base para la identificación única de organizaciones en todo el mundo, incluido Peppol. Muchos schemes EAS provienen de este catálogo, ya que solo las entradas ISO 6523 pueden promoverse a EAS.

Ejemplos:
- Número DUNS (D&B – global):
```
"cin_scheme": "0060",
"cin_value": "123456789"
```
- SIRENE francés:
```
"cin_scheme": "0002",
"cin_value": "12345678900000"
```
Schemes internos de B2Brouter Para países sin entradas oficiales en ISO 6523 ICD o EAS, B2Brouter define schemes internos. Estos códigos numéricos empiezan por 8XXX y permiten identificadores fiscales o comerciales no cubiertos por ningún registro global. Ten en cuenta que estos códigos pueden ser temporales hasta que se apruebe un scheme oficial.
Scheme universal (0001) Un scheme de reserva genérico para casos en que el ID fiscal de una empresa no pertenece a ningún scheme oficial reconocido (EAS, ISO 6523 ICD o interno). Puede usarse como tin_scheme o cin_scheme para identificadores nacionales o comerciales sin asignación formal.

Advertencia: Evita usar el scheme 0001 siempre que sea posible. Puede causar problemas de validación o legales si las autoridades exigen una codificación oficialmente regulada. Verifica siempre primero si existe un scheme oficial.

Ejemplos de uso de la API

Crear un transporte Peppol POST /accounts/{ACCOUNT_ID}/transports

{
  "transport": {
    "code": "peppol",
    "enabled": true,
    "reception": true,
    "pin_scheme": 9934,
    "pin_value": "123456789"
  }
}

Crear una cuenta con CIN POST /accounts

{
  "name": "Voorbeeld B.V.",
  "cin_scheme": "0106",
  "cin_value": "12345678",
  "country": "nl",
  "address": "Kerkstraat 12",
  "city": "Amsterdam",
  "postalcode": "1017 GM",
  "email": "john.doe@example.com"
}

Búsqueda en el directorio por scheme GET /directory/{scheme}/{value}

curl --request GET \
  --url https://api-staging.b2brouter.net/directory/9920/ESP0801900B \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'