Documentación de la API de Cálculo IBAN



Guía de integración de la API


1. ¿Qué es la API de cálculo IBAN?


El motor de Cálculo IBAN (Alias Conversión de IBAN) es un sistema de software que permite a nuestros clientes convertir códigos de banco y combinaciones de números de cuentas nacionales en números de cuenta bancaria internacional validada (IBAN).

El sistema provee a nuestros clientes con una interfaz manual, así como una API para permitir la integración de los sistemas internos de su empresa.

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



2. Características


A continuación se presentan algunas de las características clave de nuestro motor de Cálculo IBAN:




3. Países admitidos


Actualmente la API de Cálculo IBAN soporta los siguientes países y los campos requeridos por nuestra API para calcular un IBAN.

~`
Código de país Nombre del país Codigo bancario Sucursal Cuenta Código de control
AT Austria SI   SI  
BE Bélgica SI   SI SI
CH Suiza SI   SI  
DE Alemania SI   SI  
EE Estonia     SI  
ES España SI SI SI SI
FI Finlandia     SI SI
FR Francia SI SI SI SI
GB Gran Bretaña SI   SI SI
HU Hungría     SI SI
IE Irlanda SI   SI SI
IT Italia SI SI SI SI
MC Monaco SI SI SI SI
MR Mauritania SI SI SI  
MT Malta SI   SI  
NO Noruega     SI SI
PT Portugal SI SI SI SI
SE Suecia SI   SI  
SM San  Marino SI SI SI  
CZ República Checa SI   SI SI
AL Albania SI   SI  
SK República Eslovaca SI   SI SI
SI Eslovenia SI   SI SI
PL Polonia SI   SI SI
SE Suecia SI   SI SI
NL Netherlandds SI SI
La columna del dígito verificador especifica si el país admite el número de cuenta y/o la validación de código bancario para el dígito verificador.

La validación de los dígitos verificadores es una capa adicional de protección a la integridad de datos contra errores de escritura.



4. Entradas de la API


La API acepta solicitudes tanto HTTP GET y POST para los datos de entrada.
Los parámetros aceptados se listan en la tabla siguiente:

Nombre del campo Tipo Descripción
api_key Cadena Tu clave personal de la API. Obtenida en el área de cliente.
formato Cadena Formato de respuesta de la API ( xml or json )
país Cadena Código de país en dos letras ( UK/US/DE/FR )
codigo bancario Cadena Un identificador bancario único. Diferente para cada país. ( opcional ). Algunos países sólo requieren el número de cuenta.
sucursal Cadena Un identificador de sucursal local único ( opcional )
cuenta Cadena Número de cuenta personal
dc Entero Los dígitos verificadores son utilizados en algunos países.
prefijo Entero Actualmente se requiere sólo para la República Checa ( opcional )
El primer argumento es la clave de la API, se trata de una cadena única que ayuda a nuestro sistema a identificarte como usuario y permitirte el acceso a la API.

La API es compatible con múltiples formatos de respuesta con el fin de proporcionar una integración más fácil. Actualmente, XML y JSON son compatibles.

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

El Código de Sucurscal es un argumento opcional y sólo se requiere para algunos países (véase ejemplos)
El número de cuenta se requiere para todos los países y en algunos casos es el único parámetro que se utiliza para calcular un IBAN.

Los dígitos verificadores se requieren sólo para ciertos países que han incorporado este tipo de algoritmos de validación en su estructura del número de cuenta de banco local. (véase ejemplos)

El Prefijo es un campo opcional que es requerido sólo para el cálculo del IBAN en la República Checa.



5. Ejemplos de la API


En la siguiente tabla se puede encontrar un ejemplo utilizando la consulta GET a nuestra API para cada país.

País Ejemplo de consulta (GET REQUEST)
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&Sucursal=1731&cd=91&account=0006040912
FI ?country=FI&format=json&account=52900261901092
FR ?country=FR&format=json&bankcode=30056&Sucursal=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&Sucursal=30545&account=000103685854
MC ?country=MC&format=json&country=MC&bankcode=30002&Sucursal=03260&account=0000079112A
MR ?country=MR&format=json&bankcode=00012&Sucursal=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&Sucursal=0000&cd=81&account=39551148771
SE ?country=SE&format=json&bankcode=9150&account=0092395696
SM ?country=SM&format=json&country=SM&bankcode=03034&Sucursal=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 de la API


Una descripción detallada de los posibles campos devueltos puede verse en la tabla siguiente:

Nombre del campo Tipo Descripción
dirección Cadena Dirección de la sucursal del banco o de la sede
banco Cadena Nombre del banco o institución financiera
bic Cadena BIC ( Código de Identificación Bancaria ) del banco
sucursal Cadena Nombre de la sucursal identificada por el código del banco
ciudad Cadena El nombre de la ciudad en la que esté situada la sucursal.
país Cadena Abreviatura de dos letras del código de país e.g. US, UK, AU, FR … etc.
email Cadena Dirección de correo electrónico de contacto para el banco o sucursal
fax Cadena Número de fax del banco/sucursal
teléfono Cadena Teléfono de contacto del banco/sucursal
estado Cadena Estado de la dirección del banco/sucursal
sitio web Cadena Dirección del sitio web del banco/sucursal
zip Cadena Código postal de la dirección de la sucursal bancaria
El sistema de la API devuelve los resultados en XML o formato JSON, los cuales son fácil de analizar en una variedad de lenguajes y plataformas de programación.

Una muestra de una respuesta XML de la API para una búsqueda de código SORT y número de cuenta del 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>
<Sucursal>BELFAST CITY OFFICE 1</Sucursal>
<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 especifica un formato JSON será:

"iban":"GB20ULSB98006054100029","account":"54100029","sort_code":"980060","bank":"ULSTER BANK LTD","Sucursal":"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 de la API


En caso de un error, la API de cálculo del IBAN devuelve una respuesta XML o JSON que contiene el mensaje de error.
El <error></error> de las etiquetas de XML es devuelto sin otros campos en la respuesta XML.
A continuación puedes encontrar una descripción de todos los mensajes de error posibles que podrían ser devueltos:

<error>La suma de comprobación del número de cuenta no es válida.</error>
<error>El número de cuenta (suma de comprobación) no es correcto.</error>
<error>El número de cuenta tiene que ser de 11 caracteres de longitud</error>
<error>El número de cuenta tiene que ser de 14 caracteres de longitud</error>
<error>El número de cuenta tiene que ser de 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 clasificación 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>El código / KIB (suma de comprobación) del Banco/Sucurscal no es correcto.</error>
<error>El Código de Banco/ Código de Sucursal/ Número de cuenta es demasiado largo.</error>
<error>El Código de Banco/ Código de Sucursal (suma de comprobación) no es correcto.</error>
<error>El Código de Banco es inválido</error>
<error>El Código de Banco es demasiado largo.</error>
<error>Banco no encontrado</error>
<error>Banco no reconocido</error>
<error>BBAN / NIB (suma de comprobación) incorrecto.</error>
<error>El BLZ/Código de Banco es inválido</error>
<error>Sucursal/Agencia no encontrada</error>
<error>El Código de Sucursal es demasiado largo.</error>
<error>Sucursal no encontrada</error>
<error>El Dígito Verificador es demasiado largo.</error>
<error>El Clearingnummer / Número de cuenta no es válido. Dígito verificador incorrecto.</error>
<error>El Clearingnummer / Código Bancario no puede ser identificado. El IBAN no puede ser calculado.</error>
<error>El Clearingnummer o Número de cuenta es demasiado largo.</error>
<error>Codice ABI della Banca/Código Bancario inválido</error>
<error>Codice CAB della Filiale/Código de Sucursal inválido</error>
<error>El código de país no es válido</error>
<error>País o Banco incompatible</error>
<error>El IBAN no es válido</error>
<error>El Kontonummer/Número de cuenta no es válido</error>
<error>Campos faltantes</error>
<error>IBAN no es FR</error>
<error>País que no es IBAN FR</error>
<error>Campos obligatorios requeridos. Por favor ingrese el Código Bancario y Número de cuenta</error>
<error>Los campos obligatorios no se han enviado.</error>
<error>RIB inválido</error>
<error>El Código de clasificación / Código bancario no puede ser identificado. El IBAN no puede ser calculado.</error>
<error>El Código de clasificación no pudo ser encontrado</error>