Central de Ajuda

Português

Español

Português

Español

Appearance

API do Opa! Suite ​

Acesso

Caminho para liberar o acesso: Configurações → Permissões (grupo de API) e Usuários (acesso à API). A referência completa dos campos de cada recurso está em api.opasuite.com.br.

Visão geral ​

A API do Opa! Suite permite que um sistema externo consulte e altere dados da sua instalação por requisições HTTP autenticadas. Com ela, você integra o Opa! Suite a outros sistemas, por exemplo para listar atendimentos, enviar mensagens ou cadastrar clientes.

Toda requisição precisa de um token de acesso, que pertence a um usuário do Opa! Suite. O que a integração pode fazer é definido por um grupo de permissão exclusivo para API, vinculado a esse usuário.

Quando usar ​

  • Consultar atendimentos, mensagens, clientes e contatos a partir de outro sistema.
  • Enviar mensagens e modelos de mensagem a um atendimento.
  • Cadastrar ou atualizar clientes, contatos e departamentos a partir de uma base externa.
  • Alimentar relatórios externos, como o painel do Looker Studio.

Pré-requisitos ​

Como funciona ​

Endereço base ​

Todos os recursos ficam em /api/v1, no endereço da sua instalação. Exemplo:

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

Autenticação ​

Envie o token no cabeçalho Authorization, no formato Bearer:

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

A requisição é recusada quando:

  • o token não é o token atual do usuário (por exemplo, depois de gerar um novo token);
  • o usuário está inativo;
  • o endereço IP de origem não está nas Redes permitidas do grupo de API. Veja Restringir o acesso por endereço IP;
  • o grupo de API do usuário não tem a permissão do recurso e da operação pedidos.
Guarde o token como uma senha

Quem tem o token acessa a API com as permissões do grupo vinculado. Não publique o token em código aberto nem o compartilhe com pessoas não autorizadas. Se suspeitar de vazamento, gere um novo token: o anterior deixa de funcionar na hora.

Recursos disponíveis ​

A lista de recursos, com caminhos, operações e campos de cada um, fica na documentação oficial da API do Opa! Suite:

api.opasuite.com.br

Consulte essa página para saber o que você pode usar na sua integração. Ela mostra apenas os recursos disponíveis para uso externo; esta página da Central de Ajuda não os repete.

Para usar um recurso, o grupo de API do usuário precisa ter a permissão correspondente marcada. Veja Funções de cada permissão.

O envio de mensagens por Webchat usa outra proteção. Veja Webchat - modo API.

Listar registros ​

As listas (GET sem :id) leem o filtro no corpo da requisição, em JSON:

json
{
  "filter": { "status": "EA" },
  "options": { "limit": 50, "skip": 0 }
}
  • filter: informe pelo menos um filtro válido para o recurso. Um campo que não pode ser filtrado devolve erro 400, com a mensagem Field '<campo>' is not allowed.
  • options.limit: de 1 a 1000. Sem valor, ou com valor fora desse intervalo, a API devolve até 1000 registros.
  • options.skip: quantos registros pular, para paginar.

Enviar uma mensagem ao atendimento ​

POST /api/v1/atendimento/mensagem/send

json
{
  "customerServiceId": "ID_DO_ATENDIMENTO",
  "content": {
    "type": "text",
    "text": "Olá! Como posso ajudar?"
  }
}
  • customerServiceId: obrigatório.
  • content.type: text ou media.
  • content.text: obrigatório quando o tipo é text.
  • content.media: obrigatório quando o tipo é media, com url ou base64.

Formato das respostas ​

Toda resposta traz status, code e data.

Sucesso:

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

Erro:

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

Códigos de erro ​

CódigoQuando acontece
400Faltam argumentos, o tipo ou o valor de um campo é inválido, ou o corpo está vazio.
401O token não é válido (TOKEN_VERIFY_ERROR).
403O grupo de API não tem a permissão (Invalid permissions profile.) ou a rede de origem não é permitida (Access forbidden. Your network is not allowed).
404O recurso ou o registro não foi encontrado.
409O registro já existe.
500Erro no servidor ou em um serviço externo.

Registro das chamadas ​

O Opa! Suite registra cada chamada à API, com usuário, endereço IP, caminho, método, parâmetros e código da resposta.

Boas práticas ​

  • Crie um usuário e um grupo de API só para cada integração, e marque no grupo apenas o que ela usa.
  • Restrinja o grupo de API às Redes permitidas do servidor que chama a API.
  • Atualize a integração sempre que gerar um novo token.

Conteúdos relacionados ​