API de validación de códigos BIC/SWIFT

Cómo integrar el API de validación de BIC en su software

1. ¿Qué es el API de validación de BIC?

Cuando procesa transferencias y tiene que manejar transacciones relacionadas con el IBAN, proporcionar el código BIC/SWIFT correcto es importante para efectuar pagos con éxito.
Nuestra empresa dispone de la licencia oficial del Directorio BIC de S.W.I.F.T SCRL para proporcionar una forma potente y sencilla de validación automática de BIC. Este servicio le permite integrar la búsqueda de códigos BIC en su software para fines internos.

El API de validación de BIC cuenta con datos de referencia SWIFT incorporados. Los datos de códigos BIC se usan con autorización de S.W.I.F.T. SCRL. Los derechos de la base de datos están reservados 2018

2. Características

Características clave del API de validación de BIC:

  • Obtiene información sobre el banco basándose en el BIC.
  • Busca en el directorio BIC con una parte del nombre del banco y el país.
  • Busca registros históricos en el Directorio BIC.
  • Utiliza una respuesta de API completa y simplificada para facilitar la integración.


3. Utilización del API

El API de validación de BIC está basado en REST y admite peticiones HTTP GET o POST simples.

Los parámetros aceptados se enumeran en la siguiente tabla:

Nombre del campo Longitud Tipo Descripción
bic 11 Cadena Código BIC/SWIFT a buscar. Puede tener 8 u 11 caracteres
bank_name 256 Cadena Parte del nombre de un banco para realizar una búsqueda en el directorio BIC.
country 2 Cadena Código de país de dos letras. Requerido cuando se busque por nombre de banco.
api_key 128 Cadena Su llave API personal.
format 4 Cadena Se requiere para especificar el formato de los datos devueltos. Valores admitidos actualmente: json, xml
limit Entero Opcional: se puede utilizar para limitar el número de resultados al buscar por nombre de banco.
hist Entero Opcional: se puede utilizar para visualizar registros históricos de la base de datos para la búsqueda de bancos y BIC.
Dentro del portal en línea puede encontrar la llave API y la URL de solicitud de punto de acceso, que se utiliza para proteger las solicitudes de búsqueda.


4. Estructura de respuesta XML del API

Puede descargar un Esquema XSD de la respuesta del API.
En la siguiente tabla puede ver una descripción detallada de los campos recibidos:

Nombre de campo Tipo Longitud Siempre presente Descripción
INDICADOR DE MODIFICACIÓN Alfabético 1 En archivos delta:
• A (adición)
• M (modificación)
• D (eliminación) en archivos llenos:
• A (adición)
CAMPO CAMBIADO Numérico 186 No Registra el campo (o ETIQUETA) que ha cambiado como resultado de una modificación de un registro o como resultado de un nuevo EVENTO.
Una o más columnas se indican como una secuencia de números y cada número representa la columna modificada desde la instancia de registro anterior o el evento anterior.
Ejemplo "6,7,8,9"
Esto significa que TIPO DE EVENTO, FECHA DE EVENTO, BIC8, y BIC DE SUCURSAL han
cambiado.
Los siguientes CAMPOS están excluidos de ser registrados en CAMPO CAMBIADO:
• LLAVE DE REGISTRO
• CAMPO CAMBIADO
• INDICADOR DE MODIFICACIÓN
LLAVE DE REGISTRO Alfanumérico 12 La llave única del registro en el archivo
Cada registro representa un evento en el ciclo de vida del BIC.
Una vez asignada, la LLAVE DE REGISTRO nunca cambia.
LLAVE DE REGISTRO ANTERIOR Alfanumérico 12 No La LLAVE DE REGISTRO del EVENTO enlazado anteriormente
Todos los eventos relacionados están enlazados y pueden ser localizados usando esta información.
LLAVE DE REGISTRO SIGUIENTE Alfanumérico 12 No La LLAVE DE REGISTRO del siguiente EVENTO enlazado
Todos los eventos relacionados están enlazados y pueden ser localizados usando esta información
TIPO DE EVENTO Alfabético 32 El EVENTO o la descripción de modificación relacionada con el BIC que se ha producido en el pasado, en el presente o que se producirá en el futuro.
Tipos de eventos:
• BIC EMITIDO
• BIC EXPIRADO
• BIC ACTIVADO EN FIN
• BIC ACTIVADO EN FA
• BIC ACTIVADO EN IA
• BIC DESACTIVADO EN FIN
• BIC DESACTIVADO EN FA
• BIC DESACTIVADO EN IA
• BIC DESACTIVADO
• BIC SUSPENDIDO
• BIC REACTIVADO
• BIC PUBLICADO
• NOMBRE LEGAL DE BIC MODIFICADO
• NOMBRE DE INSTITUCIÓN DE BIC MODIFICADO
• DIRECCIÓN DE BIC MODIFICADA
• CÓDIGO DE SERVICIO FIN MODIFICADO
La última fecha de actualización es la última línea de la secuencia BIC (es decir, la entrada más reciente).
Cuando se añade un EVENTO nuevo, el INDICADOR DE MODIFICACIÓN y la columna de CAMPO
CAMBIADO se actualizarán en el EVENTO previo inmediatamente relacionado.
FECHA DE EVENTO Alfanumérico 8 La fecha del EVENTO
BIC8 Alfanumérico 8 BIC (sufijo de institución, país, y parte) en el que:
• Prefijo de parte (4 caract)
• Código de país (2 caract)
• Sufijo de parte (2 caract)
BIC DE SUCURSAL Alfanumérico 3 El identificador de sucursal de BIC asociado con el BIC de 8 caracteres. Si no existe ningún identificador de sucursal, se utiliza XXX.
BIC Alfanumérico 11 El BIC completo: BIC de 8 caracteres e identificador de sucursal
ESTADO DE REGISTRO Alfabético 1 Indica el estado del registro:
• [C] = Current (actual): representa el último evento de la cadena hasta la fecha de publicación, excluyendo los eventos [F]uture
• [H] = Historical (histórico): registros históricos de la cadena de eventos
• [F] = Future (futuro): evento futuro que ocurrirá después de la fecha de publicación del directorio. El evento [C]urrent indicado anteriormente será válido hasta la fecha especificada en el evento [F]uture.
Para eventos FUTUROS, la fecha indica cuando el cambio será VÁLIDO DESDE.
REGISTRO OPERACIONALMENTE ACTIVO Alfa 1 Existen varios registros para el mismo BIC. Este campo indica cuál de los registros para el mismo BIC es el BIC activo operativamente y se debe utilizar.
• [Y] Operacionalmente activo
• [N] Operacionalmente inactivo
Para cada BIC único, hay una sola entrada de registro que indica un estado ACTIVO (Y).
Los registros con estado [H] siempre indicarán [N].
Los registros con estado [C] pueden indicar [Y] o [N].
Los registros con [F] siempre indican [N].
INDICADOR DE SUBTIPO Cualquier tipo 4 El tipo de negocio de la entidad. El subtipo Indicador solo se proporciona para registros con un BIC.
FIN SWIFT Alfabético 1 Estado de la conexión de una entidad con FIN:
• [Y] conectado con FIN
• [N] no conectado con FIN
FA SWIFT Alfabético 1 Estado de accesibilidad de una entidad a través de FileAct:
• [Y] conectado con FileAct
• [N] no conectado con FileAct
IA SWIFT Alfa 1 Estado de la accesibilidad de una entidad a través de InterAct:
• [Y] conectado con InterAct
• [N] no conectado con InterAct
NOMBRE LEGAL Cualquiera 105 No Nombre legal de la institución
NOMBRE DE LA INSTITUCIÓN Cualquiera 105 Nombre comercial de la institución (nombre publicado)
TIPO DE INSTITUCIÓN Alfabético 12 Organización que se dedica principalmente a la intermediación financiera o a actividades financieras auxiliares
Tipo de institución:
• FINANCIERA
• NO FINANCIERA
TIPO DE ENTIDAD Alfabético 16 Identifica el tipo de entidad financiera:
• Entidad legal
• Sucursal
• Operativa
DIRECCIÓN RE 1 Cualquiera 35 No Nombre de calle de [Registro]
DIRECCIÓN RE 2 Cualquiera 35 No Número de calle de [Registro]
DIRECCIÓN RE 3 Cualquiera 35 No Edificio, nombre edificio, piso de [Registro]
DIRECCIÓN RE 4 Cualquiera 35 No Área de [Registro]
CIUDAD RE Cualquiera 35 No Nombre de la ciudad de la institución o sucursal de [Registro]
PPE RE Cualquiera 90 No País, provincia, estado u otra región adiminstrativa de la institución o sucursal de [Registro]
CÓDIGO POSTAL RE Cualquiera 15 No Código postal de la institución o sucursal de [Registro]
NÚMERO DE OFICINA POSTAL RE Cualquiera 35 No Campo separado por comas con el número de POB (oficina postal) de la institución o sucursal y el código postal correspondiente.
Ejemplo
"POB 103352, 40024"
Esto permite a los clientes utilizar la dirección completa de oficina postal:
POB 103352
40024, DUESSELDORF (CIUDAD)
DIRECCIÓN OP 1 Cualquiera 35 No Nombre de calle de [Operaciones]
DIRECCIÓN OP 2 Cualquiera 35 No Número de calle de [Operaciones]
DIRECCIÓN OP 3 Cualquiera 35 No Edificio, nombre de edificio, piso de [Operaciones]
DIRECCIÓN OP 4 Cualquiera 35 No Área de [Operaciones]
CIUDAD OP Cualquiera 35 No Nombre de la ciudad de la institución o sucursal de [Operaciones]
PPE OP Cualquiera 90 No País, provincia, estado u otra región adiminstrativa de la institución o sucursal de [Operaciones]
CÓDIGO POSTAL DE OP Cualquiera 15 No Código postal de la institución o sucursal de [Operaciones]
NÚMERO DE POB DE OP Cualquiera 35 No Campo separado por comas con el número de POB (oficina postal) de la institución o sucursal y el código postal correspondiente.
Ejemplo
"POB 103352, 40024"
Esto permite a los clientes utilizar la dirección completa de oficina postal:
POB 103352
40024, DUESSELDORF (CITY)
DIRECCIÓN SUC 1 Cualquiera 35 No Nombre de calle de [Sucursal]
DIRECCIÓN SUC 2 Cualquiera 35 No Número de calle de [Sucursal]
DIRECCIÓN SUC 3 Cualquiera 35 No Edificio, nombre de edificio, piso de [Sucursal]
DIRECCIÓN SUC 4 Cualquiera 35 No Área de [Sucursal]
CIUDAD DE SUC Cualquiera 35 No Nombre de la ciudad de la institución o [Sucursal]
PPE SUC Cualquiera 90 No País, provincia, estado u otra región adiminstrativa de la institución o [Sucursal]
CÓDIGO POSTAL DE SUC Cualquiera 15 No Código postal de la institución o [Sucursal]
NÚMERO DE POB DE SUC Cualquiera 35 No Campo separado por comas con el número de POB (oficina postal) de la institución o sucursal y el código postal correspondiente.
Ejemplo
"POB 103352, 40024"
Esto permite a los clientes utilizar la dirección completa de oficina postal:
POB 103352
40024, DUESSELDORF (CITY)
INFORMACIÓN DE SUCURSAL Cualquiera 70 No Información de sucursal
Se trata de una descripción en texto libre de la sucursal proporcionada por la institución financiera a la que pertenece. Por el momento, esto solo se facilitará para las entradas con un BIC y únicamente cuando la institución financiera en cuestión desee proporcionar esta información adicional. La información proviene del directorio de BIC.
NOMBRE DE PAÍS Cualquiera 70 El nombre del país de la institución o sucursal, tal como se indica en la norma ISO 3166
CÓDIGO ISO DE PAÍS Alfabético 2 El código ISO 3166-1 alfa-2 del país de la institución o sucursal
CÓDIGO DE UBICACIÓN Cualquiera type 1 Contiene la ubicación (formalmente en la posición 7 del estándar BIC:2009)
Ejemplos:
• En FR, BIC en París = P
• En BE, BIC en Bruselas = B
• En US, BIC en la Costa Este = 3
CÓDIGOS DE SERVICIO DE FIN Cualquier tipo 60 No Códigos de servicio FIN (también llamados códigos de servicio de valor añadido). Los códigos de servicio se proporcionan solo para los registros que contienen un BIC.
El campo puede contener hasta 20 códigos de tres caracteres en orden alfabético.
LLAVE DE REGISTRO DE BDP Alfanumérico 12 No La llave única del registro Bank Directory Plus en el archivo.
CAMPO A Cualquiera 1 No Reservado para uso futuro
CAMPO B Cualquiera 64 No Reservado para uso futuro
CAMPO C Cualquiera 128 No Reservado para uso futuro
CAMPO D Cualquiera 256 No Reservado para uso futuro
CAMPO E Cualquiera 11 No Reservado para uso futuro
CAMPO F Cualquiera 12 No Reservado para uso futuro
El sistema API devuelve los resultados en formato XML, que es fácil de analizar en una variedad de lenguajes de programación y plataformas.

