API pública de ChatISP

Visión general

La API pública es el canal de máquina de ChatISP: permite que otro sistema del proveedor trabaje con la atención sin abrir el panel. Funciona en las dos direcciones:

• De su sistema hacia ChatISP: llamadas HTTPS autenticadas por clave para enviar mensajes (texto, plantilla aprobada de la API oficial y archivo), listar y consultar conversaciones con su historial, transferir, cerrar, etiquetar y anotar atenciones, abrir atenciones en la cola, consultar y renombrar contactos, abrir y mover órdenes de servicio, agendar compromisos y leer los indicadores de la atención.
• De ChatISP hacia su sistema: webhooks de salida. ChatISP hace un POST firmado a la dirección que usted registre cuando un mensaje llega o sale, cuando una conversación se crea, cambia de responsable o se cierra, y cuando una orden de servicio se abre o se actualiza. Vea Webhooks de salida.

Las 37 operaciones

Toda la API usa una única dirección; la operación se elige con el parámetro r, en el formato recurso/acao (recurso/acción). La columna Alcance muestra el permiso que la clave necesita tener (vea Permisos de la clave); "cualquier clave" significa que basta con que la clave esté activa.

En la columna Método, GET indica una lectura: también acepta POST. Las operaciones marcadas con POST modifican algo y solo aceptan POST.

Casos de uso típicos de un proveedor

Programas completos para varios de estos casos están en Ejemplos prácticos.

Requisitos

Instalación propia y ChatISP Cloud

La API es la misma en las dos formas de uso; solo cambia la dirección.

• Instalación propia (servidor del proveedor): la dirección es el dominio por el que usted accede al panel. Sin dominio configurado, el servidor responde con un certificado autofirmado y su sistema tendría que aceptarlo explícitamente. Configure un dominio con Let's Encrypt en Servidor antes de poner la integración en producción.
• ChatISP Cloud: la dirección es la de su panel alojado por Ravi Systems, ya con certificado válido.

En los dos casos, la dirección exacta aparece en la tarjeta API de ChatISP, en Dirección de la API.

Crear una clave de API

La clave es la única credencial de la API: no hay usuario, contraseña ni sesión. Cree una clave para cada integración, solo con los permisos que esta usa y un límite de llamadas por minuto.

Paso a paso

1. En el menú lateral, abra Integraciones.
2. Ubique la tarjeta API de ChatISP ("Claves para que otros sistemas usen la API: mensajes, conversaciones, contactos, órdenes de servicio, agenda e indicadores, cada clave con sus permisos."). Justo debajo del título aparece la Dirección de la API, con el botón Documentación de la API: anote la dirección, es la URL que la integración va a llamar.
3. Haga clic en Nueva clave.
4. Complete el Nombre (hasta 120 caracteres) con algo que identifique la integración, por ejemplo "ERP de facturación" o "NOC". Este nombre aparece en el historial de todo lo que haga la clave.
5. Active los permisos que usa la integración. Están en tres grupos: Atención, Órdenes de servicio y agenda y Gestión. En una clave nueva, Enviar mensajes, Consultar conversaciones y Abrir atenciones vienen activados; los demás vienen desactivados. La tabla completa está en Permisos de la clave.
6. Ajuste el Límite por minuto ("Llamadas aceptadas por minuto. 0 desactiva el límite."). El valor predeterminado es 60 y el máximo es 10000.
7. Haga clic en Guardar. La ventana Clave creada muestra la clave completa en el campo Clave de API. Haga clic en Copiar y guárdela en el sistema que usará la API.

cisp_7f3a9c21d84e0b56a1f2c3d4e5f60718293a4b5c6d7e8f90

Toda clave comienza con cisp_, seguido de 48 caracteres hexadecimales. La lista de la tarjeta muestra solo el comienzo (por ejemplo cisp_7f3a9…) para que usted reconozca cuál es cuál.

La lista de claves

Revelar, editar y eliminar

