Catalisa.Building Blocks
Catálogo/Dados/Bureaus

Bureaus

Beta

Consulta a bureau com cache que impede pagar duas vezes pelo mesmo CPF

18
Endpoints
5
Entidades
2
Provedores
Tenant
Escopo
3032
Porta
2026-08
Desde

A camada entre a sua esteira e os fornecedores de dado cadastral brasileiro: formato estável, credencial cifrada, uma cobrança por documento consultado e trilha de quem perguntou o quê e por quê.

Para quem é
  • Fintechs de crédito que consultam bureau em mais de uma etapa da mesma proposta e pagam por todas
  • Times que hoje chamam a API do bureau direto do código da esteira, com o token no header e nada mais
  • Operações que precisam provar à auditoria a finalidade de cada consulta a dado pessoal de terceiro
Substitui
  • O `fetch` para a API do bureau espalhado pelo código da esteira
  • A planilha que tenta reconciliar a fatura do fornecedor com o que a empresa acha que consultou
  • O cache improvisado em Redis que ninguém sabe quando expira
O que não é
  • Um motor de decisão — não aplica regra sobre o dado que traz
  • Um serviço de KYC com biometria, prova de vida ou documentoscopia
  • Um cadastro de clientes — não guarda o cliente, guarda a consulta
O que dá para fazer

16 endpoints em 4 recursos.

Explorar a API →
01

Resumo executivo

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, teste e demonstração — que também responde score e restrição, e por isso em produção só existe para organização liberada pelo operador da plataforma (§13). O contrato de fio foi desenhado para que Serasa, QUOD ou Boa Vista entrem depois sem quebrar quem já integrou.

Consulta cadastralR$ 0,030 na tabela pública do fornecedor
Acerto de cache218 ms → 10 ms, custo zero
Consultas de uma esteira típica no mesmo CPF3 (pré-análise, política, formalização)
Cobranças com o bloco1

02

O problema

negócio

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.

03

Proposta de valor

negócio
  • 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.

04

Casos de uso reais

negócio

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.


05

Mercado e diferenciais

negócio

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.

Integração diretaCom o Bureaus
Mesmo CPF em três etapas3 cobranças1
Token do fornecedorTexto puro na configCifrado, nunca devolvido
Custo por organizaçãoDescoberto na faturaGET /usage
Finalidade da consultaNão registradaCampo obrigatório, em trilha imutável
Trocar de fornecedorReescrever quem consomeTrocar a configuração

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.


06

Modelo de cobrança e ROI

negócio

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:

Consultas no mêsPreço unitário
1 – 10.000R$ 0,030
10.001 – 50.000R$ 0,029
50.001 – 100.000R$ 0,027
100.001 – 500.000R$ 0,026
500.001 – 1.000.000R$ 0,024

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.


07

Arquitetura

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

Não fazQuem faz
Decidir com o dado — regra, árvore, tabela DMNDecision Engine
Orquestrar a esteira, callback, filaDecision Platform
Guardar o cadastro do clienteCustomers
Ler documento em imagemData Extraction
Biometria, prova de vida, documentoscopiaFora do escopo

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.


08

Conceitos e modelo de dados

Glossário

TermoSignifica
kindO tipo de pergunta, com namespace: person.basic, company.lawsuits
CanônicoO formato estável do bloco, igual para qualquer fornecedor
rawA resposta literal do fornecedor, sempre devolvida ao lado do canônico
asOfQuando a fonte apurou o dado — diferente de queriedAt, que é quando nós chamamos
purposeFinalidade declarada da consulta. Obrigatória, sem valor padrão
SujeitoO documento consultado. Gravado como HMAC, máscara e, opcionalmente, cifrado

Modelo de dados

Modelo PrismaTabelaPropósitoCampos-chave
BureauProviderConfigbureau_provider_configsFornecedor por organizaçãocredentials cifrado, settings, isDefault
BureauQuerybureau_queriesTrilha imutável e resultadosubjectHash, subjectMasked, purpose, billable, costAmount
BureauCacheEntrybureau_cache_entriesCache persistentecacheKey (HMAC), expiresAt
BureauCachePolicybureau_cache_policiesTTL por kind, por organizaçãokind, ttlSeconds
BureauSimulatedProviderGrantbureau_simulated_provider_grantsA concessão do fornecedor simulado (MOCK) a uma organização (§13). Revogar não apaga a linha, e a próxima concessão é uma linha novaorganizationId, reason, grantedBy/grantedAt, revokedBy/revokedAt. Índice único parcial: uma concessão ativa por organização — só no SQL da migration

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.


09

Referência da API

Consultas

MétodoRotaDescriçãoPermissão
POST/bureaus/api/v1/queriesConsulta síncronaBUREAUS_QUERY
POST/bureaus/api/v1/queries/batchLote, resultado item a itemBUREAUS_QUERY
GET/bureaus/api/v1/queriesA trilhaBUREAUS_READ
GET/bureaus/api/v1/queries/:idResultado, canônico e brutoBUREAUS_READ

POST /bureaus/api/v1/queries

Request

json
{
  "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
}
CampoTipoObrigatórioDescrição
kindenumsimTipo de consulta — ver GET /catalog
subject.typeCPF, CNPJ, PHONE, EMAILsimTipo do documento
subject.valuestringsimAceita com ou sem pontuação
purposeenumsimcredit_analysis, fraud_prevention, onboarding, collection, regulatory_compliance, contract_execution
legalBasisstringnãoBase legal, quando a organização exige registrá-la
maxAgeSecondsinteironãoIdade máxima aceita do cache. 0 força ida ao fornecedor
providerHintenumnãoForça um fornecedor específico
includeRawbooleanonãoPadrão true — o raw volta no envelope a menos que você peça false. O padrão não muda: há consumidor que lê o envelope cru do fornecedor real. Quem grava o envelope grava o raw junto; veja abaixo o que ele pode conter

