💳 CSuite Credit Agent — Manual de Uso

Versão: 1.0.0
Última Atualização: 2026-01-21
Status: ✅ Operacional em Produção

📋 Índice

Visão Geral
URLs de Acesso
Autenticação
Endpoints da API
Decisões e Outcomes
Regras de Política
Exemplos de Uso
Integração com Outros Agentes
Troubleshooting

🎯 Visão Geral

O CSuite Credit Agent é um agente de crédito e aprovação de pedidos que avalia risco, limite e políticas comerciais para aprovar ou bloquear pedidos de forma automática e governada.

Funcionalidades Principais

✅ Avaliação de Crédito: Analisa perfil do cliente, limite disponível e histórico de inadimplência
✅ Decisão Automática: Retorna ALLOW, RECOMMEND, ESCALATE ou DENY
✅ Condições de Aprovação: Sugere entrada mínima e prazo máximo quando necessário
✅ Integração com Policy Engine: Todas as decisões são governadas por políticas centralizadas
✅ Auditabilidade: Todas as decisões são gravadas com reason_codes explicáveis

🔗 URLs de Acesso

Recurso	URL
API Base	https://csuite.internut.com.br/credit
Swagger/Docs	https://csuite.internut.com.br/credit/docs
Health Check	https://csuite.internut.com.br/credit/health
OpenAPI JSON	https://csuite.internut.com.br/credit/openapi.json

🔐 Autenticação

O Credit Agent utiliza autenticação via csuite-auth-external. Você pode autenticar de duas formas:

1. Bearer Token

curl -X POST https://csuite.internut.com.br/credit/v1/evaluate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}'

Se você estiver logado no sistema CSuite, o cookie access_token será enviado automaticamente.

📡 Endpoints da API

GET /credit/health

Health check do serviço.

Resposta:

{
  "status": "ok",
  "service": "csuite-credit-agent",
  "env": "production",
  "ts": "2026-01-21T10:00:00.000000Z"
}

GET /credit/

Informações sobre o serviço e endpoints disponíveis.

Resposta:

{
  "service": "CSuite Credit Agent",
  "description": "Order Approval & Credit Agent",
  "version": "1.0.0",
  "status": "running",
  "endpoints": {
    "health": "/health",
    "docs": "/docs",
    "v1/request": "POST /v1/request",
    "v1/evaluate": "POST /v1/evaluate",
    "v1/decision": "GET /v1/decision/{order_id}",
    "v1/customer": "GET /v1/customer/{customer_id}",
    "v1/decisions/today": "GET /v1/decisions/today",
    "v1/risky-customers": "GET /v1/risky-customers"
  }
}

POST /credit/v1/request

Armazena um snapshot do pedido para auditoria (sem avaliar crédito).

Request Body:

{
  "customer": {
    "customer_id": 12345,
    "risk_grade": "B",
    "risk_score": 75,
    "credit_limit": 100000.00,
    "credit_used": 45000.00,
    "days_past_due_max": 0,
    "is_blocked": false,
    "is_new_customer": false
  },
  "order": {
    "order_id": "PED-2026-001",
    "order_total": 25000.00
  },
  "payment": {
    "terms_days": 30,
    "installments": 1
  },
  "pricing": {
    "status": "OK",
    "margin_ok": true,
    "policy_refs": ["PRICING-001"]
  },
  "created_by": "seller@empresa.com"
}

Resposta:

{
  "order_id": "PED-2026-001",
  "customer_id": "12345",
  "stored": true,
  "stored_at": "2026-01-21T10:00:00.000000Z"
}

POST /credit/v1/evaluate

Principal endpoint. Avalia o crédito do pedido e retorna a decisão.

Request Body:

{
  "payload": {
    "customer": {
      "customer_id": 12345,
      "risk_grade": "B",
      "risk_score": 75,
      "credit_limit": 100000.00,
      "credit_used": 45000.00,
      "days_past_due_max": 0,
      "is_blocked": false,
      "is_new_customer": false
    },
    "order": {
      "order_id": "PED-2026-001",
      "order_total": 25000.00
    },
    "payment": {
      "terms_days": 30,
      "installments": 1
    },
    "pricing": {
      "status": "OK",
      "margin_ok": true,
      "policy_refs": ["PRICING-001"]
    }
  }
}

Resposta (ALLOW):

{
  "order_id": "PED-2026-001",
  "customer_id": "12345",
  "outcome": "ALLOW",
  "approved_amount": 25000.0,
  "conditions": null,
  "reasons": ["OK"],
  "risk_grade": "B",
  "risk_score": 75,
  "policy_decision_id": "credit.approve_order",
  "recorded": true,
  "recorded_at": "2026-01-21T10:00:00.000000Z"
}

Resposta (RECOMMEND com condições):

