Como Usar a API de Pesquisa de Número de Roteamento Bancário

Você precisa validar um número de roteamento bancário dos EUA e obter o nome legal do banco, endereço, contato e status para que seu fluxo de trabalho ACH não falhe no dia do pagamento. Ao final deste artigo, você será capaz de consultar um número de roteamento, confirmar que é válido e armazenar os metadados da instituição retornados em seu aplicativo financeiro usando a API de Pesquisa de Número de Roteamento Bancário no Zyla API Hub.

O que esta API entrega e quando usá-la

A API de Pesquisa de Número de Roteamento Bancário retorna detalhes bancários autoritativos para um determinado número de roteamento dos EUA. Ela cobre:

Ilustração: Como Usar a API de Pesquisa de Número de Roteamento Bancário

Validação de que um número de roteamento está correto.
Identidade da instituição: nome do banco, tipo de agência (por exemplo, Escritório Principal).
Detalhes de contato: endereço completo, telefone.
Bandeiras operacionais: status ativo e data da última atualização.

Integrações financeiras típicas que usam esta API incluem onboarding ACH, configuração de pagamentos, painéis de operações de pagamento, etapas de validação KYC/KYB e verificações de risco internas antes do movimento de fundos.

Começando no Zyla API Hub

Abra a página da API de Pesquisa de Número de Roteamento Bancário no Zyla API Hub e inicie um teste para obter sua chave. A Zyla emite uma chave de API que você pode usar em todo o mercado com um modelo de assinatura + cota (não pago por chamada). A primeira API frequentemente oferece um teste de 7 dias ou 50 solicitações; verifique a página da API para opções de acesso e preços atuais.

Iniciar teste de 7 dias na API de Pesquisa de Número de Roteamento Bancário

Endpoints que você usará

A API expõe dois endpoints GET que você pode chamar diretamente do seu backend ou trabalhos de trabalhador. Todas as chamadas requerem o cabeçalho de Autorização com sua chave de API Zyla.

1) Obter Informações do Banco

Use isso quando você tiver um número de roteamento e um tipo de pagamento e precisar de metadados completos do banco, incluindo status e data da última atualização.

Método: GET
URL: https://zylalabs.com/api/331/routing-number-bank-lookup-api/266/get-bank-information
Parâmetros de consulta obrigatórios:
- routingnumber (número): por exemplo, 121000245
- paymentType (string): por exemplo, ach

Copie e cole cURL (cabeçalho de Autorização necessário):

curl -s -X GET "https://zylalabs.com/api/331/routing-number-bank-lookup-api/266/get-bank-information?routingnumber=121000245&paymentType=ach" \
-H "Authorization: Bearer YOUR_API_KEY"

Exemplo de resposta oficial:

{
"status": "success",
"data": {
"routingNumber": "121000245",
"paymentType": "ach",
"name": "Wells Fargo Bank, Na",
"addressFull": "255 2nd Ave South, Minneapolis, MN 55479",
"street": "255 2nd Ave South",
"city": "Minneapolis",
"state": "MN",
"zip": "55479",
"type": "Main Office",
"phone": "800-245-2426",
"active": true,
"lastUpdated": "2026-07-29"
}
}

Destaques dos campos que você realmente usará:

data.routingNumber e data.paymentType: ecoa sua entrada para correlação.
data.name, data.type: use em telas de confirmação e lógica de correspondência bancária.
data.addressFull (mais street/city/state/zip): armazene para auditoria ou fluxos de trabalho de suporte.
data.phone: útil para procedimentos de verificação manual.
data.active: bloqueie pagamentos se falso.
data.lastUpdated: uma string de data que você pode registrar para avaliar a frescura dos dados em seu cache.

2) Dados do Banco

Use isso quando você tiver apenas um número de roteamento e quiser um resultado de validação com detalhes principais da instituição.

Método: GET
URL: https://zylalabs.com/api/331/routing-number-bank-lookup-api/1353/bank-data
Parâmetros de consulta obrigatórios:
- number (número): por exemplo, 304082876

Copie e cole cURL:

Exemplo de resposta:

Campos-chave para mapear:

success e message: sinal de validação rápida para UI ou verificações em lote.
data.routing_number: número de roteamento normalizado que você pesquisou.
data.bank, data.address, data.city, data.state, data.zip, data.phone: perfil bancário principal.
data.date_of_revision: string de data indicando quando o registro foi revisado pela última vez; mantenha para reconciliação e heurísticas de invalidação de cache.

