# Documentación de Horato

Usa Horato mediante REST, SDKs, webhooks, el panel y herramientas MCP.

Horato es un plano de control de comunicaciones y agenda sobre email, calendario, contactos, tareas, reservas, webhooks y acciones de agentes con aprobación.

## Elige una superficie

Usa la API REST para integraciones backend. Usa el panel para operar organizaciones, aplicaciones, API keys, conexiones de proveedor, billing y salud de webhooks. Usa MCP cuando un agente necesite herramientas de lectura y escrituras con aprobación sobre el mismo modelo de acciones.

- API REST: recursos normalizados, IDs de proveedor, etags, payloads originales, cursores de sync y webhooks firmados.

- Panel: UI operativa para setup, monitoreo, billing, keys y reparación.

- MCP: herramientas seguras para búsqueda, disponibilidad, reservas, tareas y email.

## URLs base

El tráfico de producción usa `https://api.hora.to`. La documentación pública en español vive en `https://hora.to/es/docs`.

### Forma del request
```bash
curl https://api.hora.to/v1/email/messages \
  -H "Authorization: Bearer $HORATO_API_KEY" \
  -H "Content-Type: application/json"
```

## Documentación legible por máquinas

OpenAPI, Postman y exportes para LLMs se generan desde el mismo registro de documentación y catálogo derivado del spec.

- `/docs/openapi.json` para herramientas con esquema.

- `/docs/postman.json` para exploración manual de la API.

- `/es/llms.txt` para descubrimiento corto por agentes.

- `/es/docs/llms-full.txt` para una copia completa de docs en texto plano.

---

# Uso de la API

Autentica, conecta proveedores, lee recursos normalizados, escribe con seguridad y reproduce eventos.

Cada respuesta REST usa campos snake_case en la superficie pública. El alcance de organización y aplicación viene de la API key.

## Autenticación

Crea una API key con alcance de aplicación en el panel. Envíala como Bearer token en cada request API. Las API keys contienen scopes, application_id y organization_id.

### Clave Bearer
```bash
curl https://api.hora.to/v1/usage \
  -H "Authorization: Bearer $HORATO_API_KEY"
```

## Flujo de conexión de proveedores

Inicia la autorización OAuth para un proveedor, redirige al usuario y deja que Horato guarde la conexión y los tokens del proveedor. Consulta los endpoints de capacidades antes de intentar operaciones específicas del proveedor.

### Iniciar autorización de Google
```bash
curl -X POST https://api.hora.to/v1/auth/connectors/google/authorize \
  -H "Authorization: Bearer $HORATO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["email.read","calendar.write"],"redirect_uri":"https://app.example.com/oauth/callback"}'
```

## Leer y mutar recursos

Prefiere IDs canónicos para recursos almacenados y conserva IDs de proveedor para reconciliación. Las mutaciones deben incluir etags cuando la superficie del recurso expone control de conflictos.

### Leer mensajes
```bash
curl "https://api.hora.to/v1/email/messages?connection_id=conn_123&limit=25" \
  -H "Authorization: Bearer $HORATO_API_KEY"
```

### Crear evento de calendario
```bash
curl -X POST https://api.hora.to/v1/calendars/cal_primary/events \
  -H "Authorization: Bearer $HORATO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connection_id":"conn_123","title":"Intro call","start":"2026-06-10T16:00:00Z","end":"2026-06-10T16:30:00Z"}'
```

## Paginación e idempotencia

Los endpoints de lista devuelven `next_cursor` cuando existen más resultados. Los endpoints de escritura deben enviar el header `Idempotency-Key` para crear recursos de forma segura cuando el cliente pueda reintentar después de fallos de red.

---

# Referencia API

Catálogo de endpoints generado desde specs.json.

Esta referencia refleja la especificación actual del producto. Está diseñada para que humanos y LLMs escaneen dominios con rapidez.

## Artefactos de referencia

Descarga la referencia legible por máquinas cuando necesites clientes con esquema o herramientas externas. La vista de página agrupa endpoints por dominio.

- /docs/openapi.json

- /docs/postman.json

- /es/docs/llms-full.txt

---

# Uso del panel

Opera organizaciones, aplicaciones, conexiones, webhooks, sync, MCP y configuración desde el panel.

El panel es la superficie humana para configurar, probar, monitorear y reparar el mismo sistema que consumen REST, SDKs y MCP.

## Alcance de organización y aplicación

Elige primero la organización y luego la aplicación que posee la API key y las conexiones de proveedor. Cada request API y acción del panel debe interpretarse dentro de ese alcance de aplicación.

- Usa una aplicación por entorno de producto cuando staging y producción tengan proveedores distintos.

- Rota API keys desde la misma aplicación que atiende tráfico de producción.

- Mantén estable la metadata de cuentas para que billing y gráficas de uso sigan siendo coherentes.

## Conexiones y salud de proveedores

Usa el panel de conexiones antes de depurar errores de sync o envío. Una conexión puede estar activa, degradada, revocada o incompleta según el estado del token de proveedor y la cobertura de capacidades.

- Revisa proveedor, cuenta, estado, último sync y banderas de capacidad.

- Usa refresh solo cuando existan credenciales y el proveedor soporte la capacidad solicitada.

- Cuando un proveedor no soporte una conducta, espera `provider_capability_not_supported` en lugar de un fallback silencioso.

## API keys y uso

Crea keys de privilegio mínimo para workers de producción y keys separadas para desarrollo local. Revisa límites de uso antes de activar sync de alto volumen o jobs de replay de webhooks.

## Inspección y reparación de webhooks

Usa las vistas de entregas webhook para inspeccionar estado, intentos, latencia, código de respuesta y dead-letter. Reproduce entregas solo después de arreglar el endpoint receptor.

