Bureaus

O Bureaus fica entre a sua esteira e os fornecedores de dado cadastral brasileiro. Recebe um documento e uma pergunta, escolhe o fornecedor, devolve um formato estável, cobra uma vez só pelo que já perguntou e deixa rastro de quem perguntou e por quê.

Ele existe porque chamar a API do bureau é a parte fácil. O que custa caro é o que vem em volta: o mesmo CPF pago três vezes na mesma proposta, o token do fornecedor em texto puro na configuração, a fatura que ninguém consegue reconciliar, e nenhum registro da finalidade quando a fiscalização pergunta.

Hoje o bloco fala com o BigDataCorp, com 17 tipos de consulta implementados sobre CPF e CNPJ, mais um fornecedor sintético para desenvolvimento e teste. O contrato de fio foi desenhado para que Serasa, QUOD ou Boa Vista entrem depois sem quebrar quem já integrou.

Uma esteira de crédito toca o mesmo CPF mais de uma vez: na pré-análise, na aplicação da política e na formalização. Cada toque é uma consulta paga.

O preço unitário é baixo — três centavos —, e é justamente por isso que o desperdício não aparece. Ninguém revisa uma cobrança de três centavos. O problema aparece na fatura do mês, quando o volume multiplicou o descuido por cem mil.

Ao lado disso, três coisas que só aparecem quando já é tarde:

• O segredo. O token do fornecedor costuma ficar em texto puro na configuração da fonte de dados, porque é onde é conveniente colocá-lo.
• A conta. Sem medição por organização, a empresa descobre quanto consultou quando o boleto chega, e não tem como atribuir o custo a quem consumiu.
• A finalidade. Consultar dado pessoal de terceiro exige base legal declarada. Um fetch no meio do código não registra por que a consulta aconteceu, e a prova disso é exatamente o que a ANPD pede.

• Cache que respeita o que muda. TTL por tipo de consulta — dado cadastral vive trinta dias, cobrança vive um. Quem chama pode exigir dado fresco com maxAgeSeconds, então o cache é escolha de quem paga e não imposição.
• Uma cobrança por documento, mesmo no pico. Requisições simultâneas do mesmo CPF são deduplicadas com trava no Redis: a primeira consulta, as outras esperam o resultado dela.
• Credencial cifrada por organização, validada antes de ser gravada e nunca devolvida pela API.
• Custo medido e faturável. Cada consulta cobrada vira evento de uso no Billing, com o identificador da consulta como chave de idempotência.
• Trilha que prova a finalidade. Registro imutável por consulta, com o documento em HMAC e máscara, nunca em claro.
• Um contrato só. Trocar ou somar fornecedor não muda o formato que a esteira consome.

Esteira que consulta o mesmo CPF três vezes

Contexto. Fintech de crédito pessoal, quarenta mil propostas por mês. A esteira consulta dado cadastral na pré-análise, de novo ao aplicar a política, e mais uma vez na formalização.

Sem o bloco. Cento e vinte mil consultas pagas por mês para quarenta mil propostas.

Com o bloco. A primeira popula o cache com TTL de trinta dias; as outras duas leem de lá. Quarenta mil consultas pagas, e a esteira não mudou uma linha — o cache é transparente para quem chama.

Analista precisa provar por que consultou um CPF

Contexto. Auditoria interna pergunta por que o CPF de um não-cliente foi consultado em março.

Sem o bloco. Log de aplicação, se houver, sem finalidade nem base legal.

Com o bloco. GET /queries filtrando por documento — o valor vira HMAC no handler, então o CPF não chega a aparecer nem na query string. A resposta traz quem consultou, quando, com que finalidade e sob qual base legal.

Empresa quer saber se o fornecedor entrega o que cobra

Contexto. O contrato inclui um dataset de faturamento presumido que custa mais que o dobro da consulta cadastral.

Com o bloco. GET /usage mostra consultas, custo e taxa de acerto do cache por período e por tipo. Se um tipo custa caro e devolve pouco, o dado para renegociar está ali — e foi assim que descobrimos que um tipo estava retornando vazio por erro de mapeamento, não por ausência de dado.

O mercado brasileiro de consulta cadastral tem três faixas. Os birôs de crédito — Serasa, Boa Vista, QUOD, SPC — que vendem score e restrição. As plataformas de dado — BigDataCorp, Neoway, Assertiva — que vendem cadastro, contato, endereço e processo. E a fonte primária estatal, o Serpro Datavalid, que valida contra a base oficial em vez de retornar.

