Documentación

Referencia de la API

Documentación

La API REST de Aitelier te permite lanzar llamadas salientes, ejecutar campañas por lotes, leer sesiones e inspeccionar suscripciones de webhooks de forma programática. Esta página es una referencia rápida — la referencia interactiva, siempre actualizada y con los esquemas completos de petición/respuesta la sirve la propia API en /v1/docs, y el documento OpenAPI en /v1/openapi.json.

URL base

https://public-api.beta.aitelier.org/v1

Todos los endpoints requieren HTTPS.

Autenticación

Cada petición necesita una clave de API con ámbito de proyecto:

Authorization: Bearer avp_live_…

(X-API-Key: avp_live_… también funciona.)

Las claves de API se emiten en la pestaña API keys del proyecto, con scopes por clave, y son revocables en cualquier momento. Las claves se muestran una sola vez al crearlas; las guardamos hasheadas en reposo y no podemos recuperar el texto plano. La UI identifica las claves por su prefijo.

Scopes disponibles:

  • outbound:trigger — lanzar llamadas salientes y lotes
  • sessions:read — leer metadatos de sesiones, resultados, valores de slots
  • webhooks:read — inspeccionar suscripciones de webhooks y enviar entregas de prueba

Los scopes que concedes se convierten en las únicas operaciones que la clave puede realizar. El inicio de sesión del dashboard (código por email + JWT) es aparte; las claves de API son la única forma de hablar con la API desde tu propio código.

Idempotencia

POST /v1/calls acepta una cabecera Idempotency-Key. Deduplicamos claves idénticas durante 24 horas desde la primera recepción: reintentar con la misma clave devuelve la respuesta original, y reutilizar una clave con un cuerpo distinto devuelve 409. Úsala para reintentos seguros ante fallos de red.

Límites de tasa

Valores por defecto por clave de API, por minuto:

  • 100 peticiones para mutaciones (POST/PUT/PATCH/DELETE)
  • 1000 peticiones para lecturas (GET)

Cada respuesta lleva el estado del límite:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Window: 60

Cuando alcanzas un límite, recibes 429 Too Many Requests y una cabecera Retry-After. Espera y reintenta.

Endpoints

Llamadas salientes

  • POST /v1/calls — lanza una llamada saliente. Consulta Llamadas salientes para el esquema completo del cuerpo.

Lotes salientes

  • POST /v1/calls/bulk — inicia un lote (multipart: scenarioId, callerIdNumber opcional, el archivo CSV).
  • GET /v1/calls/batches — lista los lotes.
  • GET /v1/calls/batches/{id} — estado del lote y contadores por estado.
  • POST /v1/calls/batches/{id}/cancel — cancela las filas restantes.

Sesiones

  • GET /v1/sessions — lista, con filtros scenarioId, status, from, to, más paginación con limit/cursor.
  • GET /v1/sessions/{id} — detalle completo de la sesión: estado, resultado, valores de slots, consecución del goal.

Estados de sesión: pending, live, completed, failed, abandoned.

Webhooks

  • GET /v1/webhooks — lista las suscripciones del proyecto.
  • GET /v1/webhooks/{id} — una suscripción.
  • POST /v1/webhooks/{id}/test — envía una entrega de prueba a tu endpoint.

Las suscripciones se crean y editan en la UI web — consulta Webhooks.

Formato de errores

Cada respuesta de error es JSON:

{
  "error": {
    "code": "VALIDATION",
    "message": "phone must be a valid E.164 number",
    "details": { … }
  }
}

Códigos HTTP habituales:

  • 400 — entrada inválida (VALIDATION; el mensaje trae los detalles)
  • 401 — autenticación ausente o inválida (UNAUTHENTICATED)
  • 402 — el saldo del monedero o el límite de crédito no cubre la llamada (PAYMENT_REQUIRED)
  • 403 — autenticación correcta pero falta el scope (FORBIDDEN)
  • 404 — el recurso no existe o no puedes verlo (NOT_FOUND)
  • 409 — conflicto, p. ej. reutilizar una idempotency-key con un cuerpo distinto (CONFLICT)
  • 429 — límite de tasa alcanzado (RATE_LIMIT)
  • 500 — bug de la plataforma (INTERNAL); recibimos alertas de estos

Versionado

La versión actual es v1. Los cambios aditivos — campos nuevos, endpoints nuevos — se publican sin previo aviso y son no disruptivos por convención: ignora los campos que no reconozcas. Los cambios disruptivos reciben una nueva versión mayor con una ventana de retirada anunciada a cada integrador activo.