Guia de Uso - APIs `/sales-manager`

Base URL: https://csuite.internut.com.br/sales-manager

Documentação Swagger: https://csuite.internut.com.br/sales-manager/docs

📋 Índice

Visão Geral
Manager API
4C Lite Decision API
Exemplos Práticos
Troubleshooting

1. Visão Geral

O CSuite Sales Manager é um Gerente Virtual de Vendas B2B que prioriza e gerencia tasks para o time de vendas B2B.

Objetivos

Priorização Diária: Lista diária de revendas para contato por vendedor
4C Lite: Decisões simplificadas (Cliente, Oferta, Jeito, Hora)
Gestão de Tasks: Marcação de tasks como concluídas
Integração com Radar: Usa features RFR (Recency, Frequency, Revenue) do Context Radar

Contexto de Negócio

Time: 6 vendedores (inside sales / telemarketing B2B)
Carteira: ~1.500 revendas (250 por vendedor)
Canal: Revenda (não venda direta)
Foco: Priorização diária de revendas para contato

Arquitetura

O app é composto por 2 serviços principais:

Manager API - Gestão de tasks e resumos
Decision API - Decisões 4C Lite (oferta, canal, mensagem, horário)

Schemas e Tabelas

Schema csuite:
- core_sellers - Vendedores
- core_revendas - Revendas (carteira)
- core_orders - Pedidos por revenda (via core.core_orders)
- core_interactions - Contatos (via core.core_interactions)

Schema context_radar:
- features_revenda_rfr - Features calculadas (recency, frequência, receita, risco)
- tasks_seller_day - Lista diária de tasks por vendedor

Procedure:
- context_radar.sp_refresh_revenda_radar(IN p_ref_date DATE) - Recalcula features e tasks

2. Manager API

Base Path: /manager, /seller, /tasks

2.1 Resumo de Tasks do Dia

Endpoint: GET /manager/today

Descrição: Retorna resumo consolidado de tasks do dia para todos os vendedores.

Parâmetros de Query:
- ref_date (date, opcional) - Data de referência (padrão: hoje, formato: YYYY-MM-DD)

Exemplo:

# Resumo de hoje
curl "https://csuite.internut.com.br/sales-manager/manager/today"

# Resumo de data específica
curl "https://csuite.internut.com.br/sales-manager/manager/today?ref_date=2024-12-01"

Resposta:

{
  "ref_date": "2024-12-01",
  "total_tasks": 150,
  "por_status": {
    "pendente": 100,
    "concluida": 50
  },
  "por_seller": {
    "1 - João": 25,
    "2 - Maria": 30,
    "3 - Pedro": 20,
    "4 - Ana": 25,
    "5 - Carlos": 30,
    "6 - Julia": 20
  }
}

Campos da Resposta:
- ref_date: Data de referência
- total_tasks: Total de tasks do dia
- por_status: Distribuição por status (pendente, concluida)
- por_seller: Distribuição por vendedor (formato: {seller_id} - {nome})

Validação Policy Engine:
- Endpoint valida via Policy Engine (csuite-sales-manager.generate_daily_tasks)
- Se outcome != ALLOW e outcome != RECOMMEND, retorna erro 409

Erros:
- 400: Data inválida
- 409: Não autorizado pelo Policy Engine
- 500: Erro ao buscar dados do banco

2.2 Tasks de um Vendedor

Endpoint: GET /seller/{seller_id}/today

Descrição: Retorna lista de tasks de um vendedor específico para o dia, ordenadas por prioridade.

Parâmetros de Path:
- seller_id (int, obrigatório) - ID do vendedor

Parâmetros de Query:
- ref_date (date, opcional) - Data de referência (padrão: hoje, formato: YYYY-MM-DD)

Exemplo:

# Tasks do vendedor 1 para hoje
curl "https://csuite.internut.com.br/sales-manager/seller/1/today"

# Tasks do vendedor 1 para data específica
curl "https://csuite.internut.com.br/sales-manager/seller/1/today?ref_date=2024-12-01"

Resposta:

[
  {
    "task_id": 1,
    "ref_date": "2024-12-01",
    "seller_id": 1,
    "revenda_id": 100,
    "revenda_nome": "Revenda ABC",
    "cidade": "São Paulo",
    "estado": "SP",
    "prioridade": "alta",
    "tipo_acao": "contato",
    "motivo": "Sem pedido há 30 dias",
    "status": "pendente",
    "decision": {
      "offer": {
        "sku": "SX900S-5",
        "reason": "segmento=jeans; receita_90d=5000"
      },
      "channel": "whatsapp",
      "tone": "tecnico_direto",
      "message": "Olá Revenda ABC de São Paulo...",
      "send_at": null
    }
  },
  {
    "task_id": 2,
    "ref_date": "2024-12-01",
    "seller_id": 1,
    "revenda_id": 101,
    "revenda_nome": "Revenda XYZ",
    "cidade": "Rio de Janeiro",
    "estado": "RJ",
    "prioridade": "media",
    "tipo_acao": "followup",
    "motivo": "Pedido pendente há 7 dias",
    "status": "pendente",
    "decision": null
  }
]

Campos da Resposta:
- task_id: ID da task
- ref_date: Data de referência
- seller_id: ID do vendedor
- revenda_id: ID da revenda
- revenda_nome: Nome da revenda
- cidade: Cidade da revenda
- estado: Estado da revenda
- prioridade: Prioridade (alta, media, baixa)
- tipo_acao: Tipo de ação (contato, followup, renegociacao, etc.)
- motivo: Motivo da task
- status: Status (pendente, concluida)
- decision: Decisão 4C Lite (se disponível, pode ser null)

Ordenação:
- Tasks são ordenadas por prioridade (alta → média → baixa)
- Em caso de empate, ordena por nome da revenda

Erros:
- 404: Vendedor não encontrado
- 400: Data inválida
- 500: Erro ao buscar tasks

2.3 Completar Task

Endpoint: POST /tasks/{task_id}/complete

Descrição: Marca uma task como concluída.

Parâmetros de Path:
- task_id (int, obrigatório) - ID da task

Exemplo:

curl -X POST "https://csuite.internut.com.br/sales-manager/tasks/1/complete"

Resposta:

{
  "status": "ok",
  "task_id": 1
}

Comportamento:
1. Busca a task pelo task_id
2. Atualiza status para concluida
3. Atualiza updated_at com timestamp atual
4. Atualiza métricas de negócio (se habilitado)

Métricas Atualizadas:
- tasks_completed_total: Incrementa contador de tasks completadas
- tasks_pending: Decrementa gauge de tasks pendentes

Erros:
- 404: Task não encontrada
- 500: Erro ao atualizar task

3. 4C Lite Decision API

Base Path: /4c

3.1 Gerar Decisão 4C Lite

Endpoint: POST /4c/decide

Descrição: Gera decisão completa 4C Lite (oferta, canal, mensagem, horário) para uma revenda.

Request Body:

{
  "revenda_id": 100
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/sales-manager/4c/decide" \
  -H "Content-Type: application/json" \
  -d '{
    "revenda_id": 100
  }'

Resposta:

{
  "offer": {
    "sku": "SX900S-5",
    "reason": "segmento=jeans; receita_90d=5000",
    "confidence": 0.85
  },
  "channel": "whatsapp",
  "tone": "tecnico_direto",
  "message": "Olá Revenda ABC de São Paulo. Identificamos que você tem potencial para aumentar suas vendas com o modelo SX900S-5, especialmente considerando seu segmento de jeans e receita dos últimos 90 dias de R$ 5.000,00. Gostaria de agendar uma conversa?",
  "send_at": null
}

Campos da Resposta:
- offer: Oferta recomendada
- sku: SKU recomendado
- reason: Razão da recomendação
- confidence: Confiança da recomendação (0-1, opcional)
- channel: Canal de contato recomendado (whatsapp, email, telefone)
- tone: Tom da mensagem (tecnico_direto, amigavel, formal)
- message: Mensagem personalizada gerada
- send_at: Horário sugerido para envio (opcional, pode ser null)

Lógica de Decisão:

Oferta (SKU):
Baseado no segmento da revenda
Considera receita dos últimos 90 dias
Usa regras configuradas em rules.py
Canal:
Atualmente sempre whatsapp (MVP)
Futuro: baseado em preferências e histórico
Mensagem:
Gerada automaticamente
Personalizada com nome, cidade, SKU e razão
Tom técnico e direto (MVP)
Horário:
Atualmente null (não implementado no MVP)
Futuro: baseado em histórico de resposta

Validação Policy Engine:
- Endpoint valida via Policy Engine (csuite-sales-manager.generate_daily_tasks)
- Se outcome != ALLOW e outcome != RECOMMEND, retorna erro 409

Event Sourcing:
- Se habilitado, registra evento DECISION_CREATED com payload completo

Métricas Atualizadas:
- decisions_4c_lite_total: Incrementa contador de decisões geradas