Resposta 201

json
{
  "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

StatusCódigoQuando
400VALIDATIONpurpose ausente, dígito verificador inválido, kind incompatível com o tipo de documento
403FORBIDDENToken sem organizationId ou sem a permissão
500INTERNALFalha de transporte com o fornecedor — o único caso que merece retry

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

MétodoRotaDescriçãoPermissão
POST/bureaus/api/v1/providersCadastra e valida a credencial. 403 SIMULATED_PROVIDER_NOT_GRANTED em produção para providerType: MOCK em organização sem concessão e fora da variável de reserva (§13). 400 PROVIDER_BASE_URL_NOT_ALLOWED em produção para settings.baseUrl fora da lista de hosts do fornecedor (§13)BUREAUS_ADMIN
GET/bureaus/api/v1/providersListaBUREAUS_READ
GET/bureaus/api/v1/providers/:idDetalheBUREAUS_READ
PATCH/bureaus/api/v1/providers/:idAtualiza. Ativar (isActive: true) ou tornar padrão (isDefault: true) uma configuração MOCK recusa igual à criação. 400 PROVIDER_BASE_URL_NOT_ALLOWED em produção se o settings enviado — ou o já gravado, numa configuração que fica ativa — tem baseUrl fora da lista de hostsBUREAUS_ADMIN
DELETE/bureaus/api/v1/providers/:idRemoveBUREAUS_ADMIN
POST/bureaus/api/v1/providers/:id/test-connectionTesta a credencial. 403 PROVIDER_BASE_URL_NOT_ALLOWED em produção se a configuração aponta para host fora da lista (nenhuma chamada é feita)BUREAUS_ADMIN

A credencial nunca é devolvida, nem cifrada.

A recusa do fornecedor simulado tem código estável — leia details.code, não a mensagem:

json
{
  "error": "FORBIDDEN",
  "message": "O fornecedor simulado de bureau não está liberado para esta organização neste ambiente.",
  "details": { "code": "SIMULATED_PROVIDER_NOT_GRANTED" }
}
{
  "error": "FORBIDDEN",
  "message": "O fornecedor simulado de bureau não está liberado para esta organização neste ambiente.",
  "details": { "code": "SIMULATED_PROVIDER_NOT_GRANTED" }
}

Operador da plataforma

A concessão do fornecedor simulado (MOCK) por organização. É o caminho normal para deixar uma organização de demonstração pronta em produção: uma chamada, sem editar env de serviço nem reiniciar o bloco. É o espelho das rotas do BaaS (§9 de lá) — mesmo caminho, mesmos verbos, mesmas respostas. São duas concessões: liberar o simulado do baas não libera o do bureaus, e vice-versa (por quê, em §13).

MétodoRotaDescriçãoPermissão
GET/bureaus/api/v1/admin/platform/organizations/:organizationId/simulated-providerO estado: granted (há concessão ativa), allowedByEnvironment (a variável ou o ambiente já liberam) e allowed (o veredito de agora)operador da plataforma
PUT…/simulated-provider { reason }Concede. reason obrigatório (até 500 caracteres; sem ele, 400). Sem CPF nem CNPJ no texto — CPF, CNPJ ou CNPJ alfanumérico, colados ou separados por ponto, hífen, espaço ou barra, dão 400 com details[].code: SIMULATED_PROVIDER_REASON_HAS_DOCUMENT, nada publicado nem gravado (11 dígitos colados também, mesmo sendo celular: escreva (11) 98765-4321). O motivo vai à trilha da organização do operador, nunca à do cliente. Idempotente: repetir devolve 200 com a concessão que já existe — motivo e autor originais, nenhuma linha nova, nenhum evento novo. 503 SIMULATED_PROVIDER_TRAIL_UNAVAILABLE se a trilha não confirmou o evento ou não lê o stream do operador (details.reason: NO_TRAIL_READER): nada foi gravado. 503 SIMULATED_PROVIDER_NOT_RECORDED se o evento saiu e a gravação falhou: a concessão não existe; repetir é segurooperador da plataforma
DELETE…/simulated-providerRevoga todas as concessões ativas da organização. 204 quando não resta nenhuma; 404 SIMULATED_PROVIDER_GRANT_NOT_FOUND se não havia; 409 SIMULATED_PROVIDER_STILL_GRANTED se alguém concedeu de novo no meio. 503 SIMULATED_PROVIDER_TRAIL_UNAVAILABLE se a trilha não confirmou: nada mudou e a organização SEGUE concedida. ?force=true (emergência, trilha fora) revoga mesmo assim e responde 200 com trail: 'confirmed' | 'unconfirmed'operador da plataforma
  • Quem é operador da plataforma: permissão IAM_ORGANIZATIONS_UPDATE e organização do token em BANKING_PLATFORM_ORGANIZATION_IDS — a mesma noção (e a mesma variável) do banking e do baas, gravada também no serviço do bureaus. Lista vazia: 403 para todos. Chave de subconta recebe 403.
  • Publica antes de gravar; nada volta atrás. O evento (bureaus.simulated-provider.grant.created|revoked) sai primeiro, e só com a publicação confirmada a linha é escrita. A trilha pode ter um registro a mais, nunca um a menos. Não existe force para conceder.
  • O motivo vai à trilha do operador, não à do cliente. …grant.created é gravado na trilha da organização alvo, que o cliente lê por GET /audit-trail/api/v1/logs: leva grantId, grantedBy, grantedAt e operatorOrganizationId, e não leva o reason. O motivo sai num evento próprio, bureaus.simulated-provider.grant.reason.recorded, gravado na trilha da organização do operador (a do token que concedeu), com grantId, targetOrganizationId, reason, grantedBy e grantedAt. Depois de revogada, a concessão some do GET; é esse registro — e a linha da concessão, que não é apagada — que responde "por que esta organização teve o simulado?". O reason é texto livre do operador: tem teto (500), é recusado se trouxer algo com forma de CPF/CNPJ e não vai a log. Os dois eventos saem pelo stream do operador (abaixo), nunca pelo webhook do cliente, e os dois são confirmados antes de gravar: sem qualquer um, 503 e nada gravado. Token de operador sem organização: o motivo fica só na linha da concessão (log warn). O evento da revogação não repete o motivo: leva os grantIds.
  • Revogar não apaga nem desativa nada. A configuração MOCK que a organização já criou continua ativa e respondendo consulta. A trava é de criação e de ativação — a mesma semântica do baas. Quem quer tirar o simulado do ar desativa a configuração (PATCH isActive: false) ou a remove.
  • Os eventos não vão ao webhook do cliente. O prefixo bureaus.simulated-provider. está na lista de `@shared/lib/operator-events`: o EventPublisher grava esses eventos em outro stream (platform-operator-events), que só o audit-trail lê. Vale também para a recusa da trava (bureaus.simulated-provider.refused), que é ato do cliente: ele vê o 403, não o evento.
  • Toda resposta de erro destas rotas loga ("operação de plataforma recusada") e publica bureaus.simulated-provider.grant[.read|.revoke].<desfecho> na trilha da organização de quem tentou, com targetOrganizationId. Desfechos: refused (401/403/409), not_found (404), invalid (400) e failed (5xx). O 401 fica só no log. O 429 do limite de requisições NÃO vai à trilha: o limitador é middleware do app e responde antes de a rota (e este registro) rodar — o rastro dele é o log de segurança RATE_LIMIT_EXCEEDED.
  • O GET é o que mostra o ambiente que a trava está considerando. allowedByEnvironment: true para uma organização que não está na variável quer dizer que o serviço não está em NODE_ENV=production (ou que a variável é *): a trava está aberta para todos. Em produção de verdade, sem variável e sem concessão, o esperado é allowed: false, allowedByEnvironment: false.

Catálogo, consumo e manutenção

MétodoRotaDescriçãoPermissão
GET/bureaus/api/v1/catalogO que dá para perguntar e a que TTLBUREAUS_READ
GET/bureaus/api/v1/usageConsumo, custo e taxa de acertoBUREAUS_READ
POST/bureaus/api/v1/cache/invalidateInvalida por kind ou por documentoBUREAUS_ADMIN
POST/bureaus/api/v1/retention/purge-payloadsApaga o dado pessoal, preserva a trilhaBUREAUS_ADMIN
POST/bureaus/api/v1/retention/cleanup-cacheRemove entradas vencidasBUREAUS_ADMIN

10

Início rápido

1. Autenticar

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

bash
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

bash
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:

json
{ "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

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

Custo nulo. É esse o ponto do bloco.


11

Receitas

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.


12

Integração com outros building blocks

BlocoComo se encaixa
Decision PlatformFonte de dados do tipo BUREAU. A esteira herda cache, custo e trilha sem que a política saiba disso
BillingConsulta cobrada vira UsageEvent, via fachada, com o identificador da consulta como chave de idempotência
Audit TrailO evento bureaus.query.executed vira log de auditoria quando o consumer está rodando. A concessão do fornecedor simulado (bureaus.simulated-provider.*) chega a ele por um stream próprio, que só ele lê
CustomersGuarda o resultado como enriquecimento do cadastro
IAMEscopo por organização e as permissões BUREAUS_*

Fonte BUREAU no Decision Platform

json
{
  "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".


13

Configuração e operação

Variáveis de ambiente

VariávelObrigatóriaPadrãoDescrição
BUREAUS_CREDENTIAL_MASTER_KEYsim—64 caracteres hex. Cifra a credencial e deriva o HMAC do documento
BUREAUS_USAGE_CONSUMER_ENABLEDnãofalseLiga o faturamento das consultas
BUREAUS_CACHE_CLEANUP_ENABLEDnãotrueLimpeza automática de cache vencido
BUREAUS_RETENTION_PURGE_ENABLEDnãofalsePurga automática do payload em toda a plataforma. Desligada por padrão: apagar dado pessoal é irreversível
BUREAUS_RETENTION_DAYSnão365Retenção do payload. É variável de ambiente, e não constante de código, porque quem a decide é o jurídico
BUREAUS_RETENTION_PURGE_INTERVAL_HOURSnão24Cadência da purga
BUREAUS_CACHE_CLEANUP_INTERVAL_MINUTESnão60Cadência da limpeza
BUREAUS_SIMULATED_PROVIDER_ORGANIZATION_IDSnãovazioReserva da trava do fornecedor simulado. Em produção (NODE_ENV=production), cria ou ativa configuração MOCK a organização que tem concessão ativa ou está nesta lista. Ids separados por vírgula; * libera todas e só serve a ambiente que não é produção de verdade (staging). Fora de produção a trava não se aplica
BANKING_PLATFORM_ORGANIZATION_IDSnãovazioOrganizações (uuid, vírgula) do operador da plataforma — as únicas que concedem e revogam o fornecedor simulado (§9). É a variável do banking, com o nome dele; tem de estar gravada também no serviço do bureaus. Vazio: ninguém concede pela API (403)

| BUREAUS_PROVIDER_EXTRA_HOSTS | não | vazio | Hosts a mais na lista de hosts de fornecedor real (abaixo). Pares FORNECEDOR=host[:porta] separados por vírgula — BIGDATACORP=homolog.exemplo.com.br. Casamento exato, sem curinga; entrada malformada ou de fornecedor desconhecido é ignorada (não libera nada). Vazio: só os hosts oficiais, fixos no código. Fora de produção a lista não se aplica |

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

Chave em settingsPara quê
datasetOverridesO nome do dataset do fornecedor mudou ou diverge do padrão
priceOverridesO preço negociado, para o custo deixar de ser estimativa
baseUrlApontar para homologação. Em produção, só host da lista de hosts do fornecedor (abaixo)

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

DriverO que é
BIGDATACORPPlataforma BigBoost. POST /pessoas e /empresas, headers AccessToken e TokenId
MOCKSintético e determinístico pelo documento, para teste e demonstração sem gastar consulta. Custo 0. Em produção, só com concessão (abaixo)

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

Lista de hosts do fornecedor real (settings.baseUrl)

⚠️ PASSO DE AMBIENTE ANTES DO DEPLOY. Staging roda com NODE_ENV=production: a lista vale lá. Uma configuração BIGDATACORP de staging cuja baseUrl aponta para um dublê (mock externo, homologação) para de responder consulta com 403 PROVIDER_BASE_URL_NOT_ALLOWED quando esta versão subir, a menos que o host esteja em BUREAUS_PROVIDER_EXTRA_HOSTS, gravada no serviço bb-bureaus antes (o deploy nativo preserva o env e não lê deploy/docker-stack.*.yml). Para saber se há alguma, nos dois ambientes, antes de subir:

SELECT id, organization_id, name, is_active, settings->>'baseUrl' AS base_url
  FROM bureaus.bureau_provider_configs
 WHERE deleted_at IS NULL
   AND provider_type <> 'MOCK'
   AND coalesce(settings->>'baseUrl', '') <> '';

Linha com host que não é plataforma.bigdatacorp.com.br: em staging, ou o host entra na variável, ou a organização passa a usar o MOCK; em produção é para investigar — é exatamente o caso que a lista existe para fechar.

A regra. settings.baseUrl é configuração da organização. Sem lista, uma organização em produção aponta o "fornecedor real" para um servidor dela e recebe de volta, com o selo BIGDATACORP, o dado de crédito que ela mesma inventou — sem MOCK e sem concessão, por fora da trava do simulado. Então, com NODE_ENV=production, a URL efetiva do fornecedor tem de:

  • ser https, sem usuário/senha, sem query e sem fragmento;
  • ter o host (e a porta, se não for a padrão) exatamente igual a um da lista: os oficiais, fixos em providers/base-url-policy.ts (BIGDATACORP → plataforma.bigdatacorp.com.br), mais os de BUREAUS_PROVIDER_EXTRA_HOSTS. Não há curinga nem casamento por sufixo.

Sem baseUrl, vale o endereço padrão do driver, que é oficial. Fora de produção a regra não se aplica — o mesmo recorte da trava do simulado. O MOCK não fala com a rede e não é afetado.

OndeO que acontece com baseUrl fora da lista
POST /providers400, antes do teste de conexão — a credencial não é enviada ao host informado; nada é gravado
PATCH /providers/:id400 se o settings enviado está fora da lista (mesmo em configuração inativa), ou se a configuração fica ativa com settings gravado fora da lista. Desativar e corrigir a URL passam: são a saída
POST /providers/:id/test-connection403, sem chamada de rede
POST /queries (e lote)403, falha fechada e antes do cache: a configuração que já existia não responde nem pelo que ela mesma cacheou. A consulta fica na trilha (bureau_queries) como ERROR, errorCode: PROVIDER_BASE_URL_NOT_ALLOWED, e sai bureaus.query.failed

Toda recusa tem details.code: "PROVIDER_BASE_URL_NOT_ALLOWED" e details.reason (host_not_allowed, not_https, credentials_in_url, query_or_fragment, invalid_url, unknown_provider), log em warn e o evento bureaus.provider_config.refused — com organização, configuração, ação, motivo e só o host (nunca caminho, query ou credencial). O driver repete a conferência antes de cada chamada: é a última barreira, para qualquer caminho que o instancie.

O aviso da recusa em consulta é deduplicado. Um lote de milhares de consultas sobre a mesma configuração irregular recusa todas e grava cada uma em bureau_queries como ERROR (com o seu bureaus.query.failed), mas o log warn e o evento bureaus.provider_config.refused saem uma vez por configuração, ação, motivo e host a cada 5 minutos; o aviso seguinte traz repeatsSinceLastNotice com quantas recusas ficaram sem aviso. A memória é por processo — com duas réplicas saem até dois avisos por janela — e não depende do Redis. Criar e alterar (400) não deduplicam: cada tentativa de quem configura fica registrada.

Redirecionamento do fornecedor é erro. O driver chama o fornecedor com redirect: 'error': a lista confere o host da requisição, e um 30x levaria a credencial (num 307/308, com cabeçalhos e corpo) a um destino que ninguém conferiu. A consulta falha como erro técnico.

A regra depende de NODE_ENV=production gravado no serviço. É a mesma condição da trava do simulado: um bb-bureaus sem NODE_ENV=production não aplica a lista e não avisa que não está aplicando. Confira o env do serviço antes de considerar a lista ativa (§ Passo de ambiente, adiante).

O que a lista NÃO desfaz: consultas já respondidas. Uma configuração que apontou para servidor próprio antes desta regra pode ter gravado consultas FOUND com dado que não veio do fornecedor. Elas continuam legíveis em GET /queries e GET /queries/:id, com o selo do fornecedor, e quem já as consumiu não é avisado. Para listá-las, pegue os ids das configurações irregulares (consulta SQL do aviso acima) e rode:

sql
SELECT q.id, q.organization_id, q.config_id, q.kind, q.status,
       q.subject_masked, q.queried_at, q.cached
  FROM bureaus.bureau_queries q
 WHERE q.config_id IN ('<id-da-configuracao>')
   AND q.status = 'FOUND'
 ORDER BY q.queried_at;
SELECT q.id, q.organization_id, q.config_id, q.kind, q.status,
       q.subject_masked, q.queried_at, q.cached
  FROM bureaus.bureau_queries q
 WHERE q.config_id IN ('<id-da-configuracao>')
   AND q.status = 'FOUND'
 ORDER BY q.queried_at;

A configuração guarda só a baseUrl atual: se a URL foi trocada de volta para o host oficial antes da conferência, a consulta de configurações não a aponta mais e esta listagem não tem como separar o que veio de onde. O que fazer com as linhas (avisar a organização, invalidar decisões que as usaram) é decisão de operação; o bloco não as apaga nem as marca.

Depois de corrigir uma baseUrl, invalide o cache (POST /cache/invalidate por kind): a chave de cache é por fornecedor, não por host, então o que a configuração escreveu enquanto apontava para outro servidor volta a ser servido até o TTL vencer.

Fornecedor simulado (MOCK)

⚠️ PASSO OBRIGATÓRIO DE AMBIENTE ANTES DO DEPLOY. Staging roda com NODE_ENV=production. Sem BUREAUS_SIMULATED_PROVIDER_ORGANIZATION_IDS="*" gravada no serviço bb-bureaus de staging antes de esta versão subir, criar (ou ativar) configuração MOCK em staging passa a ser recusado com 403 SIMULATED_PROVIDER_NOT_GRANTED. O deploy nativo preserva o env do serviço e não lê deploy/docker-stack.staging.yml — a linha de lá é catálogo. As configurações MOCK que já existem seguem respondendo; o que quebra é instalar um tenant novo.

A trava. O MOCK responde score e restrição inventados, que uma análise de crédito lê como dado de bureau. Por decisão do dono (10/10/2026), em produção fornecedor externo simulado só existe para organização de demonstração liberada pelo operador da plataforma. A regra é a mesma do baas (G5):

AmbienteQuem cria ou ativa configuração MOCK
NODE_ENV ≠ productionQualquer organização com BUREAUS_ADMIN
production, variável com *Qualquer organização (é o caso de staging)
production, variável com o idA organização listada
production, concessão ativaA organização concedida (§9, Operador da plataforma)
production, sem nada dissoNinguém — 403 SIMULATED_PROVIDER_NOT_GRANTED

Onde vale

OperaçãoTrava?
POST /providers com providerType: MOCKSim
PATCH /providers/:id que ativa (isActive: false → true) ou torna padrão (isDefault: false → true) uma configuração MOCKSim — é quando ela passa a poder responder consulta
PATCH de nome, settings, credencial, desativação, ou reenviando o estado que já valeNão
POST /queries resolvendo uma configuração MOCK que já existeNão — a trava é de criação, como no baas: revogar a concessão não derruba o que existe
Qualquer operação com BIGDATACORPNão — nada mudou

Toda recusa loga (bureaus: fornecedor simulado recusado…, com organização, usuário e code) e publica bureaus.simulated-provider.refused na trilha, de melhor esforço: o 403 não espera a trilha. Concessão ilegível (banco fora) não vira "pode": 503, nada criado.

Por que a concessão é do bureaus, e não a mesma do baas. O ato do operador ("esta organização é de demonstração") é um só, e compartilhar a concessão foi a primeira opção. Não coube: os blocos rodam como serviços separados, a concessão do baas só é legível pelas rotas de operador dele (que exigem IAM_ORGANIZATIONS_UPDATE e organização da plataforma — um token interno com a organização alvo não passa), a IBaasFacade não a expõe, e o bureaus não tem dependência direta de outro bloco. Ler a concessão do vizinho exigiria rota interna nova no baas, método novo nas duas fachadas, MODULE_BAAS_URL no serviço do bureaus — e faria a criação de fornecedor de bureau cair quando o baas caísse. Duas concessões, a mesma regra; quem prepara uma organização de demonstração faz as duas chamadas.

O que o MOCK responde. Tudo determinístico pelo documento (a semente é o SHA-256 dele). Os tipos cadastrais (person.basic, person.contacts, person.addresses, person.income_estimate, person.compliance, person.lawsuits, company.basic, company.ownership, company.revenue_estimate) não mudaram. Os seis sinais de crédito saem de um perfil do documento, de modo que contam a mesma história entre si:

PerfilScore (0–1000)RestriçõesCobrança (PF)Processos (PJ)
GOOD700–950nenhumanunca cobrado0
LOW_SCORE150–399nenhuma ativajá foi cobrado, não está1–2
RESTRICTED500–6991–3 protestos e 0–2 dívidasem cobrança2–4

O score do perfil RESTRICTED fica na faixa média de propósito: é o que separa o desfecho "com restrição" do desfecho "recusado por score".

A escala do score é 0 a 1000 (scale: { min: 0, max: 1000 }, modelo MOCK_SCORE versão 1) — a da Serasa e da Boa Vista, e a que o painel já lê. Sai sempre junto do valor.

Distribuição dos documentos sem final forçado: 70 % GOOD, 15 % LOW_SCORE, 15 % RESTRICTED.

Regra de teste — o final do documento força o desfecho, com números fixos:

FinalDesfechoO que saiCPF válidoCNPJ válido
00NOT_FOUND (todo tipo, como sempre)data: null123.456.010-0011.222.386/0001-00
11aprovado — GOODscore 850, nenhuma restrição, sem cobrança, 0 processos123.456.046-1111.222.583/0001-11
22recusado por score — LOW_SCOREscore 250, nenhuma restrição ativa, 1 processo123.456.071-2211.222.581/0001-22
33com restrição — RESTRICTEDscore 600, 2 protestos (R$ 5.400,00) + 1 dívida (R$ 950,00), em cobrança, 3 processos123.456.188-3311.222.660/0001-33

Situação do CPF (person.basic) — taxIdStatus: REGULAR e deceased: false para todo CPF, salvo dois finais de teste (só neste kind; os demais não mudam):

FinaltaxIdStatusdeceasedCPF válido
44SUSPENSAfalse123.456.022-44
55TITULAR_FALECIDOtrue (deceasedAt fixo)123.456.058-55

É o que a abertura PF do banking lê: 44 recusa com CPF_NOT_REGULAR, 55 com CPF_HOLDER_DECEASED. Até esta versão, ~1 em 11 CPFs saía IRREGULAR pela semente.

O final são os dois dígitos verificadores, então qualquer CPF ou CNPJ válido com aquele final serve — os da tabela são só exemplos. O raw do envelope traz profile e forced, para o smoke saber por que saiu o que saiu.

O raw do simulado não leva o documento inteiro. raw.subject é a máscara (***.***.046-11, **.***.***/0001-33) — a mesma de subject.masked do envelope —, em FOUND e em NOT_FOUND. O raw é gravado como veio na trilha (bureau_queries.raw) e no cache (bureau_cache.raw) e volta por padrão (includeRaw: true): com o documento em claro ali, quem guardasse o envelope guardava o documento, contra a regra do bloco (glossário, "Sujeito": HMAC, máscara e, opcionalmente, cifrado). O raw também não leva a semente (generatedFrom, que existia até esta versão): eram 32 bits derivados do documento, e com a máscara ao lado o documento saía por força bruta em segundos. Três limites, ditos:

  • vale para o que o simulado responder a partir desta versão. Linhas de trilha e de cache gravadas antes seguem com o documento em raw.subject (e com raw.generatedFrom) até a retenção purgar o payload (BUREAUS_RETENTION_DAYS, padrão 365 — e só com BUREAUS_RETENTION_PURGE_ENABLED ligado, que nasce desligado) ou o cache expirar. Este PR não reescreve linha antiga;
  • o canônico de person.basic e company.basic segue trazendo taxId — é o contrato do tipo, igual ao do fornecedor real, e não é o raw;
  • o raw de fornecedor real (BIGDATACORP) é a resposta literal dele e pode conter o documento e outros dados pessoais. Quem não precisa do cru pede includeRaw: false.

Formato de cada tipo (o data do envelope; todos com cost.amount: "0.0000")

person.credit_score e company.credit_score:

json
{ "value": 850, "scale": { "min": 0, "max": 1000 },
  "model": { "name": "MOCK_SCORE", "version": "1" }, "reasons": [] }
{ "value": 850, "scale": { "min": 0, "max": 1000 },
  "model": { "name": "MOCK_SCORE", "version": "1" }, "reasons": [] }

person.restrictions e company.restrictions — um resumo por tipo de restrição, mais o total. Sem restrição: { "totalCount": 0, "totalAmount": null, "restrictions": [] }.

json
{
  "totalCount": 3,
  "totalAmount": { "amount": "6350.00", "currency": "BRL" },
  "restrictions": [
    { "kind": "PROTEST", "count": 2,
      "totalAmount": { "amount": "5400.00", "currency": "BRL" },
      "oldestAt": "2025-01-01T00:00:00.000Z", "newestAt": "2025-01-31T00:00:00.000Z",
      "items": [
        { "occurredAt": "2025-01-01T00:00:00.000Z", "amount": { "amount": "1800.00", "currency": "BRL" },
          "creditor": "Banco Exemplo S.A.", "description": "Título protestado" },
        { "occurredAt": "2025-01-31T00:00:00.000Z", "amount": { "amount": "3600.00", "currency": "BRL" },
          "creditor": "Financeira Modelo", "description": "Título protestado" }
      ] },
    { "kind": "DEBT", "count": 1,
      "totalAmount": { "amount": "950.00", "currency": "BRL" },
      "oldestAt": "2025-05-01T00:00:00.000Z", "newestAt": "2025-05-01T00:00:00.000Z",
      "items": [
        { "occurredAt": "2025-05-01T00:00:00.000Z", "amount": { "amount": "950.00", "currency": "BRL" },
          "creditor": "Banco Exemplo S.A.", "description": "Dívida vencida" }
      ] }
  ]
}
{
  "totalCount": 3,
  "totalAmount": { "amount": "6350.00", "currency": "BRL" },
  "restrictions": [
    { "kind": "PROTEST", "count": 2,
      "totalAmount": { "amount": "5400.00", "currency": "BRL" },
      "oldestAt": "2025-01-01T00:00:00.000Z", "newestAt": "2025-01-31T00:00:00.000Z",
      "items": [
        { "occurredAt": "2025-01-01T00:00:00.000Z", "amount": { "amount": "1800.00", "currency": "BRL" },
          "creditor": "Banco Exemplo S.A.", "description": "Título protestado" },
        { "occurredAt": "2025-01-31T00:00:00.000Z", "amount": { "amount": "3600.00", "currency": "BRL" },
          "creditor": "Financeira Modelo", "description": "Título protestado" }
      ] },
    { "kind": "DEBT", "count": 1,
      "totalAmount": { "amount": "950.00", "currency": "BRL" },
      "oldestAt": "2025-05-01T00:00:00.000Z", "newestAt": "2025-05-01T00:00:00.000Z",
      "items": [
        { "occurredAt": "2025-05-01T00:00:00.000Z", "amount": { "amount": "950.00", "currency": "BRL" },
          "creditor": "Banco Exemplo S.A.", "description": "Dívida vencida" }
      ] }
  ]
}

Quantidade de protestos é restrictions.find(r => r.kind === 'PROTEST')?.count ?? 0 — tipo ausente da lista é zero daquele tipo. O perfil com restrição traz sempre a entrada PROTEST.

person.collections:

json
{ "isCurrentlyOnCollection": true,
  "firstCollectionAt": "2025-01-31T00:00:00.000Z", "lastCollectionAt": "2025-09-28T00:00:00.000Z",
  "totalCollectionMonths": 5, "currentConsecutiveMonths": 3, "maxConsecutiveMonths": 4,
  "occurrences": { "last30Days": 1, "last90Days": 2, "last180Days": 3, "last365Days": 5 },
  "origins": { "last30Days": 1, "last90Days": 1, "last180Days": 2, "last365Days": 2 } }
{ "isCurrentlyOnCollection": true,
  "firstCollectionAt": "2025-01-31T00:00:00.000Z", "lastCollectionAt": "2025-09-28T00:00:00.000Z",
  "totalCollectionMonths": 5, "currentConsecutiveMonths": 3, "maxConsecutiveMonths": 4,
  "occurrences": { "last30Days": 1, "last90Days": 2, "last180Days": 3, "last365Days": 5 },
  "origins": { "last30Days": 1, "last90Days": 1, "last180Days": 2, "last365Days": 2 } }

company.lawsuits (o mesmo canônico de person.lawsuits; sem processo, totalCount: 0, totalAmount: null, items: []):

json
{ "totalCount": 3, "totalAmount": { "amount": "55500.00", "currency": "BRL" },
  "asAuthorCount": 0, "asDefendantCount": 3, "asOtherCount": 0,
  "firstLawsuitAt": "2025-03-02T00:00:00.000Z", "lastLawsuitAt": "2025-05-31T00:00:00.000Z",
  "recent": { "last30Days": 0, "last90Days": 0, "last180Days": 0, "last365Days": 3 },
  "items": [
    { "number": "00000000029946184620", "court": "TJRJ", "subject": "Cobrança", "role": "REU",
      "amount": { "amount": "18500.00", "currency": "BRL" }, "filedAt": "2025-03-02T00:00:00.000Z" }
  ] }
{ "totalCount": 3, "totalAmount": { "amount": "55500.00", "currency": "BRL" },
  "asAuthorCount": 0, "asDefendantCount": 3, "asOtherCount": 0,
  "firstLawsuitAt": "2025-03-02T00:00:00.000Z", "lastLawsuitAt": "2025-05-31T00:00:00.000Z",
  "recent": { "last30Days": 0, "last90Days": 0, "last180Days": 0, "last365Days": 3 },
  "items": [
    { "number": "00000000029946184620", "court": "TJRJ", "subject": "Cobrança", "role": "REU",
      "amount": { "amount": "18500.00", "currency": "BRL" }, "filedAt": "2025-03-02T00:00:00.000Z" }
  ] }

Duas coisas que quem consome precisa saber: valor monetário é objeto ({ amount, currency }, com amount em string decimal) — não um número; e as datas são fixas (base 01/01/2025, para o dado não mudar de um dia para o outro), de modo que as janelas (occurrences, origins, recent) são contagens declaradas pelo perfil, não derivadas das datas.

No catálogo (GET /catalog), os seis tipos aparecem com supportedBy: ["MOCK"] na organização que tem o simulado ativo. person.credit_score, company.credit_score, person.restrictions e company.restrictions continuam com supportedBy: [] em quem só tem BIGDATACORP: nenhum fornecedor real os atende.

Subida em ambiente

Staging antes de produção, sempre. Nesta ordem:

1. A migration, antes do código. Nenhum deploy do Launch toca o banco: a 20261012090000_bureaus_simulated_provider_grants sobe pelo procedimento de `scripts/launch/`. É aditiva e idempotente (uma tabela e dois índices). Sem a tabela, a organização fora da variável recebe 503 ao criar configuração MOCK, e as rotas do operador também.

bash
# aplicar
MIGRATIONS="20261012090000_bureaus_simulated_provider_grants" ALVO=staging CONFIRMA=sim ./scripts/launch/1-migrar.sh

# verificar — a tabela e o índice único parcial, pela lista do bloco
VERIFICAR_FILE=scripts/launch/verificar/bureaus-simulated-provider-grants.txt ALVO=staging ./scripts/launch/2-verificar.sh
# aplicar
MIGRATIONS="20261012090000_bureaus_simulated_provider_grants" ALVO=staging CONFIRMA=sim ./scripts/launch/1-migrar.sh

# verificar — a tabela e o índice único parcial, pela lista do bloco
VERIFICAR_FILE=scripts/launch/verificar/bureaus-simulated-provider-grants.txt ALVO=staging ./scripts/launch/2-verificar.sh

2. As variáveis, gravadas no serviço bb-bureaus (o deploy preserva o env). Antes de tudo, conferir que NODE_ENV=production está gravado no serviço bb-bureaus: src/shared/config/env.ts tem padrão development, e fora de produção a trava não se aplica — um serviço sem NODE_ENV libera o simulado para qualquer organização, sem recusa e sem log. A conferência pelo próprio bloco é o GET …/simulated-provider de uma organização sem concessão (§9): tem de responder allowedByEnvironment: false em produção.

scripts/launch-env.sh e scripts/envs/secret-keys.txt não conhecem estas duas variáveis (não são segredo e não estão no catálogo de chaves): elas não chegam ao serviço por nenhum script — são gravadas à mão no env do bb-bureaus, uma vez por ambiente.

VariávelStagingProdução
BUREAUS_SIMULATED_PROVIDER_ORGANIZATION_IDS* — obrigatório, ou criar MOCK passa a dar 403vazio (só concessão), ou os ids de reserva
BUREAUS_PROVIDER_EXTRA_HOSTSsó se houver configuração de fornecedor real apontando para dublê/homologação (a consulta SQL da lista de hosts, acima, diz) — BIGDATACORP=<host>vazio
BANKING_PLATFORM_ORGANIZATION_IDSo mesmo valor do bb-baas/bb-bankingidem

3. O audit-trail antes do bureaus. O bureaus publica a concessão no stream platform-operator-events, e só confirma o ato se o grupo audit-trail-consumers existir nele. Com o audit-trail em build anterior a a88aeca7 (ou com o consumidor desligado), conceder e revogar respondem 503 SIMULATED_PROVIDER_TRAIL_UNAVAILABLE (details.reason: NO_TRAIL_READER) — falha fechada, nada gravado. E é o audit-trail desta versão que conhece o recurso bureaus_simulated_provider_grant: com um mais antigo o evento é gravado, mas com a organização no lugar do id da concessão. O webhooks-engine pode vir em qualquer momento: ele nunca lê esse stream.

4. O bureaus. Depois, em produção, conceder a quem é de demonstração:

bash
curl -X PUT -H "Authorization: Bearer $TOKEN_DO_OPERADOR" -H "Content-Type: application/json" \
  "$BUREAUS_URL/bureaus/api/v1/admin/platform/organizations/$ORGANIZATION_ID/simulated-provider" \
  -d '{"reason":"organização de demonstração"}'
curl -X PUT -H "Authorization: Bearer $TOKEN_DO_OPERADOR" -H "Content-Type: application/json" \
  "$BUREAUS_URL/bureaus/api/v1/admin/platform/organizations/$ORGANIZATION_ID/simulated-provider" \
  -d '{"reason":"organização de demonstração"}'

Emergência — revogar com a trilha fora do ar: DELETE …/simulated-provider?force=true. A resposta traz trail; com unconfirmed, guarde a resposta e o log (bureaus: fornecedor simulado REVOGADO À FORÇA…, nível error) — eles são o registro do ato.


14

Segurança e compliance

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

RepresentaçãoComoPara quê
Chave de cacheHMAC-SHA256 com a master keyDeterminística, e não revela o documento a quem lê o banco
Trilha legívelMáscara ***.***.247-25Suporte e auditoria reconhecem sem expor
Documento completoCifrado, opcional por organizaçãoSó quando é preciso reconsultar pelo documento

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 (@shared/lib/secure-fetch), 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. Em produção há uma barreira antes dele: a lista de hosts do fornecedor (§13) — a baseUrl só pode ser um endereço oficial do fornecedor, então a organização não escolhe para onde o serviço faz requisição.


15

Limitações conhecidas

LimitaçãoSituação
Um fornecedor realSó BIGDATACORP. Cascata entre fornecedores não existe: com um driver não há o que cascatear
Consulta ao simulado não é cobrávelToda consulta atendida pelo MOCK sai billable: false, sem custo gravado e sem evento de uso para o Billing — o envelope segue com cost.amount: "0.0000". GET /usage conta a consulta e o acerto de cache, não a cobrança
Cache escrito por configuração com baseUrl fora da listaA lista de hosts (§13) fecha o apontamento para servidor próprio em produção, na criação, na alteração e na consulta. O que ela não faz: apagar o cache que uma configuração dessas já escreveu. Enquanto a configuração está fora da lista o cache não é servido (a recusa vem antes); corrigida a URL, ele volta a valer até o TTL — invalide (POST /cache/invalidate)
Consultas já gravadas por configuração irregular seguem legíveisA lista recusa a partir de agora; não revisa o passado. Linhas FOUND em bureau_queries gravadas enquanto a baseUrl apontava para fora continuam em GET /queries, com o selo do fornecedor. Há SQL de listagem por config_id em §13; se a URL já foi corrigida, nada as distingue
Aviso de recusa deduplicado por processoUma linha de log e um evento por configuração a cada 5 minutos em cada réplica; a contagem exata de recusas está em bureau_queries (error_code = 'PROVIDER_BASE_URL_NOT_ALLOWED'), não no evento
Fora de produção a baseUrl é livreDecisão, igual à trava do simulado: teste e desenvolvimento apontam para onde precisarem. Um serviço sem NODE_ENV=production gravado não aplica a lista
Host oficial únicoA lista fixa do BIGDATACORP tem um host (plataforma.bigdatacorp.com.br, o padrão do driver). Outro endereço do próprio fornecedor entra por BUREAUS_PROVIDER_EXTRA_HOSTS até virar código
Tipos antigos do MOCK fora do canônicoperson.income_estimate, person.lawsuits, company.basic e company.revenue_estimate do simulado omitem campos que o schema canônico do próprio bloco exige (CANONICAL_SCHEMAS) — hoje nada valida a saída do driver, então passam. Já era assim; os seis sinais de crédito novos passam no schema e têm teste. Não corrigido aqui
Sem score de crédito de verdade`person
Duas concessões para uma organização de demonstraçãoO simulado do bureaus e o do baas são liberados separadamente (§13). Quem prepara a organização faz as duas chamadas
Dois datasets fora do contratoowners (quadro societário) e kyc_data (PEP e sanções) respondem NOT_SUPPORTED. É liberação no BDC Center, não código
Cache de dado errado é pior que consulta caraUm documento que virou irregular ontem e volta do cache como regular aprova crédito indevido. Mitigado por TTL curto no que muda e por maxAgeSeconds
Custo é estimativa por padrãoSai com estimated: true até a organização gravar o preço negociado
Purga de payload precisa de cronNão há agendador embutido, por decisão

16

Perguntas frequentes

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.