• Revelar muestra de nuevo la clave completa, con el botón Copiar, en cualquier momento, para quien tiene el permiso Integraciones.
• Editar cambia nombre, permisos, límite por minuto y el interruptor Activa. La clave en sí no cambia: la integración sigue funcionando con el mismo valor, ya con los permisos nuevos. Desactivar Activa suspende la clave de inmediato (HTTP 401 chave_invalida) sin borrarla, y deja de contar en el límite del plan.
• Eliminar pide confirmación ("¿Eliminar esta clave? Las integraciones que la usan dejarán de funcionar.") y revoca la clave de inmediato.

Permisos de la clave (alcances)

Cada permiso de la pantalla corresponde a un alcance (scope), un código estable que la API usa para decidir qué puede hacer la clave. El código aparece en el campo escopos de chave/info y en el error permissao, que informa qué alcance faltó.

Los alcances son independientes: Gestionar órdenes de servicio no incluye Consultar órdenes de servicio, por ejemplo. Una integración que abre órdenes de servicio y después sigue su avance necesita los dos.

Catálogos: habilitados para cualquier clave

Las rutas de catálogo (chave/info, conexoes/listar, departamentos/listar, atendentes/listar, modelos/listar, etiquetas/listar y motivos/listar) no requieren alcance: cualquier clave activa puede llamarlas, incluso con todos los permisos desactivados. Devuelven los ids que piden las demás rutas (conexao_id, departamento_id, atendente_id, modelo_id, etiqueta_id, motivo_id); sin ellos ninguna integración podría armar sus llamadas. La pantalla lo recuerda justo debajo de los permisos: "Conexiones, departamentos, agentes, plantillas, etiquetas y motivos están disponibles para cualquier clave activa." Referencia en Catálogos.

Cuántas claves crear

• Una por integración, con un nombre claro: así usted limita, suspende o revoca un sistema sin afectar a los demás, y el historial de las conversaciones muestra qué sistema realizó cada acción.
• Separe lectura de escritura cuando sistemas distintos hacen cada cosa. Un panel de BI solo necesita Consultar conversaciones e Indicadores; el ERP que envía boletos solo necesita Enviar mensajes.

Dirección y autenticación

Todas las llamadas van a la misma dirección, que se muestra en la tarjeta API de ChatISP:

https://<dirección de su panel>/api_publica.php?r=<recurso>/<acao>

La clave va en el encabezado HTTP Authorization, con el esquema Bearer. Nunca va en la URL ni en el cuerpo:

Authorization: Bearer cisp_7f3a9c21d84e0b56a1f2c3d4e5f60718293a4b5c6d7e8f90

No hay inicio de sesión ni sesión: cada llamada es independiente.

Primera llamada

La ruta chave/info es la ideal para validar dirección y clave: no requiere permiso, no modifica nada y muestra lo que la clave puede hacer.

curl -s "https://atendimento.seuprovedor.com.br/api_publica.php?r=chave/info" \
  -H "Authorization: Bearer $CHATISP_CHAVE"

<?php
// Cliente mínimo reutilizable en las demás rutas
function chatisp(string $rota, array $dados = [], string $metodo = 'GET'): array {
    $base  = 'https://atendimento.seuprovedor.com.br/api_publica.php';
    $chave = getenv('CHATISP_CHAVE');
    $url   = $base . '?r=' . $rota;
    $ch    = curl_init();
    $opcoes = [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $chave, 'Content-Type: application/json'],
    ];
    if ($metodo === 'POST') {
        $opcoes[CURLOPT_POST]       = true;
        $opcoes[CURLOPT_POSTFIELDS] = json_encode($dados);
    } elseif ($dados) {
        $url .= '&' . http_build_query($dados);
    }
    $opcoes[CURLOPT_URL] = $url;
    curl_setopt_array($ch, $opcoes);
    $corpo  = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    $resposta = json_decode((string) $corpo, true) ?? ['ok' => false, 'error' => 'resposta_invalida'];
    $resposta['_http'] = $status;
    return $resposta;
}