Erros:
- 400: Dados inválidos (revenda_id faltando)
- 404: Revenda não encontrada
- 409: Decisão não autorizada pelo Policy Engine
- 500: Erro ao gerar decisão

4. Exemplos Práticos

4.1 Fluxo Completo: Resumo → Tasks → Decisão → Completar

# 1. Ver resumo do dia
curl "https://csuite.internut.com.br/sales-manager/manager/today"

# 2. Ver tasks do vendedor 1
curl "https://csuite.internut.com.br/sales-manager/seller/1/today"

# 3. Gerar decisão 4C Lite para uma revenda
curl -X POST "https://csuite.internut.com.br/sales-manager/4c/decide" \
  -H "Content-Type: application/json" \
  -d '{"revenda_id": 100}'

# 4. Completar task
curl -X POST "https://csuite.internut.com.br/sales-manager/tasks/1/complete"

4.2 Verificar Tasks Pendentes por Vendedor

# Tasks pendentes do vendedor 1
curl "https://csuite.internut.com.br/sales-manager/seller/1/today" | \
  python3 -c "import sys, json; data = json.load(sys.stdin); \
  pendentes = [t for t in data if t.get('status') == 'pendente']; \
  print(f\"Tasks pendentes: {len(pendentes)}\"); \
  [print(f\"  - {t['revenda_nome']} ({t['prioridade']}): {t['motivo']}\") for t in pendentes[:10]]"

4.3 Gerar Decisões para Múltiplas Revendas

# Gerar decisões para revendas 100, 101, 102
for revenda_id in 100 101 102; do
  echo "Gerando decisão para revenda $revenda_id..."
  curl -X POST "https://csuite.internut.com.br/sales-manager/4c/decide" \
    -H "Content-Type: application/json" \
    -d "{\"revenda_id\": $revenda_id}"
  echo ""
done

4.4 Completar Múltiplas Tasks

# Completar tasks 1, 2, 3
for task_id in 1 2 3; do
  curl -X POST "https://csuite.internut.com.br/sales-manager/tasks/$task_id/complete"
  echo ""
done

4.5 Verificar Resumo por Data Específica

# Resumo de 7 dias atrás
curl "https://csuite.internut.com.br/sales-manager/manager/today?ref_date=2024-11-24"

# Resumo de amanhã (se tasks já foram geradas)
curl "https://csuite.internut.com.br/sales-manager/manager/today?ref_date=2024-12-02"

5. Troubleshooting

Erro: "Not Found" (404)

Verifique se o serviço csuite-sales-manager está rodando
Verifique se o path está correto (/sales-manager/manager/today, etc.)
Verifique se o endpoint existe na documentação OpenAPI

Erro: "Unauthorized" (401)

Verifique autenticação via csuite-auth
Faça login em /login primeiro

Erro: "Não autorizado pelo Policy Engine" (409)

Verifique se a política csuite-sales-manager.generate_daily_tasks está configurada
Verifique se o Policy Engine está acessível
Verifique logs do Policy Engine para detalhes

Erro: "Revenda não encontrada" (404)

Verifique se a revenda existe em csuite.core_revendas
Verifique se o revenda_id está correto
Verifique se há dados no banco

Erro: "Task não encontrada" (404)

Verifique se a task existe em context_radar.tasks_seller_day
Verifique se o task_id está correto
Verifique se a task pertence à data de referência correta

Tasks não aparecem

Verifique se context_radar.sp_refresh_revenda_radar() foi executada
Verifique se há tasks para a data de referência
Verifique se o vendedor tem tasks atribuídas
Verifique se o job de refresh está rodando

Decisão 4C Lite não é gerada

Verifique se a revenda existe
Verifique se há features RFR em context_radar.features_revenda_rfr
Verifique logs do serviço para erros de regras
Verifique se o Policy Engine permite a decisão

Features RFR não aparecem

Execute context_radar.sp_refresh_revenda_radar(DATE) manualmente
Verifique se há pedidos em core.core_orders para a revenda
Verifique se o job de refresh está configurado e rodando

Decision payload é null nas tasks

Verifique se o enriquecimento de tasks está habilitado
Verifique se o script enrich_tasks_with_decisions.py está rodando
Verifique logs do serviço de enriquecimento

6. Documentação Relacionada

6.1 Documentação Interna

README: csuite-sales-manager/README.md
Guia de Desenvolvimento: csuite-sales-manager/GUIDE_CSUTE_SALES_MANAGER.md
Estrutura: csuite-sales-manager/Estrutura.md

6.2 Integrações

