ES
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 | SÍ | SÍ | ||
| BE | Bélgica | SÍ | SÍ | SÍ | |
| CH | Suiza | SÍ | SÍ | ||
| DE | Alemania | SÍ | SÍ | ||
| EE | Estonia | SÍ | |||
| EG | Egypt | SÍ | SÍ | SÍ | |
| ES | España | SÍ | SÍ | SÍ | SÍ |
| FI | Finlandia | SÍ | SÍ | ||
| FR | Francia | SÍ | SÍ | SÍ | SÍ |
| GB | Gran Bretaña | SÍ | SÍ | SÍ | |
| HU | Hungría | SÍ | SÍ | ||
| IE | Irlanda | SÍ | SÍ | SÍ | |
| IT | Italia | SÍ | SÍ | SÍ | SÍ |
| MC | Mónaco | SÍ | SÍ | SÍ | SÍ |
| MR | Mauritania | SÍ | SÍ | SÍ | |
| MT | Malta | SÍ | SÍ | ||
| NO | Noruega | SÍ | SÍ | ||
| PT | Portugal | SÍ | SÍ | SÍ | SÍ |
| SM | San Marino | SÍ | SÍ | SÍ | |
| CZ | República Checa | SÍ | SÍ | SÍ | |
| AL | Albania | SÍ | SÍ | ||
| SK | Eslovaquia | SÍ | SÍ | SÍ | |
| SI | Eslovenia | SÍ | SÍ | SÍ | |
| PL | Poland | SÍ | SÍ | SÍ | |
| PK | Pakistán | SÍ | SÍ | ||
| SE | Suecia | SÍ | SÍ | SÍ | |
| NL | Holanda | SÍ | SÍ |
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 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. |
| 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 |
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>