API de validação de código BIC / SWIFT

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

1. O que é a API de validação da BIC?

Ao processar pagamentos eletrônicos e lidar com transações relacionadas ao IBAN, fornecer o código SWIFT / BIC correto é vital para pagamentos úteis.
Nossa empresa licenciou o Diretório BIC oficial da SWIFT SCRL para fornecer uma maneira poderosa e simples de validar o BIC automaticamente. Este serviço permite integrar a pesquisa de diretório de código BIC em seu software para fins internos

A API de validação da BIC possui dados internos do SWIFTRef. Dados BIC usados ​​com permissão do SWIFT SCRL. Direitos de banco de dados reservados 2018

2. Características

Recursos-chave da API de validação BIC:

  • Recuperar informações sobre o banco com base no BIC.
  • Pesquise o diretório BIC por uma parte do nome do banco e do país.
  • Pesquise no Diretório BIC por registros históricos.
  • Use a resposta completa e simplificada da API para facilitar a integração.


3. Uso da API

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

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 ter 8 ou 11 caracteres
bank_name 256 String Parte de um nome de banco para realizar pesquisa no diretório BIC.
país 2 String Código do país de duas letras. Obrigatório ao pesquisar por nome do banco.
api_key 128 String Sua chave de API pessoal.
format 4 String Necessário para especificar o formato dos dados retornados. Valores atualmente suportados:json, xml
limit Integer Opcional: pode ser usado para limitar o número de resultados ao pesquisar por nome do banco.
hist integer Opcional: pode ser usado para exibir registros históricos do banco de dados para pesquisa de banco e BIC.
Dentro do seu portal on-line, você pode encontrar sua chave de API e o URL do ponto de extremidade de solicitação, que é usado para proteger as solicitações de pesquisa.


4. Estrutura de Resposta XML da API

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

