Chaves de API

Uma chave de API deixa o seu sistema — ERP, site, agendamento — usar o Hugi sem uma pessoa logada.

Integrações e API → Chaves de API. Exige perfil de Administrador.

Criar #

Dê um nome que diga onde ela é usada — “ERP da recepção”, “site de agendamento” — e marque os escopos: o que aquela chave pode fazer. O vocabulário é o mesmo das permissões de tela (read_conversation, respond_conversation, read_channel).

Marque só o que aquele sistema precisa. Uma chave que só avisa “seu pedido saiu para entrega” precisa de respond_conversation e de mais nada.

Uma chave por sistema, e não uma para tudo. É o que permite revogar o acesso do site sem derrubar o ERP, e é o que faz o registro dizer quem fez o quê.

Usar #

A chave vai no cabeçalho Authorization, como um token comum:

Authorization: Bearer hugi_sk_...

As rotas de conversa — receber, responder, encerrar, ler o histórico — estão em A API do Hugi. As duas abaixo são do canal API Hugi (o WhatsApp que você conecta lendo um QR), e não do canal oficial.

Ver o estado do canal #

GET /api/v1/transporte/estado

Enviar uma mensagem #

POST /api/v1/transporte/enviar
Content-Type: application/json
Authorization: Bearer hugi_sk_...

{
  "para": "5527999998888",
  "tipo": "texto",
  "texto": "Seu pedido saiu para entrega.",
  "correlacao": "pedido-4821"
}

correlacao é obrigatória. É o seu identificador para aquele envio, e é ele que volta no recibo dizendo se a mensagem foi entregue. Sem ela o recibo chegaria órfão e você não teria como ligá-lo ao que enviou — por isso o envio é recusado em vez de aceito pela metade.

Não mande tenantId. O tenant vem da chave. Se ele vier no corpo, a resposta é 400 — e não um silêncio, que faria você acreditar que aquele campo estava valendo.

As respostas de erro #

Todas trazem um código legível, e não só um número:

Erros com retentavel: true valem repetir depois; os outros não vão passar até você mudar algo.

Um pedido bem formado que o canal não sabe executar — mandar áudio por um canal que não aceita áudio — devolve 422, e não 400. A distinção existe para o seu código separar “escrevi errado” de “esse canal não faz isso”.

Revogar #

No cartão da chave, Revogar. Vale na hora. O cartão passa a mostrar Revogada em vez de sumir da lista, para o registro do que existiu continuar legível.

O que a API cobre #

A rotina inteira do atendimento: listar e ler conversas, mensagens e eventos; enviar; transferir, encerrar, reabrir e comentar; ler contatos, conexões e o seu plano; e criar e revogar as próprias chaves. O contrato completo está em a API do Hugi, e em OpenAPI no GET /api/v1/openapi.json.