$info = chatisp('chave/info');
if (!$info['ok']) {
    die("Error {$info['_http']}: {$info['error']}\n");
}
echo $info['chave']['nome'], ': ', implode(', ', $info['chave']['escopos']), PHP_EOL;

import os, requests

BASE  = "https://atendimento.seuprovedor.com.br/api_publica.php"
CHAVE = os.environ["CHATISP_CHAVE"]

def chatisp(rota, dados=None, metodo="GET"):
    cab = {"Authorization": f"Bearer {CHAVE}"}
    if metodo == "POST":
        r = requests.post(BASE, params={"r": rota}, json=dados or {}, headers=cab, timeout=30)
    else:
        r = requests.get(BASE, params={"r": rota, **(dados or {})}, headers=cab, timeout=30)
    corpo = r.json()
    corpo["_http"] = r.status_code
    return corpo

info = chatisp("chave/info")
if not info["ok"]:
    raise SystemExit(f"Error {info['_http']}: {info['error']}")
print(info["chave"]["nome"], info["chave"]["escopos"])

{
  "ok": true,
  "chave": {
    "id": 3,
    "nome": "ERP financeiro",
    "prefixo": "cisp_7f3a9…",
    "escopos": ["mensagens_enviar", "conversas_ler", "atendimentos_abrir"],
    "cota_minuto": 60
  },
  "servidor": {
    "api_versao": "1",
    "fuso_horario": "America/Sao_Paulo",
    "agora": "2026-10-01T09:30:12-03:00",
    "plano": "PREMIUM"
  }
}

Orden de validación

Toda llamada pasa por estas verificaciones, en este orden. La primera que falle define la respuesta:

1. r ausente o fuera del formato recurso/acao: HTTP 404 rota.
2. Encabezado Authorization: Bearer ... ausente o mal formado: HTTP 401 autenticacao.
3. Clave inexistente, eliminada, inactiva o fuera del formato cisp_...: HTTP 401 chave_invalida.
4. Plan sin API pública o licencia bloqueada: HTTP 403 plano.
5. La llamada se cuenta en el uso de la clave. Si superó el límite por minuto: HTTP 429 cota_excedida.
6. Cuerpo declarado como JSON, pero inválido: HTTP 400 json_invalido.
7. Ruta inexistente: HTTP 404 rota.
8. Ruta de escritura llamada sin POST: HTTP 405 metodo.
9. Clave sin el alcance de la ruta: HTTP 403 permissao, con el alcance que faltó.
10. La operación valida sus propios parámetros y se ejecuta.

Formato de la solicitud

Métodos

• Lectura (listar, consultar, catálogos, indicadores, descargar archivo): GET o POST.
• Escritura (enviar, transferir, cerrar, crear, mover...): solo POST. Con otro método, la respuesta es HTTP 405 metodo con "esperado":"POST".

Dónde van los parámetros

La query string vale con cualquier método. Cuando el mismo parámetro viene en la query y en el cuerpo, prevalece el cuerpo. Un cuerpo con Content-Type: application/json que no sea un objeto JSON válido se rechaza con HTTP 400 json_invalido.

# formulario
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=mensagens/enviar" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -d "telefone=44999990000" -d "texto=¡Hola! Su técnico está en camino."

# JSON
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=mensagens/enviar" \
  -H "Authorization: Bearer $CHATISP_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"telefone":"44999990000","texto":"¡Hola! Su técnico está en camino."}'

Tipos de parámetro

Formato de la respuesta

Toda respuesta es JSON (Content-Type: application/json; charset=utf-8, Cache-Control: no-store) con un sobre igual en todas las rutas:

El campo error es siempre un código estable, sin tildes y sin traducción, pensado para que su sistema decida qué hacer. Los campos extra ayudan a corregir la llamada: campo (qué parámetro), aceitos (valores permitidos), maximo, esperado, escopo, entre otros. Los caracteres acentuados vienen sin escape ("Suporte técnico"), al igual que las barras.

