🏠 Início / 📚 Documentação / Guias de Uso / Guia Uso Apis Sales Decision

Guia Uso Apis Sales Decision

Guia de Uso - APIs /sales-decision

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

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

📋 Índice

  1. Visão Geral
  2. 4C Lite Decision API
  3. Exemplos Práticos
  4. Troubleshooting

1. Visão Geral

O CSuite Sales Decision é uma API especializada em gerar decisões 4C Lite (Cliente, Oferta, Jeito, Hora) para revendas no contexto de vendas B2B.

Objetivos

Diferença entre Sales Decision e Sales Manager

Integrações

2. 4C Lite Decision API

Base Path: /4c

2.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-decision/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, tudo bem?\n\nVimos que suas vendas têm potencial para aumentar com o modelo SX900S-5. Quero te mostrar uma condição especial para repor ou atualizar seu mix com essa máquina. Podemos falar hoje sobre isso?",
  "send_at": null
}

Campos da Resposta:
- offer: Oferta recomendada
- sku: SKU recomendado
- reason: Razão da recomendação (segmento, receita, etc.)
- 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:

  1. Oferta (SKU):
  2. Baseado no segmento da revenda (jeans, malharia, lingerie)
  3. Mapeamento de segmento para SKU:
    • jeans → SX900S-5
    • malharia → OVL-4F
    • lingerie → AUT-BORD-900
    • Outros → SX900S-5 (padrão)

  4. Considera receita dos últimos 90 dias (se disponível)

  5. Canal:

  6. Atualmente sempre whatsapp (MVP)

  7. Futuro: baseado em preferências e histórico de interações

  8. Mensagem:

  9. Gerada automaticamente
  10. Personalizada com:
    • Nome da revenda
    • Cidade
    • SKU recomendado

  11. Tom técnico e direto (MVP)

  12. Horário:

  13. Atualmente null (não implementado no MVP)
  14. Futuro: baseado em histórico de resposta e preferências

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
- Evento inclui: revenda_id, offer, channel, tone, send_at
- Metadata inclui: dados da revenda e features RFR

Métricas Atualizadas:
- decisions_4c_lite_total: Incrementa contador de decisões geradas
- Labels: revenda_id, channel

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

Dados Utilizados:

  1. Revenda (csuite.core_revendas):

  2. revenda_id, nome, cidade, estado, segmento

  3. Features RFR (context_radar.features_revenda_rfr):

  4. recency_days: Dias desde último pedido
  5. freq_90d: Frequência de pedidos nos últimos 90 dias
  6. revenue_90d: Receita dos últimos 90 dias
  7. score_rfr: Score RFR consolidado
  8. class_risco: Classificação de risco
  9. class_valor: Classificação de valor

3. Exemplos Práticos

3.1 Decisão Básica

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

3.2 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-decision/4c/decide" \
    -H "Content-Type: application/json" \
    -d "{\"revenda_id\": $revenda_id}"
  echo ""
done

3.3 Processar Lista de Revendas

# Ler lista de revendas de um arquivo e gerar decisões
cat revendas.txt | while read revenda_id; do
  curl -X POST "https://csuite.internut.com.br/sales-decision/4c/decide" \
    -H "Content-Type: application/json" \
    -d "{\"revenda_id\": $revenda_id}" \
    -o "decisao_${revenda_id}.json"
  echo "Decisão para revenda $revenda_id salva em decisao_${revenda_id}.json"
done

3.4 Extrair Apenas SKU Recomendado

curl -X POST "https://csuite.internut.com.br/sales-decision/4c/decide" \
  -H "Content-Type: application/json" \
  -d '{"revenda_id": 100}' | \
  python3 -c "import sys, json; data = json.load(sys.stdin); print(data['offer']['sku'])"

3.5 Extrair Mensagem Completa

curl -X POST "https://csuite.internut.com.br/sales-decision/4c/decide" \
  -H "Content-Type: application/json" \
  -d '{"revenda_id": 100}' | \
  python3 -c "import sys, json; data = json.load(sys.stdin); print(data['message'])"

3.6 Verificar Canal Recomendado

curl -X POST "https://csuite.internut.com.br/sales-decision/4c/decide" \
  -H "Content-Type: application/json" \
  -d '{"revenda_id": 100}' | \
  python3 -c "import sys, json; data = json.load(sys.stdin); print(f\"Canal: {data['channel']}, Tom: {data['tone']}\")"

4. Troubleshooting

Erro: "Not Found" (404)

Erro: "Unauthorized" (401)

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

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

Decisão sempre retorna mesmo SKU

Features RFR não aparecem

Mensagem não é gerada

Canal sempre "whatsapp"

Horário sempre null

5. Documentação Relacionada

5.1 Documentação Interna

5.2 Integrações

6. Schema do Banco

Tabelas Utilizadas

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

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

Mapeamento de Segmentos

Segmentos Suportados:
- jeans → SKU: SX900S-5
- malharia → SKU: OVL-4F
- lingerie → SKU: AUT-BORD-900
- Outros → SKU: SX900S-5 (padrão)

7. 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-decision

# 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

8. Lógica de Decisão (Detalhada)

8.1 Escolha de Oferta

Algoritmo:
1. Obtém segmento da revenda
2. Normaliza para lowercase
3. Busca SKU no mapeamento SEGMENTO_SKU
4. Se não encontrado, usa SKU padrão (SX900S-5)
5. Inclui receita_90d na razão (se disponível)

Exemplo:

segmento = "jeans"  # da revenda
sku = SEGMENTO_SKU.get("jeans", "SX900S-5")  # retorna "SX900S-5"
reason = f"segmento=jeans; receita_90d=5000"

8.2 Sugestão de Canal

Algoritmo (MVP):
- Sempre retorna "whatsapp"

Futuro:
- Analisa histórico de interações
- Considera preferências da revenda
- Considera taxa de resposta por canal

8.3 Geração de Mensagem

Template:

Olá {nome} de {cidade}, tudo bem?

Vimos que suas vendas têm potencial para aumentar com o modelo {sku}. 
Quero te mostrar uma condição especial para repor ou atualizar seu mix com essa máquina. 
Podemos falar hoje sobre isso?

Personalização:
- {nome}: Nome da revenda
- {cidade}: Cidade da revenda
- {sku}: SKU recomendado

8.4 Sugestão de Horário

Algoritmo (MVP):
- Retorna null (não implementado)

Futuro:
- Analisa histórico de respostas
- Considera timezone da revenda
- Considera padrões de atividade

9. Próximos Passos

  1. Integração com 4C completo (não apenas Lite)
  2. Análise de histórico para melhorar recomendações
  3. Múltiplos canais (email, telefone, visita)
  4. Mensagens mais sofisticadas (templates variados, A/B testing)
  5. Horário inteligente baseado em histórico
  6. Confiança calculada baseada em features RFR
  7. Métricas de performance das decisões

10. Documentação OpenAPI

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

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

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

11. Comparação com Outras APIs

Sales Decision vs Sales Manager

Aspecto Sales Decision Sales Manager
Foco Apenas decisões 4C Lite Gestão completa de tasks
Endpoints /4c/decide /manager/today, /seller/{id}/today, /tasks/{id}/complete, /4c/decide
Uso Microserviço especializado App completo de gestão
Path /sales-decision /sales-manager

Sales Decision vs 4C Decision API

Aspecto Sales Decision (4C Lite) 4C Decision API
Complexidade Simplificada Completa
Modelos ML Não usa Usa modelos ML
Features Features RFR básicas Features completas do Feature Service
Contexto Revendas B2B Clientes gerais
Uso Vendas B2B Decisões comerciais gerais

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

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir