API Validação de Código BIC / SWIFT



Como integrar a API de Validação BIC em seu software


1. O que é API de Validação BIC?


Ao processar uma transferência bancária e lidar com transações relacionadas ao IBAN, fornecer o código SWIFT / BIC correto é fundamental para o sucesso do pagamento.
Nossa empresa licenciou o Diretório BIC oficial da S.W.I.F.T SCRL para oferecer uma maneira simples e poderosa de validar o BIC automaticamente. Este serviço lhe permite integrar a busca no diretório de código BIC em seu software para propósitos internos.

A API de Validação BIC possui dados SWIFTRef. Dados BIC usados com permissão da S.W.I.F.T SCRL. Direitos da Base de Dados Reservados 2017




2. Recursos:


Principais recursos da API de Validação BIC:




3. Uso da API


A API de Validação BIC é baseada em REST e suporta requisições HTTP GET ou POST.

Os parâmetros aceitos estão listados na tabela abaixo:

Nome do Campo Comprimento Tipo Descrição
bic 11 String Código BIC / SWIFT para pesquisa. Pode ser 8 ou 11 caracteres.
bank_name 256 String Parte de um nome de banco para realizar a pesquisa na diretório BIC.
country 2 String Código do país de duas letras. Necessário quando pesquisar por nome do banco.
api_key 128 String Sua chave API pessoal.
format 4 String Necessário para especificar o formato dos dados retornados. Valores suportados: json, xml
limit Integer Opcional: pode ser utilizado para limitar o número de resultados quando se procura pelo nome de banco.
hist integer Opcional: pode ser usado para exibir registros históricos do banco de dados tanto para a pesquisa de banco quando a pesquisa do BIC.
Dentro de seu Portal Online você pode encontrar a sua chave API e a URL de Requisição Endpoint, usada para proteger as requisições de pesquisa.





4. Estrutura de Resposta XML da API


Você pode baixar um esquema XSD da API de resposta.
Uma descrição detalhada dos campos retornados pode ser vista na tabela abaixo:

Nome do Campo Tipo Comprimento Sempre presente Descrição
MODIFICATION FLAG Alfabético 1 Sim Em arquivos delta:
• A (adição)
• M (modificação)
• D (exclusão) em arquivos completos:
• A (adição)
CHANGED FIELD Numérico 186 Não Registra o campo (ou TAG) que foi alterado, seja por uma alteração em um registro ou por consequência de um novo EVENTO.
Uma ou mais colunas são indicadas como uma sequência de números com cada número representando a coluna alterada a partir da instância do registro anterior ou do EVENTO anterior.
Exemplo "6,7,8,9"
Isso significa que foram alterados os campos EVENT TYPE, EVENT DATE, BIC e BRANCH BIC.

