Referência da API
Esta página é gerada do contrato que o servidor publica em GET /api/v1/openapi.json — o mesmo que a sua ferramenta pode importar. O guia de como integrar, com as decisões (webhook em vez de consulta em laço, a janela de 24 horas, o que a API não faz), está em A API do Hugi.
Versão da API: 1. Base: /api/v1.
Toda rota pede Authorization: Bearer hugi_sk_..., menos /openapi.json.
Escopos: cada chave carrega os seus, e uma rota recusa com 403 quando a chave não tem o escopo dela. O que cada escopo cobre está em Chaves de API — esta página não os repete por rota de propósito: o escopo hoje vive no código do servidor, não no contrato, e uma lista raspada acertaria metade das linhas sem dizer quais.
atendimentos #
| rota | o que faz | |
|---|---|---|
GET |
/atendimentos |
Lista conversas |
GET |
/atendimentos/{id} |
Uma conversa |
GET |
/atendimentos/{id}/eventos |
A trilha da conversa |
POST |
/atendimentos/{id}/finalizar |
Encerrar |
GET |
/atendimentos/{id}/mensagens |
O fio da conversa |
POST |
/atendimentos/{id}/mensagens |
Responder |
POST |
/atendimentos/{id}/notas |
Nota interna — o cliente não vê |
POST |
/atendimentos/{id}/reabrir |
Reabrir |
POST |
/atendimentos/{id}/transferir |
Devolver para a equipe, ou passar para uma fila |
campanhas #
| rota | o que faz | |
|---|---|---|
GET |
/campanhas |
As campanhas desta conta |
POST |
/campanhas |
Agendar uma campanha (template de marketing para uma lista com opt-in) |
GET |
/campanhas/{id} |
Uma campanha, com as contagens por resultado |
POST |
/campanhas/{id}/cancelar |
Cancelar o que ainda não saiu |
GET |
/campanhas/{id}/destinatarios |
Os destinatários e o resultado de cada um |
GET |
/campanhas/{id}/estatisticas |
As estatísticas de uma campanha: funil, custo e retorno |
POST |
/campanhas/{id}/pausar |
Pausar |
POST |
/campanhas/{id}/retomar |
Retomar uma campanha pausada |
POST |
/campanhas/previa |
A prévia de uma campanha, sem agendar |
chaves #
| rota | o que faz | |
|---|---|---|
GET |
/chaves |
As chaves de API desta conta |
POST |
/chaves |
Criar outra chave (rotação) |
DELETE |
/chaves/{id} |
Revogar uma chave |
conexoes #
| rota | o que faz | |
|---|---|---|
GET |
/conexoes |
Os números que o Hugi atende por você |
POST |
/conexoes/link |
O link para ligar mais um WhatsApp |
contatos #
| rota | o que faz | |
|---|---|---|
GET |
/contatos |
Contatos |
funil #
| rota | o que faz | |
|---|---|---|
GET |
/funil |
O funil de oportunidades (kanban) |
DELETE |
/funil/campos/{id} |
Arquivar um campo |
PATCH |
/funil/campos/{id} |
Editar um campo |
GET |
/funil/catalogo |
O catálogo de produtos e serviços |
POST |
/funil/catalogo |
Criar um item do catálogo |
DELETE |
/funil/catalogo/{id} |
Arquivar um item do catálogo |
PATCH |
/funil/catalogo/{id} |
Editar um item do catálogo |
GET |
/funil/etapas |
As etapas de todos os quadros |
POST |
/funil/importar |
Importar oportunidades de uma planilha (CSV colado) |
POST |
/funil/oportunidades |
Abrir uma oportunidade à mão |
PATCH |
/funil/oportunidades/{id} |
Editar título, valor, temperatura, responsável, previsão ou observação |
GET |
/funil/oportunidades/{id}/conversa |
A conversa da campanha, só ela |
POST |
/funil/oportunidades/{id}/ganhar |
Marcar como ganha |
GET |
/funil/oportunidades/{id}/itens |
Os itens que compõem o card |
POST |
/funil/oportunidades/{id}/itens |
Acrescentar um item do catálogo ao card |
DELETE |
/funil/oportunidades/{id}/itens/{item} |
Tirar um item do card |
POST |
/funil/oportunidades/{id}/mover |
Mover para outra etapa aberta |
POST |
/funil/oportunidades/{id}/passar-para-a-fila |
Tirar o contato da IA (ou de quem estiver) e devolvê-lo à fila |
POST |
/funil/oportunidades/{id}/perder |
Marcar como perdida, com motivo |
POST |
/funil/oportunidades/{id}/reabrir |
Reabrir uma oportunidade fechada |
POST |
/funil/oportunidades/{id}/responder |
Responder ao contato do card, pela conversa aberta dele |
GET |
/funil/oportunidades/{id}/tarefas |
As tarefas do card |
POST |
/funil/oportunidades/{id}/tarefas |
Criar uma tarefa no card |
DELETE |
/funil/oportunidades/{id}/tarefas/{tarefa} |
Cancelar a tarefa |
POST |
/funil/oportunidades/{id}/tarefas/{tarefa}/concluir |
Marcar a tarefa como feita |
GET |
/funil/quadros |
Os quadros do funil |
POST |
/funil/quadros |
Criar um quadro |
DELETE |
/funil/quadros/{id} |
Arquivar um quadro |
PATCH |
/funil/quadros/{id} |
Editar um quadro |
POST |
/funil/quadros/{id}/campos |
Criar um campo personalizado no quadro |
GET |
/funil/relatorio |
O relatório do funil: ganhas, perdidas, perdas por motivo, por origem, tempo até fechar |
mensagens #
| rota | o que faz | |
|---|---|---|
POST |
/mensagens |
Responder por número, sem guardar o id da conversa |
midias #
| rota | o que faz | |
|---|---|---|
GET |
/midias/{mensagemId} |
Baixar a mídia de uma mensagem |
modelos #
| rota | o que faz | |
|---|---|---|
GET |
/modelos |
A biblioteca de modelos de fluxo e assistente, por mercado |
GET |
/modelos/exportar |
Exportar um fluxo e/ou um assistente como modelo |
POST |
/modelos/importar |
Importar um modelo nesta empresa |
plano #
| rota | o que faz | |
|---|---|---|
GET |
/plano |
Quanto do plano já foi usado no mês |
Erros #
Toda recusa tem a mesma forma: { erro, mensagem, detalhe, traceId }. Decida pelo erro (código estável), mostre a mensagem (pode mudar) e cite o traceId no suporte.