Você tem um código SWIFT/BIC vindo de um formulário, webhook ou CSV e precisa validá-lo programaticamente antes de enviar um pagamento ou armazená-lo. Ao final deste artigo, você será capaz de validar um código SWIFT e buscar seus componentes analisados usando um único HTTP GET para um endpoint de produção que você pode implementar esta semana.
O que esta API faz e quando usá-la
A API de Consulta de Código SWIFT valida um código SWIFT (BIC) fornecido e retorna dados estruturados sobre ele. As equipes a utilizam para controlar fluxos de transferência bancária, limpar conjuntos de dados financeiros e adicionar validação do lado do servidor ao onboarding ou pagamentos. Você passa um código SWIFT; a API responde com um status, uma mensagem legível por humanos e um objeto estruturado que inclui o código e uma análise.
Como esta é uma API no Zyla API Hub, você obtém uma conta, uma chave de API e um modelo de assinatura e cota em todo o marketplace. Se você já estiver usando outras APIs da Zyla para finanças ou verificação, pode adicionar esta verificação ao seu stack sem gerenciar outra credencial.
Navegue pelo catálogo mais amplo em zylalabs.com—há mais de 10.000 APIs públicas disponíveis sob uma experiência de desenvolvedor consistente.
Começando no Zyla API Hub
Para integrar rapidamente:
- Abra a listagem da API de Consulta de Código SWIFT no Zyla API Hub e clique em Assinar. A primeira API que você adicionar pode começar com um teste de 7 dias ou 50 solicitações, dependendo da disponibilidade. Não há Plano Gratuito; o uso é por assinatura + cota, não pago por chamada—verifique a página da API para opções de acesso e preços atuais.
- Copie sua chave de API da sua conta. A autenticação é via cabeçalho: Authorization: Bearer YOUR_API_KEY.
- Chame o endpoint abaixo do seu servidor ou ferramenta de sua escolha.
Você pode sempre voltar para zylalabs.com para gerenciar assinaturas, cotas e chaves entre APIs.
Endpoint que você realmente usará
A API de Consulta de Código SWIFT expõe um único endpoint de consulta que você pode chamar diretamente com um HTTP GET. Use isso quando você tiver um código SWIFT/BIC em mãos e quiser um resultado de validação e uma análise.
Consulta de Código
- Método: GET
- URL: https://zylalabs.com/api/1714/swift-code-lookup-api/1327/code-lookup
- Parâmetro de consulta obrigatório:
- code (string): o SWIFT/BIC que você deseja validar. Exemplo de valor: ADTVBRDF
- Auth: Authorization: Bearer YOUR_API_KEY
cURL para copiar e colar
Esta é a maneira mais rápida de testar o serviço ao vivo do seu terminal. Substitua YOUR_API_KEY pela sua chave:
curl -s -X GET "https://zylalabs.com/api/1714/swift-code-lookup-api/1327/code-lookup?code=ADTVBRDF" \
-H "Authorization: Bearer YOUR_API_KEY"
Resposta de exemplo oficial
A API retorna um documento JSON com um status de nível superior e um indicador de sucesso, uma mensagem e um objeto de dados contendo o código e sua análise. Aqui está a carga útil de exemplo oficial:
{
"status": 200,
"success": true,
"message": "O código SWIFT AXISINBB301 é válido",
"data": {
"swift_code": "AXISINBB301",
"bank": null,
"city": null,
"branch": null,
"address": null,
"post_code": null,
"country": null,
"country_code": null,
"breakdown": {
"swift_code": "AXISINBB301",
"bank_code": null,
"country_code": null,
"location_code": null,
"code_status": null,
"branch_code": null
}
}
}
O que ler na prática:
- status e success: use esses para controlar seu fluxo. Um 200 com success: true significa que a consulta foi bem-sucedida.
- message: uma mensagem de validação legível por humanos que você pode registrar para operadores ou exibir em ferramentas administrativas.
- data.swift_code: o SWIFT/BIC normalizado que foi validado.
- data.breakdown: uma divisão estruturada do código em componentes. Campos individuais podem ser nulos quando não disponíveis.
Exemplo em Python que você pode colar no seu serviço
O trecho abaixo chama o mesmo endpoint e mostra como lidar com os campos de resposta e nulos de forma segura. A URL e os valores dos parâmetros correspondem ao cURL oficial acima, para que você possa executar isso sem editar nada, exceto sua chave de API.
import os
import requests
API_KEY = os.environ.get("ZYLALABS_API_KEY", "YOUR_API_KEY")
URL = "https://zylalabs.com/api/1714/swift-code-lookup-api/1327/code-lookup"
params = {"code": "ADTVBRDF"}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(URL, params=params, headers=headers, timeout=10)
resp.raise_for_status()
data = resp.json()
# Controle básico
if not data.get("success"):
raise SystemExit(f"Consulta falhou: {data.get('message')}")
print(f"Mensagem: {data.get('message')}")
payload = data.get("data", {}) or {}
swift = payload.get("swift_code")
bank = payload.get("bank") # pode ser None
country = payload.get("country") # pode ser None
breakdown = (payload.get("breakdown") or {})
bank_code = breakdown.get("bank_code") # pode ser None
country_code = breakdown.get("country_code") # pode ser None
branch_code = breakdown.get("branch_code") # pode ser None
print("Código SWIFT validado:", swift)
print("Banco (se disponível):", bank)
print("País (se disponível):", country)
print("Análise:", {
"bank_code": bank_code,
"country_code": country_code,
"branch_code": branch_code
})
Como integrar isso em fluxos reais
A maioria das equipes chama esta API do lado do servidor a partir de endpoints de criação de pagamento ou onboarding de beneficiários. Um padrão comum:
- O usuário envia os detalhes do banco, incluindo um código SWIFT/BIC.
- Seu backend valida o código SWIFT chamando o endpoint de Consulta de Código antes de salvá-lo ou usá-lo.
- Se success for true, continue; se false ou status não for 200, rejeite a entrada e registre a mensagem para revisão.
Outros usos práticos:
- Limpeza em lote: itere sobre códigos SWIFT em um CSV e armazene apenas as linhas que passam na validação.
- Ferramentas de reconciliação: sinalize automaticamente entradas com valores de análise inesperados para QA manual.
- Painéis administrativos: mostre a mensagem e a análise ao lado dos códigos SWIFT enviados pelos usuários.
Detalhes de implementação que economizam tempo
- Autenticação: cada solicitação deve incluir Authorization: Bearer YOUR_API_KEY.
- Método HTTP: apenas GET. Inclua o código como um parâmetro de consulta.
- Nulos: campos como banco, país e partes individuais da análise podem ser nulos. Sempre verifique se são nulos antes de usar.
- Cache: se você validar repetidamente o mesmo código SWIFT, armazene o resultado em seu datastore para reduzir a latência e o uso da cota. Um cache TTL simples em memória ou uma linha indexada pelo código SWIFT geralmente é suficiente.
- Observabilidade: registre o campo de mensagem ao rejeitar entradas para depuração mais rápida em escalonamentos de suporte.
- Segurança: não registre chaves de API de usuários. Armazene sua chave de API da Zyla em variáveis de ambiente ou em um gerenciador de segredos.
- Cotas: o uso das APIs da Zyla é por assinatura + cota. A primeira API pode começar com um teste de 7 dias ou 50 solicitações. Para limites atuais, veja a página da API em sua conta.
Padrões de tratamento de erros
Enquanto o exemplo acima mostra uma consulta bem-sucedida, o código de produção deve proteger contra:
- Respostas HTTP não-200: trate como falhas transitórias ou erros de entrada do usuário, dependendo do contexto.
- success false: leia a mensagem para uma breve explicação humana e decida se deve tentar novamente ou rejeitar.
- Timeouts de rede: defina timeouts razoáveis para o cliente e envolva chamadas com tentativas se a operação for idempotente.
Usando a API de agentes de IA via MCP
Se você preferir integrar esta consulta em um agente de codificação de IA ou assistente de IDE, a Zyla expõe ferramentas compatíveis via MCP. Aponte seu cliente compatível com MCP (por exemplo, Claude Code, Cursor, Windsurf) para o endpoint documentado aqui e autorize com sua chave de API. Veja a documentação do MCP para detalhes:
Isso permite que você acione a mesma Consulta de Código de dentro de um fluxo de agente sem alterar seu backend. Seu agente enviará a mesma solicitação GET e lerá os mesmos campos (status, success, message, data.swift_code, data.breakdown). Mantenha sua chave de API restrita a ambientes de desenvolvimento ao testar integrações de agentes.
Lista de verificação de validação de ponta a ponta
- Assinatura ativa no Zyla API Hub e chave de API armazenada com segurança.
- Chamada GET do lado do servidor para o endpoint de Consulta de Código com o código definido para o SWIFT/BIC fornecido pelo usuário.
- Verifique success e status antes de prosseguir com um pagamento ou salvar um beneficiário.
- Trate campos nulos de forma adequada em sua interface ou camada de dados.
- Armazene consultas por código SWIFT onde apropriado.
- Registre a mensagem para operações e suporte.
Onde obter sua chave e executar sua primeira solicitação
Assine a API, inicie o teste de 7 dias quando disponível e copie sua chave. Você pode chamar o endpoint imediatamente com o cURL acima e, em seguida, inserir o exemplo em Python em seu serviço. Gerencie seu uso e adicione outras APIs em finanças, enriquecimento de dados e utilitários a partir da mesma conta em zylalabs.com.
Inicie o teste de 7 dias na API de Consulta de Código SWIFT
FAQ
Quais formatos de entrada são suportados para o parâmetro de código?
Passe um código SWIFT/BIC como uma string simples via o parâmetro de consulta code em uma solicitação GET.
Quais campos devo considerar para decidir se um código SWIFT é válido?
Verifique success e status. Também leia a mensagem para uma explicação concisa adequada para logs ou interfaces administrativas.
Por que alguns campos em data ou breakdown são nulos?
Nem todos os metadados estão disponíveis para cada código. Sempre verifique se os campos como banco, país e partes da análise são nulos antes de usá-los.
Posso testar isso do meu terminal antes de integrar?
Sim. Use o comando cURL fornecido com sua chave de API para verificar rapidamente o endpoint e seu cabeçalho de autenticação.
Como é tratado o faturamento?
As APIs da Zyla usam um modelo de assinatura + cota, não pago por chamada. A primeira API pode começar com um teste de 7 dias ou 50 solicitações, dependendo da disponibilidade—verifique a listagem da API em sua conta para opções atuais.