API de Validación de Código BIC / SWIFT



¿Cómo integrar la API de validación BIC en tu software?


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


Al procesar pagos electrónicos y hacer frente a las transacciones relacionadas con IBAN, proporcionar el código SWIFT / BIC correcto es vital para los pagos exitosos.
Nuestra empresa ha licenciado el directorio BIC oficial de S.W.I.F.T SCRL para proporcionar una forma eficaz y sencilla de validar BIC automáticamente. Este servicio te permite integrar una búsqueda al directorio de código BIC en tu software para uso interno

La API de Validación BIC tiene dentro datos SWIFTRef. Los datos BIC son utilizados con el permiso de SWIFT SCRL. Derechos de bases de datos reservados 2017




2. Caracteristicas


Características clave de la API de Validación BIC:




3. Uso de la API


La API de validación BIC está basado en REST y es compatible con simples peticiones HTTP GET o POST.

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

Nombre del campo Longitud Tipo Descripción
bic 11 String Búsqueda de código BIC / SWIFT. Puede ser de 8 o 11 caracteres.
bank_name 256 String Parte del nombre del banco para realizar la búsqueda en el directorio BIC.
country 2 String Código de dos letras del país. Requerido en la búsqueda por el nombre del banco.
api_key 128 String Su clave API personal.
format 4 String Requerido para especificar el formato de los datos devueltos. Los valores soportados actualmente: JSON, XML
limit Integer Opcional: se puede utilizar para limitar el número de resultados al buscar por el nombre del banco.
hist integer Opcional: se puede utilizar para mostrar los registros históricos de la base de datos tanto para el banco y la búsqueda de BIC.
Dentro de su portal en línea puede encontrar la clave API y la URL de Solicitud de punto final, que se utiliza para fijar las solicitudes de búsqueda.





4. Estructura de la respuesta XML de la API


Puede descargar un esquema XSD de la respuesta de la API.
Una descripción detallada de los campos devueltos se puede ver en la siguiente tabla:

Nombre del campo Tipo Longitud Siempre presente Descripción
MODIFICATION FLAG Alphabetic 1 En archivos delta:
• A (adición)
• M (modificación)
• D (supresión) en los archivos completos En los archivos completos:
• A (adición)
CHANGED FIELD Numeric 186 No Registra el campo (o etiqueta) que ha cambiado, ya sea como resultado de una modificación de un registro o como el resultado de un nuevo evento.
Una o más columnas se indican como una secuencia de números con cada número que representa la columna cambiada desde la instancia de registro anterior o evento anterior.
Ejemplo "6,7,8,9"
Esto quiere decir que tipo de evento, fecha del evento, BIC8, y el BIC de la sucursal hancambiado.
Los siguientes campos se excluyen de ser registrados en el campo modificado:
• Llave de registro
• campo modificado
• indicador de modificación
RECORD KEY Alfanumérico 12 La clave única del registro del archivo
Cada registro representa un evento en el ciclo de vida BIC.
Una vez asignada, la CLAVE DE REGISTRO nunca cambia.
PREVIOUS RECORD KEY Alfanumérico 12 No La CLAVE DE REGISTRO del evento vinculado con anterioridad
Todos los eventos relacionados están vinculados y se pueden localizar usando esta información.
NEXT RECORD KEY Alfanumérico 12 No La CLAVE DE REGISTRO del próximo evento relacionado relacionado
Todos los eventos relacionados están vinculados y se pueden localizar utilizando esta información
EVENT TYPE Alfabético 32 La descripción del suceso o cambio relacionado con el BIC que ha ocurrido en el pasado, en el presente, o va a ocurrir en el futuro.
Tipos de eventos:
• BIC EMITIDO
• BIC CADUCADO
• 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 CAMBIADO
• Nombre de INSTITUCIÓN BIC cambiado
• DIRECCIÓN BIC CAMBIADA
• CÓDIGO DE SERVICIO FIN CAMBIADO
La última fecha de actualización es la última línea de la secuencia de BIC (es decir, la entrada más reciente).
Cuando se añade un nuevo evento, las columnas de indicador de modificación y CAMPO cambiado se actualizarán inmediatamente en el evento relacionado con el anterior.
EVENT DATE Alfanumérico 8 La fecha del evento
BIC8 Alfanumérico 8 BIC (institución, país, y el sufijo de la parte) donde:
• Prefijo de la parte (4 caracteres)
• El código de país (2 caracteres)
• Parte sufijo (2 char)
BRANCH BIC Alfanumérico 3 El identificador BIC de la sucursal asociado con el BIC de 8 caracteres. Si no existe un identificador de sucursal, a continuación, se utiliza XXX.
BIC Alfanumérico 11 El BIC completo: BIC de 8 caracteres e identificador de rama
RECORD STATUS Alfabético 1 Indica el estado del registro:
• [C] = actual que representa el último evento de la cadena hasta la fecha de publicación, con exclusión de [F]futuros eventos
• [H] = registros históricos en la cadena de eventos
• [F] = evento futuro que ocurrirá después de la fecha de publicación de la guía. El evento [C] actual indicado anteriormente será válida hasta la fecha especificada en el evento [F]futuro.
Para eventos futuros, la fecha indica cuando el cambio va a ser válida a partir.
OPERATIONALLY ACTIVE RECORD Alpha 1 Hay varios registros para el mismo BIC. Este campo indica cuál de los registros del mismo BIC es el BIC operativo activo y debe ser usado.
• [Y] Operacionalmente activa
• [N] Operacionalmente inactiva
Para cada BIC único, hay una sola entrada de registro que indica un estado ACTIVO (Y).
Los registros con [H]histórico estado siempre indicará [N].
Los registros con [C] actual pueden indicar [Y] o [N].
Los registros con [F] siempre indicará [N].
SUBTYPE INDICATOR Any type 4 El tipo de negocio de la entidad. El indicador de subtipo se proporciona sólo para registros con un BIC.
SWIFT FIN Alfabético 1 Estado de la conexión de una entidad para FIN:
• [Y] conectada a FIN
• [N] no está conectado a FIN
SWIFT FA Alfabético 1 Situación de la accesibilidad de la entidad a través de FileAct:
• [Y] conectada a FileAct
• [N] no está conectado a FileAct
SWIFT IA Alpha 1 Situación de la accesibilidad de la entidad a través de InterAct:
• [Y] conectado para interactuar
• [N] no está conectado para interactuar
LEGAL NAME Cualquiera 105 No Nombre legal de la institución
INSTITUTION NAME Cualquiera 105 Nombre comercial de la Institución (nombre publicado)
INSTITUTION TYPE Alfabético 12 Organización que se dedica principalmente a la intermediación financiera y/o actividades financieras auxiliares
Tipo de institucion:
• FINANCIERA
• NO FINANCIERA
ENTITY TYPE Alfabético 16 Identifica el tipo de entidad financiera:
• Entidad legal
• Sucursal
• Operacional
RE STREET ADDRESS 1 Cualquiera 35 No [Registro] Nombre de la calle
RE STREET ADDRESS 2 Cualquiera 35 No [Registro] Número de la calle
RE STREET ADDRESS 3 Cualquiera 35 No [Registro] Edificio, nombre del edificio, piso
RE STREET ADDRESS 4 Cualquiera 35 No [Registro] Área
RE CITY Cualquiera 35 No [Registration] City name of the institution/branch
RE CPS Cualquiera 90 No [Registro] País, provincia, estado, u otra región administrativa de la institución/sucursal propietaria
RE ZIP CODE Cualquiera 15 No [Registro] Código postal de la institución/sucursal
RE POB NUMBER Cualquiera 35 No campo separado por comas con el número POB de la institución / sucursal y el código postal correspondiente.
Ejemplo
"POB 103352, 40024"
Esto permite a los clientes utilizar la dirección POB completa:
POB 103352
40024, Dusseldorf (CIUDAD)
OP STREET ADDRESS 1 Cualquiera 35 No [Operacional] Nombre de la calle
OP STREET ADDRESS 2 Cualquiera 35 No [Operacional] Número de la calle
OP STREET ADDRESS 3 Cualquiera 35 No [Operacional] Edificio, nombre del edificio, piso
OP STREET ADDRESS 4 Cualquiera 35 No [Operacional] Área
OP CITY Cualquiera 35 No [Operacional] Nombre de la ciudad de la institución/sucursal
OP CPS Cualquiera 90 No [Operacional] País, provincia, estado, u otra región administrativa de la institución/sucursal propietaria
OP ZIP CODE Cualquiera 15 No [Operacional] Código postal de la institución/sucursal
OP POB NUMBER Cualquiera 35 No Campo separado por comas con el número POB de la institución / sucursal y el código postal correspondiente.
Ejemplo
"POB 103352, 40024"
Esto permite a los clientes utilizar la dirección POB completa:
POB 103352
40024, Dusseldorf (CIUDAD)
BR STREET ADDRESS 1 Cualquiera 35 No [Sucursal] Nombre de la calle
BR STREET ADDRESS 2 Cualquiera 35 No [Sucursal] Número de la calle
BR STREET ADDRESS 3 Cualquiera 35 No [Sucursal] edificio, nombre del edificio, piso
BR STREET ADDRESS 4 Cualquiera 35 No [Sucursal] Área
BR CITY Cualquiera 35 No [Sucursal] Nombre de la ciudad de la institución/sucursal
BR CPS Cualquiera 90 No [Sucursal] País, provincia, estado, u otra región administrativa de la institución propietaria / sucursal
BR ZIP CODE Cualquiera 15 No [Sucursal] Código postal de la institución / sucursal
BR POB NUMBER Cualquiera 35 No Campo separado por comas con el número POB de la institución / sucursal y el código postal correspondiente.
Ejemplo
"POB 103352, 40024"
Esto permite a los clientes utilizar la dirección de POB completo:
POB 103352
40024, Dusseldorf (CIUDAD)
BRANCH INFORMATION Cualquiera 70 No Información de sucursal Esta es una descripción de texto libre de la sucursal de conformidad con lo dispuesto por la entidad financiera a la que pertenece. Por el momento esto se hará efectiva sólo para las entradas con un BIC y sólo cuando la entidad financiera en cuestión quiera proporcionar esta información adicional. La información se obtiene del directorio BIC.
COUNTRY NAME Cualquiera 70 El nombre del país de la institución / sucursal como se indica en la norma ISO 3166
ISO COUNTRY CODE Alfabético 2 El código de la norma ISO 3166-1 alfa-2 del país de la institución/sucursal
LOCATION CODE Any type 1 Contiene la ubicación (formalmente en la posición 7 de la norma BIC: 2009)
Ejemplos:
• En FR, los BIC en París = P
• En BE, los BIC en Bruselas = B
• En Estados Unidos, los BIC en la costa este de = 3
FIN SERVICE CODES Any type 60 No Códigos de servicio FIN (también llamados códigos de servicio de valor agregado). Los códigos de servicio sólo se proporcionan para los registros que contienen un BIC.
El campo puede contener hasta 20 códigos de tres caracteres en orden alfabético.
RECORD KEY BDP Alfanumérico 12 No La clave única del Directorio Plus DEL Banco se registra en el archivo.
FIELD A Cualquiera 1 No reservado para uso futuro
FIELD B Cualquiera 64 No reservado para uso futuro
FIELD C Cualquiera 128 No reservado para uso futuro
FIELD D Cualquiera 256 No reservado para uso futuro
FIELD E Cualquiera 11 No reservado para uso futuro
FIELD F Cualquiera 12 No reservado para uso futuro
El sistema API devuelve los resultados en formato XML, los cuales se puede analizar fácilmente en una variedad de lenguajes de programación y plataformas.

Una respuesta XML de ejemplo de la API para una búsqueda 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 de API


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

Las etiquetas XML se devuelven sin otros campos en la respuesta XML.

A continuación puede encontrar una descripción de todos los posibles mensajes de error que podrían ser devueltos:

Código de estado Tipo Descripción
301 Error cuenta La llave API no es válida
302 Error cuenta Subscripcion vencida
303 Error cuenta No hay consultas disponibles
304 Error cuenta Usted no tiene acceso a esta API
401 Error de entrada longitud SWIFT aceptada de 8 y 11 caracteres
402 Error de entrada Nombre del banco no es válido! La búsqueda de banco debe ser de un mínimo de 4 caracteres.
Los caracteres permitidos az, AZ, 0-9, [espacio]!
403 Error de entrada Código de país incorrecto! Lo permitido es el código de país de 2 letras. Ejemplo: UK, DE, FR