Esta guía existe para responder una sola pregunta:
👉 “¿Qué API de CloudChat debo usar para lo que quiero hacer?”
Antes de copiar cualquier endpoint o escribir código, lee esta página. Evita confusiones, uso incorrecto de APIs y impactos no deseados en producción.
🧠 Visión general: existen 3 tipos de APIs en CloudChat
Las APIs de CloudChat no son todas iguales.
Se dividen en tres categorías, cada una con un objetivo claro.
📦 APIs de Extracción de Datos
Sirven para análisis histórico y reportes.
-
Exportación en lote (batch)
-
Uso típico: BI, auditorías, paneles
-
No modifican datos
-
Ideales para trabajos programados
🔍 APIs de Consulta en Tiempo Real
Sirven para leer datos actuales del sistema.
-
Buscar contactos
-
Listar tickets
-
Leer mensajes
-
No modifican datos
-
Usadas en integraciones y automatizaciones en tiempo real
✏️ APIs de Actualización y Acción
⚠️ Estas APIs modifican datos reales en producción.
-
Resolver tickets
-
Cambiar estado, prioridad o equipo
-
Crear mensajes en tickets
-
Pueden impactar operación, SLA y métricas
-
Algunas rutas son experimentales o requieren flag activa
📦 Cuando usar APIs de Extracción de Datos
Usa APIs de extracción cuando quieras:
-
Crear reportes
-
Alimentar herramientas de BI
-
Realizar auditorías
-
Analizar largos períodos de tiempo
-
Exportar muchos tickets a la vez
Estas APIs:
-
Funcionan en lote
-
Tienen límite de intervalo por solicitud
-
No deben usarse para lógica de aplicación en tiempo real
👉 Documentación específica:
📦 API de Extracción de Datos (Data Extract API)
🔍 Cuando usar APIs de Consulta en Tiempo Real
Usa APIs de consulta cuando necesites responder preguntas ahora, como:
-
“¿Este contacto ya existe?”
-
“¿Qué tickets tiene este cliente?”
-
“¿Cuál es el estado actual de este ticket?”
-
“¿Qué mensajes se intercambiaron en esta conversación?”
Estas APIs:
-
Son solo lectura (GET)
-
Operan directamente en la base de producción
-
No sustituyen la API de extracción
👉 Documentación específica:
🔍 APIs de Consulta en Tiempo Real (Contactos, Tickets y Mensajes)
✏️ Cuando usar APIs de Actualización y Acción
⚠️ Atención: estas APIs modifican datos reales en CloudChat.
Usa APIs de acción cuando quieras:
-
Resolver un ticket vía integración
-
Actualizar prioridad o equipo responsable
-
Crear mensajes automáticamente
-
Sincronizar acciones de otro sistema con CloudChat
Estas APIs:
-
Ejecutan acciones en producción
-
Pueden afectar operación y métricas
-
Deben usarse con cuidado y validación
👉 Documentación específica:
✏️ APIs de Actualización y Acción en Tickets
🧩 Regla práctica para escoger la API correcta
Pregunta siempre:
-
¿Quiero analizar datos históricos?
→ Usa API de Extracción de Datos -
¿Solo quiero leer datos actuales?
→ Usa APIs de Consulta en Tiempo Real -
¿Quiero cambiar algo en el sistema?
→ Usa APIs de Actualización y Acción
Si todavía tienes dudas, no continues. Usar la API incorrecta puede generar efectos secundarios inesperados.
🚦 Niveles de cuidado (importante)
-
Extracción de datos → riesgo bajo
-
Consulta en tiempo real → riesgo medio
-
Actualización / acción → riesgo alto
Mientras más te acerques a acciones de escritura, más atención y pruebas necesitas.
❌ Errores comunes que esta guía ayuda a evitar
-
Usar API de extracción para algo que necesita ser en tiempo real
-
Usar API de escritura pensando que solo es consulta
-
Mezclar lógica de aplicación con exportación de datos
-
Modificar tickets sin entender el impacto operacional
📌 Próximos pasos
Ahora escoge la documentación correcta para tu caso:
Este guía siempre debe leerse antes de las FAQ técnicas arriba.