Os seguintes CAMPOS (Fields) são excluídos do registro do CHANGED FIELD.
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY Alphanumeric 12 Sim A chave única do registro no arquivo
Cada registro representa um evento no ciclo de vida BIC.
Uma vez atribuído, o RECORD KEY nunca muda.
PREVIOUS RECORD KEY Alphanumeric 12 Não A RECORD KEY do próximo evento relacionado
Todos os eventos relacionados estão linkados e podem ser localizados usando esta informação
NEXT RECORD KEY Alphanumeric 12 Não A RECORD KEY do próximo evento relacionado
Todos os eventos relacionados estão linkados e podem ser localizados usando esta informação
EVENT TYPE Alfanumérico 32 Sim O EVENTO ou alteração de descrição relacionado ao BIC que ocorreu no passado, no presente, ou irá ocorrer no futuro.
Tipos de eventos:
• BIC ISSUED
• BIC EXPIRED
• BIC ACTIVATED ON FIN
• BIC ACTIVATED ON FA
• BIC ACTIVATED ON IA
• BIC DEACTIVATED ON FIN
• BIC DEACTIVATED ON FA
• BIC DEACTIVATED ON IA
• BIC DEACTIVATED
• BIC SUSPENDED
• BIC REACTIVATED
• BIC PUBLISHED
• BIC LEGAL NAME CHANGED
• BIC INSTITUTION NAME CHANGED
• BIC ADDRESS CHANGED
• FIN SERVICE CODE CHANGED
A data da última atualização é a última linha da sequência do BIC (ou seja, a entrada mais recente).
Quando um novo EVENTO é adicionado, as colunas MODIFICATION FLAG e CHANGED FIELD
serão atualizadas no evento relacionado imediatamente anterior.
EVENT DATE Alphanumeric 8 Sim A data do EVENTO
BIC8 Alfanumérico 8 Sim BIC (instituição, país e sufixo do banco), onde:
• Prefixo banco (4 caracteres)
• Código do país (2 caracteres)
• Sufixo banco / agência (2 caracteres)
BRANCH BIC Alfanumérico 3 Sim O identificador BIC da agência associado ao BIC de 8 caracteres. Se não existir nenhum identificador, então será usado XXX.
BIC Alfanumérico 11 Sim O BIC completo: os 8 caracteres do BIC e o identificador da agência
RECORD STATUS Alfanumérico 1 Sim Indica o status do registro:
• [C] = Atualmente representando o último evento na cadeia até a data de publicação, excluindo eventos [F]uturos.
• [H] = Registros históricos da cadeia de eventos
• [F] = Evento futuro que irá ocorrer após a data de publicação do diretório. O evento [C] indicado anteriormente ] será válido até a data especificada evento [F]uturo.
Para eventos FUTUROS, a data indica quando a mudança será VALID FROM.
OPERATIONALLY ACTIVE RECORD Alpha 1 Sim Há vários registros para o mesmo BIC. Este campo aponta qual dos registros do mesmo BIC é o BIC operacionalmente ativo e que deve ser usado.
• [Y] Operacionalmente ativo
• [N] Operacionalmente inativo
Para cada BIC único, há uma única entrada de registro indicando o status de ativo (Y).
Registros com o estado [H] histórico sempre indicarão [N].
Registros com [C] de atual, podem indicar [Y] ou [N].
Registros com [F] sempre indicarão [N].
SUBTYPE INDICATOR Qualquer tipo 4 Sim O tipo de negócio da entidade. O SUBTYPE INDICATOR é fornecido apenas para registros com um BIC.
SWIFT FIN Alfanumérico 1 Sim Status da conexão de uma entidade ao FIN:
• [Y] conectado ao FIN
• [N] não conectado ao FIN
SWIFT FA Alfanumérico 1 Sim Status de acessibilidade de uma entidade através do FileAct:
• [Y] conectado ao FileAct
• [N] não conectado ao FileAct
SWIFT IA Alpha 1 Sim Status de acessibilidade de uma entidade através do InterAct:
• [Y] conectado ao InterAct
• [N] não conectado ao InterAct
LEGAL NAME Qualquer 105 Não Nome legal da instituição
INSTITUTION NAME Qualquer 105 Sim Nome comercial da instituição (nome publicado)
INSTITUTION TYPE Alfanumérico 12 Sim Organização que está principalmente envolvida na intermediação financeira e/ou em serviços financeiros auxiliares
Tipo de Instituição:
• FINANCIAL
• NONFINANCIAL
ENTITY TYPE Alfanumérico 16 Sim Identifica o tipo de entidade financeira:
• Entidade legal
• Agência (branch)
• Operacional
RE STREET ADDRESS 1 Qualquer 35 Não [Registro] Nome da rua
RE STREET ADDRESS 2 Qualquer 35 Não [Registro] Número da rua
RE STREET ADDRESS 3 Qualquer 35 Não [Registro] Prédio, nome do prédio, andar
RE STREET ADDRESS 4 Qualquer 35 Não [Registro] Área
RE CITY Qualquer 35 Não [Registro] Nome da cidade da instituição/agência
RE CPS Qualquer 90 Não [Registo] País, província, estado ou outra região administrativa da instituição/agência proprietária.
RE ZIP CODE Qualquer 15 Não [Registro] CEP da instituição/agência
RE POB NUMBER Qualquer 35 Não Campo separado por vírgula com o número POB da instituição/agência e o CEP relacionado.
Exemplo
"POB 103352, 40024"
Isso permite que os clientes usem o endereço POB completo:
POB 103352
40024, DUESSELDORF (CIDADE)
OP STREET ADDRESS 1 Qualquer 35 Não [Operacional] Nome da rua
OP STREET ADDRESS 2 Qualquer 35 Não [Operacional] Número da rua
OP STREET ADDRESS 3 Qualquer 35 Não [Operacional] Prédio, nome do prédio, andar
OP STREET ADDRESS 4 Qualquer 35 Não [Operacional] Área
OP CITY Qualquer 35 Não [Operacional] Nome da cidade da instituição / agência
OP CPS Qualquer 90 Não [Operacional] País, província, estado ou outra região administrativa da instituição/agência proprietária.
OP ZIP CODE Qualquer 15 Não [Operacional] CEP da instituição/agência
OP POB NUMBER Qualquer 35 Não Campo separado por vírgula com o número POB da instituição/agência e o CEP relacionado.
Exemplo
"POB 103352, 40024"
Isso permite que os clientes usem o endereço POB completo:
POB 103352
40024, DUESSELDORF (CIDADE)
BR STREET ADDRESS 1 Qualquer 35 Não [Agência] Nome da rua
BR STREET ADDRESS 2 Qualquer 35 Não [Agência] Número da rua
BR STREET ADDRESS 3 Qualquer 35 Não [Agência] Prédio, nome do prédio, andar
BR STREET ADDRESS 4 Qualquer 35 No [Agência] Área
BR CITY Qualquer 35 No [Agência] Nome da cidade da instituição / agência
BR CPS Qualquer 90 No [Agência] País, província, estado ou outra região administrativa da instituição/agência proprietária.
BR ZIP CODE Qualquer 15 No [Agência] CEP da instituição/agência
BR POB NUMBER Qualquer 35 No Campo separado por vírgula com o número POB da instituição/agência e o CEP relacionado.
Exemplo
"POB 103352, 40024"
Isso permite que os clientes usem o endereço POB completo:
POB 103352
40024, DUESSELDORF (CIDADE)
BRANCH INFORMATION Qualquer 70 No Informações da agência Esta é a descrição de texto livre da agência, tal como fornecida pela instituição financeira a que pertence. Por enquanto, isso será fornecido apenas para entradas com um BIC e somente quando a instituição financeira em questão desejar fornecer essa informação extra. A informação é obtida a partir do Diretório BIC.
COUNTRY NAME Qualquer 70 Sim O nome do país da instituição/agência, conforme indicado na ISO 3166
ISO COUNTRY CODE Alfanumérico 2 Sim O código alfa de 2 caracteres da ISO 3166-1 do país da instituição/agência
LOCATION CODE Qualquer tipo 1 Sim Contém a localização (formalmente na posição 7 da norma BIC: 2009)
Exemplos:
• Em FR, o BIC em Paris = P
• Em BE, o BIC em Bruxelas = B
• Nos EUA, o BIC em East Cost = 3
FIN SERVICE CODES Qualquer tipo 60 No Códigos de serviço FIN (também chamados de códigos de serviço de valor agregado). Os códigos de serviço são fornecidos somente para os registros que contêm um BIC.
O campo pode conter até 20 de códigos de três caracteres em ordem alfabética.
RECORD KEY BDP Alphanumeric 12 No A chave única do registro Bank Directory Plus no arquivo.
FIELD A Qualquer 1 No Reservado para uso futuro
FIELD B Qualquer 64 No Reservado para uso futuro
FIELD C Qualquer 128 No Reservado para uso futuro
FIELD D Qualquer 256 No Reservado para uso futuro
FIELD E Qualquer 11 No Reservado para uso futuro
FIELD F Qualquer 12 No Reservado para uso futuro
O sistema API retorna resultados em formato XML, que é fácil de analisar em uma variedade de linguagens de programação e plataformas.

Uma resposta XML de exemplo da API para uma pesquisa BIC seria:


<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. Erros da API


Em caso de algum erro a API retornará uma resposta XML contendo a mensagem de erro.

As tags XML são devolvidas sem quaisquer outros campos na resposta XML.

Abaixo você pode encontrar uma descrição de todas as mensagens de erro possíveis que podem ser retornadas


Código de Status Tipo Descrição
301 Erro de conta Chave API é inválida
302 Erro de conta A subscrição expirou
303 Erro de conta Nenhuma query disponível
304 Erro de conta Você não tem acesso a esta API
401 Erro de Input Comprimento aceito de SWIFT de 8 ou 11 caracteres
402 Erro de Input Nome do banco inválido! A pesquisa do Banco deve ser de no mínimo de 4 caracteres.
Caracteres permitidos a-z, A-Z, 0-9, [espaço]!
403 Erro de Input Código de país incorreto! Permitido apenas código do país de 2 letras. Exemplo: UK, DE, FR