Documentación API REST

Guía técnica completa para integrar la API de validación bancaria BankValidor en sus aplicaciones.

La API REST BankValidor permite validar coordenadas bancarias internacionales (IBAN, SWIFT/BIC, ABA Routing, Sort Code UK) mediante llamadas HTTP simples. Cada validación realiza hasta 3 capas de verificación: sintaxis, checksum y registro oficial.

Autenticación

Todas las solicitudes API requieren una clave API válida transmitida en el encabezado HTTP. Obtenga su clave API suscribiéndose a un Paquete Starter o Business.

X-API-Key: your_api_key_here

Mantenga su clave API segura. Nunca la exponga en código del lado del cliente ni en repositorios públicos.

URL base

Todos los endpoints de la API son accesibles únicamente por HTTPS. Utilice la siguiente URL base para todas sus solicitudes.

https://bankvalidor.com/api/v1

Endpoints de validación

La API expone endpoints dedicados para cada tipo de coordenada bancaria. Todos los endpoints aceptan solicitudes POST con un cuerpo JSON.

POST/api/v1/validate/us

Valida un par ABA Routing Number + Account Number estadounidense. Verifica la sintaxis, el checksum ABA y la presencia en el directorio de la Reserva Federal.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
routing_number	string	Sí	ABA Routing Number (9 dígitos)
account_number	string	Sí	Número de cuenta bancaria (4-17 dígitos)

Parámetros de consulta

Campo	Tipo	Por defecto	Descripción
enrich	boolean	false	Enriquecer con datos FDIC (nombre oficial, dirección, coordenadas GPS)

Ejemplo de solicitud

curl -X POST https://bankvalidor.com/api/v1/validate/us?enrich=true \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "routing_number": "021000021",
    "account_number": "1234567890"
  }'

Ejemplo de respuesta

{
  "status": "VALID",
  "confidence": "HIGH",
  "reliability_message": "...",
  "reliability_color": "green",
  "bank_info": {
    "name": "JPMORGAN CHASE BANK, NA",
    "city": "Tampa",
    "state": "FL",
    "active": true,
    "fdic_cert": "628",
    "headquarters_address": "1111 Polaris Parkway, Columbus, OH 43240",
    "coordinates": { "latitude": 40.1289, "longitude": -82.9813 },
    "enriched": true
  },
  "validation_details": {
    "routing_number": {
      "valid": true,
      "checksum_passed": true,
      "found_in_registry": true,
      "errors": [],
      "warnings": []
    },
    "account_number": {
      "valid": true,
      "format_correct": true,
      "length_valid": true,
      "errors": [],
      "warnings": []
    }
  },
  "warnings": [],
  "errors": [],
  "cache_hit": false,
  "response_time_ms": 42
}

POST/api/v1/validate/uk

Valida un par Sort Code + Account Number británico. Verifica el formato, el modulus check y la presencia en el directorio Pay.UK.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
sort_code	string	Sí	Sort Code británico (formato XX-XX-XX o 6 dígitos)
account_number	string	Sí	Número de cuenta bancaria (8 dígitos)

Ejemplo de solicitud

curl -X POST https://bankvalidor.com/api/v1/validate/uk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "sort_code": "20-00-00",
    "account_number": "12345678"
  }'

Ejemplo de respuesta

{
  "status": "VALID",
  "confidence": "HIGH",
  "reliability_message": "...",
  "reliability_color": "green",
  "bank_info": {
    "name": "BARCLAYS BANK UK PLC",
    "branch_name": "Barclays Bank",
    "city": "London",
    "country_code": "GB",
    "active": true,
    "supports_faster_payments": true,
    "supports_bacs": true,
    "supports_chaps": true
  },
  "validation_details": {
    "sort_code": {
      "valid": true,
      "modulus_check_passed": true,
      "found_in_registry": true,
      "errors": [],
      "warnings": []
    },
    "account_number": {
      "valid": true,
      "format_correct": true,
      "length_valid": true,
      "errors": [],
      "warnings": []
    }
  },
  "warnings": [],
  "errors": [],
  "cache_hit": false,
  "response_time_ms": 38
}

POST/api/v1/validate/swift

Valida un código SWIFT/BIC internacional. Verifica el formato ISO 9362 y la presencia en el directorio SWIFT.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
bic	string	Sí	Código SWIFT/BIC (8 u 11 caracteres)

Ejemplo de solicitud

curl -X POST https://bankvalidor.com/api/v1/validate/swift \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "bic": "CHASUS33XXX"
  }'

Ejemplo de respuesta

