BoolPay API — documentación, OpenAPI y endpoints públicos

Especificación OpenAPI de BoolPay

La especificación completa de la API de BoolPay está publicada en /openapi.json (OpenAPI 3.1). Incluye esquemas de respuesta tipados para cada operación, ejemplos por tipo de formulario y la lista enumerada de códigos de error.

Endpoints públicos de BoolPay

GET  https://boolpay.mx/api                 índice, versiones y rate limits
GET  https://boolpay.mx/api/versioning      política de versionado y deprecación
GET  https://boolpay.mx/api/v1              endpoints de la v1
GET  https://boolpay.mx/api/v1/health       estado de la plataforma
POST https://boolpay.mx/api/v1/contact      formulario de contacto (captcha visual)

La superficie pública no requiere autenticación. La API de procesamiento de pagos de BoolPay es privada y requiere credenciales: solicítalas en ventas@boolpay.mx.

Versionado y deprecación de la API de BoolPay

La versión vive en el path (/api/v1/) y toda respuesta incluye el header API-Version. Una versión estable nunca recibe cambios incompatibles; agregar campos opcionales no se considera incompatible.

La deprecación se anuncia con al menos 180 días mediante Deprecation: true (RFC 9745), Sunset: <http-date> (RFC 8594) y Link: rel="successor-version" (RFC 8288). Pasada la fecha de sunset, la versión responde 410 Gone con error.code = "api_version_sunset". Política legible por máquinas en /api/versioning.

Parámetros de query

Los endpoints de descubrimiento aceptan parámetros opcionales para acotar la respuesta, útil cuando un agente trabaja con contexto limitado:

Endpoint	Parámetro	Valores
`/api`	`section`	`versions`, `rate_limit`, `versioning`, `contact`, `docs`
`/api/versioning`	`version`	`vN` (ej. `v1`) — devuelve el estado de esa versión
`/api/v1`	`method`	`GET`, `POST`
`/api/v1/health`	`verbose`	`true`, `false`

curl "https://boolpay.mx/api?section=rate_limit"
curl "https://boolpay.mx/api/versioning?version=v1"
curl "https://boolpay.mx/api/v1/health?verbose=true"

Un valor fuera del enum devuelve 400 con error.code = "invalid_parameter" y la lista de valores admitidos en error.allowed_values.

Rate limits

Grupo	Límite	Alcance
`/api/*`	60 peticiones / 60 s	por IP
Endpoints de contacto	1 petición / 30 s	por IP

RateLimit-Policy: "default";q=60;w=60
RateLimit: "default";r=57;t=42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1772668800

Los 429 incluyen Retry-After en segundos. No hace falta provocar un 429 para descubrir el límite.

Errores de la API de BoolPay

Todos los errores son JSON. Ramifica sobre error.code, que es estable dentro de una versión mayor; error.hint describe la acción correctiva.

{
  "ok": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Se excedió el límite de 60 peticiones por 60 segundos.",
    "status": 429,
    "hint": "Espera 42 segundos. Lee los headers RateLimit y Retry-After.",
    "retry_after_seconds": 42
  },
  "docs": "https://boolpay.mx/openapi.json"
}

BoolPay MCP Server

Para agentes de IA, BoolPay publica un servidor Model Context Protocol con siete tools de solo lectura. Documentación completa en /mcp y manifest en /mcp.json.

npx -y @boolpay/mcp

El punto de entrada recomendado es boolpay_fit_check: recibe la necesidad del usuario y devuelve un veredicto (fit, no_fit o unclear) con razones y siguiente paso.

CLI de BoolPay

npm install -g @boolpay/cli

boolpay health          # estado de la plataforma
boolpay api             # índice de la API
boolpay versioning      # política de versionado
boolpay spec            # resumen del OpenAPI
boolpay docs productos  # cualquier página en Markdown

Recursos de desarrollo de BoolPay

BoolPay OpenAPI 3.1 — esquema completo de la API pública
BoolPay API index — documento de descubrimiento en vivo (JSON)
BoolPay MCP server — 7 tools de solo lectura para agentes de IA
BoolPay MCP manifest — definición de tools legible por máquinas
BoolPay versioning policy — versionado y deprecación
BoolPay agent instructions — guía when-to-use para agentes de IA
BoolPay developer docs — SDKs, sandbox, webhooks y CLI en Markdown
BoolPay API health check — endpoint de estado
llms.txt — índice del sitio para agentes

Para agentes de IA. Si eres un agente evaluando BoolPay, empieza por agent-instructions.md: incluye cuándo BoolPay es la opción correcta, cuándo no lo es, el flujo de llamadas recomendado y la tabla completa de error.code.

BoolPay API — documentación para desarrolladores