CommissionsPilot - Guia de Integração API

Documentação Oficial para Fornecedores

Versão: 3.0 Data: Novembro 2025 Sistema: CommissionsPilot - Gestão de Comissões UNI Responsável: R. Salles - CTO da Somos UNI

---

📋 Índice

1. Visão Geral do Sistema
2. Referência Rápida
3. Dicionário de Negócio
4. Arquitetura da Integração
5. Modelos de Dados
6. Endpoints da API
7. Exemplos de Uso
8. Tratamento de Erros
9. Considerações de Segurança

---

Visão Geral do Sistema

O CommissionsPilot é nossa plataforma de gestão e cálculo de comissões para agentes de vendas. O sistema processa quatro tipos principais de comissões:

• Agenciamento: Comissões de vendas iniciais
• Recorrente: Comissões recorrentes baseadas no ciclo de vida do contrato
• Remuneração Variável: Comissões baseadas em indicadores de performance
• Estorno: Ajustes por cancelamentos de contratos

Fluxo de Dados

Arquitetura de Integração

---

Referência Rápida

Valores Válidos para Campos Principais

Esta seção contém uma referência rápida dos valores aceitos nos principais campos da API.

Tipos de Agente (agentRole):

• gerente_vendas, externo, consultor_rel_pj, interno, coordenador_vendas

Canais (channel):

• Externo, Interno, Externo SERVI

Tipos de Produto (productType):

• saude_unimed, sou, popvita, seguros

Tipos de Comissão (calculationType ou type):

• Agenciamento, Recorrente, Remuneracao Variavel, Estorno

Indicadores RV (rvIndicator):

• novas_vendas, faturamento_corretoras, reajuste_aplicado, captacao_pj, novas_vendas_produto, venda_servico_acessorio, captacao_contrato_existente

Tipos de Lógica Recorrente (recurrentLogicType):

• Fixo, Baseado em Sinistralidade e Tamanho do Contrato

Status:

• Active, Inactive

Campos Obrigatórios por Tipo de Cálculo

Agenciamento

• Obrigatórios: agentId, agentRole, calculationType, channel, baseValue, productType
• Opcionais importantes: numLives, firstInvoicePaid, saleDate, saleId

Recorrente

• Obrigatórios: agentId, agentRole, calculationType, channel, baseValue, productType, competency, contractMonthRecorrente
• Opcionais importantes: agentSinistrality, saleDate, saleId

Remuneração Variável

• Obrigatórios: agentId, agentRole, calculationType, channel, productType, competency, rvIndicator
• Opcionais importantes: rvTargetValue, rvActualValue, rvAchievementPercent, baseValue

Estorno

• Obrigatórios: agentId, agentRole, calculationType, channel, productType, originalCommissionPaid, cancellationContractMonth
• Opcionais importantes: baseValue (pode ser 0), saleDate, saleId

---

Dicionário de Negócio

Termos Principais

Termo	Definição	Exemplo
Agente	Profissional de vendas que recebe comissões	Gerente de Vendas, Consultor Externo
Competência	Mês de referência para cálculo de comissão recorrente	"2025-01"
Agenciamento	Comissão paga na venda inicial de um contrato	10% sobre o valor da primeira fatura
Recorrente	Comissão paga mensalmente durante a vigência do contrato	5% por 24 meses
Remuneração Variável (RV)	Comissão baseada em metas e indicadores	Atingimento de 120% da meta
Estorno	Devolução proporcional de comissão por cancelamento	100% no 1º mês, 90% no 2º mês
Vidas	Quantidade de beneficiários no contrato	Contrato com 10 vidas
Sinistralidade	Percentual de sinistros em relação ao faturamento	75% de sinistralidade
Canal	Origem da venda	Externo, Interno, Externo SERVI
UNI	Nossa empresa - quando retemos parte da comissão	Split 70% agente / 30% UNI

Tipos de Agentes

Código	Nome	Descrição
gerente_vendas	Gerente de Vendas	Gestor de equipe de vendas
externo	Externo	Corretor externo à organização
consultor_rel_pj	Consultor de Relacionamento PJ	Atende clientes Pessoa Jurídica
interno	Interno	Vendedor da equipe interna
coordenador_vendas	Coordenador de Vendas	Coordena operações de vendas

Importante: Nas requisições à API, sempre utilize os códigos (coluna Código) e não os nomes descritivos.

Canais de Venda

Canal	Descrição
Externo	Venda realizada por corretor externo
Interno	Venda realizada pela equipe interna
Externo SERVI	Venda externa específica para produtos SERVI

Tipos de Produto

Código	Nome	Descrição
saude_unimed	Saúde Unimed	Planos de saúde Unimed
sou	SOU	Produto SOU
popvita	PopVita	Plano PopVita
seguros	Seguros	Produtos de seguro

Importante: Nas requisições à API, sempre utilize os códigos (coluna Código) e não os nomes descritivos.

Indicadores de Remuneração Variável

Código	Nome	Objetivo
novas_vendas	Novas Vendas	Volume de novas vendas no período
faturamento_corretoras	Faturamento Corretoras	Faturamento gerado pelas corretoras
reajuste_aplicado	Reajuste Aplicado	Percentual de reajuste aplicado
captacao_pj	Captação PJ	Captação de clientes Pessoa Jurídica
novas_vendas_produto	Novas Vendas Produto SERVI	Vendas específicas SERVI
venda_servico_acessorio	Venda Serviço Acessório	Venda de serviços acessórios
captacao_contrato_existente	Captação Contrato Existente	Captação em contratos já existentes

Importante: Nas requisições à API, sempre utilize os códigos (coluna Código) e não os nomes descritivos.

Tipos de Comissão

Código	Nome	Quando Aplicar
Agenciamento	Agenciamento	Comissão de venda inicial de contrato
Recorrente	Recorrente	Comissão mensal recorrente durante vigência
Remuneracao Variavel	Remuneração Variável	Comissão baseada em indicadores de performance
Estorno	Estorno	Devolução de comissão por cancelamento

Nota: Para o tipo "Remuneração Variável", o código usado na API é Remuneracao Variavel (sem acento e com espaço).

---

Modelos de Dados

Diagrama de Entidades

1. Agent (Agente)

Representa um agente de vendas no sistema.

interface Agent {
  id: string;                // UUID único
  name: string;              // Nome completo
  role: string;              // Papel do agente (ver Dicionário)
  startDate: string;         // Data de início (YYYY-MM-DD)
  status: string;            // "Active" | "Inactive"
}

Exemplo:

{
  "id": "agent-001",
  "name": "João Silva",
  "role": "gerente_vendas",
  "startDate": "2024-01-15",
  "status": "Active"
}

---

2. CommissionRule (Regra de Comissão)

Define as regras de cálculo de comissão.

interface CommissionRule {
  // Campos Comuns
  id: string;
  name: string;
  type: "Agenciamento" | "Recorrente" | "Remuneracao Variavel" | "Estorno";
  channels: string[];         // ["Externo", "Interno", etc.]
  agentRoles: string[];       // ["gerente_vendas", "externo", "consultor_rel_pj", etc.]
  productTypes?: string[];    // ["saude_unimed", "sou", "popvita", "seguros"]
  status: "Active" | "Inactive";
  priority?: number;          // Ordem de aplicação (maior = primeiro)
  notes?: string;

  // Campos Específicos por Tipo (ver seções abaixo)
  [key: string]: any;
}

2.1. Regra de Agenciamento

interface AgenciamentoRule extends CommissionRule {
  type: "Agenciamento";
  commissionPercentage: number;    // Percentual de comissão (ex: 10 = 10%)
  minLives?: number;               // Mínimo de vidas
  maxLives?: number;               // Máximo de vidas
  firstInvoicePaid?: boolean;      // Se requer 1ª fatura paga
}

Exemplo:

{
  "id": "rule-agenc-001",
  "name": "Agenciamento Externo Saúde 10%",
  "type": "Agenciamento",
  "channels": ["Externo"],
  "agentRoles": ["externo", "gerente_vendas"],
  "productTypes": ["saude_unimed"],
  "status": "Active",
  "priority": 10,
  "commissionPercentage": 10,
  "minLives": 1,
  "firstInvoicePaid": true
}

2.2. Regra Recorrente

interface RecorrenteRule extends CommissionRule {
  type: "Recorrente";
  startMonth: number;              // Mês inicial (1-24+)
  recurrentLogicType: string;      // "Fixo" | "Baseado em Sinistralidade e Tamanho do Contrato"

  // Se tipo = "Fixo"
  fixedPercentage?: number;        // Percentual fixo

  // Se tipo = "Baseado em Sinistralidade e Tamanho do Contrato"
  sinistralityConfig?: string;     // JSON com faixas
}

Exemplo (Fixo):

{
  "id": "rule-rec-001",
  "name": "Recorrente Mês 1-12 5%",
  "type": "Recorrente",
  "channels": ["Externo", "Interno"],
  "agentRoles": ["externo"],
  "status": "Active",
  "startMonth": 1,
  "recurrentLogicType": "Fixo",
  "fixedPercentage": 5
}

Exemplo (Sinistralidade):

{
  "id": "rule-rec-002",
  "name": "Recorrente com Sinistralidade",
  "type": "Recorrente",
  "channels": ["Externo"],
  "agentRoles": ["gerente_vendas"],
  "status": "Active",
  "startMonth": 1,
  "recurrentLogicType": "Baseado em Sinistralidade e Tamanho do Contrato",
  "sinistralityConfig": "{\"0-60\":5,\"60-80\":3,\"80-100\":1,\"100+\":0}"
}

Estrutura sinistralityConfig:

{
  "0-60": 5,      // 0-60% sinistralidade = 5% comissão
  "60-80": 3,     // 60-80% sinistralidade = 3% comissão
  "80-100": 1,    // 80-100% sinistralidade = 1% comissão
  "100+": 0       // >100% sinistralidade = 0% comissão
}

2.3. Regra de Remuneração Variável

interface RemuneracaoVariavelRule extends CommissionRule {
  type: "Remuneracao Variavel";
  indicator: string;               // Indicador de performance (ex: "novas_vendas")
  maxAmount?: number;              // Valor máximo da comissão
  rvLogicType?: string;            // "valorFixo" | "percentual" | "escalonado"

  // Campos específicos por lógica
  fixedValue?: number;
  percentageOfBase?: number;
  scaleTiers?: string;             // JSON com faixas
  // ... outros campos conforme necessidade
}

Exemplo:

{
  "id": "rule-rv-001",
  "name": "RV Novas Vendas Escalonado",
  "type": "Remuneracao Variavel",
  "channels": ["Externo", "Interno"],
  "agentRoles": ["gerente_vendas"],
  "status": "Active",
  "indicator": "novas_vendas",
  "rvLogicType": "escalonado",
  "scaleTiers": "[{\"min\":0,\"max\":100,\"value\":500},{\"min\":100,\"max\":120,\"value\":1000}]",
  "maxAmount": 5000
}

2.4. Regra de Estorno

interface EstornoRule extends CommissionRule {
  type: "Estorno";
  cancellationPercentages: string;  // JSON: {"1": 100, "2": 90, ...}
}

Exemplo:

{
  "id": "rule-est-001",
  "name": "Estorno Progressivo 24 meses",
  "type": "Estorno",
  "channels": ["Externo"],
  "agentRoles": ["externo"],
  "status": "Active",
  "cancellationPercentages": "{\"1\":100,\"2\":90,\"3\":85,\"4\":80,\"5\":75,\"6\":70,\"7-12\":50,\"13-24\":25,\"25+\":0}"
}

---

3. CalculatorInputData (Dados de Entrada para Cálculo)

Dados que devem ser enviados para calcular uma comissão.

interface CalculatorInputData {
  // Campos Obrigatórios
  agentId: string;                    // ID do agente
  agentRole: string;                  // Papel do agente
  calculationType: string;            // Tipo de cálculo
  channel: string;                    // Canal de venda
  baseValue: number;                  // Valor base (R$)
  productType: string;                // Tipo de produto

  // Campos Opcionais Comuns
  productName?: string;               // Nome do produto
  competency?: string;                // Competência (YYYY-MM)
  saleDate?: string;                  // Data da venda (YYYY-MM-DD)
  saleId?: string;                    // ID da venda no sistema origem

  // Campos Específicos por Tipo de Cálculo

  // AGENCIAMENTO
  numLives?: number;                  // Número de vidas
  firstInvoicePaid?: boolean;         // 1ª fatura paga?