Exemplo de ponta a ponta em Python

O script abaixo chama Obter Informações do Banco, verifica o status e imprime campos normalizados que você comumente persistirá. Ele usa a URL exata e os parâmetros mostrados acima. Substitua YOUR_API_KEY pela sua chave Zyla.

import os
import requests

API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
URL = "https://zylalabs.com/api/331/routing-number-bank-lookup-api/266/get-bank-information"
params = {
"routingnumber": "121000245",
"paymentType": "ach",
}
headers = {
"Authorization": f"Bearer {API_KEY}",
}

resp = requests.get(URL, params=params, headers=headers, timeout=15)
resp.raise_for_status()
payload = resp.json()

if payload.get("status") != "success" or "data" not in payload:
raise SystemExit(f"Lookup failed or unexpected response: {payload}")

data = payload["data"]

normalized = {
"routing_number": data.get("routingNumber"),
"payment_type": data.get("paymentType"),
"bank_name": data.get("name"),
"branch_type": data.get("type"),
"address_full": data.get("addressFull"),
"city": data.get("city"),
"state": data.get("state"),
"zip": data.get("zip"),
"phone": data.get("phone"),
"active": data.get("active"),
"last_updated": data.get("lastUpdated"),
}

print("Registro bancário validado:")
for k, v in normalized.items():
print(f"{k}: {v}")

# Exemplo: lógica de bloqueio simples
if not normalized["active"]:
raise SystemExit("O roteamento bancário não está ativo; bloqueie a configuração ACH.")

# Persistir em seu armazenamento de dados ou continuar o fluxo de onboarding aqui.

Escolhendo o endpoint certo para seu fluxo

Use Obter Informações do Banco quando precisar da bandeira ativa, do tipo (por exemplo, Escritório Principal) e de uma data lastUpdated clara junto com um endereço estruturado e contexto de tipo de pagamento ACH.
Use Dados do Banco para uma verificação de validade leve que retorna os campos principais do perfil da instituição e uma mensagem de validação.

Você pode combiná-los se seu fluxo de trabalho começar com uma verificação rápida de validade (Dados do Banco) e escalar para uma extração de perfil mais rica (Obter Informações do Banco) apenas para validações bem-sucedidas ou para bancos que você não armazenou em cache recentemente.

Notas de implementação prática que economizam tempo

Autenticação: Defina Authorization: Bearer YOUR_API_KEY em cada solicitação. Não passe chaves em parâmetros de consulta.
Cache: Números de roteamento são identificadores estáveis. Armazene em cache as pesquisas bem-sucedidas com chave pelo routingNumber. Use lastUpdated ou date_of_revision para decidir se você precisa atualizar. Um trabalho de atualização diário para registros alterados é um padrão comum.
Normalização: Armazene tanto a string de endereço completo quanto os campos separados. A string completa é útil para exibição e tickets de suporte, enquanto campos separados são melhores para pesquisa e correspondência.
Frescor dos dados: lastUpdated (Obter Informações do Banco) é uma string de data. date_of_revision (Dados do Banco) também é uma string de data. Mantenha esses para logs de auditoria.
Contexto ACH: paymentType=ach é obrigatório em Obter Informações do Banco. Mantenha este parâmetro explícito em seu cliente para evitar incompatibilidades acidentais em sua lógica upstream.
Idempotência: Se você reexecutar a mesma consulta de routingnumber, as respostas são determinísticas para registros inalterados. Isso torna seguro chamar durante as tentativas.
Registro: Registre o número de roteamento que você solicitou e os campos de status/sucesso apenas. Evite registrar a chave da API.

Casos de uso financeiros comuns

Onboarding ACH: Valide o número de roteamento em seu formulário “Vincular conta bancária”, exiba o nome do banco e a cidade de volta ao usuário e armazene a bandeira ativa antes de habilitar pagamentos.
Operações de pagamento: Antes de processar um arquivo de pagamento, execute uma verificação em lote para garantir que todos os números de roteamento retornem sucesso/active=true; rejeite ou coloque em quarentena entradas inválidas.
Conformidade e risco: Mantenha o nome legal e o endereço do banco em arquivo para revisões de contraparte e artefatos de auditoria interna.
Suporte ao cliente: Use o telefone e o endereço retornados para ajudar usuários que digitarem incorretamente um número de roteamento ou para confirmar detalhes da instituição durante revisões manuais.