Todos los ejemplos asumen una clave con el scope indicado y un plan Pro o Enterprise (ver
[Planes y límites](/api/plans-and-limits/)). Sustituye `aa_TU_CLAVE_COMPLETA` por tu clave real.

## 1. Sincronizar leads hacia tu propio CRM

Tu agencia ya usa un CRM (HubSpot, Zoho…) además de Aymar Agents. En vez de que nosotros empujemos hacia
tu CRM, tu integración **tira** de los leads nuevos cada hora con `dateFrom`:

```bash
curl "https://api.aymaragents.com/public/v1/leads?dateFrom=2026-09-01T00:00:00Z" \
  -H "X-API-Key: aa_TU_CLAVE_COMPLETA"
```

```python
import requests

resp = requests.get(
    "https://api.aymaragents.com/public/v1/leads",
    params={"dateFrom": "2026-09-01T00:00:00Z"},
    headers={"X-API-Key": "aa_TU_CLAVE_COMPLETA"},
)
for lead in resp.json()["data"]:
    sync_to_my_crm(lead)
```

Scope: `tenant:leads.read`.

## 2. Capturar leads desde tu propia web

Tienes una landing fuera del widget embebible de Aymar Agents y no quieres montar el widget de chat en
ella — envía el formulario directamente:

```javascript
await fetch("https://api.aymaragents.com/public/v1/leads", {
  method: "POST",
  headers: {
    "X-API-Key": "aa_TU_CLAVE_COMPLETA",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customerPhone: "+34600111222",
    stageId: "...",
    notes: "Formulario de la landing de servicios",
  }),
});
```

Scope: `tenant:leads.manage` (o `tenant:contacts.manage` si envías el formulario a `/contacts` en su lugar).

## 3. Mantener un calendario externo unificado

Ya usas Calendly o Google Calendar como fuente de verdad de otro equipo — consulta los huecos libres de
Aymar Agents antes de ofrecer una cita, y créala aquí para que quede reflejada en ambos sitios:

```bash
curl "https://api.aymaragents.com/public/v1/availability?from=2026-09-10&to=2026-09-14" \
  -H "X-API-Key: aa_TU_CLAVE_COMPLETA"
```

```python
slot = pick_a_slot(available_slots)
requests.post(
    "https://api.aymaragents.com/public/v1/appointments",
    json={"userId": slot["userId"], "startsAt": slot["startsAt"], "customerId": customer_id},
    headers={"X-API-Key": "aa_TU_CLAVE_COMPLETA"},
)
```

Scopes: `tenant:appointments.read` (disponibilidad) + `tenant:appointments.manage` (crear).

## 4. Sincronizar tickets con tu helpdesk

Tu propio Zendesk o Freshdesk (distinto de una integración nuestra de Zendesk) refleja en ambas direcciones
el estado de cada ticket:

```javascript
const res = await fetch("https://api.aymaragents.com/public/v1/tickets?status=open", {
  headers: { "X-API-Key": "aa_TU_CLAVE_COMPLETA" },
});
const { data: openTickets } = await res.json();
```

```bash
curl -X PATCH "https://api.aymaragents.com/public/v1/tickets/TICKET_ID" \
  -H "X-API-Key: aa_TU_CLAVE_COMPLETA" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'
```

Scopes: `tenant:tickets.read` (lectura) + `tenant:tickets.manage` (crear/actualizar/comentar).

## 5. Automatización low-code (Zapier y similares)

Dispara un Zap cuando entra un lead nuevo (por sondeo periódico a `GET /leads`, hasta que exista un webhook)
y usa como acción "enviar WhatsApp desde una hoja de cálculo":

```bash
curl -X POST "https://api.aymaragents.com/public/v1/conversations/CONVERSATION_ID/messages" \
  -H "X-API-Key: aa_TU_CLAVE_COMPLETA" \
  -H "Content-Type: application/json" \
  -d '{"text": "Tu cita queda confirmada para mañana a las 10:00"}'
```

Scope: `tenant:conversations.manage`. **Recuerda**: si el contacto es de WhatsApp y su ventana de 24h está
cerrada, esta llamada responde `409 WHATSAPP_SESSION_WINDOW_CLOSED` sin intentar el envío — usa
`POST /conversations/start` con una plantilla aprobada para abrir una conversación nueva. Y en cualquier
caso, el mensaje enviado **no aparece al instante** en el inbox de la Plataforma — ver la nota en
[Empezar con la API](/api/getting-started/).