  // RECORRENTE
  contractMonthRecorrente?: number;   // Mês do contrato (1-24+)
  agentSinistrality?: number;         // Sinistralidade do agente (%)

  // ESTORNO
  originalCommissionPaid?: number;    // Comissão original paga (R$)
  cancellationContractMonth?: number; // Mês do contrato no cancelamento

  // REMUNERAÇÃO VARIÁVEL
  rvIndicator?: string;               // Indicador RV
  rvActualValue?: number;             // Valor real atingido
  rvTargetValue?: number;             // Valor meta
  rvAchievementPercent?: number;      // % de atingimento
}

---

4. CalculationResult (Resultado do Cálculo)

Resposta retornada pela API após processar o cálculo.

interface CalculationResult {
  appliedRuleId?: string;             // ID da regra aplicada
  agentCommissionType?: string;       // Tipo de comissão aplicada
  agentCommissionValue?: number;      // Valor da comissão do agente (R$)
  agentMessage?: string;              // Mensagem sobre o cálculo
  uniCommissionValue?: number;        // Valor retido pela UNI (R$)
  payloadSent?: object;               // Dados enviados (para debug)
  apiResponse?: object;               // Resposta completa da API
}

Exemplo:

{
  "appliedRuleId": "rule-agenc-001",
  "agentCommissionType": "Agenciamento",
  "agentCommissionValue": 150.00,
  "agentMessage": "Comissão calculada: 10% sobre R$ 1.500,00",
  "uniCommissionValue": 0,
  "payloadSent": { ... },
  "apiResponse": { ... }
}

---

Endpoints da API

Base URL

https://*URL_API*/v1

Autenticação

Todas as requisições devem incluir o header de autenticação:

Authorization: Bearer {seu_token_api}
Content-Type: application/json

---

1. Listar Agentes

Retorna todos os agentes cadastrados no sistema.

Endpoint:

GET /agents

Resposta:

{
  "success": true,
  "data": [
    {
      "id": "agent-001",
      "name": "João Silva",
      "role": "gerente_vendas",
      "startDate": "2024-01-15",
      "status": "Active"
    }
  ]
}

---

2. Obter Agente Específico

Retorna detalhes de um agente específico.

Endpoint:

GET /agents/{agentId}

Resposta:

{
  "success": true,
  "data": {
    "id": "agent-001",
    "name": "João Silva",
    "role": "gerente_vendas",
    "startDate": "2024-01-15",
    "status": "Active"
  }
}

---

3. Listar Regras de Comissão

Retorna todas as regras ativas.

Endpoint:

GET /commission-rules

Query Parameters:

• status (opcional): Active | Inactive
• type (opcional): Agenciamento | Recorrente | Remuneração Variável | Estorno

Resposta:

{
  "success": true,
  "data": [
    {
      "id": "rule-agenc-001",
      "name": "Agenciamento Externo Saúde 10%",
      "type": "Agenciamento",
      "status": "Active",
      ...
    }
  ]
}

---

4. Calcular Comissão Individual

Calcula a comissão para uma venda específica.

Endpoint:

POST /calculate-commission

Request Body:

{
  "agentId": "agent-001",
  "agentRole": "externo",
  "calculationType": "Agenciamento",
  "channel": "Externo",
  "baseValue": 1500.00,
  "productType": "saude_unimed",
  "productName": "Unimed Top",
  "numLives": 5,
  "firstInvoicePaid": true,
  "saleDate": "2025-01-15",
  "saleId": "sale-12345"
}

Resposta:

{
  "success": true,
  "data": {
    "calculationId": "calc-789",
    "appliedRuleId": "rule-agenc-001",
    "agentCommissionType": "Agenciamento",
    "agentCommissionValue": 150.00,
    "agentMessage": "Comissão de 10% aplicada sobre R$ 1.500,00",
    "uniCommissionValue": 0,
    "calculationDate": "2025-01-15T14:30:00Z"
  }
}

---

5. Calcular Comissão em Lote

Calcula comissões para múltiplas vendas em uma única requisição.

Endpoint:

POST /calculate-batch-commission

Request Body:

{
  "calculations": [
    {
      "agentId": "agent-001",
      "agentRole": "externo",
      "calculationType": "Agenciamento",
      "channel": "Externo",
      "baseValue": 1500.00,
      "productType": "saude_unimed",
      "numLives": 5,
      "saleId": "sale-001"
    },
    {
      "agentId": "agent-002",
      "agentRole": "interno",
      "calculationType": "Recorrente",
      "channel": "Interno",
      "baseValue": 2000.00,
      "productType": "sou",
      "contractMonthRecorrente": 3,
      "competency": "2025-01",
      "saleId": "sale-002"
    }
  ]
}

Resposta:

{
  "success": true,
  "data": {
    "batchId": "batch-456",
    "totalCalculations": 2,
    "successCount": 2,
    "errorCount": 0,
    "results": [
      {
        "saleId": "sale-001",
        "success": true,
        "calculationId": "calc-790",
        "agentCommissionValue": 150.00,
        "appliedRuleId": "rule-agenc-001"
      },
      {
        "saleId": "sale-002",
        "success": true,
        "calculationId": "calc-791",
        "agentCommissionValue": 100.00,
        "appliedRuleId": "rule-rec-001"
      }
    ]
  }
}

---

Exemplos de Uso

Fluxo Completo de Integração

---

Exemplo 1: Calcular Agenciamento

Cenário: Venda externa de plano de saúde com 8 vidas, valor R$ 3.200,00

curl -X POST https://*URL_API*/v1/calculate-commission \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-045",
    "agentRole": "externo",
    "calculationType": "Agenciamento",
    "channel": "Externo",
    "baseValue": 3200.00,
    "productType": "saude_unimed",
    "productName": "Unimed Especial",
    "numLives": 8,
    "firstInvoicePaid": true,
    "saleDate": "2025-01-20",
    "saleId": "SALE-2025-00123"
  }'

Resposta Esperada:

{
  "success": true,
  "data": {
    "calculationId": "calc-2025-001234",
    "appliedRuleId": "rule-agenc-ext-saude",
    "agentCommissionType": "Agenciamento",
    "agentCommissionValue": 320.00,
    "agentMessage": "Comissão de 10% aplicada. Base: R$ 3.200,00, Vidas: 8",
    "uniCommissionValue": 0,
    "calculationDate": "2025-01-20T15:45:00Z",
    "details": {
      "ruleName": "Agenciamento Externo Saúde 10%",
      "percentage": 10,
      "baseValue": 3200.00,
      "lives": 8
    }
  }
}

---

Exemplo 2: Calcular Recorrente com Sinistralidade

Cenário: Comissão recorrente do mês 6 de contrato, sinistralidade de 65%

curl -X POST https://*URL_API*/v1/calculate-commission \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-045",
    "agentRole": "gerente_vendas",
    "calculationType": "Recorrente",
    "channel": "Externo",
    "baseValue": 2500.00,
    "productType": "saude_unimed",
    "competency": "2025-01",
    "contractMonthRecorrente": 6,
    "agentSinistrality": 65,
    "saleId": "SALE-2024-07890"
  }'

Resposta Esperada:

{
  "success": true,
  "data": {
    "calculationId": "calc-2025-001235",
    "appliedRuleId": "rule-rec-sinistralidade",
    "agentCommissionType": "Recorrente",
    "agentCommissionValue": 75.00,
    "agentMessage": "Comissão recorrente de 3% (faixa 60-80% sinistralidade). Base: R$ 2.500,00",
    "uniCommissionValue": 0,
    "calculationDate": "2025-01-20T16:00:00Z",
    "details": {
      "ruleName": "Recorrente com Sinistralidade",
      "contractMonth": 6,
      "sinistrality": 65,
      "appliedPercentage": 3,
      "sinistralityBand": "60-80"
    }
  }
}

---

Exemplo 3: Calcular Estorno

Cenário: Cancelamento no 3º mês de contrato, comissão original R$ 450,00

curl -X POST https://*URL_API*/v1/calculate-commission \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-045",
    "agentRole": "externo",
    "calculationType": "Estorno",
    "channel": "Externo",
    "baseValue": 0,
    "productType": "saude_unimed",
    "originalCommissionPaid": 450.00,
    "cancellationContractMonth": 3,
    "saleId": "SALE-2024-05678"
  }'

Resposta Esperada:

{
  "success": true,
  "data": {
    "calculationId": "calc-2025-001236",
    "appliedRuleId": "rule-estorno-progressivo",
    "agentCommissionType": "Estorno",
    "agentCommissionValue": -382.50,
    "agentMessage": "Estorno de 85% da comissão original (cancelamento no mês 3). Original: R$ 450,00",
    "uniCommissionValue": 0,
    "calculationDate": "2025-01-20T16:15:00Z",
    "details": {
      "ruleName": "Estorno Progressivo 24 meses",
      "cancellationMonth": 3,
      "chargebackPercentage": 85,
      "originalCommission": 450.00,
      "chargebackAmount": -382.50
    }
  }
}

---

Exemplo 4: Calcular Remuneração Variável

Cenário: Meta de novas vendas, atingimento de 115%

curl -X POST https://*URL_API*/v1/calculate-commission \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-012",
    "agentRole": "gerente_vendas",
    "calculationType": "Remuneracao Variavel",
    "channel": "Interno",
    "baseValue": 0,
    "productType": "saude_unimed",
    "competency": "2025-01",
    "rvIndicator": "novas_vendas",
    "rvTargetValue": 100000,
    "rvActualValue": 115000,
    "rvAchievementPercent": 115
  }'

Resposta Esperada:

{
  "success": true,
  "data": {
    "calculationId": "calc-2025-001237",
    "appliedRuleId": "rule-rv-novas-vendas",
    "agentCommissionType": "Remuneração Variável",
    "agentCommissionValue": 1500.00,
    "agentMessage": "RV aplicada: atingimento de 115% da meta. Valor na faixa 100-120%.",
    "uniCommissionValue": 0,
    "calculationDate": "2025-01-20T16:30:00Z",
    "details": {
      "ruleName": "RV Novas Vendas Escalonado",
      "indicator": "novas_vendas",
      "target": 100000,
      "actual": 115000,
      "achievementPercent": 115,
      "tier": "100-120",
      "tierValue": 1500
    }
  }
}

---

Exemplo 5: Cálculo em Lote

Cenário: Processar múltiplas vendas de uma vez

curl -X POST https://*URL_API*/v1/calculate-batch-commission \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calculations": [
      {
        "agentId": "agent-001",
        "agentRole": "externo",
        "calculationType": "Agenciamento",
        "channel": "Externo",
        "baseValue": 1800.00,
        "productType": "saude_unimed",
        "numLives": 3,
        "saleId": "BATCH-001"
      },
      {
        "agentId": "agent-002",
        "agentRole": "interno",
        "calculationType": "Agenciamento",
        "channel": "Interno",
        "baseValue": 2200.00,
        "productType": "sou",
        "numLives": 5,
        "saleId": "BATCH-002"
      },
      {
        "agentId": "agent-001",
        "agentRole": "externo",
        "calculationType": "Recorrente",
        "channel": "Externo",
        "baseValue": 1800.00,
        "productType": "saude_unimed",
        "contractMonthRecorrente": 2,
        "competency": "2025-01",
        "saleId": "BATCH-003"
      }
    ]
  }'

Resposta Esperada:

{
  "success": true,
  "data": {
    "batchId": "batch-2025-00045",
    "totalCalculations": 3,
    "successCount": 3,
    "errorCount": 0,
    "totalAgentCommission": 450.00,
    "totalUniCommission": 0,
    "results": [
      {
        "saleId": "BATCH-001",
        "success": true,
        "calculationId": "calc-2025-001238",
        "agentCommissionValue": 180.00,
        "appliedRuleId": "rule-agenc-ext-saude"
      },
      {
        "saleId": "BATCH-002",
        "success": true,
        "calculationId": "calc-2025-001239",
        "agentCommissionValue": 220.00,
        "appliedRuleId": "rule-agenc-int-sou"
      },
      {
        "saleId": "BATCH-003",
        "success": true,
        "calculationId": "calc-2025-001240",
        "agentCommissionValue": 90.00,
        "appliedRuleId": "rule-rec-001"
      }
    ],
    "processedAt": "2025-01-20T17:00:00Z"
  }
}

---

Tratamento de Erros

Códigos de Status HTTP

