Pricing Engine

O Pricing Engine responde uma pergunta só, e responde sempre da mesma forma: quanto custa emprestar para este cliente, neste produto, neste valor e neste prazo. Você cadastra as faixas de score com a taxa de cada uma, cadastra as regras comerciais com as tarifas, comissões e seguros, e a esteira passa a perguntar o preço por API em vez de consultar uma planilha.

Na prática, é a diferença entre uma financeira que muda a taxa da faixa de score 700–799 com um PATCH e uma que abre um chamado de engenharia. E, na hora que o cliente reclamar da taxa, a resposta da API já traz o nome da faixa e o nome da regra que a produziram — não um número solto.

Está em beta desde novembro de 2025, com host publicado em staging. As duas tabelas, as onze rotas e o cálculo de taxa, tarifa, comissão e seguro estão implementados e cobertos por testes unitários e de integração. O que não está: regra do tipo DECISION, que existe no schema mas nunca chama o Decision Engine. Leia a §15 antes de prometer isso a cliente.

flowchart LR
  E["Proposta<br/>produto · score · valor · prazo"] --> C["POST /pricing/api/v1/calculate"]
  C --> R["Taxa mensal<br/>tarifas · comissões · seguros"]
  C --> J["A faixa e a regra<br/>que decidiram o preço"]

  style C fill:#1f6feb,stroke:#1f6feb,color:#fff

O cenário. Uma financeira não vende crédito a um preço só. Vende a 1,89% ao mês para quem tem score alto e vem pelo aplicativo, a 2,49% para quem tem score médio e vem pelo correspondente, com TAC de R$ 89,90 num canal e isenta em outro, com comissão de 1,5% para o parceiro e prestamista obrigatório acima de R$ 20 mil. Isso não é uma tabela — são dezenas de combinações que mudam quando o custo de funding muda, quando a inadimplência da safra piora, ou quando o comercial fecha um acordo novo.

O caminho que esse preço percorre hoje, na operação típica, passa por três traduções antes de chegar ao cliente — e cada seta é um lugar onde o número muda de forma involuntária:

flowchart LR
  R["Comitê de risco<br/>decide a curva"] --> X["Planilha .xlsx<br/>compartilhada"]
  X --> T["TI transcreve para<br/>constante no código"]
  T --> D["Fila de release<br/>PR, revisão, janela"]
  D --> P["Preço no ar"]

  X -. "erro de célula" .-> F1["Taxa errada em produção"]
  T -. "erro de transcrição" .-> F1
  D -. "10 a 15 dias" .-> F2["Vende com a taxa velha"]

  style F1 fill:#7d1a1a,stroke:#7d1a1a,color:#fff
  style F2 fill:#7d1a1a,stroke:#7d1a1a,color:#fff

O que trava hoje.

• A tabela de preço mora em planilha. O time de risco mantém um .xlsx, alguém exporta para o time de TI, e TI transcreve para constante no código. Cada transcrição é uma chance de erro, e a taxa de erro de célula em planilhas corporativas é conhecida e alta — a literatura de auditoria de planilhas de Raymond Panko documenta erro em uma fração relevante das planilhas operacionais examinadas (Panko, *What We Know About Spreadsheet Errors*).
• Mudar a taxa exige deploy. Ajustar a faixa de score 700–799 em 20 pontos-base vira ticket, sprint e janela de release. O comercial pede na segunda e recebe no mês seguinte, quando o concorrente já ajustou.
• Ninguém consegue explicar a taxa depois. Seis meses após a contratação, a pergunta "por que este cliente pagou 2,49%" não tem resposta reproduzível: a planilha foi sobrescrita, o if foi refatorado e o número está sozinho no contrato.
• Tarifa, comissão e seguro são calculados em três lugares. A taxa sai de um sistema, a TAC de outro, o prestamista de uma planilha da seguradora. Quando os três discordam, o cliente descobre na fatura.
• Faixa de score é fácil de errar e caro de errar. Uma sobreposição de faixas mal declarada — 700–799 e 750–850 ativas ao mesmo tempo — faz clientes iguais receberem preços diferentes conforme a ordem em que o banco devolveu as linhas.

O custo de não resolver. O custo direto é o tempo de resposta comercial: enquanto a taxa não muda, cada proposta perdida por preço é receita que não volta. O custo indireto é regulatório e jurídico: o preço cobrado precisa ser reconstruível na data do contrato, e a carteira de crédito do Sistema Financeiro Nacional somava R$ 7,1 trilhões em janeiro de 2026 (BACEN, Estatísticas Monetárias e de Crédito). Precificação que não se explica é a matéria-prima de ação revisional.

A faixa e a regra vêm na resposta. Todo cálculo devolve riskBand.id, riskBand.name e pricingRule.id, pricingRule.name. Quem for auditar o contrato não precisa reconstruir a política — precisa ler dois campos e buscar os dois registros.

flowchart TD
  C["Resposta de POST /calculate"] --> A["approved"]
  C --> N["O número<br/>interestRate · totalFees<br/>totalCommissions · totalInsurance"]
  C --> Q["A justificativa<br/>riskBand.id e name<br/>pricingRule.id e name"]
  C --> B["O detalhe item a item<br/>fees · commissions · insurances"]

  Q --> AUD["Auditoria dois anos depois:<br/>duas consultas por identificador"]

  style Q fill:#1f6feb,stroke:#1f6feb,color:#fff
  style AUD fill:#1a7d4a,stroke:#1a7d4a,color:#fff

Tarifa, comissão e seguro são parte do preço, não um adendo. As três configurações vivem em JSONB dentro da regra de precificação e são calculadas na mesma passada da taxa, com o detalhe item a item na resposta. A TAC de R$ 89,90 e a comissão de 1,5% do parceiro saem do mesmo lugar que a taxa.

A recusa é um resultado, não uma exceção. Score fora de qualquer faixa, valor fora de qualquer regra, ou taxa acima do teto da faixa devolvem 200 com approved: false e rejectionReason em texto. A sua esteira trata isso como decisão de negócio, não como falha de integração.

Cada tenant vê só a própria política. Toda consulta filtra por organizationId vindo do token assinado, nunca do corpo. Um correspondente não descobre a tabela de outro.

Exclusão é lógica. Faixa e regra excluídas ficam com deletedAt preenchido e a linha preservada. A política de ontem continua consultável no banco depois de a de hoje entrar.

Panorama. O mercado resolve precificação de crédito em dois extremos. De um lado, plataformas de decisão corporativas — FICO, Provenir, Earnix — que fazem score, política, orquestração, simulação e preço, com licença negociada e projeto de implantação. Do outro, a planilha: a esmagadora maioria das operações de médio porte mantém a tabela de taxas num arquivo compartilhado e transcreve para o código. Entre os dois não há muita coisa, e é nesse vão que este building block se coloca.

Vale separar duas coisas que costumam ser vendidas juntas. Modelar risco — decidir qual score o cliente tem e qual a probabilidade de inadimplência — é o produto da FICO e da Zest AI. Aplicar preço — dado o score, qual taxa, qual tarifa, qual comissão — é uma mecânica determinística e auditável. O Pricing Engine faz só a segunda, e não pretende fazer a primeira.

flowchart LR
  D["Dados do cliente<br/>bureau, cadastro, comportamento"] --> M["MODELAR RISCO<br/>probabilístico, estatístico<br/>FICO · Zest AI · Neurotech"]
  M --> S["creditScore"]
  S --> AP["APLICAR PREÇO<br/>determinístico, auditável<br/>Catalisa Pricing Engine"]
  AP --> PR["Taxa, tarifa, comissão, seguro"]

  style AP fill:#1f6feb,stroke:#1f6feb,color:#fff

Nenhum dos cinco fornecedores publica tabela de preço. Consulta feita em 2026-08. As linhas sobre o comportamento deles descrevem o posicionamento público de cada um e não substituem uma avaliação técnica direta com o fornecedor.

Nossos diferenciais

1. A justificativa do preço vem junto com o preço. riskBand e pricingRule estão na mesma resposta que a taxa, com nome e identificador. Não é uma funcionalidade de auditoria bolt-on — é o formato do retorno, e por isso não tem como o integrador esquecer de guardar.
2. Tarifa, comissão e seguro entram no mesmo cálculo. Numa operação de crédito brasileira, a taxa nominal é a menor parte da conversa. Fornecedor que resolve só a taxa devolve o problema mais chato — consolidar TAC, comissão de parceiro e prestamista — para o time de integração.
3. É a peça, não a plataforma. Onze rotas, duas tabelas, dependência de PostgreSQL e do IAM. Entra ao lado da esteira que existe, sem projeto de substituição e sem obrigar a trocar o motor de decisão que já roda.
4. Recusa é 200, não 4xx. Cliente fora de faixa devolve approved: false com motivo em texto. A esteira distingue "não tem preço para este perfil" de "a integração quebrou" sem inspecionar mensagem de erro.

