Referência da API

Documentação completa da API para integrar a Hanc.AI nas suas aplicações. Faça a gestão de agentes, obtenha dados de chamadas, coloque chamadas e opere cada parte da plataforma programaticamente.

---

Visão geral rápida

URL Base	https://api.hanc.ai
Autenticação	Chave de API via cabeçalho x-api-key
Formato	JSON

Gere uma chave de API a partir de Integration → API Keys no dashboard. Pode ter até 3 chaves por utilizador — consulte a secção API Keys em Integrações para configuração, permissões e orientação de segurança.

curl -X GET "https://api.hanc.ai/v1/agent/list" \
  -H "x-api-key: YOUR_API_KEY"

---

Endpoints disponíveis

Chamadas

Ação	Método	Endpoint
Listar chamadas	GET	/v1/call/list
Detalhes da chamada (transcrição, sentimento, resumo)	GET	/v1/call/:id
Análises gerais (métricas por data/agente)	GET	/v1/call/general-metrics
Análises diárias	GET	/v1/call/daily-metrics
Estatísticas de sentimento	GET	/v1/call/sentiment-stats
Detalhamento de custos	GET	/v1/call/costs-breakdown
Exportar chamadas (CSV)	GET	/v1/call/list/export
Exportar custos (CSV)	GET	/v1/call/costs-breakdown/export
Fazer uma chamada telefónica	POST	/v1/call/make-phone-call
Fazer uma chamada web	POST	/v1/call/make-web-call

Agentes

Ação	Método	Endpoint
Listar agentes	GET	/v1/agent/list
Detalhes do agente	GET	/v1/agent/:id
Criar agente	POST	/v1/agent
Atualizar agente	PATCH	/v1/agent/:id
Eliminar agente	DELETE	/v1/agent/:id
Estatísticas de chamadas do agente	GET	/v1/agent/:id/call-stats
Listar templates de agente	GET	/v1/agent/agent_template/list

Ações de Agente:

Ação	Método	Endpoint
Listar ações	GET	/v1/agent/:id/actions
Adicionar ação	POST	/v1/agent/:id/actions
Atualizar ação	PATCH	/v1/agent/:id/actions/:actionId
Eliminar ação	DELETE	/v1/agent/:id/actions/:actionId

Ferramentas de Agente:

Ação	Método	Endpoint
Listar ferramentas	GET	/v1/agent/:id/tools
Adicionar ferramenta	POST	/v1/agent/:id/tools
Atualizar ferramenta	PATCH	/v1/agent/:id/tools/:toolId
Eliminar ferramenta	DELETE	/v1/agent/:id/tools/:toolId

Base de Conhecimento

Ação	Método	Endpoint
Listar bases de conhecimento	GET	/v1/knowledge-base/list
Criar base de conhecimento	POST	/v1/knowledge-base
Carregar ficheiro(s)	POST	/v1/knowledge-base/:id/file(s)
Eliminar ficheiro	DELETE	/v1/knowledge-base/:id/file
Atribuir agentes	PUT	/v1/knowledge-base/:id/agents

Números de Telefone

Ação	Método	Endpoint
Listar números	GET	/v1/phone-number/list
Números disponíveis (por país)	GET	/v1/phone-number/available
Comprar um número	POST	/v1/phone-number/buy
Importar número	POST	/v1/phone-number/import
Ligar a SIP	PATCH	/v1/phone-number/connect-to-sip

Vozes

Ação	Método	Endpoint
Listar vozes	GET	/v1/voice/list

Filtrar por idioma: GET /v1/voice/list?language=de

Subscrição

Ação	Método	Endpoint
Detalhes da subscrição	GET	/v1/subscription
Configurar recarga automática	PATCH	/v1/subscription/auto-top-up
Definir valor de recarga	PATCH	/v1/subscription/top-up-amount

Clientes

Ação	Método	Endpoint
Listar clientes	GET	/v1/customer/list
Detalhes do cliente	GET	/v1/customer/:id
Criar cliente	POST	/v1/customer
Atualizar cliente	PATCH	/v1/customer/:id
Eliminar cliente	DELETE	/v1/customer/:id

Workspaces

Ação	Método	Endpoint
Operações de workspace	GET/POST/PATCH/DELETE	/v1/workspaces/*
Convidar membro	POST	/v1/workspaces/:id/invite-member
Remover membro	DELETE	/v1/workspaces/:id/invite-member

---

O que não está disponível via API

Algumas operações estão apenas disponíveis através do dashboard:

Funcionalidade	Motivo
Gestão de chaves de API	Segurança — as chaves não podem criar outras chaves
Configuração de números de telefone	Requer configuração interativa
Integração Google Calendar	Requer autorização interativa
Faturação e pagamentos	Geridos através do dashboard

---

Precisa de ajuda?

Contacte a nossa equipa de suporte em support@hanc.ai para questões relacionadas com a API.