Este bloco não compete com nenhum: é a camada que fala com todos.

Uma armadilha que o desenho resolve. O score da QUOD vai de 300 a 1000 e o da Serasa de 0 a 1000. Um score 300 da QUOD é o pior valor possível; um 300 da Serasa está a um terço do caminho. O canônico guarda value e scale juntos — gravar só o número perde a informação, e nenhum refactor recupera depois o que nunca foi capturado.

Unidade: consulta a bureau. Precificação do bloco em definição.

Drivers de custo: consultas efetivamente cobradas pelo fornecedor, taxa de acerto do cache, e quais datasets estão habilitados no contrato.

A tabela pública do BigDataCorp para a consulta cadastral é escalonada por volume mensal:

Uma esteira que toca o mesmo documento três vezes paga três vezes. O cache transforma isso em uma. Em quarenta mil propostas por mês, é a diferença entre consumir cento e vinte mil consultas e consumir quarenta mil — e, de quebra, descer de faixa de preço.

O custo é medido, não estimado às cegas. Sai marcado com estimated: true quando vem da tabela pública; gravando o preço negociado em settings.priceOverrides, passa a sair com estimated: false.

flowchart TB
  ESTEIRA["Decision Platform<br/>fonte do tipo BUREAU"]
  APP["Outro consumidor<br/>Customers, backoffice"]

  subgraph BUREAUS["Building Block Bureaus"]
    ROTA["POST /queries<br/>valida documento e finalidade"]
    CACHE{"cache válido?"}
    LOCK["trava no Redis<br/>deduplicação em voo"]
    DRIVER["driver do fornecedor<br/>traduz para o canônico"]
    TRILHA["trilha imutável<br/>HMAC + máscara"]
  end

  BDC["BigDataCorp"]
  BILL["Billing<br/>via fachada"]

  ESTEIRA --> ROTA
  APP --> ROTA
  ROTA --> CACHE
  CACHE -- "sim" --> TRILHA
  CACHE -- "não" --> LOCK
  LOCK --> DRIVER
  DRIVER --> BDC
  DRIVER --> TRILHA
  TRILHA --> BILL

O que o bloco não faz, e quem faz

A fronteira que sustenta isso: bureau responde sobre um documento; KYC responde sobre uma pessoa presente. São contratos comerciais, ciclos de mudança e exigências regulatórias diferentes.

Sem dependência direta de outro building block. O consumo vai ao Billing pela fachada IBillingFacade; o Decision Platform chega aqui pela IBureausFacade.

Glossário

Modelo de dados

costAmount é Decimal(15,4) e não (15,2) como o resto do schema: o preço unitário de bureau tem três casas (R$ 0,024), e truncar em duas transforma medição de custo em ficção.

Estados de uma consulta

Os cinco valores são deliberadamente distintos. NOT_FOUND é resposta legítima e cobrada; NOT_SUPPORTED é configuração e não custa nada. Colapsar o par destrói a medição de custo e faz o retry insistir numa resposta que não vai mudar.

Consultas

POST /bureaus/api/v1/queries

Request

{
  "kind": "person.basic",
  "subject": { "type": "CPF", "value": "529.982.247-25" },
  "purpose": "credit_analysis",
  "maxAgeSeconds": 86400,
  "includeRaw": true
}

{
  "kind": "person.basic",
  "subject": { "type": "CPF", "value": "529.982.247-25" },
  "purpose": "credit_analysis",
  "maxAgeSeconds": 86400,
  "includeRaw": true
}

Resposta 201

{
  "data": {
    "queryId": "3f2a0c1e-…",
    "kind": "person.basic",
    "provider": "BIGDATACORP",
    "status": "FOUND",
    "subject": { "type": "CPF", "masked": "***.***.247-25" },
    "data": { "name": "…", "taxIdStatus": "REGULAR", "deceased": false },
    "raw": { "…": "resposta literal do fornecedor" },
    "asOf": "2026-07-10T00:00:00.000Z",
    "queriedAt": "2026-08-25T14:02:11.000Z",
    "cached": false,
    "cost": { "amount": "0.0300", "currency": "BRL", "estimated": true },
    "elapsedMs": 412
  }
}