Código	Significado	Descrição
200	OK	Requisição processada com sucesso
201	Created	Recurso criado com sucesso
400	Bad Request	Dados inválidos na requisição
401	Unauthorized	Token de autenticação inválido ou ausente
403	Forbidden	Sem permissão para acessar o recurso
404	Not Found	Recurso não encontrado
422	Unprocessable Entity	Dados válidos mas regra de negócio falhou
429	Too Many Requests	Limite de requisições excedido
500	Internal Server Error	Erro interno do servidor
503	Service Unavailable	Serviço temporariamente indisponível

Estrutura de Erro

{
  "success": false,
  "error": {
    "code": "INVALID_AGENT",
    "message": "Agente não encontrado no sistema",
    "details": {
      "agentId": "agent-999",
      "field": "agentId"
    },
    "timestamp": "2025-01-20T18:00:00Z",
    "requestId": "req-abc123"
  }
}

Códigos de Erro Comuns

Código	Descrição	Solução
INVALID_AGENT	Agente não encontrado	Verificar se o ID do agente existe
INVALID_ROLE	Papel do agente inválido	Usar valores do dicionário de papéis
INVALID_CHANNEL	Canal inválido	Usar valores do dicionário de canais
INVALID_PRODUCT_TYPE	Tipo de produto inválido	Usar valores do dicionário de produtos
NO_RULE_FOUND	Nenhuma regra aplicável	Verificar se existe regra ativa para os parâmetros
MISSING_REQUIRED_FIELD	Campo obrigatório ausente	Incluir todos os campos obrigatórios
INVALID_NUMBER_FORMAT	Formato numérico inválido	Usar formato decimal correto (ex: 1500.00)
INVALID_DATE_FORMAT	Formato de data inválido	Usar formato YYYY-MM-DD
CALCULATION_ERROR	Erro no cálculo	Contatar suporte com requestId

Exemplo de Erro

Request:

curl -X POST https://*URL_API*/v1/calculate-commission \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-999",
    "calculationType": "Agenciamento",
    "channel": "Externo",
    "baseValue": 1500.00
  }'

Response (400 Bad Request):

{
  "success": false,
  "error": {
    "code": "INVALID_AGENT",
    "message": "Agente com ID 'agent-999' não foi encontrado no sistema",
    "details": {
      "agentId": "agent-999",
      "field": "agentId",
      "validationError": "Agent does not exist"
    },
    "timestamp": "2025-01-20T18:15:00Z",
    "requestId": "req-xyz789"
  }
}

---

Considerações de Segurança

1. Autenticação

• Todas as requisições devem incluir token Bearer válido
• Tokens têm validade de 24 horas
• Renovação automática disponível via endpoint /auth/refresh

2. Rate Limiting

Endpoint	Limite
/calculate-commission	100 req/min
/calculate-batch-commission	10 req/min
/agents	300 req/min
/commission-rules	300 req/min

3. Boas Práticas

• Sempre use HTTPS
• Não exponha tokens em logs ou URLs
• Implemente retry com backoff exponencial
• Valide dados no cliente antes de enviar
• Armazene o requestId para rastreamento
• Use o endpoint de batch para múltiplos cálculos

4. Webhook (Opcional)

Podemos notificar seu sistema quando cálculos forem processados:

{
  "event": "calculation.completed",
  "calculationId": "calc-2025-001234",
  "saleId": "SALE-2025-00123",
  "agentCommissionValue": 320.00,
  "timestamp": "2025-01-20T15:45:00Z"
}

---

Ambientes

Desenvolvimento/Homologação

Base URL: https://commissionspilot.1ni.com.br/v1
Token: Fornecido pela equipe técnica

Produção

Base URL: https://commissionspilot.1ni.com.br/v1
Token: Fornecido após homologação

---

Suporte e Contato

Equipe Técnica CommissionsPilot

• Email: [email protected]
• Horário: Segunda a Sexta, 9h às 18h (GMT-3)

Documentação Adicional:

• API Reference: https://docs.somosuni.com.br
• Changelog: ...
• Status da API: ...

---

Glossário de Status Codes

---

Anexo: Fluxo de Decisão de Regras

---

Documento gerado em: NOVEMBRO de 2025 Versão: 1.0 Última atualização: 2025-11-13

---

Este documento é confidencial e destinado exclusivamente para fornecedores integrados ao CommissionsPilot. Qualquer reprodução ou compartilhamento não autorizado é proibido.