Cómo funciona la API de CALADESK
La plataforma ya tiene una puerta para personas: entras con tu usuario, ves la bandeja, pulsas botones. Una API es la misma puerta pero para programas — tu ERP, tu CRM, tu web, tu hoja de cálculo — y en vez de una contraseña usa una credencial.
Dos formas de que dos sistemas se enteren
Tirar · API
«Déjame consultar cuando yo quiera.»
Tu sistema pregunta: dame los tickets abiertos. CALADESK responde. Tú decides cuándo preguntas.
Empujar · Webhooks
«Avísame en cuanto pase.»
Le das a CALADESK una dirección tuya, y cuando ocurre algo — entra un ticket, responde un cliente — te llama al instante.
Hacen falta las dos. Con solo webhooks, un panel propio tiene que reconstruir el estado a partir de los avisos que le fueron llegando, y si pierde uno queda desincronizado para siempre. La API le permite releer la verdad cuando quiera. Con solo API, se entera tarde de todo.
Los tres avisos que se pueden activar desde Configuración → Avisos a
otros sistemas: ticket.creado,
ticket.respondido (contestó el
cliente) y ticket.resuelto. Cada envío
va firmado con un secreto tuyo, para que compruebes que viene de aquí y nadie te cuele uno
falso.
Qué puede hacer hoy
Tres cosas. Ni una más — y eso es a propósito.
| Se puede pedir | Qué devuelve | ¿Permiso extra? |
|---|---|---|
| Listar tickets | La lista paginada, con filtros de estado, prioridad y fechas | No |
| Ver un ticket | El caso con toda su conversación | No |
| Crear un ticket | El ticket nuevo, con su número | Sí |
No se puede modificar ni cerrar un ticket desde fuera. No es un olvido: cada cosa que se abre hacia fuera es superficie que hay que defender para siempre, y se abre cuando hay una necesidad concreta detrás, no por catálogo. Si vas a prometerle algo a un cliente, que no incluya gestionar CALADESK entero desde su sistema — hoy no se puede.
Cómo lo implementa un cliente
1. Emite una credencial
En Configuración → Acceso por API, le pone un nombre («CRM», «panel de dirección») y pulsa crear. Se muestra una sola vez: se guarda cifrada, así que ni nosotros podemos volver a enseñarla.
2. Decide qué necesita: leer, escribir, o las dos
Nace pudiendo solo leer. Si además va a abrir tickets, enciende el permiso de escritura con el interruptor que hay junto a la credencial.
3. Guarda la credencial donde guarda sus contraseñas
Nunca en el código de una página web: cualquiera que abra el navegador la vería, y con ella podría leer todos sus tickets.
4. La manda en cada llamada
En una cabecera: Authorization: Bearer cal_....
La empresa viene dada por la credencial, así que no existe forma de pedir los tickets de otro
cliente ni equivocándose.
5. Si va a crear tickets, manda también una clave de idempotencia
Una cabecera Idempotency-Key
con algo que identifique el hecho — el número de pedido, el id de su formulario. Si su petición se
corta a medias y reintenta, no se abre un segundo caso: se le devuelve el que ya
existía.
Los límites, y por qué existen
| Límite | Cuánto | Para qué está |
|---|---|---|
| Lecturas | 120 por minuto, por credencial | Que una integración con un bucle mal escrito no afecte a los demás |
| Creaciones | 30 por minuto, por credencial | Evita que un formulario roto abra cien casos iguales |
| Tamaño de página | 200 tickets como máximo | Pedir «todos» con miles de casos sería una descarga sin fin |
Qué construye la gente con esto
- Un panel para dirección: cuántos casos abiertos, cuántos vencidos, solo lectura.
- El formulario de su web abre el ticket directamente, sin pasar por un correo.
- La ficha del cliente en su CRM muestra sus casos de soporte.
- Sus propios informes, en su hoja de cálculo, con sus fórmulas.
- Un ticket urgente que salta en su Slack o su Teams, por webhook.
¿Quieres verlo funcionando de principio a fin, sin escribir un programa?
Sigue la guía de la hoja de Google — monta una sincronización real en veinte minutos.¿Todavía no usas CALADESK?
La API es una pieza más. Los correos, Telegram, WhatsApp y el chat de tu web entran todos en la misma bandeja.
Hablemos