Quando escolher o concorrente

flowchart TD
  Q{"Qual é o seu problema<br/>de verdade?"}
  Q -- "Construir e governar<br/>o modelo de score" --> F["FICO ou Zest AI"]
  Q -- "Otimizar preço por<br/>elasticidade de demanda" --> E["Earnix"]
  Q -- "Orquestrar a decisão inteira<br/>com editor visual" --> P["Provenir · ou Decision Platform<br/>+ Decision Engine na Catalisa"]
  Q -- "Regra de preço que não cabe em<br/>faixa de score, valor e prazo" --> M["Motor de regras de verdade<br/>o tipo DECISION daqui não está implementado"]
  Q -- "Aplicar uma política declarada,<br/>de forma rastreável" --> C["Catalisa Pricing Engine"]

  style C fill:#1f6feb,stroke:#1f6feb,color:#fff
  style M fill:#7d1a1a,stroke:#7d1a1a,color:#fff

Quando escolher o concorrente. Se o seu problema é modelar risco — construir e governar o modelo que produz o score, monitorar drift, provar explicabilidade a um regulador — escolha FICO ou Zest AI, e use este building block depois deles, se usar.

Se você precisa de otimização de preço com elasticidade de demanda, curva de aceitação e simulação de cenário de margem, o Earnix faz isso e nós não fazemos nem temos no roadmap.

Se a exigência é orquestrar a decisão inteira — bureau, política, árvore, fallback, retentativa, editor visual para o time de risco mexer sem engenharia — o Provenir entrega isso pronto, e o equivalente na Catalisa é o Decision Platform somado ao Decision Engine, não este bloco.

E se a sua política de preço depende de uma regra que não cabe em faixa de score mais faixa de valor e prazo, hoje você precisa de um motor de regras de verdade: o tipo DECISION existe no schema daqui, mas não está implementado (§15).

Este bloco ganha quando o problema é aplicar uma política de preço declarada, de forma rastreável, sem contratar uma plataforma inteira.

Unidade de cobrança. Precificação em definição. Não há preço fechado para este building block e não vamos inventar um.

O que dispara custo. Três drivers em consideração:

Comparação de custo. Não dá para fazer comparação numérica honesta: nenhum dos cinco análogos publica tabela de preço. FICO, Provenir, Earnix, Zest AI e Neurotech trabalham com contrato negociado. O que dá para comparar é a forma do custo, e a diferença é material:

Estimativa de forma, não de valor, consultada em 2026-08. Nenhum número de fornecedor foi extrapolado aqui porque nenhum é público.

ROI. A conta de guardanapo tem duas linhas.

flowchart LR
  subgraph L1["Linha 1 — ciclo de alteração de preço"]
    A["Comitê decide<br/>a taxa nova"] --> B["Ticket, sprint,<br/>janela de release"] --> C["Dias a semanas<br/>vendendo com a taxa velha"]
    A2["Comitê decide<br/>a taxa nova"] --> B2["PATCH por faixa"] --> C2["Minutos"]
  end
  subgraph L2["Linha 2 — reconstruir o preço de um contrato"]
    D["Sem faixa e regra<br/>registradas"] --> E["Arqueologia de<br/>planilha e commit"]
    D2["Com riskBand.id e<br/>pricingRule.id gravados"] --> E2["Consulta por identificador"]
  end

  style C fill:#7d1a1a,stroke:#7d1a1a,color:#fff
  style C2 fill:#1a7d4a,stroke:#1a7d4a,color:#fff
  style E fill:#7d1a1a,stroke:#7d1a1a,color:#fff
  style E2 fill:#1a7d4a,stroke:#1a7d4a,color:#fff

A primeira é o ciclo de alteração de preço. Numa operação em que mudar uma taxa custa um ticket, uma sprint e uma janela de release, o intervalo entre a decisão do comitê e o preço novo em produção é de dias a semanas. Enquanto isso, ou a instituição vende com margem menor que a decidida, ou perde proposta para quem já ajustou. Aqui a alteração é um PATCH por faixa. Uma financeira que revisa a curva de preço mensalmente recupera de dez a quinze dias de defasagem por revisão.

A segunda linha é a que ninguém orça até precisar: reconstruir por que um contrato específico saiu naquela taxa. Sem faixa e regra registradas na resposta, isso é arqueologia de planilha e de commit. Com elas, é uma consulta por identificador. O valor não é o tempo economizado — é a diferença entre conseguir e não conseguir responder a um questionamento de cliente, de Procon ou de auditoria.

As camadas

flowchart TD
  H["HTTP"] --> APP["Hono app · basePath /pricing<br/>applyCommonMiddleware + errorHandler"]

  APP --> R1["/api/v1/risk-bands<br/>riskBandsRouter · 5 rotas"]
  APP --> R2["/api/v1/pricing-rules<br/>pricingRulesRouter · 5 rotas"]
  APP --> R3["/api/v1/calculate<br/>pricingRouter · 1 rota"]
  APP --> R4["/health<br/>identificação e versão do build"]

  R1 --> MW["authMiddleware → requirePermission(P) → requireOrganization<br/>Zod parse → ResultAsync"]
  R2 --> MW
  R3 --> MW

  MW --> S1["PricingService<br/>o cálculo. Sem I/O além dos dois repositórios"]
  MW --> S2["RiskBandService<br/>CRUD + validação de faixa + eventos"]
  MW --> S3["PricingRuleService<br/>CRUD + validação de faixa, prazo e data + eventos"]

  S1 --> REP["repositories/ (Prisma)<br/>toda query de leitura filtra<br/>organizationId E deletedAt null"]
  S2 --> REP
  S3 --> REP
  REP --> PG[("PostgreSQL<br/>schema pricing")]

  S2 --> EV["EventPublisher<br/>6 tipos de evento"]
  S3 --> EV

  style S1 fill:#1f6feb,stroke:#1f6feb,color:#fff

O applyCommonMiddleware cobre limite de corpo de 1 MB, CORS, cabeçalhos de segurança e rate limit; o errorHandler traduz AppError em resposta HTTP. Os seis eventos publicados são pricing.risk_band.created, .updated e .deleted, mais pricing.pricing_rule.created, .updated e .deleted.

O caminho de uma chamada de cálculo

flowchart TD
  IN["POST /pricing/api/v1/calculate<br/>productId · creditScore<br/>requestedAmount · numberOfInstallments"] --> P1

  P1{"1. Encontra a faixa de risco<br/>findFirst · ORDER BY priority ASC"}
  P1 -- "não achou" --> X1["200 approved false<br/>No risk band found for credit score N"]
  P1 -- "achou" --> P2

  P2{"2. Encontra a regra de precificação<br/>findFirst · ORDER BY priority ASC"}
  P2 -- "não achou" --> X2["200 approved false<br/>No applicable pricing rule found for amount..."]
  P2 -- "achou" --> P3

  P3{"3. interestRate = baseRate + rateSpread<br/>da FAIXA"}
  P3 -- "maxRate definido e<br/>interestRate maior que ele" --> X3["200 approved false<br/>Interest rate exceeds maximum..."]
  P3 -- "dentro do teto" --> P4

  P4["Calcula fees, commissions e insurances<br/>da REGRA<br/>effectiveAnnualRate = (1 + interestRate)^12 − 1"]
  P4 --> OK["200 approved true<br/>interestRate · fees · totalFees · commissions<br/>insurances · riskBand · pricingRule"]

  style OK fill:#1a7d4a,stroke:#1a7d4a,color:#fff
  style X1 fill:#7d1a1a,stroke:#7d1a1a,color:#fff
  style X2 fill:#7d1a1a,stroke:#7d1a1a,color:#fff
  style X3 fill:#7d1a1a,stroke:#7d1a1a,color:#fff

As duas consultas do desenho acima são literais no código. Vale ler as cláusulas com atenção, porque é nelas que mora a maioria das dúvidas de integração:

Decisões não óbvias

• Recusa é 200, não 4xx. createRejectionResult monta um resultado de sucesso com approved: false e o motivo em texto. Não ter preço para um perfil é uma decisão de negócio, não uma falha de integração — e tratar como erro HTTP faria a esteira do cliente confundir "score fora de faixa" com "o serviço caiu". O custo dessa escolha: o objeto de recusa vem com riskBand.id e pricingRule.id vazios (""), porque não houve faixa nem regra. Sempre cheque approved antes de ler qualquer outro campo.

• A seleção é "a primeira por priority", não "a melhor". Tanto a faixa quanto a regra usam findFirst com ORDER BY priority ASC. Se você declarar duas faixas que se sobrepõem — 700–799 e 750–850, ambas ativas — o cliente com score 780 recebe a de menor priority, e nada no serviço avisa que há sobreposição. Não existe validação de sobreposição de faixas. Use priority deliberadamente e trate a checagem de sobreposição como responsabilidade sua.

• productId não tem chave estrangeira. É um uuid livre nas duas tabelas. O Pricing Engine não verifica se o produto existe em lugar nenhum, porque o produto pode morar no Banking Product Portfolio, no Products ou no core do cliente. O preço da flexibilidade: um productId digitado errado não dá erro — dá "nenhuma faixa encontrada".

• effectiveAnnualRate é composição pura de juros, e não é CET. O campo vale (1 + interestRate)^12 − 1. Ele não inclui tarifa, comissão, seguro nem IOF. Não use este número como Custo Efetivo Total em nenhum documento entregue ao cliente — CET é apurado no Calculations Engine, a partir do valor líquido liberado.

• Taxas em Decimal(10,8) no banco, number na aplicação. O Postgres guarda as taxas como decimal de 8 casas para não perder centésimo de ponto-base. A conversão para number acontece na fronteira do serviço, com Number(riskBand.baseRate). Isso é adequado para taxa (magnitude pequena, 8 casas), mas significa que a aritmética de tarifa e comissão é ponto flutuante binário, com arredondamento explícito a duas casas em cada item.

• Fee, comissão e seguro em JSONB, não em tabela. Uma regra de precificação pode ter zero ou muitas tarifas, de tipos diferentes. Modelar em tabelas exigiria três tabelas filhas e três JOIN para um dado que só é lido junto com a regra-mãe. O trade-off: o Postgres não valida a estrutura — a garantia vem do Zod no router, e um INSERT feito direto no banco passa por cima dela.

• Evento publicado dentro da cadeia de Result. Cada mutação encadeia a publicação do evento com ResultAsync.fromPromise. Falha ao publicar vira INTERNAL depois de a gravação já ter acontecido. Ou seja: a linha está no banco e o evento não saiu. Trate os eventos como notificação melhor-esforço, não como fonte de verdade transacional.

O desempate por priority, desenhado

A regra de seleção é a mesma nos dois passos e cabe em uma frase: a primeira linha ativa que casa, ordenada por priority crescente. Duas faixas sobrepostas não são erro para o serviço — são duas linhas que casam, e vence a de menor priority.

flowchart TD
  S["creditScore = 780"] --> Q["Faixas ativas do produto que casam"]
  Q --> B1["Score alto · 700 a 799<br/>priority 20"]
  Q --> B2["Score premium · 750 a 850<br/>priority 10"]
  B1 --> ORD["ORDER BY priority ASC<br/>findFirst"]
  B2 --> ORD
  ORD --> W["Vence Score premium<br/>priority 10 é menor"]
  W --> N["Nada no serviço avisa<br/>que havia sobreposição"]

  style W fill:#1f6feb,stroke:#1f6feb,color:#fff
  style N fill:#7d1a1a,stroke:#7d1a1a,color:#fff

Monolito vs. standalone. Em monolito, src/app.ts monta o app e os serviços vêm do container TypeDI (registerPricingEngine). Em standalone — o modo usado em produção —, main.ts sobe o Bun na porta configurada (3012 por convenção do projeto) e o serviço precisa apenas de PostgreSQL e do JWT_SECRET; a verificação de token é local, sem chamada de rede ao IAM. Não há diferença de comportamento entre os modos: este building block não consome nenhum outro por HTTP.

Glossário

Modelo de dados — schema pricing no PostgreSQL. Dois modelos, ambos com organizationId, productId, createdBy, updatedBy e deletedAt.