Context Radar: Features RFR e tasks (context_radar schema)
Policy Engine: Validação de decisões (csuite-executive)
4C Decision API: Motor completo de decisões (futuro)

7. Schema do Banco

Tabelas Principais

csuite.core_sellers
- Vendedores do time
- Campos: seller_id, name, email, etc.

csuite.core_revendas
- Revendas (carteira)
- Campos: revenda_id, nome, cidade, estado, segmento, etc.

context_radar.features_revenda_rfr
- Features calculadas por revenda
- Campos: revenda_id, recency_days, freq_90d, revenue_90d, score_rfr, class_risco, class_valor

context_radar.tasks_seller_day
- Lista diária de tasks por vendedor
- Campos: task_id, ref_date, seller_id, revenda_id, prioridade, tipo_acao, motivo, status, decision_payload, created_at, updated_at

Procedure

context_radar.sp_refresh_revenda_radar(IN p_ref_date DATE)
- Recalcula features RFR
- Recria tasks do dia
- Deve ser executada diariamente (via EVENT ou job)

8. Configuração

Variáveis de Ambiente

# Database
DB_HOST=vallery.catmgckfixum.sa-east-1.rds.amazonaws.com
DB_PORT=3306
DB_USER=core
DB_PASSWORD=***
DB_NAME=csuite

# Path
ROOT_PATH=/sales-manager

# Autenticação
AUTH_ENABLED=true
AUTH_SERVICE_URL=https://csuite.internut.com.br/auth

# Policy Engine
EXECUTIVE_API_URL=http://tasks.csuite-executive_csuite-api:8000

9. Jobs e Automação

9.1 Refresh do Radar

Job: context-jobs/job_refresh_radar.py

Descrição: Executa context_radar.sp_refresh_revenda_radar() para recalcular features e tasks.

Execução Manual:

cd context-jobs
docker build -t csuite-refresh-radar .
docker run --rm \
  -e DB_HOST=seu_host \
  -e DB_USER=seu_usuario \
  -e DB_PASSWORD=sua_senha \
  csuite-refresh-radar

Execução Automática:
- Via EVENT MySQL (diário)
- Via cron job
- Via scheduler do Docker Swarm

9.2 Enriquecimento de Tasks

Script: scripts/enrich_tasks_with_decisions.py

Descrição: Enriquece tasks com decisões 4C Lite automaticamente.

Execução:
- Via systemd timer (enrich_tasks.timer)
- Via cron job
- Via scheduler

10. Próximos Passos

Integração com 4C completo (não apenas Lite)
Dashboard web para visualização
Notificações para vendedores
Histórico de interações e feedback
A/B testing de mensagens
Métricas de performance por vendedor

11. Documentação OpenAPI

Swagger UI: https://csuite.internut.com.br/sales-manager/docs

OpenAPI JSON: https://csuite.internut.com.br/sales-manager/openapi.json

ReDoc: https://csuite.internut.com.br/sales-manager/redoc

Última atualização: 2024-12-20
Versão: 0.1.0

Guia de Uso - APIs /sales-manager

📋 Índice

1. Visão Geral

Objetivos

Contexto de Negócio

Arquitetura

Schemas e Tabelas

2. Manager API

2.1 Resumo de Tasks do Dia

2.2 Tasks de um Vendedor

2.3 Completar Task

3. 4C Lite Decision API

3.1 Gerar Decisão 4C Lite

4. Exemplos Práticos

4.1 Fluxo Completo: Resumo → Tasks → Decisão → Completar

4.2 Verificar Tasks Pendentes por Vendedor

4.3 Gerar Decisões para Múltiplas Revendas

4.4 Completar Múltiplas Tasks

4.5 Verificar Resumo por Data Específica

5. Troubleshooting

Erro: "Not Found" (404)

Erro: "Unauthorized" (401)

Erro: "Não autorizado pelo Policy Engine" (409)

Erro: "Revenda não encontrada" (404)

Erro: "Task não encontrada" (404)

Tasks não aparecem

Decisão 4C Lite não é gerada

Features RFR não aparecem

Decision payload é null nas tasks

6. Documentação Relacionada

6.1 Documentação Interna

6.2 Integrações

7. Schema do Banco

Tabelas Principais

Procedure

8. Configuração

Variáveis de Ambiente

9. Jobs e Automação

9.1 Refresh do Radar

9.2 Enriquecimento de Tasks

10. Próximos Passos

11. Documentação OpenAPI

🔊 Text-to-Speech

Guia de Uso - APIs `/sales-manager`