API

# API KambaChat — para programadores

Esta API permite que sistemas externos (o seu site, app ou ERP) criem pedidos automaticamente na sua conta KambaChat. Os pedidos entram no painel e seguem o fluxo normal: confirmar e concluir.

> Disponibilidade (GEO) — As montras são exclusivas de Angola. Esta API cria pedidos na sua montra digital, por isso aplica-se a vendedores de Angola. Utilizadores internacionais: o KambaChat foca-se em automação de WhatsApp, Facebook e Instagram com IA — a montra e a API de pedidos não estão disponíveis fora de Angola.

1. Autenticação

A autenticação é feita por uma chave secreta no cabeçalho de cada pedido.

1. Crie uma chave em Painel → Definições → Chaves API: dê um nome e (opcional) uma expiração, e clique em Criar Chave.

2. A chave (af_...) é mostrada uma única vez. É guardada cifrada (SHA-256) — nunca é recuperável. Guarde-a em segredo.

3. Envie-a em cada pedido no cabeçalho: Authorization: Bearer af_...

Segurança

• A chave nunca é guardada em texto simples — só o seu hash.
• Pode definir expiração (30/90/365 dias) e apagar uma chave a qualquer momento (revoga de imediato).
• Limites de pedidos (rate-limit): 60/min por IP e 120/min por chave.
• Nunca exponha a chave no frontend/navegador — use-a só do lado do servidor.

2. Criar um pedido

POST /api/webhooks/orders

Cria um pedido na sua conta (estado Pendente) e dispara-lhe uma notificação no painel.

Exemplo

```bash

curl -X POST https://kambachat.com/api/webhooks/orders \

-H "Authorization: Bearer af_xxxxxxxx..." \

-H "Content-Type: application/json" \

-d '{

"customerName": "Ana Silva",

"customerPhone": "+244923000000",

"customerEmail": "[email protected]",

"address": "Kilamba, Luanda",

"channel": "WHATSAPP",

"notes": "Cliente VIP — contactar por WhatsApp",

"items": [

{ "productId": "PRODUCT_ID_1", "quantity": 2 },

{ "productId": "PRODUCT_ID_2", "quantity": 1 }

]

}'

```

Resposta (201)

```json

{ "success": true, "orderNumber": "WA12345678", "orderId": "ckx...", "total": 7500 }

```

Os productId têm de pertencer à sua conta. Se enviar items, o total é recalculado a partir dos preços reais dos produtos.

3. Obter o catálogo público

GET /api/webhooks/orders?store=SLUG

Devolve os dados públicos da montra (nome, produtos ativos, config da IA) pelo *slug*. Não precisa de chave (é público).

```bash

curl "https://kambachat.com/api/webhooks/orders?store=a-minha-loja"

```

4. Códigos de estado

5. Assistente de voz (KambaChat Voz)

Leia as chamadas da sua assistente de voz (resumo, nota, contacto e transcrição) com a mesma chave af_.... Só leitura.

GET /api/v1/voz/chamadas

As chamadas, das mais recentes para as mais antigas. A resposta traz proximo: passe-o em cursor para a página seguinte (null no fim).

Exemplo

```bash

curl "https://kambachat.com/api/v1/voz/chamadas?desde=2026-10-01T00:00:00Z&limite=20" \

-H "Authorization: Bearer af_xxxxxxxx..."

```

Resposta (200)

```json

{

"chamadas": [

{ "id": "cm...", "canal": "telefone", "lingua": "pt-AO", "inicio": "2026-10-21T09:12:03.000Z", "segundos": 84,

"resumo": "Cliente quis saber o preço da limpeza e marcou para sexta.", "nota": 5, "resolvida": true,

"sentimento": "positivo", "contacto": { "nome": "Ana", "telefone": "923000000" }, "quemLigou": "244923000000" }

],

"proximo": "cm..."

}

```

GET /api/v1/voz/chamadas/{id} — uma chamada, sempre com a transcrição.

Ações da assistente (o seu sistema)

Em Painel → Assistente de voz → Avançado → Ações da assistente define o que a assistente pode consultar no seu sistema a meio da chamada. Cada consulta é um POST JSON para o seu endereço https, assinado com HMAC-SHA256 do corpo no cabeçalho X-KambaChat-Assinatura: sha256=<hex> (o mesmo segredo do webhook). Responda em até 8 s com JSON ou texto curto: a assistente diz ao cliente o que vier na resposta.

```json

{ "evento": "acao", "acao": "ver_encomenda", "argumentos": { "numero": "A-1043" },

"chamada": { "id": "cm...", "canal": "telefone", "quemLigou": "244923000000" } }

```