HTTP 400  {"ok":false,"error":"parametro_invalido","campo":"estado","aceitos":["ia","fila","humano","encerrada","auto"]}
HTTP 403  {"ok":false,"error":"permissao","escopo":"tickets_gerir"}
HTTP 404  {"ok":false,"error":"nao_encontrado"}

Estado HTTP

El estado HTTP es real y coherente con el resultado: verifique el estado y el campo ok.

Respuestas que no son JSON

Solo mensagens/arquivo: en caso de éxito devuelve el propio archivo, con el Content-Type del archivo (imágenes y PDF) o application/octet-stream (demás tipos) y Content-Disposition con el nombre original. En caso de error, devuelve el sobre JSON normal.

Objetos que se repiten

Las rutas de mensajes, conversaciones y contactos devuelven la conversación y el mensaje siempre con los mismos campos (los detalles están en Conversaciones y Mensajes). Valores que encontrará:

Paginación y cursor

Paginación numerada

Los listados grandes (conversas/listar, contatos/listar, tickets/listar y agenda/listar) usan página y límite:

La respuesta trae el bloque paginacao:

"paginacao": {
  "pagina": 2,
  "limite": 50,
  "total": 137,
  "paginas": 3
}

total es la cantidad de registros que cumplen los filtros y paginas es cuántas páginas existen con ese límite (0 cuando no hay registros). Para recorrer todo, llame hasta que pagina llegue a paginas. Una página posterior a la última devuelve la lista vacía, sin error.

Cursor del historial de mensajes

El historial de una conversación (conversas/mensagens) usa un cursor por el id del mensaje, que no se desplaza cuando llegan mensajes nuevos:

"tem_mais": true,
"cursor": {
  "antes_de": 402801,
  "depois_de": 402850
}

tem_mais indica si todavía hay mensajes en la dirección solicitada. Para seguir retrocediendo, pase cursor.antes_de en el próximo antes_de; para seguir los nuevos, guarde cursor.depois_de y úselo como depois_de en la próxima consulta. Los mensajes vienen siempre en orden cronológico (del más antiguo al más nuevo).

Fechas y zona horaria

Fechas en la respuesta

Todas las fechas de salida vienen en ISO 8601 con la zona horaria del servidor, por ejemplo 2026-10-01T09:12:40-03:00. Las fechas ausentes vienen como null. La zona horaria del servidor aparece en chave/info (servidor.fuso_horario), junto con su reloj (servidor.agora), útil para verificar la diferencia horaria con su sistema.

Fechas en la solicitud

Años fuera de 2000 a 2100 o texto que no es una fecha responden HTTP 400 data_invalida con el campo. Los períodos con fin anterior al inicio, o mayores que lo permitido por la ruta (366 días en indicadores y agenda), responden periodo_invalido.

Teléfonos

El teléfono sigue la misma regla de la pantalla del panel. Se ignoran la puntuación, los espacios y los paréntesis.

Reglas de los números brasileños: código de área de 11 a 99 (sin cero) y, cuando el número tiene 11 dígitos, el tercero debe ser el 9 del celular. Fuera de eso, la respuesta es HTTP 400 telefone_invalido. Sin el +, un número que no encaja como brasileño también se rechaza, para no enviar el mensaje al país equivocado.

En las consultas por teléfono (conversaciones, contactos), ChatISP busca el número con y sin el noveno dígito, porque el WhatsApp de algunos celulares antiguos todavía usa el formato de 8 dígitos. En las respuestas, el teléfono viene solo con dígitos y con el código de país, en el formato en que la conversación está registrada.

Códigos de error

Lista completa de los valores posibles de error. Cada página de la referencia muestra qué errores puede devolver cada ruta.

Límites

Límite por minuto de la clave

Cada clave tiene su Límite por minuto (predeterminado 60, máximo 10000, 0 sin límite). El conteo es por minuto del reloj del servidor: se reinicia cuando cambia el minuto (a las 10:41:00, a las 10:42:00...), no en una ventana móvil de 60 segundos.

Con un límite definido, toda respuesta trae los encabezados:

Una clave con límite 0 no recibe los encabezados X-RateLimit-*.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Content-Type: application/json; charset=utf-8

{"ok":false,"error":"cota_excedida","cota_minuto":60}

La llamada rechazada no se ejecutó: espere el Retry-After y repita. Los rechazos también cuentan en el minuto, así que repetir en bucle sin esperar no sirve.

Tamaños y cantidades

Ritmo de envío masivo

La API envía cada mensaje en el momento en que se llama. Para avisos a muchos suscriptores, distribuya los envíos en el tiempo en lugar de disparar cientos de llamadas simultáneas, y ajuste el límite por minuto de la clave a ese ritmo. Para listas grandes con seguimiento de entregas y respuestas, la pantalla Automatización de envíos ya controla el ritmo por sí sola.

Versión de la API

Toda respuesta, incluso las de error, trae el encabezado:

X-ChatISP-Api-Versao: 1

El mismo valor aparece en chave/info, en el campo servidor.api_versao. La versión actual es la 1. Registre el valor en los logs de la integración: ayuda a soporte a identificar con qué versión habló su sistema.

Las rutas, los nombres de campo y los códigos de error documentados aquí son estables. La API puede ganar rutas, parámetros opcionales y campos nuevos en las respuestas sin cambiar de versión; por eso su sistema debe ignorar los campos desconocidos en lugar de rechazar la respuesta. Los campos antiguos se mantienen para quien ya integró: por ejemplo, atendimentos/abrir sigue devolviendo conversa_id, protocolo, estado y ja_existia en el nivel superior, además del objeto conversa completo.

Seguridad y buenas prácticas

Lista de verificación

• Una clave por integración, con un Nombre claro y solo los alcances necesarios.
• Guarde la clave en una variable de entorno o en el almacén de secretos del servidor, nunca en el código versionado ni en logs.
• Use siempre HTTPS. En una instalación propia, configure un dominio con certificado válido antes de producción.
• Un límite por minuto compatible con el uso real: también protege contra un bucle descontrolado en su sistema.
• Verifique ok y el estado HTTP en toda respuesta; decida según el código de error.
• Ante un 429, respete el Retry-After. Ante un error de red o HTTP 5xx, repita las lecturas con espera creciente. No repita envíos a ciegas: un mensaje que dio timeout puede haberse entregado, y repetir duplica el envío al cliente. Antes, verifique el historial con conversas/mensagens.
• Guarde los ids devueltos (conversa_id, mensagem_id, ticket_id) para cruzarlos con los webhooks.
• Guarde en caché los catálogos (departamentos, agentes, etiquetas, motivos) y actualícelos de vez en cuando, en lugar de consultarlos en cada llamada.
• Prefiera los webhooks a consultar en bucle para saber qué cambió.
• Desactive o elimine las claves de integraciones apagadas. Para cambiar una clave, cree la nueva, actualice la integración y solo entonces elimine la antigua.

Qué queda registrado

Las acciones hechas por la API aparecen en el panel con el nombre de la clave: el evento "API" en la línea de tiempo de la conversación, las notas como "API (nombre de la clave): ...", las transferencias y cierres con "API: nombre de la clave", y los comentarios de OS con "[API: nombre de la clave]". Los mensajes enviados por la API salen con autor sistema, sin firma de agente.

Problemas frecuentes

Colección para Postman e Insomnia

Para probar la API sin escribir código, descargue la colección lista con las 37 rutas, ya con el método, parámetros de ejemplo y la descripción de cada una:

Descargar la colección (chatisp-api.postman_collection.json)

1. En Postman, use Import y elija el archivo. En Insomnia, use Import en una colección; el formato de Postman se reconoce.
2. En las variables de la colección, complete base_url con la dirección de su panel (por ejemplo https://atendimento.seuprovedor.com.br, sin barra al final) y chave con su clave cisp_....
3. Ejecute primero Informações da chave (información de la clave, chave/info) para confirmar dirección, clave y alcances.
4. Use los catálogos para descubrir los ids reales de su instalación antes de probar las rutas de escritura.