Nome do campo Tipo comprimento Sempre presente Descrição
BANDEIRA DE MODIFICAÇÃO Alfabético 1 sim Em arquivos delta:
• A (Adição)
• M (modificação)
• D (deleção) em arquivos completos Em arquivos completos:
• A (Adição)
CAMPO MUDADO Numérico 186 Não Registra o campo (ou TAG) que foi alterado como resultado de uma modificação em um registro ou como resultado 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 da instância de registro anterior ou EVENTO anterior.
Exemplo "6,7,8,9"
Isso significa que TIPO DE EVENTO, DATA DO EVENTO, BIC8 e BRANCH BIC
mudou.
Os seguintes FIELDS estão excluídos de serem registrados no CAMPO MUDADO:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY Alfanumérico 12 Sim A chave exclusiva do registro no arquivo
Cada registro representa um evento no ciclo de vida do BIC.
Uma vez atribuída, a tecla RECORD nunca muda.
PREVIOUS RECORD KEY Alfanumérico 12 Não A tecla RECORD do evento anteriormente vinculado
Todos os eventos relacionados estão vinculados e podem ser localizados usando essas informações.
NEXT RECORD KEY Alfanumérico 12 Não A tecla RECORD do próximo evento relacionado relacionado
Todos os eventos relacionados estão vinculados e podem ser localizados usando essas informações
EVENT TYPE Alfabético 32 Sim O EVENTO ou descrição de alteração relacionada ao BIC que ocorreu no passado, no presente ou ocorrerá no futuro.
Tipos de Eventos:
• BIC EMITIDO
• BIC EXPIRADO
• BIC ATIVADO EM FIN
• BIC ATIVADO NO FA
• BIC ATIVADO EM IA
• BIC DEACTIVATED ON FIN
• BIC DEACTIVATED ON FA
• BIC DESATIVADO EM IA
• BIC DESATIVADO
• BIC SUSPENSO
• BIC REACTIVATED
• BIC PUBLICADO
• NOME LEGAL DA BIC MUDADO
• NOME DA INSTITUIÇÃO BIC MUDADO
• ENDEREÇO ​​BIC MUDADO
• FIN CÓDIGO DE SERVIÇO MUDADO
A última data de atualização é a última linha da seqüência BIC (ou seja, a entrada mais recente).
Quando um novo EVENTO é adicionado, a BANDEIRA DE MODIFICAÇÃO e MUDADA
A coluna FIELD será atualizada no EVENTO relacionado imediato anterior.
DATA DO EVENTO Alfanumérico 8 Sim A data do evento
BIC8 Alfanumérico 8 Sim BIC (instituição, país e sufixo do partido) em que:
• Prefixo (4 char)
• código do país (2 char)
• Sufixo (2 char)
BIC DA AGÊNCIA Alfanumérico 3 Sim O identificador de ramificação BIC associado ao BIC de 8 caracteres. Se nenhum identificador de ramificação existir, XXX será usado.
BIC Alfanumérico 11 Sim O BIC completo: BIC de 8 caracteres e identificador de ramificação
RECORD STATUS Alfabético 1 Sim Indica o status do registro:
• [C] = Atual representando o último evento na cadeia até a data de publicação, excluindo [F] uturos eventos
• [H] = registros históricos na cadeia de eventos
• [F] = Evento futuro que ocorrerá após a data de publicação do diretório. O evento [C] atual indicado anteriormente será válido até a data especificada no evento [F] uturo.
Para eventos futuros, a data indica quando a mudança será válida.
REGISTRO OPERACIONALMENTE ATIVO Alpha 1 Sim Existem vários registros para o mesmo BIC. Este campo indica qual dos registros para o mesmo BIC é o BIC operacionalmente ativo e deve ser usado.
• [Y] Operacionalmente ativo
• [N] Operacionalmente inativo
Para cada BIC exclusivo, há uma entrada de registro única indicando um status ATIVO (Y).
Registros com status histórico [H] sempre indicarão [N].
Registros com [C] atual podem indicar [Y] ou [N].
Registros com [F] sempre indicarão [N].
INDICADOR SUBTYPE Qualquer tipo 4 Sim O tipo de negócio da entidade. Indicador de subtipo é fornecido apenas para registros com um BIC.
SWIFT FIN Alfabético 1 Sim Status da conexão de uma entidade ao FIN:
• [Y] conectado a FIN
• [N] não conectado ao FIN
SWIFT FA Alfabético 1 Sim Status da acessibilidade de uma entidade por meio do FileAct:
• [Y] conectado ao FileAct
• [N] não conectado ao FileAct
SWIFT IA Alpha 1 Sim Status da acessibilidade de uma entidade por meio do InterAct:
• [Y] conectado ao InterAct
• [N] não conectado ao InterAct
NOME LEGAL Qualquer 105 Não Nome legal da instituição
NOME DA INSTITUIÇÃO Qualquer 105 Sim Nome comercial da instituição (nome publicado)
TIPO DE INSTITUIÇÃO Alfabético 12 Sim Organização que se dedica principalmente à intermediação financeira e / ou a atividades financeiras auxiliares
Tipo de instituição:
• FINANCEIRO
• NÃO FINANCEIRO
TIPO DE ENTIDADE Alfabético 16 Sim Identifica o tipo de entidade financeira:
• Entidade legal
• Ramo
• Operacional
RE ENDEREÇO ​​DE RUA 1 Qualquer 35 Não [Registro] nome da rua
RE ENDEREÇO ​​DE RUA 2 Qualquer 35 Não [Registro] Número da rua
RE ENDEREÇO ​​DE RUA 3 Qualquer 35 Não [Inscrição] Edifício, nome do edifício, andar
RE ENDEREÇO ​​DE RUA 4 Qualquer 35 Não Área [Registro]
RE CIDADE Qualquer 35 Não [Registro] Nome da cidade da instituição / filial
RE CPS Qualquer 90 Não [Registro] Condado, província, estado ou outra região administrativa da instituição / filial do proprietário
RE CEP Qualquer 15 Não [Registro] CEP da instituição / filial
RE POB NUMBER Qualquer 35 Não Campo separado por vírgula com o número do POB da instituição / filial e o CEP relacionado.
Exemplo
"POB 103352, 40024"
Isso permite que os clientes usem o endereço completo do POB:
POB 103352
40024, DUESSELDORF (CITY)
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 Área [operacional]
OP CITY Qualquer 35 Não [Operacional] Nome da cidade da instituição / filial
OP CPS Qualquer 90 Não [Operacional] Condado, província, estado ou outra região administrativa da instituição / filial do proprietário
NO CEP Qualquer 15 Não [Operacional] CEP da instituição / filial
OP POB NUMBER Qualquer 35 Não Campo separado por vírgula com o número do POB da instituição / filial e o CEP relacionado.
Exemplo
"POB 103352, 40024"
Isso permite que os clientes usem o endereço completo do POB:
POB 103352
40024, DUESSELDORF (CITY)
BR STREET ADDRESS 1 Qualquer 35 Não [Filial] Nome da rua
BR STREET ADDRESS 2 Qualquer 35 Não [Filial] Número da rua
BR STREET ADDRESS 3 Qualquer 35 Não [Filial] Construindo, nome de edifício, chão
BR STREET ADDRESS 4 Qualquer 35 Não [Filial] Área
BR CITY Qualquer 35 Não [Filial] Nome da cidade da instituição / filial
BR CPS Qualquer 90 Não [Filial] Condado, província, estado ou outra região administrativa da instituição / filial proprietária
CEP BR BR Qualquer 15 Não [Filial] CEP da instituição / filial
BR POB NUMBER Qualquer 35 Não Campo separado por vírgula com o número do POB da instituição / filial e o CEP relacionado.
Exemplo
"POB 103352, 40024"
Isso permite que os clientes usem o endereço completo do POB:
POB 103352
40024, DUESSELDORF (CITY)
BRANCH INFORMATION Qualquer 70 Não Informações sobre filiais
Esta é uma descrição de texto livre da agência, conforme fornecida pela instituição financeira à qual pertence. Por enquanto, isso será fornecido apenas para inscrições com um BIC e somente quando a instituição financeira em questão quiser fornecer essas informações extras. As informações são provenientes do diretório BIC.
NOME DO PAÍS Qualquer 70 Sim O nome do país da instituição / filial conforme indicado na ISO 3166
CÓDIGO ISO PAÍS Alfabético 2 Sim O código ISO 3166-1 alpha-2 do país da instituição / filial
CÓDIGO DE LOCALIZAÇÃO Qualquer tipo 1 Sim Contém a localização (formalmente na posição 7 do padrão BIC: 2009)
Exemplos:
• Em FR, BICs em Paris = P
• Em BE, os BICs em Bruxelas = B
• Nos EUA, os BICs no Custo Leste = 3
CÓDIGOS DO SERVIÇO FINAL Qualquer tipo 60 Não Códigos de serviço FIN (também chamados códigos de serviço de valor agregado). Os códigos de serviço são fornecidos apenas para registros que contêm um BIC.
O campo pode conter até 20 códigos de três caracteres em ordem Alfabética.
RECORD KEY BDP Alfanumérico 12 Não A chave exclusiva do registro Bank Directory Plus no arquivo.
FIELD A Qualquer 1 Não Reservado para uso futuro
FIELD B Qualquer 64 Não Reservado para uso futuro
FIELD C Qualquer 128 Não Reservado para uso futuro
FIELD D Qualquer 256 Não Reservado para uso futuro
FIELD E Qualquer 11 Não Reservado para uso futuro
FIELD F Qualquer 12 Não Reservado para uso futuro
O sistema da API retorna resultados em formato XML, que é fácil de analisar em uma variedade de linguagens e plataformas de programação.

Uma amostra de resposta XML 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 erro, a API retorna uma resposta XML contendo a mensagem de erro.

As Tags XML são retornadas sem qualquer outro campo 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 na conta A chave da API é inválida
302 Erro na conta Assinatura expirada
303 Erro na conta Nenhuma consulta disponível
304 Erro na conta Você não tem acesso a esta API
401 Erro de Entrada Comprimento SWIFT aceito de 8 ou 11 caracteres
402 Erro de Entrada Nome do banco inválido! A busca do banco deve ter no mínimo 4 caracteres.
Caracteres permitidos az, AZ, 0-9, [espaço]!
403 Erro de Entrada Código do país incorreto! Permitido é o código do país de 2 letras. Exemplo: UK, DE, FR