Autenticación y permisos de la API
Cómo crear una API key, qué permisos existen, cómo se envía en cada petición y qué significan los errores y las reglas de paginación e idempotencia.
La API pública de Orkestal te deja leer y modificar tus contactos y conversaciones, enviar mensajes de WhatsApp y recibir eventos, desde tus propios sistemas o desde herramientas como n8n.
Conceptos básicos#
- URL base:
https://orkestal-backend-production.up.railway.app/api/public/v1. También se muestra en Integraciones → n8n. - Formato: JSON sobre HTTPS.
- Aislamiento: cada API key pertenece a un solo negocio y solo ve sus datos. No hay forma de leer datos de otro negocio.
Autenticación#
Todas las peticiones llevan tu API key en la cabecera Authorization:
Authorization: Bearer ork_live_...Para comprobarla, llama a GET /me: devuelve el nombre de tu negocio, el nombre de la key y sus permisos.
curl https://orkestal-backend-production.up.railway.app/api/public/v1/me \
-H "Authorization: Bearer ork_live_..."Crear y administrar API keys#
Solo un Admin puede crear keys, en Integraciones → n8n → Crear API key.
- Ponle un nombre que diga para qué es («n8n producción»).
- Marca solo los permisos que necesita.
- Cópiala en ese momento. Se muestra una sola vez: Orkestal solo guarda una huella (hash) de la key y no puede recuperarla. Si la pierdes, revócala y crea otra.
Puedes tener hasta 20 keys activas por negocio. Para dejar de usar una, revócala: deja de funcionar de inmediato.
Permisos#
El acceso es denegado por defecto: una key solo puede hacer lo que tiene marcado.
| Permiso | Qué permite |
|---|---|
contacts:read | Leer contactos |
contacts:write | Crear y editar contactos |
conversations:read | Leer conversaciones y su historial |
conversations:write | Cambiar estado, asignar y pausar el agente |
messages:read | Leer mensajes |
messages:write | Enviar mensajes |
tags:read | Leer etiquetas |
tags:write | Asignar y quitar etiquetas |
templates:read | Leer plantillas de WhatsApp |
templates:write | Crear y borrar plantillas de WhatsApp |
broadcasts:write | Disparar campañas de difusión |
webhooks:write | Crear y borrar suscripciones a webhooks |
Una key no hereda el rol de quien la creó: tiene solo los permisos que marcaste.
Errores#
Los errores devuelven un código HTTP y un JSON con un campo detail que explica el motivo, en español.
| Código | Significa | Qué hacer |
|---|---|---|
401 | La key no es válida, está mal escrita o fue revocada | Revisa que el valor sea Bearer ork_live_…, con el espacio |
402 | La cuenta está suspendida por falta de pago | Regulariza el pago; el acceso por API se reactiva solo |
403 | La key no tiene el permiso necesario | El mensaje dice cuál falta; crea una key con ese permiso |
404 | El recurso no existe (o no pertenece a tu negocio) | Revisa el identificador |
409 | Conflicto. Por ejemplo, mensaje libre fuera de la ventana de 24 horas | Usa una plantilla aprobada |
422 | Falta un dato, un dato es inválido, o reusaste una Idempotency-Key con otro contenido | El mensaje dice qué corregir |
502 | Meta falló al procesar el envío | Reintenta más tarde |
Paginación#
Los listados (/contacts, /conversations) usan cursor:
limit: cuántos resultados (por defecto 25, máximo 100).cursor: el valor de la página anterior.
Cuando hay más resultados, la respuesta incluye la cabecera Link con rel="next" y la cabecera X-Next-Cursor. Herramientas como n8n siguen el Link solas.
Idempotencia#
Los envíos de mensajes se cobran y una repetición crearía otro mensaje. Para que un reintento no duplique nada, manda la cabecera:
Idempotency-Key: un-valor-unico-por-envio- Si repites la petición con la misma clave y el mismo contenido, Orkestal devuelve el resultado de la primera sin volver a enviar.
- Si reutilizas la clave con otro contenido, responde
422.
Úsala siempre en POST /messages y POST /whatsapp/messages.
Límites de uso#
Orkestal no publica un límite de peticiones por minuto, pero evita ráfagas: Meta sí limita la velocidad de envío de WhatsApp (error 130429), y una cuenta con calidad baja puede quedar bloqueada para campañas. Mira Reglas de WhatsApp.
Siguiente paso#
El detalle de cada ruta está en la Referencia. Para recibir eventos en tu servidor, mira Webhooks.