Especificação de integração de API

1. O que a API de recuperação do IBAN faz?

Essa API fornece a funcionalidade exclusiva para recuperar até dois caracteres desconhecidos de qualquer número de conta bancária internacional. Essa função pode ser usada nos casos em que partes do IBAN são ilegíveis ou quando a entrada do usuário é validada. O sistema leva em consideração a formatação e duração específicas do país para garantir que ele produza o mínimo de sugestões. Todas as permutações possíveis de dígitos e letras, de acordo com o esquema de formatação internacional, são testadas em relação ao algoritmo de dígito de verificação modular.
Casos de uso:

- caracteres ilegíveis - Ao digitalizar IBANs de portadores de papel, é possível que impressões degradadas produzam caracteres ilegíveis. Nosso sistema permite que você coloque um ponto de interrogação no lugar dos caracteres desconhecidos. Nosso mecanismo de validação gera todas as combinações válidas possíveis para este IBAN.

- Adivinha Educada - Se você tiver um IBAN inválido, poderá adivinhar quais posições o erro pode estar executando várias tentativas de recuperação com curinga em diferentes posições.

2. Características

A API de recuperação do IBAN permite que você faça o seguinte:

• Obtenha uma lista de IBANs válidos que sugiram a possível variante correta.
• Extraia o código do banco interno do IBAN original enviado.
• Extraia o código da agência doméstica do IBAN original enviado.
• Extraia o número da conta interna do IBAN original enviado.

3. Solicitações da API de recuperação

O sistema API permite automatizar a recuperação do IBAN por meio de uma solicitação HTTP GET ou POST simples.
Os parâmetros aceitos estão listados na tabela abaixo:

Nome do campo	Comprimento	Tipo	Descrição
IBAN	Max 100	String	O IBAN mascarado que você deseja validar. Usar ? (ponto de interrogação) no lugar do caractere desconhecido. Por exemplo: DE79850?0300310018056?
api_key	128	String	Sua chave de API pessoal.
format	5	String	Formato da resposta XML e JSON suportados.

* Para obter uma chave de API, entre em contato conoscocontact@iban.com ou comprar uma assinatura em nossa página de encomenda

EXEMPLO - Recupere um IBAN
Um exemplo de uso da API de validação do IBAN com uma solicitação GET pode ser encontrado abaixo:

https://api.iban.com/clients/api/recover-iban.php?api_key=key&format=xml&iban=IBAN

Onde:

• chave é sua chave de API
• IBAN enviado para validação pelo módulo API. Exemplo: CH8?0853410203475000?
• xml é o formato de resposta. Além disso, uma palavra-chave json pode ser especificada para resposta formatada por json.

Quando uma solicitação HTTP GET ou POST é feita com a chave de API correta, o sistema retornará os resultados no formato especificado. Você pode encontrar uma resposta de amostra na próxima seção “Estrutura de resposta da API”

4. Resposta da API de recuperação

Um esquema XSD da resposta da API pode ser encontrado abaixo:

Uma descrição detalhada dos campos do objeto format_data retornados pode ser vista na tabela abaixo:

Nome do campo	Comprimento	Tipo	Descrição
País	Max 2	String	O código do país ISO de 2 letras.
iban_length	Max 2	Integer	A duração exata de todos os IBANs para este país.
format_template	Max 2	String	Um modelo com o comprimento exato do IBAN mostrando os diferentes caracteres dentro de cada posição. C = Misto (Alfabeto 0-9), A = Caráter (alfabético), N = Dígito (0-9).
bank_code	Max 99	String	O código de identificação do banco interno para este IBAN.
branch_code	Max 99	String	O identificador de filial doméstica para este IBAN.
account_number	Max 99	String	O número da conta bancária interna para este IBAN.

Uma amostra de resposta XML da API para uma consulta de validação do IBAN seria:

	
		CH
		21
		CCNNNNNNNCCCCCCCCCCCC
		85341
		
		0203475000
	
	
		CH810853410203475000K
		CH860853410203475000R
		CH8908534102034750002
	
	

5. Códigos de status da API de recuperação

A API de recuperação IBAN retorna os seguintes códigos de erro

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	Campos obrigatórios em falta.
402	Erro de entrada	Muitos curingas. Máximo de dois curingas permitidos.
403	Erro de entrada	Muito poucos curingas. É necessário um mínimo de curingas.