Una respuesta XML de ejemplo del API para una búsqueda de BIC sería:


<result>
<bicdata>
<row>
<modification_flag>A</modification_flag>
<changed_field>34</changed_field>
<record_key>BP0000004OQQ</record_key>
<previous_record_key>BP00000030XZ</previous_record_key>
<next_record_key/>
<event_type>BIC ADDRESS CHANGED</event_type>
<event_date>20150606</event_date>
<bic8>BARCGB22</bic8>
<branch_bic>XXX</branch_bic>
<bic>BARCGB22XXX</bic>
<record_status>C</record_status>
<operationally_active_record>Y</operationally_active_record>
<subtype_indicator>SUPE</subtype_indicator>
<swift_fin>Y</swift_fin>
<swift_fa>N</swift_fa>
<swift_ia>N</swift_ia>
<legal_name>BARCLAYS BANK PLC</legal_name>
<institution_name>BARCLAYS BANK PLC</institution_name>
<institution_type>FINANCIAL</institution_type>
<entity_type>Legal Entity</entity_type>
<re_street_address_1>1, CHURCHILL PLACE</re_street_address_1>
<re_street_address_2/>
<re_street_address_3/>
<re_street_address_4/>
<re_city>LONDON</re_city>
<re_cps/>
<re_zip_code>E14 5HP</re_zip_code>
<re_pob_number/>
<op_street_address_1>1 CHURCHILL PLACE</op_street_address_1>
<op_street_address_2/>
<op_street_address_3/>
<op_street_address_4/>
<op_city>LONDON</op_city>
<op_cps>LONDON E14 5HP</op_cps>
<op_zip_code/>
<op_pob_number/>
<br_street_address_1/>
<br_street_address_2/>
<br_street_address_3/>
<br_street_address_4/>
<br_city/>
<br_cps/>
<br_zip_code/>
<br_pob_number/>
<branch_information>(ALL U.K. OFFICES)</branch_information>
<country_name>UNITED KINGDOM</country_name>
<iso_country_code>GB</iso_country_code>
<location_code>2</location_code>
<fin_service_codes>EBAERPFINSCOSTGTGT</fin_service_codes>
<record_key_bdp>BD00000006FO</record_key_bdp>
<field_a/>
<field_b/>
<field_c/>
<field_d/>
<field_e/>
<field_f></field_f>
</row>
</bicdata>
<errors/>
</result>




5. Errores del API

En caso de error, la API devuelve una respuesta XML que contiene el mensaje de error.

Las etiquetas XML se devuelven sin ningún otro campo en la respuesta XML.

A continuación encontrará una descripción de todos los posibles mensajes de error que podrían devolverse:

Código de estado Tipoe Descripción
301 Error de cuenta La llave API no es válida
302 Error de cuenta Suscripción expirada
303 Error de cuenta No quedan consultas disponibles
304 Error de cuenta No tiene acceso a este API
401 Error de entrada Se acepta SWIFT de 8 u 11 caracteres de longitud
402 Error de entrada ¡Nombre del banco inválido! La búsqueda de banco debe tener un mínimo de 4 caracteres.
¡Los caracteres permitidos son a-z, A-Z, 0-9, [espacio]!
403 Error de entrada ¡Código de país incorrecto! Se admite el código de país de 2 letras. Ejemplo: UK, DE, FR