{
  "data": {
    "queryId": "3f2a0c1e-…",
    "kind": "person.basic",
    "provider": "BIGDATACORP",
    "status": "FOUND",
    "subject": { "type": "CPF", "masked": "***.***.247-25" },
    "data": { "name": "…", "taxIdStatus": "REGULAR", "deceased": false },
    "raw": { "…": "resposta literal do fornecedor" },
    "asOf": "2026-07-10T00:00:00.000Z",
    "queriedAt": "2026-08-25T14:02:11.000Z",
    "cached": false,
    "cost": { "amount": "0.0300", "currency": "BRL", "estimated": true },
    "elapsedMs": 412
  }
}

Erros

NOT_FOUND, NOT_SUPPORTED e DENIED voltam com HTTP 201: são respostas do fornecedor, não erros. O status do envelope é quem distingue.

Fornecedores

A credencial nunca é devolvida, nem cifrada.

Catálogo, consumo e manutenção

1. Autenticar

TOKEN=$(curl -s -X POST https://iam.stg.catalisa.app/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)

TOKEN=$(curl -s -X POST https://iam.stg.catalisa.app/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. Cadastrar o fornecedor

A credencial é validada contra a API do fornecedor antes de ser cifrada e gravada — guardar segredo que não funciona só adia a descoberta para a primeira consulta de produção.

curl -X POST https://bureaus.stg.catalisa.app/api/v1/providers \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "bigdatacorp-prod",
    "providerType": "BIGDATACORP",
    "credentials": { "accessToken": "SEU-ACCESSTOKEN", "tokenId": "SEU-TOKENID" },
    "isDefault": true
  }'

curl -X POST https://bureaus.stg.catalisa.app/api/v1/providers \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "bigdatacorp-prod",
    "providerType": "BIGDATACORP",
    "credentials": { "accessToken": "SEU-ACCESSTOKEN", "tokenId": "SEU-TOKENID" },
    "isDefault": true
  }'

3. Consultar

curl -X POST https://bureaus.stg.catalisa.app/api/v1/queries \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "kind": "person.basic",
    "subject": { "type": "CPF", "value": "529.982.247-25" },
    "purpose": "credit_analysis"
  }'

curl -X POST https://bureaus.stg.catalisa.app/api/v1/queries \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "kind": "person.basic",
    "subject": { "type": "CPF", "value": "529.982.247-25" },
    "purpose": "credit_analysis"
  }'

Resposta esperada:

{ "data": { "status": "FOUND", "cached": false,
  "cost": { "amount": "0.0300", "currency": "BRL", "estimated": true } } }

{ "data": { "status": "FOUND", "cached": false,
  "cost": { "amount": "0.0300", "currency": "BRL", "estimated": true } } }

4. Repetir a mesma consulta

{ "data": { "status": "FOUND", "cached": true, "cost": null } }

{ "data": { "status": "FOUND", "cached": true, "cost": null } }

Custo nulo. É esse o ponto do bloco.

Exigir dado fresco numa etapa crítica. maxAgeSeconds: 0 força a ida ao fornecedor mesmo com cache válido. Útil na formalização, onde vale pagar de novo para não decidir com dado de trinta dias.

Descobrir o que o contrato cobre. Peça vários datasets numa chamada só à API do fornecedor: os não contratados voltam com código negativo sem custo, e o próprio fornecedor diz o que está liberado.

Ajustar o TTL de um tipo de consulta. A tabela bureau_cache_policies aceita TTL por kind e por organização, sobrescrevendo o padrão do catálogo.

Forçar reconsulta de um documento. POST /cache/invalidate com o subject apaga a entrada em todos os fornecedores configurados.

Fonte BUREAU no Decision Platform

{
  "name": "bureau-cadastral",
  "type": "BUREAU",
  "typeConfig": {
    "kind": "person.basic",
    "subjectField": "proposta.cpf",
    "subjectType": "CPF",
    "purpose": "credit_analysis",
    "maxAgeSeconds": 86400
  },
  "inputMapping": [
    { "path": "$.name",        "targetField": "nomeBureau" },
    { "path": "$.taxIdStatus", "targetField": "situacaoCpf" },
    { "path": "$._cached",     "targetField": "veioDoCache" }
  ]
}