{
  "order_id": "PED-2026-002",
  "customer_id": "99999",
  "outcome": "RECOMMEND",
  "approved_amount": 10000.0,
  "conditions": {
    "down_payment_pct": 0.50,
    "max_terms_days": 30
  },
  "reasons": ["NEW_CUSTOMER"],
  "risk_grade": "NA",
  "risk_score": 0,
  "policy_decision_id": "credit.approve_order",
  "recorded": true
}

GET /credit/v1/decision/{order_id}

Consulta a decisão de crédito de um pedido específico.

Resposta:

{
  "decision_id": 1,
  "order_id": "PED-2026-001",
  "customer_id": 12345,
  "outcome": "ALLOW",
  "approved_amount": 25000.0,
  "conditions_json": null,
  "reasons_json": {"reasons": ["OK"]},
  "risk_grade": "B",
  "risk_score": 75,
  "created_at": "2026-01-21T10:00:00"
}

GET /credit/v1/customer/{customer_id}

Retorna o perfil de crédito de um cliente.

Resposta:

{
  "customer_id": 12345,
  "risk_grade": "B",
  "risk_score": 75,
  "credit_limit": 100000.00,
  "credit_used": 45000.00,
  "credit_available": 55000.00,
  "days_past_due_max": 0,
  "is_blocked": false,
  "is_new_customer": false,
  "last_review_at": "2026-01-15T14:30:00"
}

GET /credit/v1/decisions/today

Lista todas as decisões de crédito do dia.

Resposta:

{
  "decisions": [
    {
      "decision_id": 5,
      "order_id": "PED-2026-005",
      "customer_id": 66666,
      "outcome": "ESCALATE",
      "reasons_json": {"reasons": ["OVER_LIMIT"]},
      "created_at": "2026-01-21T10:24:20"
    }
  ],
  "count": 5
}

GET /credit/v1/risky-customers

Lista clientes de alto risco (grades D/E ou com inadimplência).

🎯 Decisões e Outcomes

Outcome	Descrição	Ação Recomendada
ALLOW	Pedido aprovado	Liberar pedido normalmente
RECOMMEND	Aprovado com condições	Exigir entrada ou prazo menor
ESCALATE	Requer aprovação humana	Abrir exceção para análise
DENY	Bloqueado	Rejeitar pedido

Cores de Status

🟢 ALLOW - Verde
🟡 RECOMMEND - Amarelo
🟠 ESCALATE - Laranja
🔴 DENY - Vermelho

📜 Regras de Política

O Credit Agent aplica as seguintes regras em ordem de prioridade:

Hard Blocks (DENY)

Regra	Condição	Motivo
CREDIT_BLOCK_CUSTOMER	`is_blocked = true`	Cliente bloqueado
CREDIT_DENY_HIGH_PAST_DUE	`days_past_due >= 30`	Inadimplência grave

Soft Blocks (ESCALATE)

Regra	Condição	Motivo
CREDIT_BLOCK_PRICING_NOT_OK	`pricing.status != OK`	Pricing não aprovado
CREDIT_ESCALATE_PAST_DUE	`15 <= days_past_due < 30`	Inadimplência moderada
CREDIT_ESCALATE_OVER_LIMIT	`order_total > available_limit`	Pedido acima do limite

Regra	Condição	Condições Sugeridas
CREDIT_RECOMMEND_NEW_CUSTOMER	`is_new_customer = true`	Entrada 50%, Prazo 30d
CREDIT_RECOMMEND_RISKY_TERMS	`risk_grade in (D,E) AND terms > 30d`	Entrada 40%, Prazo 30d

Default (ALLOW)

Regra	Condição	Resultado
CREDIT_ALLOW_DEFAULT	Nenhuma regra anterior aplicada	Aprovado

💻 Exemplos de Uso

Exemplo 1: Cliente Normal (ALLOW)

curl -X POST https://csuite.internut.com.br/credit/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "customer": {
        "customer_id": 12345,
        "risk_grade": "B",
        "credit_limit": 100000,
        "credit_used": 40000,
        "days_past_due_max": 0,
        "is_blocked": false,
        "is_new_customer": false
      },
      "order": {"order_id": "TEST-001", "order_total": 20000},
      "payment": {"terms_days": 30},
      "pricing": {"status": "OK", "margin_ok": true}
    }
  }'

Resultado: ALLOW ✅

curl -X POST https://csuite.internut.com.br/credit/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "customer": {
        "customer_id": 99999,
        "risk_grade": "NA",
        "credit_limit": 50000,
        "credit_used": 0,
        "days_past_due_max": 0,
        "is_blocked": false,
        "is_new_customer": true
      },
      "order": {"order_id": "TEST-002", "order_total": 10000},
      "payment": {"terms_days": 60},
      "pricing": {"status": "OK", "margin_ok": true}
    }
  }'

Resultado: RECOMMEND com condições:
- Entrada mínima: 50%
- Prazo máximo: 30 dias

Exemplo 3: Cliente Bloqueado (DENY)

curl -X POST https://csuite.internut.com.br/credit/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "customer": {
        "customer_id": 88888,
        "is_blocked": true
      },
      "order": {"order_id": "TEST-003", "order_total": 1000},
      "payment": {"terms_days": 30},
      "pricing": {"status": "OK", "margin_ok": true}
    }
  }'

Resultado: DENY ❌ (CUSTOMER_BLOCKED)

Exemplo 4: Pedido Acima do Limite (ESCALATE)

curl -X POST https://csuite.internut.com.br/credit/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "customer": {
        "customer_id": 77777,
        "credit_limit": 50000,
        "credit_used": 45000,
        "days_past_due_max": 0,
        "is_blocked": false,
        "is_new_customer": false
      },
      "order": {"order_id": "TEST-004", "order_total": 10000},
      "payment": {"terms_days": 30},
      "pricing": {"status": "OK", "margin_ok": true}
    }
  }'

Resultado: ESCALATE 🟠 (OVER_LIMIT)
- Limite disponível: R$ 5.000
- Pedido: R$ 10.000
- Requer aprovação humana

🔗 Integração com Outros Agentes

Fluxo Completo: Leads-Agent → Pricing Agent → Credit Agent

┌─────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ Leads-Agent │────▶│  Pricing Agent  │────▶│  Credit Agent    │
│   (Lead)    │     │ (Cálculo Preço) │     │ (Aprovação)      │
└─────────────┘     └─────────────────┘     └──────────────────┘
                            │                        │
                            ▼                        ▼
                    pricing_result ────────▶  credit_decision
                    {status: "OK",             {outcome: "ALLOW",
                     margin_ok: true}           approved_amount: X}

Payload do Pricing Agent

O Credit Agent espera receber o resultado do Pricing Agent no campo pricing:

{
  "pricing": {
    "status": "OK",           // Obrigatório: OK, ERROR, PENDING
    "margin_ok": true,        // Opcional: margem está OK?
    "policy_refs": ["PRC-001"] // Opcional: referências de políticas aplicadas
  }
}

🔧 Troubleshooting

Erro: "missing_auth"

Causa: Token de autenticação não fornecido ou inválido.

Solução:
1. Verifique se o header Authorization: Bearer TOKEN está presente
2. Verifique se o token não expirou
3. Em desenvolvimento, o bypass de auth está habilitado

Erro: "policy_engine_error"

Causa: O Policy Engine não conseguiu avaliar a decisão.

Solução:
- O Credit Agent usa fallback local automaticamente
- Verifique se o Policy Engine está operacional
- A decisão credit.approve_order precisa estar mesclada no Policy Engine

Erro: "db_error"

Causa: Erro ao acessar o banco de dados.

Solução:
1. Verifique a conectividade com o MySQL
2. Verifique se as tabelas foram criadas corretamente
3. Revise os logs do serviço: docker service logs csuite-credit_csuite-credit-agent

📚 Referências

Swagger/OpenAPI: https://csuite.internut.com.br/credit/docs
Código Fonte: /c-suite/agents/credit/
Schema SQL: /c-suite/agents/credit/sql/
Políticas: /c-suite/agents/credit/policies/credit.v1.yaml
Checklist: /development/credit-agent/CHECKLIST_CREDIT_AGENT.md

Dúvidas? Entre em contato com a equipe de desenvolvimento ou consulte a documentação do Policy Engine.

💳 CSuite Credit Agent — Manual de Uso

📋 Índice

🎯 Visão Geral

Funcionalidades Principais

🔗 URLs de Acesso

🔐 Autenticação

1. Bearer Token

2. Cookie (access_token)

📡 Endpoints da API

GET /credit/health

GET /credit/

POST /credit/v1/request

POST /credit/v1/evaluate

GET /credit/v1/decision/{order_id}

GET /credit/v1/customer/{customer_id}

GET /credit/v1/decisions/today

GET /credit/v1/risky-customers

🎯 Decisões e Outcomes

Cores de Status

📜 Regras de Política

Hard Blocks (DENY)

Soft Blocks (ESCALATE)

Condições (RECOMMEND)

Default (ALLOW)

💻 Exemplos de Uso

Exemplo 1: Cliente Normal (ALLOW)

Exemplo 2: Cliente Novo (RECOMMEND)

Exemplo 3: Cliente Bloqueado (DENY)

Exemplo 4: Pedido Acima do Limite (ESCALATE)

🔗 Integração com Outros Agentes

Fluxo Completo: Leads-Agent → Pricing Agent → Credit Agent

Payload do Pricing Agent

🔧 Troubleshooting

Erro: "missing_auth"

Erro: "policy_engine_error"

Erro: "db_error"

📚 Referências

🔊 Text-to-Speech