{
  "status": "VALID",
  "confidence": "HIGH",
  "reliability_message": "...",
  "reliability_color": "green",
  "bank_info": {
    "name": "JPMORGAN CHASE BANK, N.A.",
    "city": "New York",
    "country_code": "US",
    "country_name": "United States",
    "branch_code": "XXX",
    "active": true,
    "is_test_code": false
  },
  "validation_details": {
    "bic": {
      "valid": true,
      "format_correct": true,
      "found_in_registry": true,
      "country_valid": true,
      "errors": [],
      "warnings": []
    }
  },
  "warnings": [],
  "errors": [],
  "cache_hit": false,
  "response_time_ms": 25
}

POST/api/v1/validate/iban

Valida un IBAN internacional. Verifica la sintaxis ISO 13616, los dígitos de control (mod-97) y el código de país.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
iban	string	Sí	Número IBAN completo (15-34 caracteres)

Ejemplo de solicitud

curl -X POST https://bankvalidor.com/api/v1/validate/iban \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "iban": "DE89370400440532013000"
  }'

Ejemplo de respuesta

{
  "status": "VALID",
  "confidence": "HIGH",
  "reliability_message": "...",
  "reliability_color": "green",
  "bank_info": null,
  "validation_details": {
    "iban": {
      "valid": true,
      "syntax_valid": true,
      "checksum_valid": true,
      "country_recognized": true,
      "bban_format_valid": true,
      "is_sepa": true,
      "country_code": "DE",
      "country_name": "Germany",
      "check_digits": "89",
      "bban": "370400440532013000",
      "bank_code": "37040044",
      "account_number": "0532013000",
      "errors": [],
      "warnings": []
    }
  },
  "warnings": [],
  "errors": [],
  "cache_hit": false,
  "response_time_ms": 15
}

POST/api/v1/validate/iban/detailed

Validación detallada de IBAN con desglose completo, información bancaria (BIC, nombre, dirección) y estado de servicios SEPA (SCT, SDD, B2B, SCT Inst).

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
iban	string	Sí	Número IBAN completo (15-34 caracteres)

Ejemplo de solicitud

curl -X POST https://bankvalidor.com/api/v1/validate/iban/detailed \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "iban": "FR7640618803220004034973118"
  }'

Ejemplo de respuesta

{
  "iban": "FR7640618803220004034973118",
  "is_valid": true,
  "country": {
    "code": "FR",
    "name": "France",
    "iban_length": 27
  },
  "checks": {
    "length_valid": true,
    "checksum_valid": true,
    "bank_code_valid": true,
    "account_checksum_valid": true
  },
  "bank_info": {
    "bic": "BOUSFRPP",
    "name": "BOURSORAMA",
    "address": "18 Quai du Point du Jour, 92100 Boulogne-Billancourt"
  },
  "sepa": {
    "member": true,
    "sct": true,
    "sdd": true,
    "b2b": true,
    "sct_inst": true
  }
}

GET/api/v1/health

Verifica el estado de la API y la conectividad con los servicios (base de datos, caché). Útil para monitoreo y health checks.

Ejemplo de solicitud

curl https://bankvalidor.com/api/v1/health \
  -H "X-API-Key: your_api_key_here"

Ejemplo de respuesta

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-01-15T10:30:00Z",
  "database": "connected",
  "cache": "connected"
}

Gestión de errores

La API utiliza códigos HTTP estándar para indicar el resultado de una solicitud. En caso de error, el cuerpo de la respuesta contiene detalles sobre el problema.

Código	Estado	Descripción
200	OK	Solicitud procesada exitosamente. El resultado de la validación está en el cuerpo de la respuesta.
400	Bad Request	La solicitud está mal formada. Verifique el formato JSON y los campos requeridos.
422	Unprocessable Entity	Los datos proporcionados no pasan la validación del esquema Pydantic.
429	Too Many Requests	Límite de velocidad superado. Espere antes de reintentar (ver encabezado X-RateLimit-Reset).
500	Internal Server Error	Error interno del servidor. Contacte al soporte si el problema persiste.

// Error response example

{
  "detail": [
    {
      "loc": ["body", "routing_number"],
      "msg": "Routing number must contain only digits",
      "type": "value_error"
    }
  ]
}

Límites de velocidad

La API aplica límites de velocidad por clave API para garantizar la disponibilidad del servicio. Los encabezados de respuesta contienen información de cuota.

Encabezado	Descripción
X-RateLimit-Limit	Número máximo de solicitudes permitidas por ventana de tiempo
X-RateLimit-Remaining	Número de solicitudes restantes en la ventana actual
X-RateLimit-Reset	Timestamp Unix indicando la reinicialización del contador

Los límites de velocidad dependen de su paquete API. Paquete Starter: 100 req/min. Paquete Business: 500 req/min. Contáctenos para necesidades superiores.

Documentación relacionada

Validación CSV masiva

Valide miles de coordenadas bancarias en una sola solicitud mediante la carga de CSV.

Consultar →

Webhooks

Reciba notificaciones en tiempo real cuando sus validaciones estén completas.

Consultar →

Última actualización: febrero 2026