Documentación del API de la calculadora de IBAN

Este API es parte de nuestro servicio IBAN Suite

Guía de integración del API

1. ¿Qué es el API de calculadora de IBAN?

El motor de cálculo de IBAN (también conocido como conversión IBAN) es un sistema de software que permite a nuestros clientes convertir combinaciones de códigos bancarios y números de cuenta nacionales en números de cuenta bancarios internacionales validados (IBAN).

El sistema permite a nuestros clientes una interfaz manual además de un API que permite la integración en los sistemas internos de su empresa.

El sistema también identifica a los bancos e instituciones financieras y proporciona los detalles a nuestros clientes.

2. Características

A continuación están algunas de las características clave de nuestro motor de cálculo de IBAN:

  • Valida las checksum del código bancario o número de cuenta local (*ver países admitidos)
  • Recupera información sobre el banco basada en el código del banco o sucursal local.
  • Genera automáticamente un formato IBAN válido para el código de banco o sucursal y el número de cuenta suministrados.
  • El sistema admite múltiples formatos de respuesta (JSON/XML)


3. Países admitidos

El API de cálculo de IBAN admite actualmente los siguientes países y los campos requeridos por nuestro API para calcular un IBAN.

Código de país Nombre de país Código bancario Sucursal Cuenta Dígito de verificación **
AT Austria    
BE Bélgica  
CH Suiza    
DE Alemania    
EE Estonia      
ES España
FI Finlandia    
FR Francia
GB Gran Bretaña  
HU Hungría    
IE Irlanda  
IT Italia
MC Mónaco
MR Mauritania  
MT Malta    
NO Noruega    
PT Portugal
SM San Marino  
CZ República Checa  
AL Albania    
SK Eslovaquia  
SI Eslovenia  
PL Poland  
PK Pakistán    
SE Suecia  
NL Holanda
La columna de dígito de verificación especifica si el país admite la validación de dígitos de control de número de cuenta o código bancario.

La validación de los dígitos de verificación es una capa adicional de protección de la integridad de los datos contra errores tipográficos.

4. Entradas del API

El API acepta tanto peticiones HTTP GET como POST para datos de entrada.
Los parámetros aceptados se enumeran en la tabla siguiente:

Nombre del campo Tipo Descripción
api_key Cadena Su llave API personal. Se obtiene en el área de clientes.
format Cadena Formato de respuesta de API (xml o json)
country Cadena Código de país de 2 letras (UK/US/DE/FR)
bankcode Cadena Un identificador único del banco. Diferente para cada país (opcional). Algunos países solo requieren un número de cuenta.
branch Cadena Un identificador único de sucursal local (opcional)
account Cadena Número de cuenta personal
cd Entero Dígitos de verificación que se usan en algunos países.
prefix Entero Actualmente solo se requiere para la República Checa (opcional)
El primer argumento es la llave API, esta es una cadena única que ayuda a nuestro sistema a identificarlo como usuario y le permite acceder al API.

El API admite varios formatos de respuesta para facilitar la integración. Actualmente, se admiten XML y JSON.

Los argumentos de país deben consistir en un código de país ISO de 2 letras como UK para el Reino Unido, DE para Alemania, FR para Francia...
El código bancario tiene una longitud y estructura diferente para cada país.

El código de sucursal es un argumento opcional que solo se requiere para algunos países (consulte Ejemplos).
El número de cuenta es obligatorio para todos los países y, en algunos casos, es el único parámetro utilizado para calcular un IBAN.

Los dígitos de verificación solo se requieren para ciertos países que han incorporado dichos algoritmos de validación en su estructura de número de cuenta bancaria nacional (ver ejemplos).

El prefijo es un campo requerido opcionalmente solo para el cálculo del IBAN de la República Checa.

5. Ejemplos del API

En la siguiente tabla puede encontrar el ejemplo de consulta GET de nuestro API para cada país.

País Consulta de ejemplo (SOLICITUD GET)
AT ?country=AT&format=json&bankcode=12000&account=52700357958
BE ?country=BE&format=json&bankcode=250&account=0135106&cd=70
CH ?country=CH&format=json&bankcode=0240&account=240C08011570
DE ?country=DE&format=json&bankcode=BLZ37010050&account=399509
EE ?country=EE&format=json&account=55000005511439
ES ?country=ES&format=json&bankcode=0081&branch=1731&cd=91&account=0006040912
FI ?country=FI&format=json&account=52900261901092
FR ?country=FR&format=json&bankcode=30056&branch=00264&account=02640016443
GB ?country=GB&format=json&bankcode=090127&account=93496333
HU ?country=HU&format=json&account=107000240416330551100005
IE ?country=IE&format=json&bankcode=905838&account=71924374
IT ?country=IT&format=json&country=IT&bankcode=02008&branch=30545&account=000103685854
MC ?country=MC&format=json&country=MC&bankcode=30002&branch=03260&account=0000079112A
MR ?country=MR&format=json&bankcode=00012&branch=00001&account=00000078326
MT ?country=MT&format=json&bankcode=07113&account=199008240010
NO ?country=NO&format=json&account=96803502045
PT ?country=PT&format=json&bankcode=0038&branch=0000&cd=81&account=39551148771
PK ?country=PK&format=json&bankcode=HABBPKKA&account=39551148771
SE ?country=SE&format=json&bankcode=9150&account=0092395696
SM ?country=SM&format=json&country=SM&bankcode=03034&branch=09800&account=000060164676
CZ ?country=CZ&format=json&prefix=51&account=1707230277&bankcode=0100
AL ?country=AL&format=json&bankcode=20511117&account=374362CLPRCFEURC
SK ?country=SK&format=json&prefix=&account=4110053902&bankcode=3100
SI ?country=SI&format=json&bankcode=33000&account=0000102423
PL ?country=PL&format=xml&bankcode=11402004&account=0000360275244226
SE ?country=SE&format=json&bankcode=9300&account=5913222524
NL ?country=NL&format=json&account=0006642318

