API
La API te permite trabajar con los bots de CleverApp desde tu propio código: buscar y crear contactos, enviarles mensajes, cambiar variables y etiquetas, recargar saldos y gestionar listas. Por ejemplo, el CRM de tu sitio web puede pasar un lead al bot, y un sistema de pagos puede otorgar bonos después de una compra.
La API está disponible para el propietario de la cuenta con el plan Pro. Cada solicitud se ejecuta en nombre del propietario de la clave y con sus permisos.
Clave de API
La clave se obtiene en tu perfil, en la pestaña «API»: consulta Clave de API. La clave da acceso completo a la cuenta: guárdala en tu servidor y nunca la pongas en el código de páginas web ni de apps para teléfono.
Pasa la clave en el encabezado Authorization:
Authorization: Bearer YOUR_API_KEY
Si no puedes definir un encabezado, pasa la clave en el parámetro api_token, en la URL o en el cuerpo de la solicitud. El encabezado es más seguro: las URL con parámetros quedan en los registros del servidor.
El botón «Regenerar» del perfil reemplaza la clave, y la anterior deja de funcionar de inmediato. La clave también se restablece cuando cambias o restableces la contraseña; después obtén una nueva. Para comprobar una clave, llama a getMe: devuelve la cuenta a la que pertenece la clave.
Solicitudes
Todos los métodos están en:
https://app.cleverapp.pro/api/v1/methodName
- La mayoría de los métodos aceptan tanto
GETcomoPOST; en cada método se indica cuáles. Llama conPOSTa los métodos que modifican datos. - Los parámetros de
POSTse envían como JSON (Content-Type: application/json) o como campos de formulario; los deGET, en la URL. - Las respuestas son JSON en UTF-8.
Importante
Envía el encabezado
Accept: application/jsonen cada solicitud. Sin él, los errores de validación llegan como una redirección en lugar de una respuesta JSON422, y tu código no podrá procesarlos.
Ejemplo: los contactos de un bot.
curl -X POST "https://app.cleverapp.pro/api/v1/getContacts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"bot_id": 12345}'
El ID del bot (bot_id) es el número que aparece en la dirección del bot en el panel: /bots/12345/….
Límites
- Frecuencia: 120 solicitudes por minuto por cuenta, sumando todos los métodos.
- Por encima del límite, la API responde con
429. El encabezadoRetry-Afterindica cuántos segundos esperar;X-RateLimit-Remainingmuestra cuántas solicitudes quedan en el minuto actual.
Errores
Una respuesta correcta tiene el código 200 o 201. Errores:
| Código | Cuándo | Respuesta |
|---|---|---|
401 |
No hay clave, la clave es incorrecta o se regeneró | {"error": "unauthorized"} |
402 |
El propietario de la clave no tiene el plan Pro | {"error": "…", "code": "pro_required"} |
403 |
Sin acceso al bot o al objeto; la cuenta está bloqueada | {"error": "…"} |
404 |
No se encontró el bot, el contacto o el registro | {"error": "…"} o {"message": "…"} |
410 |
El método se desactivó (un método obsoleto después de su fecha de retirada) | {"error": "…", "code": "method_removed"} |
422 |
Los parámetros no pasaron la validación | {"message": "…", "errors": {"field": ["…"]}} |
429 |
Demasiadas solicitudes | {"message": "Too Many Attempts."} |
Un error 422 enumera en errors cada campo con sus motivos:
{
"message": "The contact id field is required.",
"errors": {
"contact_id": ["The contact id field is required."]
}
}
Los textos de error pueden cambiar: en tu código, guíate por el código de estado y por los campos code y errors.
Hasta que se desactiva, un método obsoleto funciona como antes, pero cada respuesta lleva el encabezado Deprecation: true y un encabezado Sunset con la fecha de desactivación. Compruébalos en tu código para pasar a tiempo al método que lo reemplaza.