Casos de uso

Todos los ejemplos asumen una clave con el scope indicado y un plan Pro o Enterprise (ver Planes y límites). 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:

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

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:

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:

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

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:

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();

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”:

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.