6. Estructura de respuesta XML del API

En la siguiente tabla puede ver una descripción detallada de los posibles campos devueltos:

Nombre del campo Tipo Descripción
address Cadena Dirección de la sucursal bancaria o de la sede central
bank Cadena Nombre del banco o de la institución financiera
bic Cadena BIC (código de identificación del banco) del banco
branch Cadena Nombre de la sucursal identificada por el código bancario
city Cadena El nombre de la ciudad en la que se encuentra la sucursal.
country Cadena Abreviatura de dos letras del código de país, por ejemplo: US, UK, AU, FR … etc.
email Cadena Dirección de correo electrónico de contacto designada para el banco o sucursal
fax Cadena Número de fax del banco o la sucursal
phone Cadena Número de contacto del banco o la sucursal
state Cadena Estado de la dirección del banco o la sucursal
website Cadena Dirección web del banco o la sucursal
zip Cadena Código postal de la dirección de la sucursal bancaria
El sistema API devuelve los resultados en formato XML o JSON, que son fáciles de analizar en una variedad de lenguajes de programación y plataformas.

Una respuesta XML de ejemplo del API para una búsqueda de código SORT y número de cuenta en el Reino Unido sería:

URL de consulta:

?api_key=9834hAHx78ba4g8habsdk&country=GB&format=json&bankcode=110377&account=10218962

<result>
<iban>GB20ULSB98006054100029</iban>
<account>54100029</account>
<sort_code>980060</sort_code>
<bank>ULSTER BANK LTD</bank>
<branch>BELFAST CITY OFFICE 1</branch>
<bic>ULSBGB2BXXX</bic>
<address>PO BOX 232 11-16 DONEGALL SQUARE EAST </address>
<city>BT1 5UB</city>
<country>GB<country/>
<phone>028 90244112</phone>
</result>

La respuesta para la misma consulta si el usuario especificó un formato JSON será:

"iban":"GB20ULSB98006054100029","account":"54100029","sort_code":"980060","bank":"ULSTER BANK LTD","branch":"BELFAST CITY OFFICE 1","bic":"ULSBGB2BXXX","address":"PO BOX 232 11-16 DONEGALL SQUARE EAST ","city":"BT1 5UB","country":"GB","phone":"028 90244112"

7. Errores del API

En caso de error, el API de cálculo IBAN devuelve una respuesta XML o JSON que contiene el mensaje de error.
Las etiquetas XML <error></error> se devuelven sin otros campos en la respuesta XML.
A continuación encontrará una descripción de todos los posibles mensajes de error que podrían devolverse:

<error>La checksum del número de cuenta es inválida.</error>
<error>La checksum del número de cuenta no es correcta.</error>
<error>El número de cuenta debe tener 11 caracteres de longitud</error>
<error>El número de cuenta debe tener 14 caracteres de longitud</error>
<error>El número de cuenta debe tener 24 caracteres de longitud</error>
<error>El número de cuenta no es válido</error>
<error>El número de cuenta del código de sucursal no es válido</error>
<error>El prefijo del número de cuenta es demasiado largo.</error>
<error>El número de cuenta es demasiado largo.</error>
<error>Checksum de código bancario o de sucursal no es correcto.</error>
<error>El número de cuenta, código bancario o código de sucursal es demasiado largo.</error>
<error>La checksum del código bancario o de sucursal no es correcto.</error>
<error>El código bancario no es válido</error>
<error>El código bancario es demasiado largo.</error>
<error>Banco no encontrado</error>
<error>Banco no reconocido</error>
<error>La checksum del BBAN/NIBno es correcta.</error>
<error>El código bancario o BLZno es válido</error>
<error>Sucursal no encontrada</error>
<error>El código de sucursal demasiado largo.</error>
<error>Sucursal no encontrada</error>
<error>El dígito de verificación demasiado largo.</error>
<error>El número de cuenta o de compensación no es válido.</error>
<error>No se pudo identificar el código bancario o el número de compensación. No se pudo calcular el IBAN.</error>
<error>El número de cuenta o de compensación es demasiado largo.</error>
<error>El código bancario ABI o código bancario no válido</error>
<error>El código CAB de la sucursal o código de la sucursal no válido</error>
<error>El código de país no es válido</error>
<error>No se admite el país o banco</error>
<error>El IBAN no es válido</error>
<error>El número de cuenta no es válido</error>
<error>Faltan campos</error>
<error>IBAN no válido para FR</error>
<error>País de IBAN no FR</error>
<error>Falta un campo obligatorio. Ingrese el código bancario y el número de cuenta</error>
<error>Hay campos obligatorios sin enviar.</error>
<error>El RIB no es válido</error>
<error>No se puede identificar el código de sucursal o código bancario. No se puede calcular el IBAN.</error>
<error>No se pudo encontrar el código de sucursal</error>