omniplug

Documentação da API

Autenticação

São duas camadas de credencial, uma autoriza o seu sistema e a outra isola o cliente da chamada:

  • Chave de API do app: o seu sistema usa em todas as chamadas, no header x-api-key ou Authorization: Bearer omp_.... Ela pertence a um app criado no painel e tem escopos, cada chave só faz o que você liberou.
  • Token do cliente: cada cliente recebe um token próprio. Enviado no header x-customer-token junto da chave de API, ele limita a chamada aos dados daquele cliente. Sem misturar nada.

Um exemplo de chamada

Conversas ativas de um cliente do seu sistema:

curl https://api.omniplug.com.br/v1/conversations \
  -H "x-api-key: omp_..." \
  -H "x-customer-token: <token do cliente>"

As rotas que mexem nos dados de um cliente exigem os dois headers. A chave sozinha lista contas de canal, templates e endpoints, mas conversas, mensagens e contatos só aparecem com o token de quem é dono delas.

Escopos da chave de API

No painel, cada chave nasce com os escopos que você escolher. Chamada a rota que pede um escopo que a chave não tem responde 403. Os escopos seguem o padrão recurso:ação:

EscopoO que libera
company:readDados da empresa e do app da chave
customers:read / customers:writeClientes do app e os tokens deles
contacts:read / contacts:writeContatos do cliente (nome, e-mail e telefone)
channel_accounts:read / channel_accounts:writeNúmeros e contas de canal conectados
messages:send / messages:readEnviar mensagens e ver o andamento dos envios
conversations:read / conversations:writeConversas, mensagens em tempo real e ações da conversa
templates:read / templates:writeTemplates aprovados na Meta e a sincronização deles
webhooks:read / webhooks:writeEndpoints de webhook e o histórico de entregas

O token do cliente

O cliente recebe o próprio token na conexão do número. Se um token vazar ou você quiser trocá-lo por precaução, POST /v1/customers/:id/token gera outro e derruba o antigo; DELETE /v1/customers/:id/token remove o acesso pela API.

Credenciais no lugar? O caminho é configurar a chave no painel e seguir para a conexão do número do primeiro cliente.