## Aprobaciones MCP e historial de ejecuciones

Las herramientas de solo lectura pueden ejecutarse directamente. Las escrituras externas, envío de email, cambios de reserva y operaciones destructivas deben crear aprobaciones visibles en el panel y vinculadas al historial de ejecución.

---

# Uso de MCP

Expón herramientas seguras para agentes con aprobaciones explícitas.

Las herramientas MCP exponen lectura segura y escrituras con aprobación sobre el mismo modelo de acciones que REST.

## Modelo de herramientas

Las herramientas son bindings ligeros sobre recursos de Horato. El catálogo debe incluir esquema de entrada, capacidad requerida, política de aprobación y forma de salida.

- `email.search` lee mensajes e hilos.

- `calendar.availability` lee libre/ocupado y disponibilidad de reservas.

- `booking.create` crea o mantiene una reserva.

- `email.send` requiere aprobación antes de enviar correo visible externamente.

## Configuración del servidor

Configura la API key y la URL base en el entorno del servidor MCP.

### Entorno del servidor MCP
```bash
HORATO_API_KEY=hr_live_...
HORATO_API_BASE_URL=https://api.hora.to
```

### Config del agente
```json
{
  "mcpServers": {
    "horato": {
      "command": "npx",
      "args": ["@horato/mcp"],
      "env": {
        "HORATO_API_KEY": "hr_live_..."
      }
    }
  }
}
```

## Política de aprobación

Exige aprobación para operaciones que envían mensajes, crean reservas, modifican eventos, eliminan datos, rotan keys, reproducen entregas o inician jobs de exportación.

### Escritura con aprobación
```typescript
tools.register("email.send", {
  requiresApproval: true,
  inputSchema: sendEmailSchema,
  handler: horato.mcp.email.send
});
```

## Historial de ejecuciones

Cada ejecución de agente debe estar visible en `/v1/mcp/runs` y vinculada con aprobaciones, operaciones de proveedor y eventos webhook. Usa replay de ejecuciones para flujos de reparación después de fallos transitorios del proveedor.

---

# Webhooks

Firma, entrega, inspecciona, reintenta y repara webhooks.

Horato firma eventos salientes, conserva entregas y permite replay para que los consumidores puedan recuperarse de fallos.

## Firmas

Verifica timestamp y firma antes de procesar un evento. Rechaza timestamps vencidos para reducir riesgo de replay.

### Verificación en Node
```javascript
import { verifyHoratoWebhook } from "@horato/unified";

const verified = verifyHoratoWebhook({
  rawBody,
  signature: req.headers["horato-signature"],
  secret: process.env.HORATO_WEBHOOK_SECRET
});
```

## Entregas y replay

Usa el inspector de entregas cuando un receptor devuelva un estado distinto de 2xx. Arregla el receptor, reproduce la entrega y luego limpia colas dead-letter de forma intencional.

- Lista entregas con `/v1/webhooks/deliveries`.

- Reproduce una entrega con `/v1/webhooks/deliveries/{delivery_id}/replay`.

- Reencola eventos dead-letter con `/v1/webhooks/dead-letter/{event_id}/requeue`.

---

# SDKs

Usa los SDKs JavaScript y Python sobre la misma API REST.

Los SDKs mantienen los mismos nombres de recursos y payloads snake_case que la API pública.

## JavaScript

Usa el cliente JavaScript en runtimes Node del lado servidor.

### Leer mensajes
```javascript
import { Horato } from "@horato/sdk";

const horato = new Horato({ apiKey: process.env.HORATO_API_KEY });
const messages = await horato.email.messages.list({ connection_id: "conn_123" });
```

## Python

Usa el cliente Python para workers, reparación de datos y automatización interna.

### Consultar libre/ocupado
```python
from horato import Horato

client = Horato(api_key=HORATO_API_KEY)
slots = client.calendar.free_busy.query(connection_id="conn_123", calendar_ids=["primary"])
```

---

# Errores de API

Maneja códigos de error estables, conflictos y límites de capacidad por proveedor.

Los clientes deben depender de códigos de error estables y no de texto humano.

## Formato común

Cada error devuelve un objeto `error` con código estable, mensaje legible y request_id.

### Respuesta de error
```json
{
  "error": {
    "code": "provider_capability_not_supported",
    "message": "Provider has no tasks support.",
    "request_id": "req_123"
  }
}
```

## Conflictos y etags

Los clientes deben ramificar por código, no por el mensaje.

- `bad_request`: input inválido o campo faltante.

- `unauthorized`: API key ausente o inválida.

- `forbidden`: la key no tiene scope o una política de sesión bloquea la acción.

- `not_found`: el recurso no existe en el alcance actual de organización/aplicación.

- `conflict`: etag vencido, conexión revocada o autorización incompleta.

- `rate_limited`: reintenta después de la ventana de límite documentada.

---

# Sync y reparación

Usa cursores, deltas de proveedor, reparación y replay para mantener datos canónicos.

El sync usa cursores, checkpoints y jobs reparables para mantener datos canónicos sin perder estado del proveedor.

## Cursores

Los deltas de proveedor actualizan filas canónicas y emiten eventos internos antes de entregar webhooks al cliente. Guarda el `next_cursor` o checkpoint de sync devuelto por superficies de lista y sync.

## Reparación

Cuando un proveedor invalida un cursor, inicia un sync de reparación para esa conexión y recurso. Usa replay de entregas webhook después de que los sistemas aguas abajo estén listos para consumir eventos reparados.

### Encolar reparación de sync
```bash
curl -X POST https://api.hora.to/v1/sync/connections/conn_123/email \
  -H "Authorization: Bearer $HORATO_API_KEY"
```