Skip to content

API de ¡Hola! Suite ​

Acceso

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 ​

Cómo funciona ​

Dirección base ​

Todos los recursos están en /api/v1, en la dirección de tu instalación. Ejemplo:

text
https://seu-opa-suite.com.br/api/v1/atendimento

Autenticación ​

Envía el token en el encabezado Authorization, en formato Bearer:

http
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

La 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.
Guarda el token como una contraseña

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:

api.opasuite.com.br

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:

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 error 400, con el mensaje Field '<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

json
{
  "customerServiceId": "ID_DO_ATENDIMENTO",
  "content": {
    "type": "text",
    "text": "Olá! Como posso ajudar?"
  }
}
  • customerServiceId: obligatorio.
  • content.type: text o media.
  • content.text: obligatorio cuando el tipo es text.
  • content.media: obligatorio cuando el tipo es media, con url o base64.

Formato de las respuestas ​

Toda respuesta trae status, code y data.

Éxito:

json
{
  "status": "success",
  "code": 200,
  "data": {}
}

Error:

json
{
  "status": "error",
  "code": 403,
  "data": { "message": "Invalid permissions profile." },
  "description": "Bad role"
}

Códigos de error ​

CódigoCuándo ocurre
400Faltan argumentos, el tipo o el valor de un campo es inválido, o el cuerpo está vacío.
401El token no es válido (TOKEN_VERIFY_ERROR).
403El 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).
404No se encontró el recurso o el registro.
409El registro ya existe.
500Error 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.

Contenidos relacionados ​