Esquemes

Aquesta guia pretén proporcionar una visió general clara i completa dels diversos esquemes d’identificació (scheme) que governen els codis d’empresa via l’API de B2Brouter. Explica els conceptes de TIN, CIN, PIN i taxcode, així com els esquemes EAS i ICD i el camp country, de manera que qualsevol integrador sàpiga exactament quina informació ha de proporcionar en cada escenari.

Cada número d’identificació oficial d’empresa té un esquema corresponent per indicar el tipus de TIN, CIN o PIN que representa.

Podeu revisar cada identificador usant l’endpoint GET /schemes, que retorna el número d’esquema, si és un identificador fiscal i si es troba a les llistes d’identificadors vàlids d’EAS i ICD.

Resposta d’exemple de l’endpoint /schemes:

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

code: Número d’identificació de l’esquema (en aquest cas 9914).
name: Nom oficial de l’identificador (en aquest cas UID).
country: País corresponent a l’identificador (at per a Àustria).
eas: Indica si pertany a la llista EAS (en aquest cas true).
icd: Indica si pertany a la llista ICD (en aquest cas false).
taxcode: Indica si l’identificador és un TIN (true) o CIN (false). Aquí, true significa que és un TIN (Tax Identification Number).

Definicions bàsiques

TIN (Tax Identifier Number)

L’identificador fiscal principal d’una empresa, vàlid tant per a la facturació nacional com internacional. Per verificar si un identificador és el Tax Identifier Number d’un país determinat, useu l’endpoint d’esquemes de B2Brouter.

Per a Europa, el portal VIES valida els identificadors dels estats membres de la UE. Tots els TIN europeus comencen amb el codi ISO del país.

Si "taxcode": true, l’identificador es considera un TIN i es pot usar per a la facturació fiscal.

Exemples:

NIF alemany:

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

NIF espanyol:

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

Número de TVA francès:

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

Partita IVA italiana:

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

Nota: Si el codi de país ISO 3166-1 alpha-2 no està ja inclòs al tin_value, s’afegirà automàticament al principi en desar un TIN.

CIN (Company Identifier Number)

Qualsevol identificador d’empresa vàlid diferent del Tax Identifier Number, com ara identificadors per a subdivisions, administracions públiques, comptes bancaris, etc. Per crear un compte o contacte sense especificar un TIN, definiu "taxcode": false. Tots els esquemes amb taxcode: false es tracten com a CIN. Una empresa pot tenir múltiples CIN.

Exemples:

SIRET francès:

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

Global Location Number (GLN):

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

Organisationsnummer suec:

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

Nota: A Suècia, per facturar a nivell fiscal heu d’activar el booleà registered_for_empl_tax un cop aprovada la F-tax.

PIN (Peppol Identifier Number)

S’usa per als termes de negoci “Seller electronic address ID” (BT‑34) i “Buyer electronic address ID” (BT‑49), on scheme indica l’esquema d’identificació (per exemple, KVK amb codi 0088).

L’identificador d’empresa usat com a adreça de bústia Peppol. Un PIN pot ser un TIN o un CIN, sempre que aparegui a la llista EAS. Podeu recuperar els PIN via l’endpoint d’esquemes. Una empresa pot tenir múltiples PIN i connectar-se a Peppol a través de múltiples programaris de facturació.

Implementació:

Transport Peppol: Afegiu el vostre PIN a la configuració de Transports activant la vostra connexió Peppol. Referència API - POST create-transport
Contactes i factures: Especifiqueu un PIN en crear el contacte o directament a la factura. Referència API - POST create-contact Exemple:

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

Esquemes admesos

EAS (EN 16931 – Electronic Address Scheme) Llista oficial d’esquemes d’identificadors d’adreces electròniques reconeguts per l’estàndard europeu de facturació electrònica (EN 16931). Mantinguda per Digital Europe i actualitzada dues vegades l’any.
ICD (ISO 6523 – International Code Designator) Registre global d’esquemes d’identificadors d’entitats mantingut per ISO. Cada autoritat assignadora té un codi numèric únic (ICD). Serveix de base per a la identificació única d’organitzacions a tot el món, inclòs Peppol.

Exemples:
- Número DUNS (D&B – global):
```
"cin_scheme": "0060",
"cin_value": "123456789"
```
- SIRENE francès:
```
"cin_scheme": "0002",
"cin_value": "12345678900000"
```
Esquemes interns de B2Brouter Per als països sense entrades oficials d’ISO 6523 ICD o EAS, B2Brouter defineix esquemes interns. Aquests codis numèrics comencen amb 8XXX i permeten identificadors fiscals o comercials no coberts per cap registre global.
Esquema universal (0001) Un esquema de reserva genèric per als casos en que l’ID fiscal d’una empresa no pertany a cap esquema oficial reconegut (EAS, ISO 6523 ICD o intern).

Avís: Eviteu usar l’esquema 0001 sempre que sigui possible. Pot causar problemes de validació o legals si les autoritats requereixen codificació regulada oficialment. Comproveu sempre primer si existeix un esquema oficial.

Exemples d’ús de l’API

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

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

Crear un compte amb 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"
}

Cerca al directori per esquema 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'