{
  "name": "bureau-cadastral",
  "type": "BUREAU",
  "typeConfig": {
    "kind": "person.basic",
    "subjectField": "proposta.cpf",
    "subjectType": "CPF",
    "purpose": "credit_analysis",
    "maxAgeSeconds": 86400
  },
  "inputMapping": [
    { "path": "$.name",        "targetField": "nomeBureau" },
    { "path": "$.taxIdStatus", "targetField": "situacaoCpf" },
    { "path": "$._cached",     "targetField": "veioDoCache" }
  ]
}

subjectField é o que diferencia esta fonte da HTTP: em vez de uma URL fixa, o documento sai do input da execução, então a mesma fonte serve qualquer proposta. Além do canônico, o handler expõe _status, _cached, _asOf e _queryId, para que a política possa ter uma regra para "sem registro no bureau".

Variáveis de ambiente

A master key faz dois trabalhos, então trocá-la invalida todo o cache existente além de tornar ilegível a credencial gravada. Ela é carregada sob demanda — padrão da casa —, então um deploy sem ela sobe com /health verde e falha na primeira consulta, com a mensagem BUREAUS_CREDENTIAL_MASTER_KEY is not configured.

Configuração por organização, sem deploy

Manutenção

A limpeza de cache é automática, com trava no Redis para que só uma réplica varra a tabela por rodada. A purga de payload é endpoint e precisa de cron externo: retentionDays é decisão de negócio, não constante de código, e o disparo fica auditável.

A purga apaga o dado pessoal e preserva o registro da consulta, porque é o registro que prova que havia finalidade declarada. Apagar os dois juntos destruiria exatamente a prova que se quer ter numa fiscalização.

Fornecedores

Autenticação é assunto do driver, nunca do framework: o BigDataCorp autentica em header e a Serasa, no corpo da requisição.

O documento nunca é gravado em claro. São três representações, cada uma com um trabalho:

A busca na trilha por documento converte o valor em HMAC no handler — o documento não chega a aparecer no log de acesso.

Finalidade obrigatória. purpose não tem valor padrão. O atrito é intencional: campo opcional em bloco de compliance nunca é preenchido depois, e o valor dele é ser completo.

Retenção em duas velocidades. O payload expira com a política da organização; o registro da consulta fica.

Credencial. Cifrada com aes-256-gcm pela primitiva compartilhada @shared/lib/credential-crypto, validada antes de gravar, e nunca devolvida pela API — nem em resposta, nem em log, nem em evento.

Proteção contra SSRF. Toda saída HTTP passa pelo guard compartilhado, que resolve o nome e bloqueia faixa privada, loopback e link-local. Apontar a baseUrl de um fornecedor para o endereço de metadata de nuvem é recusado.

Isso substitui uma consulta ao Serasa?

Não. O bloco é a camada de integração, não o dado. Ele fala com o fornecedor que você contratar. Hoje há driver para o BigDataCorp; Serasa, QUOD e Boa Vista entram como drivers novos, sem mudar o formato que a esteira consome.

Por que NOT_FOUND volta com HTTP 201 e não 404?

Porque é resposta, não erro — e é cobrada pelo fornecedor. Tratá-la como erro estragaria a medição de custo e faria o retry insistir numa resposta que não vai mudar. O status do envelope é quem distingue.

Posso comparar o score de dois birôs diferentes?

Não pelo número cru. A QUOD vai de 300 a 1000 e a Serasa de 0 a 1000. Por isso o canônico guarda value e scale juntos: dá para normalizar quando houver dois fornecedores, inclusive retroativamente sobre o histórico.

O cache pode me fazer decidir com dado velho?

Pode, e é por isso que o TTL é curto no que muda rápido — cobrança vive um dia, dado cadastral trinta. Quem chama controla com maxAgeSeconds, e o envelope sempre informa cached e asOf.

Preciso do Billing para usar?

Não. Sem conta de faturamento configurada, o consumidor registra no log e segue; o consumo continua visível em GET /usage, que é a fonte de verdade do bloco.

Um campo do canônico veio nulo mas o dado está no raw. E agora?

É nome de chave divergente. Se for o nome do dataset, resolve em settings.datasetOverrides — configuração, não release. Se for a chave da resposta, é ajuste no mapeamento do driver. Em ambos os casos o raw está lá, e quem consome pode se virar enquanto isso.

Ele faz KYC?

Não, e vale ser categórico. Bureau responde sobre um documento; KYC responde sobre uma pessoa presente. Biometria, prova de vida e documentoscopia são outro problema, com outro ciclo e outra exigência regulatória. Contrate um provedor especializado e guarde o resultado.