Tienes un código SWIFT/BIC proveniente de un formulario, webhook o CSV y necesitas validarlo programáticamente antes de enviar un pago o almacenarlo. Al final de este artículo, podrás validar un código SWIFT y obtener sus componentes analizados utilizando una sola solicitud HTTP GET a un endpoint de producción que puedes implementar esta semana.
Qué hace esta API y cuándo usarla
La API de Búsqueda de Códigos SWIFT valida un código SWIFT (BIC) dado y devuelve datos estructurados sobre él. Los equipos la utilizan para controlar flujos de transferencias bancarias, limpiar conjuntos de datos financieros y agregar validación del lado del servidor a la incorporación o pagos. Pasas un código SWIFT; la API responde con un estado, un mensaje legible por humanos y un objeto estructurado que incluye el código y un desglose.
Debido a que esta es una API en Zyla API Hub, obtienes una cuenta, una clave API y un modelo de suscripción y cuota en todo el mercado. Si ya estás utilizando otras APIs de Zyla para finanzas o verificación, puedes agregar esta verificación a tu stack sin gestionar otra credencial.
Navega por el catálogo más amplio en zylalabs.com—hay más de 10,000 APIs públicas disponibles bajo una experiencia de desarrollador consistente.
Comenzando en Zyla API Hub
Para integrar rápidamente:
- Abre la lista de la API de Búsqueda de Códigos SWIFT en Zyla API Hub y haz clic en Suscribirse. La primera API que agregues puede comenzar con una prueba de 7 días o 50 solicitudes, dependiendo de la disponibilidad. No hay un Plan Gratuito; el uso es suscripción + cuota, no pago por llamada—verifica la página de la API para las opciones de acceso y precios actuales.
- Copiar tu clave API desde tu cuenta. La autenticación es a través de encabezado: Authorization: Bearer YOUR_API_KEY.
- Llama al endpoint a continuación desde tu servidor o herramienta de elección.
Siempre puedes regresar a zylalabs.com para gestionar suscripciones, cuotas y claves a través de APIs.
Endpoint que realmente usarás
La API de Búsqueda de Códigos SWIFT expone un único endpoint de búsqueda que puedes llamar directamente con un HTTP GET. Usa esto cuando tengas un código SWIFT/BIC en mano y desees un resultado de validación y un desglose analizado.
Búsqueda de Código
- Método: GET
- URL: https://zylalabs.com/api/1714/swift-code-lookup-api/1327/code-lookup
- Parámetro de consulta requerido:
- code (string): el SWIFT/BIC que deseas validar. Valor de ejemplo: ADTVBRDF
- Auth: Authorization: Bearer YOUR_API_KEY
Copia-pega cURL
Esta es la forma más rápida de probar el servicio en vivo desde tu terminal. Reemplaza YOUR_API_KEY con tu clave:
curl -s -X GET "https://zylalabs.com/api/1714/swift-code-lookup-api/1327/code-lookup?code=ADTVBRDF" \
-H "Authorization: Bearer YOUR_API_KEY"
Respuesta de ejemplo oficial
La API devuelve un documento JSON con un estado de nivel superior e indicador de éxito, un mensaje y un objeto de datos que contiene el código y su desglose. Aquí está la carga útil de muestra oficial:
{
"status": 200,
"success": true,
"message": "El código SWIFT AXISINBB301 es 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
}
}
}
Qué leer en la práctica:
- status y success: usa estos para controlar tu flujo. Un 200 con success: true significa que la búsqueda tuvo éxito.
- message: un mensaje de validación legible por humanos que puedes registrar para operadores o mostrar en herramientas administrativas.
- data.swift_code: el SWIFT/BIC normalizado que fue validado.
- data.breakdown: un desglose estructurado del código en componentes. Los campos individuales pueden ser nulos cuando no están disponibles.
Ejemplo de Python que puedes pegar en tu servicio
El fragmento a continuación llama al mismo endpoint y muestra cómo manejar los campos de respuesta y nulos de manera segura. La URL y los valores de parámetros coinciden con el cURL oficial anterior, por lo que puedes ejecutar esto sin editar nada excepto tu clave 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()
# Control básico
if not data.get("success"):
raise SystemExit(f"La búsqueda falló: {data.get('message')}")
print(f"Mensaje: {data.get('message')}")
payload = data.get("data", {}) or {}
swift = payload.get("swift_code")
bank = payload.get("bank") # puede ser None
country = payload.get("country") # puede ser None
breakdown = (payload.get("breakdown") or {})
bank_code = breakdown.get("bank_code") # puede ser None
country_code = breakdown.get("country_code") # puede ser None
branch_code = breakdown.get("branch_code") # puede ser None
print("Código SWIFT validado:", swift)
print("Banco (si está disponible):", bank)
print("País (si está disponible):", country)
print("Desglose:", {
"bank_code": bank_code,
"country_code": country_code,
"branch_code": branch_code
})
Cómo integrar esto en flujos reales
La mayoría de los equipos llaman a esta API del lado del servidor desde la creación de pagos o endpoints de incorporación de beneficiarios. Un patrón común:
- El usuario envía detalles bancarios, incluyendo un código SWIFT/BIC.
- Tu backend valida el código SWIFT llamando al endpoint de Búsqueda de Código antes de guardarlo o usarlo.
- Si success es true, continúa; si es false o el estado no es 200, rechaza la entrada y registra el mensaje para revisión.
Otros usos prácticos:
- Limpieza por lotes: itera sobre códigos SWIFT en un CSV y almacena solo las filas que pasan la validación.
- Herramientas de conciliación: marca automáticamente entradas con valores de desglose inesperados para QA manual.
- Tableros administrativos: muestra el mensaje y el desglose junto a los códigos SWIFT enviados por el usuario.
Detalles de implementación que ahorran tiempo
- Autenticación: cada solicitud debe incluir Authorization: Bearer YOUR_API_KEY.
- Método HTTP: solo GET. Incluye el código como un parámetro de consulta.
- Nulos: campos como banco, país y partes individuales del desglose pueden ser nulos. Siempre verifica nulos antes de usarlos.
- Cacheo: si validas repetidamente el mismo código SWIFT, almacena el resultado en tu datastore para reducir la latencia y el uso de cuota. Un simple caché TTL en memoria o una fila indexada por código SWIFT suele ser suficiente.
- Observabilidad: registra el campo de mensaje al rechazar entradas para una depuración más rápida en escalaciones de soporte.
- Seguridad: no registres claves API de usuario. Almacena tu clave API de Zyla en variables de entorno o en un gestor de secretos.
- Cuotas: el uso de las APIs de Zyla es suscripción + cuota. La primera API puede comenzar con una prueba de 7 días o 50 solicitudes. Para límites actuales, consulta la página de la API en tu cuenta.
Patrones de manejo de errores
Si bien el ejemplo anterior muestra una búsqueda exitosa, el código de producción debe protegerse contra:
- Respuestas HTTP no 200: trata como fallos transitorios o errores de entrada del usuario dependiendo del contexto.
- success false: lee el mensaje para una breve explicación humana y decide si reintentar o rechazar.
- Time-outs de red: establece time-outs razonables para el cliente y envuelve las llamadas con reintentos si la operación es idempotente.
Usando la API desde agentes de IA a través de MCP
Si prefieres integrar esta búsqueda en un agente de codificación de IA o asistente de IDE, Zyla expone herramientas compatibles a través de MCP. Apunta tu cliente compatible con MCP (por ejemplo, Claude Code, Cursor, Windsurf) al endpoint documentado aquí y autoriza con tu clave API. Consulta la documentación de MCP para más detalles:
Esto te permite activar la misma Búsqueda de Código desde dentro de un flujo de trabajo de agente sin cambiar tu backend. Tu agente enviará la misma solicitud GET y leerá los mismos campos (status, success, message, data.swift_code, data.breakdown). Mantén tu clave API limitada a entornos de desarrollo al probar integraciones de agentes.
Lista de verificación de validación de extremo a extremo
- Suscripción activa en Zyla API Hub y clave API almacenada de forma segura.
- Llamada GET del lado del servidor al endpoint de Búsqueda de Código con el código establecido en el SWIFT/BIC proporcionado por el usuario.
- Verifica success y status antes de proceder con un pago o guardar un beneficiario.
- Maneja los campos nulos de manera adecuada en tu interfaz de usuario o capa de datos.
- Cachea las búsquedas por código SWIFT donde sea apropiado.
- Registra el mensaje para operaciones y soporte.
Dónde obtener tu clave y ejecutar tu primera solicitud
Suscríbete a la API, inicia la prueba de 7 días cuando esté disponible y copia tu clave. Puedes llamar al endpoint de inmediato con el cURL anterior y luego insertar el ejemplo de Python en tu servicio. Gestiona tu uso y agrega otras APIs en finanzas, enriquecimiento de datos y utilidades desde la misma cuenta en zylalabs.com.
Inicia prueba de 7 días en la API de Búsqueda de Códigos SWIFT
FAQ
¿Qué formatos de entrada son compatibles para el parámetro de código?
Pasa un código SWIFT/BIC como una cadena simple a través del parámetro de consulta code en una solicitud GET.
¿En qué campos debo confiar para decidir si un código SWIFT es válido?
Verifica success y status. También lee el mensaje para una explicación concisa adecuada para registros o interfaces de usuario administrativas.
¿Por qué algunos campos en data o breakdown son nulos?
No todos los metadatos están disponibles para cada código. Siempre verifica nulos en campos como banco, país y partes del desglose antes de usarlos.
¿Puedo probar esto desde mi terminal antes de integrar?
Sí. Usa el comando cURL proporcionado con tu clave API para verificar rápidamente el endpoint y tu encabezado de autenticación.
¿Cómo se maneja la facturación?
Las APIs de Zyla utilizan un modelo de suscripción + cuota, no pago por llamada. La primera API puede comenzar con una prueba de 7 días o 50 solicitudes dependiendo de la disponibilidad—verifica la lista de la API en tu cuenta para las opciones actuales.