Empezar con la API

La API pública de Aymar Agents es una superficie REST curada — leads, contactos, conversaciones, citas y tickets de tu cuenta — pensada para que integres tu propio código, tu CRM o tu automatización con tu cuenta, sin pasar por la interfaz web. No es un espejo de todo lo que hace la Plataforma: solo existen rutas para estos 5 recursos, sea cual sea el permiso de tu clave.

Disponible en los planes Pro y Enterprise. Con el plan Starter, cualquier llamada devuelve 403 PLAN_NOT_ELIGIBLE aunque la clave y el permiso sean correctos — ver Planes y límites.

1. Crea tu clave

Las claves de API se crean y gestionan desde Perfil → Mis claves de API (o Ajustes → Claves de API para una clave de empresa) — el procedimiento completo, con capturas, está en la guía Claves de API. Al crearla:

• En «Qué puede hacer esta clave», pulsa «Personalizar» y marca solo los recursos que tu integración necesita — ver el listado completo en Autenticación. Una clave sin el permiso de un recurso recibe 403 PERMISSION_DENIED al llamar a sus rutas, aunque el resto de la clave funcione.
• La clave completa se muestra una sola vez: cópiala a un gestor de secretos antes de cerrar el diálogo.

2. Comprueba tu clave

GET /me no exige ningún permiso propio — solo una clave válida de un tenant con plan elegible — así que es la forma más rápida de confirmar que todo está en orden:

curl https://api.aymaragents.com/public/v1/me \
  -H "X-API-Key: aa_TU_CLAVE_COMPLETA"

{
  "tenantId": "b3f5b6b0-...",
  "keyPrefix": "aa_1b2e1ebd",
  "scopes": ["tenant:leads.read", "tenant:leads.manage"],
  "plan": "pro",
  "rateLimit": { "perMinute": 180, "perDay": 50000 }
}

Si scopes no incluye lo que esperabas, revisa el recorte «Personalizar» de tu clave (apartado 7 de la guía de claves) — el recorte queda sellado al crearla, no se actualiza solo.

3. Haz tu primera llamada de negocio

Con una clave que tenga tenant:leads.read, lista los leads más recientes:

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

Cada respuesta de lista usa el mismo formato de paginación que el resto de la API — revisa el campo meta de la respuesta para pedir la página siguiente.

Antes de automatizar un envío de mensajes

POST /public/v1/conversations/{id}/messages y POST /public/v1/conversations/start entregan el mensaje al canal real, pero no aparecen al instante en el inbox de la Plataforma ni en el widget del visitante — un operador humano los ve en el siguiente refresco/reconexión de su pantalla, no en tiempo real. Si tu integración necesita que un operador reaccione enseguida, avísale por otra vía (tu propio sistema, un ticket…) además de enviar el mensaje. Detalle completo en la guía de Conversaciones de la referencia.

Sigue por aquí

• Autenticación — cabecera X-API-Key, catálogo completo de permisos.
• Planes y límites — qué plan necesitas y cuántas peticiones puedes hacer.
• Errores — el envelope de error y el catálogo completo de códigos.
• Casos de uso — 5 integraciones reales con ejemplos de código.
• Referencia, en la barra lateral — una página por operación, generada desde la definición OpenAPI real de la API.

¿Dudas integrando? Escribe a soporte@aymaragents.com.