ES
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. |
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 | Sí | 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 | Sí | 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 | Sí | 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 | Sí | La fecha del EVENTO |
| BIC8 | Alfanumérico | 8 | Sí | 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 | Sí | 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 | Sí | El BIC completo: BIC de 8 caracteres e identificador de sucursal |
| ESTADO DE REGISTRO | Alfabético | 1 | Sí | 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 | Sí | 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 | Sí | El tipo de negocio de la entidad. El subtipo Indicador solo se proporciona para registros con un BIC. |
| FIN SWIFT | Alfabético | 1 | Sí | Estado de la conexión de una entidad con FIN: • [Y] conectado con FIN • [N] no conectado con FIN |
| FA SWIFT | Alfabético | 1 | Sí | Estado de accesibilidad de una entidad a través de FileAct: • [Y] conectado con FileAct • [N] no conectado con FileAct |
| IA SWIFT | Alfa | 1 | Sí | 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 | Sí | Nombre comercial de la institución (nombre publicado) |
| TIPO DE INSTITUCIÓN | Alfabético | 12 | Sí | 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 | Sí | 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 | Sí | 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 | Sí | 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 | Sí | 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 |
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
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 |