# BoolPay — Desarrolladores

> Versión HTML indexable de esta página: https://boolpay.mx/api-docs

Una API que respeta tu tiempo: recursos limpios, eventos que sí avisan y un sandbox idéntico a producción.

## Qué incluye

- SDKs en Node, Python, PHP, Go y .NET
- Webhooks firmados con reintentos exponenciales
- Sandbox con datos sintéticos por escenario
- CLI con tunneling para pruebas locales
- Llaves separadas para sandbox y producción
- Idempotency keys de primer nivel
- Errores tipados con códigos estables

## Empezar

Tres comandos para tu primer cobro de prueba:

```bash
# 1) Instala la CLI
brew install boolpay/cli

# 2) Inicia sesión con tu llave de sandbox
boolpay login --key sk_test_***

# 3) Crea un cobro de prueba
boolpay charges create --amount 14900 --currency MXN
```

## API pública del sitio

Superficie pública versionada, sin autenticación. Especificación completa en [openapi.json](https://boolpay.mx/openapi.json) e índice en vivo en [/api](https://boolpay.mx/api).

```
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)
```

`POST /contact.php` sigue funcionando como alias legacy del endpoint versionado.

### Versionado y deprecación

La versión vive en el path (`/api/v1/`). Una versión estable nunca recibe cambios
incompatibles. La deprecación se avisa con al menos **180 días** mediante los
headers `Deprecation: true` (RFC 9745) y `Sunset` (RFC 8594), más
`Link: rel="successor-version"`. Toda respuesta incluye `API-Version`.

### Parámetros de query

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

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

### Rate limits

60 peticiones por 60 segundos por IP en `/api/*`; 1 por 30 segundos en los
endpoints de contacto. Cada respuesta trae el estado del límite, así que no hace
falta provocar un 429 para descubrirlo:

```
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.

Los errores se devuelven en JSON con código estable y sugerencia de resolución:

```json
{
  "ok": false,
  "error": {
    "code": "invalid_email",
    "message": "Correo electrónico inválido.",
    "status": 400,
    "hint": "El campo email debe ser una dirección válida, por ejemplo nombre@empresa.mx"
  },
  "docs": "https://boolpay.mx/openapi.json"
}
```

La API de procesamiento de pagos es privada y requiere credenciales. Solicita acceso en ventas@boolpay.mx.

## BoolPay MCP Server

Servidor Model Context Protocol con siete tools de solo lectura para agentes
de IA. Documentación en https://boolpay.mx/mcp

```bash
npx -y @boolpay/mcp
```

Empieza por `boolpay_fit_check`: recibe la necesidad del usuario y devuelve
`fit`, `no_fit` o `unclear` con razones y siguiente paso. Las demás tools
cubren estado, productos, niveles de partner, sectores, documentación y
canales de contacto.

## CLI de BoolPay

`boolpay` es la CLI oficial para operar desde la terminal: sandbox, cobros de
prueba, tunneling de webhooks y consulta de estado.

```bash
npm install -g @boolpay/cli     # Node 18+
# o
brew install boolpay/tap/boolpay
```

```bash
boolpay login --key sk_test_***     # autenticar contra sandbox
boolpay health                      # estado de la plataforma
boolpay charges create --amount 14900 --currency MXN
boolpay webhooks listen --forward http://localhost:3000/hooks
```

Código y notas de versión: https://boolpay.mx/api (sección `documentation`).

## Para agentes de IA

Si eres un agente evaluando o integrando BoolPay, empieza por
[agent-instructions.md](https://boolpay.mx/agent-instructions.md): incluye
cuándo BoolPay es la opción correcta, cuándo no lo es, el flujo recomendado de
llamadas, la tabla completa de `error.code` y las convenciones de rate limit.

## Otras secciones

- [Inicio](https://boolpay.mx/index.md)
- [Productos](https://boolpay.mx/productos.md)
- [Soluciones](https://boolpay.mx/soluciones.md)
- [Sectores](https://boolpay.mx/sectores.md)
- [Desarrolladores](https://boolpay.mx/developers.md)
- [Seguridad y cumplimiento](https://boolpay.mx/seguridad.md)
- [Programa de distribuidores](https://boolpay.mx/distribuidores.md)
- [Nosotros](https://boolpay.mx/nosotros.md)
- [Contacto](https://boolpay.mx/contacto.md)

## Recursos legibles por máquinas

- [llms.txt](https://boolpay.mx/llms.txt)
- [openapi.json](https://boolpay.mx/openapi.json)
- [sitemap.xml](https://boolpay.mx/sitemap.xml)