SEPA · Participação bancária · Respostas da API

Verificar a participação SEPA de um banco com a API IBAN-Test

Utilize uma resposta de validação de IBAN para verificar a participação de um banco no débito direto principal SEPA, débito direto corporativo, transferência bancária e transferência bancária em tempo real. Considere cada procedimento separadamente e diferencie entre participação confirmada e desconhecida.

Este guia explica os campos de resposta e inclui um exemplo Python para avaliar uma resposta ao vivo ou um ficheiro JSON salvo. O que é verificado é a participação do banco, e não a capacidade de uma conta específica efetuar um pagamento.

Estado dos testes: A avaliação passou em sete testes locais sobre procedimentos independentes, dados faltantes, IBANs inválidos, erros técnicos e campos incorretos. O comando offline também foi executado. Os dados de teste não vêm de uma consulta bancária real; uma verificação de API ao vivo autenticada não foi realizada neste exemplo.

O que significam os quatro campos

A API IBAN-Test compara a participação com os registros de participantes do Conselho Europeu de Pagamentos. Os procedimentos descrevem diferentes serviços de pagamento; A confirmação de um não confirma a participação nos demais. As listas subjacentes podem ser encontradas em Registros de participantes do EPC.

1. Verifique o IBAN

Use o endpoint de verificação IBAN normal. Nenhuma chamada SEPA adicional é necessária para este processo:

POST https://www.iban-test.eu/api/v2/iban/validate
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{"iban":"DE89 3704 0044 0532 0130 00"}

O IBAN acima é um exemplo e não uma instrução de pagamento. Primeiro verifique o status do HTTP e o resultado da validação. Uma resposta utilizável para um IBAN válido inclui code: 2100 e error: false. Os campos SEPA estarão disponíveis em details.sepa se a API os fornecer. Os terminais separados para verificação BIC e verificação de conta alemã não fornecem esses campos SEPA.

2. Distinguir entre “confirmado” e “desconhecido”.

Cada procedimento inclui status e reason:

• confirmed: A API encontrou uma correspondência atual e inequívoca no registo deste esquema.
• unknown: A API não conseguiu confirmar a participação. Isto não significa que o banco não suporte o esquema.

O trecho a seguir destina-se expressamente a fins ilustrativos. Mostra por que quatro colunas separadas são mais úteis do que um único indicador “suportado pela SEPA”:

{
  "sddCore": {"status": "confirmed", "reason": "matched"},
  "sddB2b":  {"status": "unknown",   "reason": "no_match"},
  "sct":     {"status": "confirmed", "reason": "matched"},
  "sctInst": {"status": "unknown",   "reason": "stale_data"}
}

Core e SCT são confirmados nestes dados de teste. O B2B permanece não confirmado e o resultado das transferências em tempo real é baseado em dados desatualizados. Nenhum desses valores desconhecidos altera o resultado original da verificação do IBAN.

3. Execute o exemplo offline

Descompacte o download e execute:

python3 sepa_check.py --response example-response.json

Nenhuma solicitação de rede é enviada e nenhum token é necessário. O programa gera um resumo JSON contendo iban_status, informações bancárias e quatro resultados de procedimentos separados. source: "offline_file" indica a fonte de entrada. O ficheiro fornecido nomeia um banco fictício e não pode ser usado como prova de uma instituição real.

Se os campos SEPA estiverem faltando em uma resposta salva, o auxiliar retornará unknown com missing_response_data. Este motivo é uma marca local do exemplo, não um código de motivo da API IBAN-Test. Valores de status inesperados ou objetos procedurais defeituosos interrompem o programa em vez de serem aceitos silenciosamente.

4. Verifique uma resposta ao vivo

python3 sepa_check.py --iban "DE89 3704 0044 0532 0130 00"

O programa irá consultar seu token sem exibi-lo. Alternativamente, implemente IBAN_TEST_API_TOKEN por meio da configuração secreta do seu ambiente de execução. Uma execução ao vivo executa uma solicitação de verificação de IBAN e cobra sua quota de API. O auxiliar usa um tempo limite, verifica o TLS, não segue redirecionamentos e não repete solicitações automaticamente.

No Windows, use py -3 em vez de python3 quando necessário. O comando termina com 0 para um IBAN válido, mesmo que um ou mais esquemas sejam desconhecidos; com 2 se o IBAN falhar a validação e com 1 para um erro operacional ou de entrada. Consulte cada esquema separadamente: o código 0 não significa que todos estejam confirmados.

Compreendendo um resultado desconhecido

Guarde o estado e o motivo juntos. Para resultados desconhecidos, apresente “Não foi possível confirmar a participação” e trate o caso segundo o processo de análise da aplicação. Não marque automaticamente o IBAN como inválido nem afirme que o banco não suporta esse tipo de pagamento.

Separe os erros da API dos resultados de participação

Um erro de autenticação HTTP, quota esgotada ou erro de servidor não é um resultado de participação do banco unknown. O exemplo para antes da avaliação do procedimento se a solicitação já falhar. Da mesma forma, um IBAN com um checksum inválido não conduz a uma decisão processual. Isto significa que um serviço indisponível não se torna uma declaração enganosa sobre as capacidades de um banco.

Execute os testes off-line incluídos usando python3 -m unittest -v. Para listas de entrada maiores, comece com Instruções CSV e Python e mantenha um par status-motivo separado para cada procedimento à medida que expande a saída.

Referência técnica: documentação da API IBAN-Test e códigos de motivo SEPA. Uma verificação do IBAN e a participação bancária confirmada não provam a titularidade da conta, a existência da conta, o mandato, os fundos disponíveis ou o sucesso do pagamento.

Criar conta API Compare quotas de API