Autenticación
Crea claves con permisos mínimos y envíalas desde tu servidor.
Cada solicitud lleva una clave de API de la organización en la cabecera Authorization. La clave define qué organización ves y qué operaciones puedes llamar.
Crea una clave
Solo los propietarios y administradores de la organización pueden crear y revocar claves.
- Abre Configuración → API en Ricky.
- Escribe un nombre que identifique la integración, por ejemplo
ERP de tiendas. - Marca solo los permisos que la integración necesita.
- Elige el vencimiento: 90 días o 1 año.
- Selecciona Crear clave y copia la clave.
Ricky muestra la clave completa una sola vez y guarda solo su huella SHA-256. Si la pierdes, crea otra.
Una clave tiene la forma rky_live_ seguida de 43 caracteres.
Envía la clave
curl https://getricky.ai/api/v1/members \
-H "Authorization: Bearer rky_live_…"Usa la clave solo en tu servidor. No la incluyas en una página web, una app móvil, una URL ni un registro. Guárdala en un gestor de secretos o en una variable de entorno.
Vigencia
La clave pertenece a la organización y actúa en nombre de la persona que la creó. Deja de funcionar en cualquiera de estos casos:
- Alguien la revoca en Configuración → API. El efecto es inmediato.
- Llega su fecha de vencimiento.
- Quien la creó deja la organización o pierde el rol de propietario o administrador. Ricky lo comprueba en cada solicitud.
Una clave que no funciona recibe 401 unauthorized.
Para rotar una clave, crea la nueva, despliégala en tu servidor y revoca la anterior.
Permisos
Cada operación exige un permiso (scope). Una clave sin ese permiso recibe 403 insufficient_scope.
| Permiso | Permite |
|---|---|
contacts:read | Leer contactos y campos de contacto. |
contacts:write | Crear y actualizar contactos. |
conversations:read | Leer conversaciones, mensajes y canales. |
conversations:write | Asignar, cerrar y reabrir conversaciones. |
messages:send | Iniciar conversaciones, enviar mensajes y consultar envíos. |
templates:read | Leer las plantillas de WhatsApp. |
members:read | Leer los miembros de la organización. |
tags:read | Leer las etiquetas de contactos. |
webhooks:manage | Crear, listar y desactivar webhooks; consultar y reintentar sus entregas. |
La tabla siguiente sale del contrato de la API: es la lista exacta de operaciones y el permiso de cada una.
| Operación | Endpoint | Permiso |
|---|---|---|
| List contacts | GET /contacts | contacts:read |
| Create a contact | POST /contacts | contacts:write |
| Get a contact | GET /contacts/{contact_id} | contacts:read |
| Update a contact | PATCH /contacts/{contact_id} | contacts:write |
| List contact fields | GET /contact-fields | contacts:read |
| List conversations | GET /conversations | conversations:read |
| Start a conversation | POST /conversations | messages:send |
| Get a conversation | GET /conversations/{conversation_id} | conversations:read |
| Assign a conversation | PATCH /conversations/{conversation_id}/assignment | conversations:write |
| Close a conversation | POST /conversations/{conversation_id}/close | conversations:write |
| Reopen a conversation | POST /conversations/{conversation_id}/reopen | conversations:write |
| List messages | GET /conversations/{conversation_id}/messages | conversations:read |
| Send a message | POST /conversations/{conversation_id}/messages | messages:send |
| Get a send | GET /sends/{send_id} | messages:send |
| List channels | GET /channels | conversations:read |
| List members | GET /members | members:read |
| List tags | GET /tags | tags:read |
| List templates | GET /templates | templates:read |
| List webhooks | GET /webhooks | webhooks:manage |
| Create a webhook | POST /webhooks | webhooks:manage |
| Disable a webhook | DELETE /webhooks/{webhook_id} | webhooks:manage |
| List deliveries | GET /webhooks/{webhook_id}/deliveries | webhooks:manage |
| Retry a delivery | POST /webhooks/{webhook_id}/deliveries/{delivery_id}/retry | webhooks:manage |
Respuestas de autenticación
| Situación | Respuesta |
|---|---|
| Falta la cabecera, está mal formada, o la clave venció o fue revocada | 401 unauthorized |
| La clave no tiene el permiso de la operación | 403 insufficient_scope |
| La clave superó 120 solicitudes en el minuto | 429 rate_limited |
Consulta Errores y Idempotencia, límites y reintentos.