API de ¡Hola! Suite
Ruta para liberar el acceso: Configuraciones → Permisos (grupo de API) y Usuarios (acceso a la API). La referencia completa de los campos de cada recurso está en api.opasuite.com.br.
Visión general
La API de ¡Hola! Suite permite que un sistema externo consulte y modifique datos de tu instalación mediante solicitudes HTTP autenticadas. Con ella, integras ¡Hola! Suite con otros sistemas, por ejemplo para listar atenciones, enviar mensajes o registrar clientes.
Toda solicitud necesita un token de acceso, que pertenece a un usuario de ¡Hola! Suite. Lo que la integración puede hacer lo define un grupo de permisos exclusivo para API, vinculado a ese usuario.
Cuándo usar
- Consultar atenciones, mensajes, clientes y contactos desde otro sistema.
- Enviar mensajes y plantillas de mensaje a una atención.
- Registrar o actualizar clientes, contactos y departamentos desde una base externa.
- Alimentar informes externos, como el panel de Looker Studio.
Requisitos previos
- Un usuario con Tiene acceso a la API del sistema activo y un Grupo de permisos de la API vinculado. Consulta Generar el token de acceso de la API.
- El token de ese usuario.
- Un grupo de permisos exclusivo para API con los permisos necesarios marcados. Consulta Crear y configurar un grupo de permisos y Funciones de cada permiso.
Cómo funciona
Dirección base
Todos los recursos están en /api/v1, en la dirección de tu instalación. Ejemplo:
https://seu-opa-suite.com.br/api/v1/atendimentoAutenticación
Envía el token en el encabezado Authorization, en formato Bearer:
Authorization: Bearer SEU_TOKEN
Content-Type: application/jsonLa solicitud se rechaza cuando:
- el token no es el token actual del usuario (por ejemplo, después de generar uno nuevo);
- el usuario está inactivo;
- la dirección IP de origen no está en las Redes permitidas del grupo de API. Consulta Restringir el acceso por dirección IP;
- el grupo de API del usuario no tiene el permiso del recurso y de la operación pedidos.
Quien tiene el token accede a la API con los permisos del grupo vinculado. No publiques el token en código abierto ni lo compartas con personas no autorizadas. Si sospechas una filtración, genera un token nuevo: el anterior deja de funcionar al instante.
Recursos disponibles
La lista de recursos, con rutas, operaciones y campos de cada uno, está en la documentación oficial de la API de ¡Hola! Suite:
Consulta esa página para saber qué puedes usar en tu integración. Muestra solo los recursos disponibles para uso externo; esta página del Centro de Ayuda no los repite.
Para usar un recurso, el grupo de API del usuario debe tener marcado el permiso correspondiente. Consulta Funciones de cada permiso.
El envío de mensajes por Webchat usa otra protección. Consulta Webchat - modo API.
Listar registros
Las listas (GET sin :id) leen el filtro en el cuerpo de la solicitud, en JSON:
{
"filter": { "status": "EA" },
"options": { "limit": 50, "skip": 0 }
}filter: informa al menos un filtro válido para el recurso. Un campo que no se puede filtrar devuelve error400, con el mensajeField '<campo>' is not allowed.options.limit: de 1 a 1000. Sin valor, o con un valor fuera de ese intervalo, la API devuelve hasta 1000 registros.options.skip: cuántos registros omitir, para paginar.
Enviar un mensaje a la atención
POST /api/v1/atendimento/mensagem/send
{
"customerServiceId": "ID_DO_ATENDIMENTO",
"content": {
"type": "text",
"text": "Olá! Como posso ajudar?"
}
}customerServiceId: obligatorio.content.type:textomedia.content.text: obligatorio cuando el tipo estext.content.media: obligatorio cuando el tipo esmedia, conurlobase64.
Formato de las respuestas
Toda respuesta trae status, code y data.
Éxito:
{
"status": "success",
"code": 200,
"data": {}
}Error:
{
"status": "error",
"code": 403,
"data": { "message": "Invalid permissions profile." },
"description": "Bad role"
}Códigos de error
| Código | Cuándo ocurre |
|---|---|
400 | Faltan argumentos, el tipo o el valor de un campo es inválido, o el cuerpo está vacío. |
401 | El token no es válido (TOKEN_VERIFY_ERROR). |
403 | El grupo de API no tiene el permiso (Invalid permissions profile.) o la red de origen no está permitida (Access forbidden. Your network is not allowed). |
404 | No se encontró el recurso o el registro. |
409 | El registro ya existe. |
500 | Error en el servidor o en un servicio externo. |
Registro de las llamadas
¡Hola! Suite registra cada llamada a la API, con usuario, dirección IP, ruta, método, parámetros y código de la respuesta.
Buenas prácticas
- Crea un usuario y un grupo de API solo para cada integración, y marca en el grupo únicamente lo que usa.
- Restringe el grupo de API a las Redes permitidas del servidor que llama a la API.
- Actualiza la integración siempre que generes un nuevo token.