Documentacao da API

API REST para integracao com o Agente Gestor - Sistema de roteamento inteligente de WhatsApp.

Visao Geral

O Agente Gestor permite que voce conecte multiplos sistemas a um unico numero de WhatsApp. Cada sistema recebe mensagens via webhook e pode enviar respostas e mensagens proativas.

Fluxo de Integracao

1. Registre seu sistema (via admin ou API)
2. Implemente o webhook para receber mensagens
3. Cadastre usuarios via API
4. Comece a atender!

Autenticacao

Todas as requisicoes devem incluir o header X-System-Secret com o secret do seu sistema.

curl -X POST https://agenter.assistent.top/api/systems/register-users \
  -H "Content-Type: application/json" \
  -H "X-System-Secret: seu-secret-aqui" \
  -d '{"system_slug": "meu-sistema", "users": [...]}'

Codigos de Erro

Registrar Usuarios

Registra usuarios em massa no seu sistema. Idempotente - pode ser chamado multiplas vezes.

{
  "system_slug": "meu-sistema",
  "users": [
    {
      "phone": "5591999999999",
      "name": "Joao Silva"
    },
    {
      "phone": "5591888888888",
      "name": "Maria Santos"
    }
  ]
}

{
  "success": true,
  "total": 2,
  "registered": 2,
  "already_registered": 0,
  "failed": 0,
  "details": [
    {"phone": "5591999999999", "status": "registered"},
    {"phone": "5591888888888", "status": "registered"}
  ]
}

Enviar Mensagem Proativa

Envia uma mensagem para um usuario via WhatsApp. Cria ou reatribui sessao automaticamente.

{
  "system_slug": "meu-sistema",
  "phone": "5591999999999",
  "message": "Ola! Sua consulta foi agendada para amanha.",
  "force_session": false  // opcional: toma sessao de outro sistema
}

{
  "success": true,
  "message_id": "msg_abc123",
  "session_created": true
}

Receber Mensagens (Webhook)

Quando um usuario envia mensagem, o Agente Gestor encaminha para o webhook do seu sistema.

Payload Recebido

{
  "user": {
    "id": "uuid-do-usuario",
    "phone": "5591999999999",
    "name": "Joao Silva"
  },
  "message": {
    "type": "text",
    "content": "Ola, preciso de ajuda",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "session": {
    "id": "uuid-da-sessao",
    "token": "token-unico",
    "started_at": "2024-01-15T10:25:00Z",
    "context": {}
  },
  "application": {
    "id": "uuid-do-app",
    "slug": "meu-sistema"
  }
}

Resposta Esperada

{
  "response": {
    "type": "text",
    "content": "Ola! Como posso ajudar?"
  },
  "session_action": "continue"  // ou "end_session"
}

Validar Assinatura HMAC

Todas as requisicoes de webhook incluem uma assinatura HMAC-SHA256 para validacao.

Header de Assinatura

X-Router-Signature: sha256=abc123...

Validacao em Python

import hmac
import hashlib
import json

def validate_signature(payload: dict, signature: str, secret: str) -> bool:
    """Valida assinatura HMAC do webhook"""
    expected = hmac.new(
        secret.encode(),
        json.dumps(payload, separators=(',', ':')).encode(),
        hashlib.sha256
    ).hexdigest()

    return signature == f"sha256={expected}"

Relatorio de Saude

Retorna status de todos os sistemas conectados.

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "systems": [
    {
      "slug": "autopecas-rag",
      "name": "AutoPecas RAG",
      "health": "HEALTHY",
      "response_time_ms": 145,
      "user_count": 1250,
      "usage_24h": 89
    }
  ]
}

Status Rapido

Retorna apenas o status resumido dos sistemas.

{
  "total": 5,
  "healthy": 4,
  "unhealthy": 1,
  "systems": {
    "autopecas-rag": "HEALTHY",
    "geragentes": "HEALTHY",
    "dedireito": "DOWN"
  }
}