erDiagram
  RISK_BAND {
    uuid id PK
    uuid organization_id "do token, nunca do corpo"
    uuid product_id "sem chave estrangeira"
    string name "único por organização e produto"
    int min_score
    int max_score
    decimal base_rate "Decimal(10,8)"
    decimal max_rate "opcional, é o freio"
    decimal rate_spread "pode ser negativo"
    int priority "menor vence"
    boolean is_active
    datetime deleted_at "exclusão lógica"
  }
  PRICING_RULE {
    uuid id PK
    uuid organization_id "do token, nunca do corpo"
    uuid product_id "sem chave estrangeira"
    string name "único por organização e produto"
    enum rule_type "DB_RULE ou DECISION"
    enum status "só ACTIVE entra no cálculo"
    decimal min_amount "Decimal(15,2)"
    decimal max_amount "Decimal(15,2)"
    int min_term
    int max_term
    jsonb fees
    jsonb commissions
    jsonb insurances
    datetime effective_from
    datetime effective_to
    int priority "menor vence"
    datetime deleted_at "exclusão lógica"
  }
  PRODUTO_EXTERNO {
    uuid product_id "mora no Portfolio, no Products ou no core do cliente"
  }

  PRODUTO_EXTERNO ||..o{ RISK_BAND : "product_id, sem FK"
  PRODUTO_EXTERNO ||..o{ PRICING_RULE : "product_id, sem FK"

Enumerações

As fórmulas, exatamente como estão no código (PricingService)

As quatro famílias de cálculo são independentes entre si e rodam na mesma passada. A taxa vem da faixa; tarifa, comissão e seguro vêm da regra. Cada uma tem sua ordem de aplicação, e a ordem importa — o arredondamento é sempre o último passo de cada item.

flowchart LR
  F["FAIXA de risco"] --> T1["TAXA"]
  R["REGRA de precificação"] --> T2["TARIFA"]
  R --> T3["COMISSÃO"]
  R --> T4["SEGURO"]
  T1 --> AN["ANUALIZAÇÃO<br/>effectiveAnnualRate"]
  T1 --> RES["Resposta"]
  T2 --> RES
  T3 --> RES
  T4 --> RES
  AN --> RES

  style T1 fill:#1f6feb,stroke:#1f6feb,color:#fff

Fórmula — taxa

Fórmula — tarifa

A sequência de limites e arredondamento da tarifa é a que mais surpreende quem lê só a fórmula do método:

flowchart LR
  M{"calculationMethod"} -- "FIXED" --> A["amount = value"]
  M -- "PERCENTAGE_OF_PRINCIPAL" --> B["amount = valor solicitado × value ÷ 100"]
  M -- "PERCENTAGE_OF_TOTAL" --> B
  A --> P["piso: se abaixo de minAmount,<br/>amount = minAmount"]
  B --> P
  P --> T["teto: se acima de maxAmount,<br/>amount = maxAmount"]
  T --> RD["arredonda a 2 casas"]
  RD --> SU["totalFees = soma dos amount"]

Fórmula — comissão

Fórmula — seguro

Fórmula — anualização

Atenção a duas escolhas do código: percentage da comissão e monthlyRate do seguro são lidos como percentual (o schema Zod aceita 0 a 100 e o cálculo divide por 100), enquanto baseRate e rateSpread são lidos como decimal (0 a 1). São convenções diferentes no mesmo módulo — declare baseRate: 0.0189 para 1,89% ao mês e monthlyRate: 0.035 para 0,035% ao mês.

Estados da regra de precificação

stateDiagram-v2
  [*] --> DRAFT: POST /pricing-rules sem status no corpo
  DRAFT --> ACTIVE: PATCH status
  ACTIVE --> INACTIVE: PATCH status
  INACTIVE --> DRAFT: PATCH status
  ACTIVE --> DRAFT: PATCH status
  DRAFT --> INACTIVE: PATCH status
  INACTIVE --> ACTIVE: PATCH status

  note right of ACTIVE
    Só ACTIVE participa do cálculo.
  end note

Não há máquina de estados no serviço: qualquer transição é aceita por PATCH. Só ACTIVE participa do cálculo. A faixa de risco não tem status — tem o booleano isActive.

DELETE em qualquer um dos dois é lógico: grava deletedAt e a linha fica. Nenhuma leitura volta a enxergá-la.

stateDiagram-v2
  direction LR
  state "Faixa ou regra viva — deletedAt null" as VIVA
  state "Excluída logicamente — deletedAt preenchido" as MORTA
  [*] --> VIVA: POST
  VIVA --> MORTA: DELETE
  MORTA --> [*]: nenhuma leitura volta a enxergá-la

Prefixo do app: /pricing — atenção, não /pricing-engine. Em staging a base é https://pricing.bb.stg.catalisa.app; em desenvolvimento local no modo monolito, http://localhost:3000.

Todas as 11 rotas exigem authMiddleware (Bearer JWT), requirePermission(...) e requireOrganization. Token sem organizationId recebe 403 antes de a regra de negócio rodar.

Cálculo de preço

Faixas de risco — /pricing/api/v1/risk-bands

Filtros da listagem: productId, isActive (true/false). Paginação: pageNumber, pageSize (padrão 20). Ordenação fixa: productId, depois priority, depois minScore.

Regras de precificação — /pricing/api/v1/pricing-rules

Filtros da listagem: productId, status, ruleType, name (trecho do nome, sem distinguir maiúsculas) e effectiveAt (ISO-8601: só regras cuja vigência cobre o instante; 400 se a data for inválida). Ordenação fixa: productId, depois priority, depois createdAt decrescente.

Saúde

POST /pricing/api/v1/calculate

O endpoint que a esteira chama. Todo o corpo vem dentro do envelope JSON:API.

sequenceDiagram
  autonumber
  participant E as Esteira de originação
  participant A as Hono · /pricing
  participant S as PricingService
  participant B as RiskBandRepository
  participant R as PricingRuleRepository

  E->>A: POST /api/v1/calculate + Bearer JWT
  A->>A: authMiddleware · requirePermission(PRICING_CALCULATE)<br/>requireOrganization · Zod parse
  A->>S: calculatePricing(input, organizationId)
  S->>B: findByProductIdAndScore(productId, org, creditScore)
  B-->>S: faixa de menor priority, ou nulo
  alt Nenhuma faixa
    S-->>E: 200 approved false · No risk band found...
  else Faixa encontrada
    S->>R: findActiveByProduct(productId, org, amount, term)
    R-->>S: regra ACTIVE de menor priority, ou nulo
    alt Nenhuma regra
      S-->>E: 200 approved false · No applicable pricing rule...
    else Regra encontrada
      S->>S: taxa, tarifas, comissões, seguros e anualização
      S-->>E: 200 approved true + riskBand + pricingRule
    end
  end

O PricingService não faz nenhuma chamada de rede: os dois repositórios são as únicas dependências dele. Não há bureau, não há Decision Engine, não há cache.

Request

{
  "data": {
    "type": "pricing-calculations",
    "attributes": {
      "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "creditScore": 742,
      "requestedAmount": 15000,
      "numberOfInstallments": 36,
      "customerId": "9c858901-8a57-4791-81fe-4c455b099bc9",
      "context": { "canal": "app", "convenio": "inss" }
    }
  }
}

{
  "data": {
    "type": "pricing-calculations",
    "attributes": {
      "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "creditScore": 742,
      "requestedAmount": 15000,
      "numberOfInstallments": 36,
      "customerId": "9c858901-8a57-4791-81fe-4c455b099bc9",
      "context": { "canal": "app", "convenio": "inss" }
    }
  }
}

Resposta 200 — aprovado

{
  "data": {
    "type": "pricing-calculations",
    "attributes": {
      "riskBand": {
        "id": "b1a2c3d4-0000-0000-0000-000000000001",
        "name": "Score alto",
        "minScore": 700,
        "maxScore": 799
      },
      "pricingRule": {
        "id": "e5f6a7b8-0000-0000-0000-000000000002",
        "name": "Crédito pessoal — app",
        "ruleType": "DB_RULE"
      },
      "interestRate": 0.0214,
      "baseRate": 0.0189,
      "rateSpread": 0.0025,
      "fees": [
        { "feeType": "REGISTRATION", "name": "TAC", "amount": 89.9,
          "calculationMethod": "FIXED", "isFinanced": true },
        { "feeType": "ANALYSIS", "name": "Análise de crédito", "amount": 300,
          "calculationMethod": "PERCENTAGE_OF_PRINCIPAL", "isFinanced": false }
      ],
      "totalFees": 389.9,
      "commissions": [
        { "commissionType": "PARTNER", "name": "Comissão do parceiro", "amount": 225 }
      ],
      "totalCommissions": 225,
      "insurances": [
        { "insuranceType": "LIFE", "name": "Prestamista",
          "monthlyPremium": 5.25, "totalPremium": 189 }
      ],
      "totalInsurance": 189,
      "effectiveAnnualRate": 0.28928889574814853,
      "approved": true
    }
  }
}

{
  "data": {
    "type": "pricing-calculations",
    "attributes": {
      "riskBand": {
        "id": "b1a2c3d4-0000-0000-0000-000000000001",
        "name": "Score alto",
        "minScore": 700,
        "maxScore": 799
      },
      "pricingRule": {
        "id": "e5f6a7b8-0000-0000-0000-000000000002",
        "name": "Crédito pessoal — app",
        "ruleType": "DB_RULE"
      },
      "interestRate": 0.0214,
      "baseRate": 0.0189,
      "rateSpread": 0.0025,
      "fees": [
        { "feeType": "REGISTRATION", "name": "TAC", "amount": 89.9,
          "calculationMethod": "FIXED", "isFinanced": true },
        { "feeType": "ANALYSIS", "name": "Análise de crédito", "amount": 300,
          "calculationMethod": "PERCENTAGE_OF_PRINCIPAL", "isFinanced": false }
      ],
      "totalFees": 389.9,
      "commissions": [
        { "commissionType": "PARTNER", "name": "Comissão do parceiro", "amount": 225 }
      ],
      "totalCommissions": 225,
      "insurances": [
        { "insuranceType": "LIFE", "name": "Prestamista",
          "monthlyPremium": 5.25, "totalPremium": 189 }
      ],
      "totalInsurance": 189,
      "effectiveAnnualRate": 0.28928889574814853,
      "approved": true
    }
  }
}

Os valores acima foram calculados com as fórmulas da §8 para requestedAmount: 15000, numberOfInstallments: 36, baseRate: 0.0189, rateSpread: 0.0025, TAC fixa de 89.90, análise de 2% do principal e prestamista de 0.035% ao mês. effectiveAnnualRate é (1.0214)^12 − 1.

Resposta 200 — recusado

{
  "data": {
    "type": "pricing-calculations",
    "attributes": {
      "riskBand": { "id": "", "name": "", "minScore": 0, "maxScore": 0 },
      "pricingRule": { "id": "", "name": "", "ruleType": "DB_RULE" },
      "interestRate": 0,
      "baseRate": 0,
      "rateSpread": 0,
      "fees": [],
      "totalFees": 0,
      "approved": false,
      "rejectionReason": "No risk band found for credit score 420"
    }
  }
}

{
  "data": {
    "type": "pricing-calculations",
    "attributes": {
      "riskBand": { "id": "", "name": "", "minScore": 0, "maxScore": 0 },
      "pricingRule": { "id": "", "name": "", "ruleType": "DB_RULE" },
      "interestRate": 0,
      "baseRate": 0,
      "rateSpread": 0,
      "fees": [],
      "totalFees": 0,
      "approved": false,
      "rejectionReason": "No risk band found for credit score 420"
    }
  }
}

Os três motivos de recusa que o código produz, em texto literal:

No terceiro caso — e só nele — riskBand e pricingRule vêm preenchidos, com interestRate, baseRate e rateSpread reais. Nos dois primeiros, vêm vazios.

Erros

POST /pricing/api/v1/risk-bands

Request

{
  "data": {
    "type": "risk-bands",
    "attributes": {
      "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Score alto",
      "displayLabel": "AA — 700 a 799",
      "minScore": 700,
      "maxScore": 799,
      "baseRate": 0.0189,
      "maxRate": 0.0299,
      "rateSpread": 0.0025,
      "priority": 10,
      "isActive": true
    }
  }
}

{
  "data": {
    "type": "risk-bands",
    "attributes": {
      "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Score alto",
      "displayLabel": "AA — 700 a 799",
      "minScore": 700,
      "maxScore": 799,
      "baseRate": 0.0189,
      "maxRate": 0.0299,
      "rateSpread": 0.0025,
      "priority": 10,
      "isActive": true
    }
  }
}

Resposta 201 — o recurso, com links.self apontando para /pricing/api/v1/risk-bands/:id.

Erros

A validação não checa sobreposição com outras faixas. Duas faixas 700–799 e 750–850 convivem sem aviso, e o desempate é priority.

POST /pricing/api/v1/pricing-rules

Request

{
  "data": {
    "type": "pricing-rules",
    "attributes": {
      "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Crédito pessoal — app",
      "description": "Tabela do canal digital, vigente a partir de setembro",
      "ruleType": "DB_RULE",
      "status": "ACTIVE",
      "priority": 10,
      "minAmount": 1000,
      "maxAmount": 50000,
      "minTerm": 6,
      "maxTerm": 48,
      "fees": [
        { "feeType": "REGISTRATION", "name": "TAC",
          "calculationMethod": "FIXED", "value": 89.90, "isFinanced": true },
        { "feeType": "ANALYSIS", "name": "Análise de crédito",
          "calculationMethod": "PERCENTAGE_OF_PRINCIPAL", "value": 2,
          "maxAmount": 400 }
      ],
      "commissions": [
        { "commissionType": "PARTNER", "name": "Comissão do parceiro",
          "percentage": 1.5, "maxAmount": 900 }
      ],
      "insurances": [
        { "insuranceType": "LIFE", "name": "Prestamista",
          "monthlyRate": 0.035, "isMandatory": true, "isFinanced": true }
      ],
      "effectiveFrom": "2026-09-01T00:00:00.000Z",
      "effectiveTo": "2026-12-31T23:59:59.000Z"
    }
  }
}

{
  "data": {
    "type": "pricing-rules",
    "attributes": {
      "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Crédito pessoal — app",
      "description": "Tabela do canal digital, vigente a partir de setembro",
      "ruleType": "DB_RULE",
      "status": "ACTIVE",
      "priority": 10,
      "minAmount": 1000,
      "maxAmount": 50000,
      "minTerm": 6,
      "maxTerm": 48,
      "fees": [
        { "feeType": "REGISTRATION", "name": "TAC",
          "calculationMethod": "FIXED", "value": 89.90, "isFinanced": true },
        { "feeType": "ANALYSIS", "name": "Análise de crédito",
          "calculationMethod": "PERCENTAGE_OF_PRINCIPAL", "value": 2,
          "maxAmount": 400 }
      ],
      "commissions": [
        { "commissionType": "PARTNER", "name": "Comissão do parceiro",
          "percentage": 1.5, "maxAmount": 900 }
      ],
      "insurances": [
        { "insuranceType": "LIFE", "name": "Prestamista",
          "monthlyRate": 0.035, "isMandatory": true, "isFinanced": true }
      ],
      "effectiveFrom": "2026-09-01T00:00:00.000Z",
      "effectiveTo": "2026-12-31T23:59:59.000Z"
    }
  }
}

Erros

Armadilha frequente: sem status no corpo, a regra nasce DRAFT e o POST /calculate continua devolvendo "No applicable pricing rule found". Passe "status": "ACTIVE" ou faça um PATCH depois.

PATCH /pricing/api/v1/risk-bands/:id e PATCH /pricing/api/v1/pricing-rules/:id

O corpo exige o envelope completo, com o id dentro de data:

{
  "data": {
    "type": "risk-bands",
    "id": "b1a2c3d4-0000-0000-0000-000000000001",
    "attributes": { "baseRate": 0.0209 }
  }
}

{
  "data": {
    "type": "risk-bands",
    "id": "b1a2c3d4-0000-0000-0000-000000000001",
    "attributes": { "baseRate": 0.0209 }
  }
}

O id que vale é o da URL; o de data.id é exigido pelo schema Zod mas não é usado para localizar o recurso. Todos os campos de attributes são opcionais — só o que você mandar é alterado.

Do zero a um preço calculado. Quatro chamadas.

flowchart LR
  P1["1 · Autenticar no IAM<br/>TOKEN"] --> P2["2 · Criar a faixa de risco<br/>700 a 799 · 1,89% + 0,25%"]
  P2 --> P3["3 · Criar a regra<br/>já ACTIVE"]
  P3 --> P4["4 · Calcular o preço<br/>score 742 · R$ 15.000 · 36x"]
  P4 --> P5["5 · Ver a recusa acontecer<br/>score 420"]

  style P4 fill:#1a7d4a,stroke:#1a7d4a,color:#fff
  style P5 fill:#7d1a1a,stroke:#7d1a1a,color:#fff

Os comandos abaixo não foram executados contra staging nesta sessão — o ambiente não estava acessível a partir da máquina de documentação. As rotas, permissões e formatos vieram da leitura de routes/*.ts e dos schemas Zod, e os números da resposta de exemplo foram calculados com as fórmulas da §8. Confirme na primeira execução.

1. Autenticar no IAM

export API=https://pricing.bb.stg.catalisa.app/pricing/api/v1

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

export API=https://pricing.bb.stg.catalisa.app/pricing/api/v1

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

2. Criar a faixa de risco

PRODUCT_ID=$(uuidgen | tr 'A-Z' 'a-z')

BAND=$(curl -s -X POST $API/risk-bands \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"risk-bands\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"name\":\"Score alto\",
        \"minScore\":700,\"maxScore\":799,
        \"baseRate\":0.0189,\"rateSpread\":0.0025,\"maxRate\":0.0299,
        \"priority\":10}}}")

echo "$BAND" | jq '.data.id, .data.attributes.baseRate'

PRODUCT_ID=$(uuidgen | tr 'A-Z' 'a-z')

BAND=$(curl -s -X POST $API/risk-bands \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"risk-bands\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"name\":\"Score alto\",
        \"minScore\":700,\"maxScore\":799,
        \"baseRate\":0.0189,\"rateSpread\":0.0025,\"maxRate\":0.0299,
        \"priority\":10}}}")

echo "$BAND" | jq '.data.id, .data.attributes.baseRate'

Resposta esperada — o identificador da faixa e a taxa base que ela guarda:

"b1a2c3d4-0000-0000-0000-000000000001"
0.0189

"b1a2c3d4-0000-0000-0000-000000000001"
0.0189

3. Criar a regra de precificação — já ACTIVE

curl -s -X POST $API/pricing-rules \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"pricing-rules\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"name\":\"Crédito pessoal — app\",
        \"ruleType\":\"DB_RULE\",
        \"status\":\"ACTIVE\",
        \"minAmount\":1000,\"maxAmount\":50000,
        \"minTerm\":6,\"maxTerm\":48,
        \"fees\":[{\"feeType\":\"REGISTRATION\",\"name\":\"TAC\",
                   \"calculationMethod\":\"FIXED\",\"value\":89.90}],
        \"insurances\":[{\"insuranceType\":\"LIFE\",\"name\":\"Prestamista\",
                         \"monthlyRate\":0.035}]}}}" | jq '.data.id'

curl -s -X POST $API/pricing-rules \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"pricing-rules\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"name\":\"Crédito pessoal — app\",
        \"ruleType\":\"DB_RULE\",
        \"status\":\"ACTIVE\",
        \"minAmount\":1000,\"maxAmount\":50000,
        \"minTerm\":6,\"maxTerm\":48,
        \"fees\":[{\"feeType\":\"REGISTRATION\",\"name\":\"TAC\",
                   \"calculationMethod\":\"FIXED\",\"value\":89.90}],
        \"insurances\":[{\"insuranceType\":\"LIFE\",\"name\":\"Prestamista\",
                         \"monthlyRate\":0.035}]}}}" | jq '.data.id'

Resposta esperada — o identificador da regra:

"e5f6a7b8-0000-0000-0000-000000000002"

"e5f6a7b8-0000-0000-0000-000000000002"

4. Calcular o preço

curl -s -X POST $API/calculate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"pricing-calculations\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"creditScore\":742,
        \"requestedAmount\":15000,
        \"numberOfInstallments\":36}}}" \
  | jq '.data.attributes | {approved, interestRate, totalFees, totalInsurance,
                            faixa: .riskBand.name, regra: .pricingRule.name}'

curl -s -X POST $API/calculate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"pricing-calculations\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"creditScore\":742,
        \"requestedAmount\":15000,
        \"numberOfInstallments\":36}}}" \
  | jq '.data.attributes | {approved, interestRate, totalFees, totalInsurance,
                            faixa: .riskBand.name, regra: .pricingRule.name}'

Resposta esperada, com as fórmulas da §8:

{
  "approved": true,
  "interestRate": 0.0214,
  "totalFees": 89.9,
  "totalInsurance": 189,
  "faixa": "Score alto",
  "regra": "Crédito pessoal — app"
}

{
  "approved": true,
  "interestRate": 0.0214,
  "totalFees": 89.9,
  "totalInsurance": 189,
  "faixa": "Score alto",
  "regra": "Crédito pessoal — app"
}

interestRate é 0.0189 + 0.0025. totalInsurance é 15000 × 0.035 / 100 × 36, ou seja 5.25 × 36.

5. Ver a recusa acontecer

curl -s -X POST $API/calculate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"pricing-calculations\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"creditScore\":420,
        \"requestedAmount\":15000,
        \"numberOfInstallments\":36}}}" \
  | jq '.data.attributes | {approved, rejectionReason}'

curl -s -X POST $API/calculate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"pricing-calculations\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"creditScore\":420,
        \"requestedAmount\":15000,
        \"numberOfInstallments\":36}}}" \
  | jq '.data.attributes | {approved, rejectionReason}'

{
  "approved": false,
  "rejectionReason": "No risk band found for credit score 420"
}

{
  "approved": false,
  "rejectionReason": "No risk band found for credit score 420"
}

Status HTTP 200. Isso é proposital — veja §7.

Credenciais de staging, documentadas em AMBIENTES.md. Nunca use credencial de produção em documentação ou script de exemplo.

Montar uma curva de preço completa por produto

Uma curva típica tem quatro faixas. Declare todas com priority explícita e sem sobreposição.

flowchart LR
  S["creditScore"] --> F1["800 a 1000<br/>1,59% · priority 10"]
  S --> F2["700 a 799<br/>1,89% · priority 20"]
  S --> F3["600 a 699<br/>2,49% · priority 30"]
  S --> F4["500 a 599<br/>3,29% · priority 40"]
  S --> F5["abaixo de 500<br/>nenhuma faixa"]
  F5 --> REJ["approved false<br/>No risk band found"]

  style REJ fill:#7d1a1a,stroke:#7d1a1a,color:#fff

for f in "Score muito alto:800:1000:0.0159:10" \
         "Score alto:700:799:0.0189:20" \
         "Score médio:600:699:0.0249:30" \
         "Score baixo:500:599:0.0329:40"; do
  IFS=':' read -r NOME MIN MAX RATE PRIO <<< "$f"
  curl -s -X POST $API/risk-bands \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"data\":{\"type\":\"risk-bands\",\"attributes\":{
          \"productId\":\"$PRODUCT_ID\",\"name\":\"$NOME\",
          \"minScore\":$MIN,\"maxScore\":$MAX,
          \"baseRate\":$RATE,\"maxRate\":0.0399,\"priority\":$PRIO}}}" \
    | jq -r '.data.id // .message'
done

for f in "Score muito alto:800:1000:0.0159:10" \
         "Score alto:700:799:0.0189:20" \
         "Score médio:600:699:0.0249:30" \
         "Score baixo:500:599:0.0329:40"; do
  IFS=':' read -r NOME MIN MAX RATE PRIO <<< "$f"
  curl -s -X POST $API/risk-bands \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"data\":{\"type\":\"risk-bands\",\"attributes\":{
          \"productId\":\"$PRODUCT_ID\",\"name\":\"$NOME\",
          \"minScore\":$MIN,\"maxScore\":$MAX,
          \"baseRate\":$RATE,\"maxRate\":0.0399,\"priority\":$PRIO}}}" \
    | jq -r '.data.id // .message'
done

Resposta esperada — quatro identificadores, um por faixa criada:

"b1a2c3d4-0000-0000-0000-000000000001"
"b1a2c3d4-0000-0000-0000-000000000002"
"b1a2c3d4-0000-0000-0000-000000000003"
"b1a2c3d4-0000-0000-0000-000000000004"

"b1a2c3d4-0000-0000-0000-000000000001"
"b1a2c3d4-0000-0000-0000-000000000002"
"b1a2c3d4-0000-0000-0000-000000000003"
"b1a2c3d4-0000-0000-0000-000000000004"

Armadilhas.

• Nada valida sobreposição. Se você escrever 700:799 e 750:850, as duas ficam ativas e o desempate é priority. Confira com GET /risk-bands?productId=... ordenado — a listagem já vem por priority e depois minScore.
• Score abaixo de 500 fica sem faixa neste exemplo, e toda proposta desse perfil recebe approved: false. Se a sua política é recusar mesmo, isso está certo; se não é, falta uma faixa.
• name é único por produto. Rodar o laço duas vezes devolve 409 na segunda.
• maxRate é o freio. Com maxRate: 0.0399 e uma faixa de baseRate: 0.0329 mais rateSpread: 0.008, o resultado é 0.0409 e o cálculo recusa. Isso é o comportamento desejado, mas surpreende quem esperava que a taxa fosse apenas limitada ao teto.

Rodar uma campanha promocional com data de fim

O rateSpread negativo e a vigência da regra resolvem campanha sem duplicar a curva inteira.

A vigência é filtro de consulta, não estado: a regra entra e sai do cálculo sozinha, sem ninguém publicar nem despublicar nada.

flowchart LR
  A["Antes de 01/09<br/>effectiveFrom no futuro"] --> B["Durante setembro<br/>a regra de campanha vence<br/>priority 1"]
  B --> C["Depois de 30/09<br/>effectiveTo no passado"]
  A -.-> R1["Regra padrão responde"]
  C -.-> R2["Regra padrão volta a responder<br/>campanha continua ACTIVE na listagem"]

  style B fill:#1f6feb,stroke:#1f6feb,color:#fff

# Regra de campanha, prioridade menor que a regra padrão → vence
curl -s -X POST $API/pricing-rules \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"pricing-rules\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"name\":\"Campanha de setembro — TAC zero\",
        \"ruleType\":\"DB_RULE\",\"status\":\"ACTIVE\",\"priority\":1,
        \"fees\":[],
        \"effectiveFrom\":\"2026-09-01T00:00:00.000Z\",
        \"effectiveTo\":\"2026-09-30T23:59:59.000Z\"}}}" | jq '.data.id'

# Regra de campanha, prioridade menor que a regra padrão → vence
curl -s -X POST $API/pricing-rules \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"pricing-rules\",\"attributes\":{
        \"productId\":\"$PRODUCT_ID\",
        \"name\":\"Campanha de setembro — TAC zero\",
        \"ruleType\":\"DB_RULE\",\"status\":\"ACTIVE\",\"priority\":1,
        \"fees\":[],
        \"effectiveFrom\":\"2026-09-01T00:00:00.000Z\",
        \"effectiveTo\":\"2026-09-30T23:59:59.000Z\"}}}" | jq '.data.id'

Armadilhas.

• A campanha zera a tarifa, não a taxa. A taxa vem da faixa, não da regra. Para descontar taxa na campanha, você precisa mexer em rateSpread das faixas — e aí o desconto vale para todo mundo, não só para a campanha. Essa é uma limitação real do modelo (§15).
• priority menor vence. A regra de campanha precisa de priority menor que a regra padrão. Se as duas tiverem 0, o desempate fica indefinido na prática.
• Depois de effectiveTo, a regra some do cálculo sozinha — mas continua ACTIVE na listagem. Isso é intencional: a vigência é filtro de consulta, não mudança de estado.

Descobrir por que o cálculo recusou

Três consultas, sempre na mesma ordem: o que a recusa disse, quais faixas existem, quais regras estão ACTIVE.

flowchart TD
  R["rejectionReason"] --> A{"Qual texto veio?"}
  A -- "No risk band found" --> B["Passo 2: as faixas ativas do produto<br/>o score cabe em alguma?"]
  A -- "No applicable pricing rule found" --> C["Passo 3: as regras ACTIVE do produto<br/>valor, prazo e vigência cobrem a proposta?"]
  A -- "Interest rate exceeds maximum" --> D["Faixa e regra foram achadas.<br/>baseRate + rateSpread passou do maxRate da faixa"]

  style D fill:#1f6feb,stroke:#1f6feb,color:#fff

# 1. O que veio na recusa
curl -s -X POST $API/calculate -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d "$PAYLOAD" \
  | jq '.data.attributes | {approved, rejectionReason, riskBand, pricingRule}'

# 2. As faixas ativas do produto
curl -s "$API/risk-bands?productId=$PRODUCT_ID&isActive=true" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {nome: .attributes.name, min: .attributes.minScore,
                   max: .attributes.maxScore, prio: .attributes.priority}'

# 3. As regras ACTIVE do produto
curl -s "$API/pricing-rules?productId=$PRODUCT_ID&status=ACTIVE" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {nome: .attributes.name, minA: .attributes.minAmount,
                   maxA: .attributes.maxAmount, minT: .attributes.minTerm,
                   maxT: .attributes.maxTerm, de: .attributes.effectiveFrom,
                   ate: .attributes.effectiveTo}'

# 1. O que veio na recusa
curl -s -X POST $API/calculate -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d "$PAYLOAD" \
  | jq '.data.attributes | {approved, rejectionReason, riskBand, pricingRule}'

# 2. As faixas ativas do produto
curl -s "$API/risk-bands?productId=$PRODUCT_ID&isActive=true" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {nome: .attributes.name, min: .attributes.minScore,
                   max: .attributes.maxScore, prio: .attributes.priority}'

# 3. As regras ACTIVE do produto
curl -s "$API/pricing-rules?productId=$PRODUCT_ID&status=ACTIVE" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {nome: .attributes.name, minA: .attributes.minAmount,
                   maxA: .attributes.maxAmount, minT: .attributes.minTerm,
                   maxT: .attributes.maxTerm, de: .attributes.effectiveFrom,
                   ate: .attributes.effectiveTo}'

Ordem de diagnóstico, do erro mais comum ao menos comum:

1. A regra está DRAFT. Criada sem status, ela nasce DRAFT e nunca entra no cálculo. É de longe a causa mais frequente de "No applicable pricing rule found".
2. O productId está errado. Não há chave estrangeira: um UUID inexistente não dá erro, dá "nenhuma faixa encontrada". Confira que o productId do cálculo é literalmente o mesmo da faixa.
3. A faixa não cobre o score. Os limites são inclusivos nos dois lados. Score 800 numa faixa 700–799 não entra.
4. A vigência da regra já passou ou ainda não começou. Compare effectiveFrom e effectiveTo com o horário do servidor, em UTC.
5. A taxa estourou o maxRate. Se rejectionReason menciona exceeds maximum, a faixa e a regra foram encontradas — o problema é baseRate + rateSpread acima do teto da própria faixa.
6. A organização está errada. O organizationId vem do token. Faixa criada com um token e consultada com outro simplesmente não existe do outro lado.

Reajustar a curva inteira sem downtime

# Sobe todas as faixas do produto em 20 pontos-base
curl -s "$API/risk-bands?productId=$PRODUCT_ID&pageSize=100" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -c '.data[] | {id: .id, novo: (.attributes.baseRate + 0.002)}' \
  | while read -r linha; do
      ID=$(echo "$linha" | jq -r .id)
      NOVO=$(echo "$linha" | jq -r .novo)
      curl -s -X PATCH "$API/risk-bands/$ID" \
        -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
        -d "{\"data\":{\"type\":\"risk-bands\",\"id\":\"$ID\",
              \"attributes\":{\"baseRate\":$NOVO}}}" | jq -r '.data.id'
    done

# Sobe todas as faixas do produto em 20 pontos-base
curl -s "$API/risk-bands?productId=$PRODUCT_ID&pageSize=100" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -c '.data[] | {id: .id, novo: (.attributes.baseRate + 0.002)}' \
  | while read -r linha; do
      ID=$(echo "$linha" | jq -r .id)
      NOVO=$(echo "$linha" | jq -r .novo)
      curl -s -X PATCH "$API/risk-bands/$ID" \
        -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
        -d "{\"data\":{\"type\":\"risk-bands\",\"id\":\"$ID\",
              \"attributes\":{\"baseRate\":$NOVO}}}" | jq -r '.data.id'
    done

Armadilhas.

• Não há operação em lote. É um PATCH por faixa, e não há transação envolvendo todas. Se o laço parar no meio, metade da curva ficou reajustada. Rode fora do horário de pico e confira o resultado com um GET no fim.
• O PATCH vale na chamada seguinte. Não há cache neste building block. Propostas em voo no instante do reajuste podem ter pegado a taxa antiga — se isso importa, congele a taxa no seu lado no momento da proposta.
• maxRate não é reajustado junto. Subir baseRate sem subir maxRate pode fazer faixas passarem a recusar. Reajuste os dois.
• Guarde o antes. O evento pricing.risk_band.updated carrega só as mudanças, não o valor anterior. Se você precisa do histórico, faça o GET da curva antes do laço e guarde o retorno.

Entregar a taxa para o Calculations Engine

O Pricing Engine devolve a taxa; a parcela é do Calculations Engine. O encadeamento é do seu orquestrador — não há chamada automática entre os dois (§12).

sequenceDiagram
  autonumber
  participant O as Seu orquestrador
  participant P as Pricing Engine
  participant C as Calculations Engine

  O->>P: POST /pricing/api/v1/calculate
  P-->>O: interestRate 0.0214 · fees · isFinanced
  Note over O: O orquestrador compõe o presentValue.<br/>Tarifa financiada muda o principal.
  O->>C: POST /loan-payment-calculator/calculations<br/>interestRate · numberOfPayments · presentValue
  C-->>O: payment 601.81

TAXA=$(curl -s -X POST $API/calculate -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d "$PAYLOAD" \
  | jq -r '.data.attributes.interestRate')

CALC=https://calculations.bb.stg.catalisa.app/calculations-engine/api/v1/calculations

curl -s -X POST "$CALC/loan-payment-calculator/calculations" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"loan-payment-calculation\",\"attributes\":{
        \"interestRate\":$TAXA,
        \"numberOfPayments\":36,
        \"presentValue\":15000}}}" | jq '.data.attributes.payment'

TAXA=$(curl -s -X POST $API/calculate -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d "$PAYLOAD" \
  | jq -r '.data.attributes.interestRate')

CALC=https://calculations.bb.stg.catalisa.app/calculations-engine/api/v1/calculations

curl -s -X POST "$CALC/loan-payment-calculator/calculations" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"loan-payment-calculation\",\"attributes\":{
        \"interestRate\":$TAXA,
        \"numberOfPayments\":36,
        \"presentValue\":15000}}}" | jq '.data.attributes.payment'

Com interestRate: 0.0214, numberOfPayments: 36 e presentValue: 15000, a resposta é 601.81 — número conferido rodando o calculador diretamente.

Armadilhas.

• A convenção de taxa é a mesma nos dois. interestRate é decimal mensal (0.0214) nos dois building blocks. Não multiplique por 100 no caminho.
• effectiveAnnualRate não é CET. Para o CET você precisa do valor líquido liberado — valor solicitado menos IOF menos tarifas não financiadas — e do endpoint de CET do Calculations Engine. §12 mostra a sequência.
• Tarifa financiada muda o principal. Se isFinanced: true, a tarifa entra no valor financiado, e o presentValue que você manda para o cálculo da parcela não é mais o requestedAmount. O Pricing Engine devolve a flag; a composição é sua.

Seja honesto na venda: o Pricing Engine não chama nenhum outro building block. Não há facade, não há ModuleClient, não há import cruzado — PricingService depende exclusivamente de RiskBandRepository e PricingRuleRepository. E nenhum outro building block chama este: o Banking Product Portfolio documenta explicitamente que o POST /simulate dele devolve parâmetros resolvidos, sem taxa, sem parcela e sem CET. A composição da esteira é feita pelo orquestrador do cliente ou pelo Decision Platform. O diagrama abaixo é o desenho da esteira, não uma cadeia de chamadas automáticas.

Onde este bloco entra na esteira de crédito

flowchart TD
  PROP["PROPOSTA<br/>cliente pede R$ 15.000 em 36x"]

  PROP --> BPP["BANKING PRODUCT PORTFOLIO — o mandato<br/>POST /simulate<br/>devolve os LIMITES: faixa de valor, faixa de TAXA,<br/>prazo, iofDailyRate. Não devolve preço."]

  BPP --> DEC["DECISION PLATFORM + DECISION ENGINE — a decisão<br/>bureau, política, DMN<br/>aprovado? qual limite? qual SCORE?"]

  DEC -- "score em mãos" --> PE["PRICING ENGINE — você está aqui<br/>POST /pricing/api/v1/calculate<br/>entrada: productId, creditScore, requestedAmount, prazo<br/>saída: interestRate, fees, commissions, insurances<br/>+ riskBand e pricingRule que decidiram"]

  PE --> CHK["O orquestrador confere:<br/>interestRate cabe no teto do Portfolio?"]
  CHK --> CE["CALCULATIONS ENGINE — a matemática<br/>parcela PRICE ou SAC · IOF · CET sobre o líquido liberado<br/>entradas: valor, prazo, interestRate daqui,<br/>tarifas daqui, iofDailyRate do Portfolio"]

  CE -- "parcela e CET" --> CT["CONTRATO<br/>guarda riskBand.id, pricingRule.id e versionId. Sempre."]
  CT --> ES["E-SIGNATURE assina"]
  CT --> AT["AUDIT TRAIL registra"]
  CT --> BI["BILLING cobra"]

  style PE fill:#1f6feb,stroke:#1f6feb,color:#fff
  style CT fill:#1a7d4a,stroke:#1a7d4a,color:#fff

A fronteira entre este bloco e o Calculations Engine, em uma frase. O Pricing Engine decide quanto custa — a taxa e os encargos, a partir do risco e da política comercial. O Calculations Engine calcula como isso se paga — a parcela, o cronograma, o IOF e o CET, a partir de números que alguém já decidiu. Um é política; o outro é aritmética. Por isso um tem banco de dados e escopo de tenant, e o outro é stateless e sem persistência.

Por que esse encadeamento é o argumento comercial. Cada peça sozinha é substituível. Junto, o encaixe é o produto: o teto de taxa que o Portfolio congelou no snapshot é o limite que a taxa daqui precisa respeitar; a interestRate daqui é a entrada da parcela lá no Calculations; e o par riskBand.id mais pricingRule.id que o contrato guarda é o que permite, dois anos depois, reconstruir a política que produziu aquele preço.

Variáveis de ambiente

Este building block não tem variável própria. Usa só a configuração compartilhada.

Dependências de infraestrutura

Sem S3, sem fila, sem serviço externo. provedores: 0 no frontmatter é literal.

Limites

Catálogo de erros

Recusa de crédito não é erro. approved: false vem com status 200. Não trate como 4xx.

Observabilidade

• GET /pricing/health devolve identificação e versão do build. Não sonda o banco — não é uma verificação de dependência, é um sinal de vida do processo.
• Seis eventos são publicados: pricing.risk_band.created, .updated, .deleted e pricing.pricing_rule.created, .updated, .deleted. Todos carregam metadata.organizationId e metadata.timestamp, e os de atualização carregam o objeto de mudanças recebido no PATCH.
• Não há métrica própria de latência de cálculo nem contador de recusas. Se a taxa de approved: false é um indicador do seu negócio, instrumente do lado do chamador — o building block não expõe isso hoje (§15).

Isolamento entre tenants

O organizationId é claim assinado no JWT. As onze rotas aplicam o middleware local requireOrganization, que devolve 403 quando o claim está ausente, antes de qualquer regra de negócio. Nenhuma rota lê organizationId do corpo da requisição — o valor sempre vem de c.get('user').organizationId. Nos repositórios, toda leitura filtra organizationId e deletedAt: null na mesma cláusula; buscar por ID uma faixa de outra organização devolve 404, não 403, para não confirmar a existência do recurso.

flowchart TD
  T["JWT assinado pelo IAM<br/>claim organizationId"] --> M["requireOrganization<br/>403 se o claim não existe"]
  M --> C["c.get('user').organizationId"]
  C --> S["Serviço"]
  B["Corpo da requisição"] -. "organizationId NUNCA<br/>é lido daqui" .-> X["Ignorado"]
  S --> F["findById(id, organizationId)"]
  F -- "outra organização" --> N404["404 — não confirma<br/>a existência do recurso"]
  F -- "mesma organização" --> W["update ou softDelete<br/>recebem só o id"]

  style X fill:#7d1a1a,stroke:#7d1a1a,color:#fff
  style N404 fill:#1f6feb,stroke:#1f6feb,color:#fff

As operações de escrita (update, softDelete) recebem apenas o id, mas os serviços só as chamam depois de um findById(id, organizationId) que já falhou com 404 caso o recurso não pertença ao tenant. O isolamento é garantido na camada de serviço; não há Row-Level Security no schema pricing.

Dados sensíveis

Este building block não guarda dado pessoal. Não há nome, CPF, e-mail nem telefone nas duas tabelas. O creditScore e o customerId chegam na requisição de cálculo e não são persistidos — o cálculo é feito em memória e a resposta é devolvida. customerId sequer é usado no cálculo.

Do ponto de vista de LGPD, isso significa que o Pricing Engine não é controlador nem operador de dado pessoal em repouso. O que ele guarda é política comercial da organização: faixas, taxas, tarifas e comissões — informação sensível do ponto de vista concorrencial, não pessoal. É por isso que o isolamento entre tenants é a preocupação central desta seção, e não a anonimização.

Autenticação e permissões

Bearer JWT verificado localmente com JWT_SECRET (HS256). Nove permissões, todas do vocabulário compartilhado do IAM:

A separação entre PRICING_CALCULATE e as permissões de gestão é deliberada: a esteira de originação precisa apenas de PRICING_CALCULATE. Um token de integração que só calcula não consegue ler nem alterar a curva de preço da instituição.

Proteções de borda

O applyCommonMiddleware aplica limite de corpo de 1 MB, CORS fail-safe (sem origens configuradas em produção, bloqueia cross-origin), cabeçalhos de segurança (HSTS, CSP, nosniff, X-Frame-Options) e rate limit global. Em DEPLOYMENT_MODE=standalone — o modo de produção — esse conjunto é aplicado pelo próprio app.ts do módulo, não herdado do monolito.

Exclusão lógica

Faixas e regras usam deletedAt. A linha sobrevive à remoção, que é o que auditoria e obrigação de retenção exigem. Não há expurgo automatizado.

Enquadramento regulatório — o que este building block faz e o que ele não faz

Ele não contém nenhuma regra regulatória codificada: não há teto de juros, não há alíquota, não há validação de conformidade. As taxas que você declara são as que ele aplica. Consequências práticas que precisam estar claras na venda:

• O teto de juros do consignado, definido pelo CNPS e pelo Conselho de Recursos da Previdência Social nos termos da Lei 10.820/2003 — alterada pela MP 1.292/2025 e convertida na Lei 15.179/2025 —, não é verificado aqui. Use maxRate na faixa para materializar o teto que a sua área jurídica determinar, e trate isso como controle seu, não como conformidade nossa.
• O Custo Efetivo Total, exigido pela Resolução CMN 4.881/2020, em vigor desde 1º de fevereiro de 2021 e que substituiu a revogada Resolução 3.517/2007, não é produzido por este building block. O campo effectiveAnnualRate é composição de juros e nada mais. O CET é apurado no Calculations Engine, a partir do valor líquido liberado.
• O IOF, regido pelo Decreto 6.306/2007, também não aparece aqui.

Em resumo: o Pricing Engine é a ferramenta com que você implementa a sua política, inclusive a parte dela que é imposta por norma. Ele não a garante.

As catorze limitações abaixo se dividem em quatro situações, e a diferença entre elas importa na hora de decidir se dá para vender:

flowchart TD
  L["Limitações conhecidas"] --> A["Especificado, não implementado<br/>o campo existe e não faz nada<br/>ruleType DECISION · customerId · context"]
  L --> B["Conhecido<br/>simplificação assumida, documentada no código<br/>PERCENTAGE_OF_TOTAL · seguro sobre valor solicitado<br/>evento que falha após a gravação"]
  L --> C["Roadmap<br/>sobreposição de faixas · versionamento da política<br/>simulação em lote · health que sonda o banco · métricas"]
  L --> D["Por design<br/>effectiveAnnualRate não é CET · productId sem FK<br/>cálculo sem persistência · sem Row-Level Security"]

  style A fill:#7d1a1a,stroke:#7d1a1a,color:#fff

O Pricing Engine calcula o score do cliente?

Não. Ele consome o score que você já tem. Quem produz score é o seu modelo, o bureau, ou o Decision Platform somado ao Decision Engine. Este building block responde "dado este score, qual o preço", e essa separação é deliberada: modelar risco e aplicar preço são problemas diferentes, com ciclos de mudança diferentes e donos diferentes dentro da instituição.

Por que a recusa vem com status 200?

Porque não ter preço para um perfil é uma decisão de negócio, não uma falha de integração. Se a recusa fosse 4xx, a sua esteira precisaria inspecionar o corpo do erro para distinguir "score fora de faixa" de "o serviço caiu" — e alguém acabaria tratando as duas coisas do mesmo jeito num catch. Cheque approved antes de ler qualquer outro campo da resposta.

Posso usar o effectiveAnnualRate como CET na proposta ao cliente?

Não. effectiveAnnualRate é só a anualização composta da taxa mensal: (1 + interestRate)^12 − 1. Ele não inclui tarifa, comissão, seguro nem IOF. O Custo Efetivo Total é exigido pela Resolução CMN 4.881/2020, precisa considerar todos os encargos e o valor efetivamente liberado, e é apurado pelo Calculations Engine.

Criei a faixa e a regra, mas o cálculo diz que não achou regra. Por quê?

Quase certamente a regra nasceu DRAFT. Sem "status": "ACTIVE" no corpo, o padrão do schema é DRAFT, e só regra ACTIVE entra no cálculo. É o chamado de suporte mais comum deste building block. A segunda causa mais comum é productId diferente entre a faixa, a regra e o cálculo — não há chave estrangeira que avise.

O que acontece se duas faixas cobrirem o mesmo score?

O cálculo pega a de menor priority, e ninguém avisa que há sobreposição. Se as duas tiverem a mesma priority, a escolha depende da ordem que o Postgres devolver, o que na prática é imprevisível. Declare priority explícita em todas as faixas e trate a checagem de sobreposição como responsabilidade sua, hoje.

Como eu reconstruo, dois anos depois, por que aquele contrato saiu a 2,49%?

Guardando riskBand.id e pricingRule.id na sua proposta no momento do cálculo. Este building block não versiona a política nem persiste o resultado do cálculo — se você alterar a baseRate da faixa, o valor antigo se perde. Guardar os dois identificadores permite pelo menos identificar qual faixa e qual regra decidiram; para guardar os valores da época, grave a resposta inteira do cálculo do seu lado. É a limitação mais relevante da §15.

Dá para dar desconto de taxa numa campanha sem mexer na curva inteira?

Hoje, não de forma limpa. A taxa vem da faixa, e a campanha é modelada como regra — que controla tarifa, comissão, seguro e vigência, mas não a taxa. Na prática, campanha de taxa exige criar faixas paralelas com rateSpread negativo e um productId próprio para o canal da campanha. É contornável, mas é contorno.

Preciso do Banking Product Portfolio para usar o Pricing Engine?

Não. Os dois são independentes e não se chamam. O que o Banking Product Portfolio acrescenta é o mandato: a faixa minInterestRate–maxInterestRate congelada numa versão de produto, contra a qual o seu orquestrador confere se a taxa daqui é vendável. Sem ele, o teto que existe é o maxRate da faixa, que você mesmo declara.

Este building block me deixa em conformidade com a regulação de crédito?

Não, e essa é uma resposta que precisa ser dada assim. Ele não codifica teto de juros, alíquota nem regra de divulgação. Ele é a ferramenta com que você implementa a política que a sua área jurídica determinou, inclusive a parte imposta por norma. Quem garante conformidade é o seu processo; o que ele oferece é a mecânica de aplicar e a rastreabilidade de ter aplicado.

Qual a diferença entre este e o Calculations Engine?

Este decide quanto custa — taxa, tarifa, comissão, seguro — a partir do risco e da política comercial. O Calculations Engine calcula como isso se paga — parcela, cronograma, IOF, CET — a partir de números que alguém já decidiu. Um é política, com banco de dados e escopo de tenant; o outro é aritmética, stateless e sem persistência.

_{Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md}