Agent guide

# Integración con Recaudo — Guía para Agentes de IA

## Qué es Recaudo
Recaudo es una plataforma de orquestación de pagos con API REST. Permite crear links de pago,
cobrar con tarjeta, gestionar clientes, suscripciones, facturas, WhatsApp y más.

## Base URL
```
https://recaudo.app/api/v1
```

## Autenticación
Todas las peticiones requieren el header:
```
Authorization: Bearer {SECRET_KEY}
```
La Secret Key se obtiene desde el panel en Configuración → API Keys.
NUNCA exponer la Secret Key en código frontend.

## Montos
TODOS los montos son en DECIMALES (100.00 = $100 pesos). NO usar centavos.

## Endpoints principales

### Clientes
- `GET    /customers` — Listar clientes (paginado, ?search=, ?page=)
- `POST   /customers` — Crear cliente (name, email, phone?, city?, notes?)
- `GET    /customers/{id}` — Ver cliente
- `PUT    /customers/{id}` — Actualizar cliente
- `DELETE /customers/{id}` — Eliminar cliente

### Links de Pago
- `GET    /payment-links` — Listar links
- `POST   /payment-links` — Crear link (title, amount, currency?, description?, expiration_days?)
- `GET    /payment-links/{id}` — Ver link
- `PUT    /payment-links/{id}` — Actualizar link
- `DELETE /payment-links/{id}` — Eliminar link

### Cargos (cobro directo con tarjeta tokenizada)
- `POST   /charges` — Crear cargo (customer_id, amount, currency, payment_method_token, description?)
- `GET    /charges/{id}` — Ver cargo

### Tokenización (guardar tarjeta)
- `POST   /customers/{id}/payment-methods` — Tokenizar tarjeta (card_number, exp_month, exp_year, cvv, holder_name)
- `GET    /customers/{id}/payment-methods` — Listar métodos de pago
- `DELETE /customers/{id}/payment-methods/{pm_id}` — Eliminar método

### Suscripciones
- `GET    /subscriptions` — Listar suscripciones
- `POST   /subscriptions` — Crear (customer_id, plan_name, amount, currency, interval: monthly|yearly, payment_method_token?)
- `GET    /subscriptions/{id}` — Ver suscripción
- `POST   /subscriptions/{id}/cancel` — Cancelar
- `POST   /subscriptions/{id}/pause` — Pausar
- `POST   /subscriptions/{id}/resume` — Reanudar

### Facturas
- `GET    /invoices` — Listar facturas
- `POST   /invoices` — Crear factura (customer_id, items[{description, quantity, unit_price}], due_date?, notes?)
- `GET    /invoices/{id}` — Ver factura
- `POST   /invoices/{id}/send` — Enviar por email
- `POST   /invoices/{id}/mark-paid` — Marcar como pagada

### Webhooks
- `GET    /webhook-endpoints` — Listar endpoints
- `POST   /webhook-endpoints` — Crear endpoint (url, events[], description)
- `GET    /webhook-endpoints/{id}` — Ver detalle con secret
- `PUT    /webhook-endpoints/{id}` — Actualizar url, eventos, estado
- `DELETE /webhook-endpoints/{id}` — Eliminar endpoint
- `POST   /webhook-endpoints/{id}/test` — Enviar evento de prueba
- `POST   /webhook-endpoints/{id}/rotate-secret` — Rotar secret
- `GET    /webhook-endpoints/{id}/deliveries` — Ver entregas
- `POST   /webhook-endpoints/{id}/deliveries/{delivery_id}/resend` — Reenviar

### Conversaciones (WhatsApp)
- `GET    /conversations` — Listar conversaciones
- `GET    /conversations/{id}` — Ver conversación con mensajes
- `POST   /conversations/{id}/messages` — Enviar mensaje (body)
- `POST   /conversations/{id}/close` — Cerrar conversación

### Templates de WhatsApp (HSM)
- `GET    /whatsapp-templates` — Listar templates aprobados
- `POST   /whatsapp-templates/{id}/send` — Enviar template (customer_id, parameters?)

### Seguimientos (Cobranza)
- `GET    /follow-ups` — Listar seguimientos (?status=pending|completed|overdue)
- `POST   /follow-ups` — Crear (customer_id, title, description?, due_date, type: call|email|whatsapp|visit|other)
- `PUT    /follow-ups/{id}` — Actualizar
- `POST   /follow-ups/{id}/complete` — Marcar completado

### Productos (Tienda)
- `GET    /products` — Listar productos
- `POST   /products` — Crear (name, price, description?, sku?, stock?)
- `PUT    /products/{id}` — Actualizar
- `DELETE /products/{id}` — Eliminar

### Pedidos (Tienda)
- `GET    /orders` — Listar pedidos
- `GET    /orders/{id}` — Ver pedido
- `PUT    /orders/{id}/status` — Cambiar status (status: pending|processing|shipped|delivered|cancelled)

### Equipo
- `GET    /team` — Listar miembros del equipo

### Fuentes de Clientes
- `GET    /customer-sources` — Listar fuentes de clientes

## Paginación
Todas las listas devuelven paginación:
```json
{
  "data": [...],
  "meta": { "current_page": 1, "last_page": 5, "per_page": 25, "total": 112 },
  "links": { "next": "...?page=2", "prev": null }
}
```
Parámetros: `?page=1&per_page=25` (máximo 100).

## Errores
```json
{
  "error": { "code": "validation_error", "message": "...", "details": {...} }
}
```
Códigos HTTP: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 422 Unprocessable, 429 Rate Limited, 500 Server Error.

## MCP Server (recomendado para Claude Code)
Si usas Claude Code, conecta el MCP server para acceso directo:
```bash
claude mcp add recaudo -e RECAUDO_API_KEY=sk_live_tu_key -- npx -y @recaudo/mcp-server
```
Esto te da 131 herramientas nativas sin necesidad de hacer requests HTTP manuales.

## Ejemplo rápido: crear cliente + link de pago
```bash
# 1. Crear cliente
curl -X POST https://recaudo.app/api/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Juan Pérez", "email": "juan@email.com", "phone": "+5255123456"}'

# 2. Crear link de pago
curl -X POST https://recaudo.app/api/v1/payment-links \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Consultoría", "amount": 1500.00, "currency": "MXN"}'
```

## Notas para el agente
- Siempre validar que la respuesta sea 2xx antes de proceder.
- Los IDs son UUIDs (formato: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
- El rate limit es 60 requests/minuto por API key.
- Para desarrollo, usa API keys de prueba (prefijo sk_test_).
- La moneda por defecto es MXN si no se especifica.