API

# API KambaChat — para programadores

Esta API permite que sistemas externos (o seu site, app ou ERP) criem encomendas automaticamente na sua loja KambaChat. As encomendas entram no painel e seguem o fluxo normal: confirmar, preparar, entregar (motoboy).

> Disponibilidade (GEO) — As lojas são exclusivas de Angola. Esta API cria encomendas na sua loja online, por isso aplica-se a lojistas de Angola. Utilizadores internacionais: o KambaChat foca-se em automação de WhatsApp, Facebook e Instagram com IA — a loja e a API de encomendas 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 uma encomenda

POST /api/webhooks/orders

Cria uma encomenda na sua loja (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": "ana@exemplo.com",

"address": "Kilamba, Luanda",

"channel": "WHATSAPP",

"notes": "Entregar à tarde",

"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 loja. 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 loja (nome, produtos ativos, config da IA) pelo *slug* da loja. Não precisa de chave (é público).

```bash

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

```

4. Códigos de estado