Bureaus
BetaConsulta a bureau com cache que impede pagar duas vezes pelo mesmo CPF
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ê.
- 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
- 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
- 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
16 endpoints em 4 recursos.
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 cadastral | R$ 0,030 na tabela pública do fornecedor |
| Acerto de cache | 218 ms → 10 ms, custo zero |
| Consultas de uma esteira típica no mesmo CPF | 3 (pré-análise, política, formalização) |
| Cobranças com o bloco | 1 |
O problema
negócioUma 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
fetchno meio do código não registra por que a consulta aconteceu, e a prova disso é exatamente o que a ANPD pede.
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.
Casos de uso reais
negócioEsteira 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.
Mercado e diferenciais
negócioO 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 direta | Com o Bureaus | |
|---|---|---|
| Mesmo CPF em três etapas | 3 cobranças | 1 |
| Token do fornecedor | Texto puro na config | Cifrado, nunca devolvido |
| Custo por organização | Descoberto na fatura | GET /usage |
| Finalidade da consulta | Não registrada | Campo obrigatório, em trilha imutável |
| Trocar de fornecedor | Reescrever quem consome | Trocar 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.
Modelo de cobrança e ROI
negócioUnidade: 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ês | Preço unitário |
|---|---|
| 1 – 10.000 | R$ 0,030 |
| 10.001 – 50.000 | R$ 0,029 |
| 50.001 – 100.000 | R$ 0,027 |
| 100.001 – 500.000 | R$ 0,026 |
| 500.001 – 1.000.000 | R$ 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.
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 --> BILLO que o bloco não faz, e quem faz
| Não faz | Quem faz |
|---|---|
| Decidir com o dado — regra, árvore, tabela DMN | Decision Engine |
| Orquestrar a esteira, callback, fila | Decision Platform |
| Guardar o cadastro do cliente | Customers |
| Ler documento em imagem | Data Extraction |
| Biometria, prova de vida, documentoscopia | Fora 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.
Conceitos e modelo de dados
Glossário
| Termo | Significa |
|---|---|
kind | O tipo de pergunta, com namespace: person.basic, company.lawsuits |
| Canônico | O formato estável do bloco, igual para qualquer fornecedor |
raw | A resposta literal do fornecedor, sempre devolvida ao lado do canônico |
asOf | Quando a fonte apurou o dado — diferente de queriedAt, que é quando nós chamamos |
purpose | Finalidade declarada da consulta. Obrigatória, sem valor padrão |
| Sujeito | O documento consultado. Gravado como HMAC, máscara e, opcionalmente, cifrado |
Modelo de dados
| Modelo Prisma | Tabela | Propósito | Campos-chave |
|---|---|---|---|
BureauProviderConfig | bureau_provider_configs | Fornecedor por organização | credentials cifrado, settings, isDefault |
BureauQuery | bureau_queries | Trilha imutável e resultado | subjectHash, subjectMasked, purpose, billable, costAmount |
BureauCacheEntry | bureau_cache_entries | Cache persistente | cacheKey (HMAC), expiresAt |
BureauCachePolicy | bureau_cache_policies | TTL por kind, por organização | kind, ttlSeconds |
BureauSimulatedProviderGrant | bureau_simulated_provider_grants | A 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 nova | organizationId, 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.
Referência da API
Consultas
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /bureaus/api/v1/queries | Consulta síncrona | BUREAUS_QUERY |
POST | /bureaus/api/v1/queries/batch | Lote, resultado item a item | BUREAUS_QUERY |
GET | /bureaus/api/v1/queries | A trilha | BUREAUS_READ |
GET | /bureaus/api/v1/queries/:id | Resultado, canônico e bruto | BUREAUS_READ |
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
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
kind | enum | sim | Tipo de consulta — ver GET /catalog |
subject.type | CPF, CNPJ, PHONE, EMAIL | sim | Tipo do documento |
subject.value | string | sim | Aceita com ou sem pontuação |
purpose | enum | sim | credit_analysis, fraud_prevention, onboarding, collection, regulatory_compliance, contract_execution |
legalBasis | string | não | Base legal, quando a organização exige registrá-la |
maxAgeSeconds | inteiro | não | Idade máxima aceita do cache. 0 força ida ao fornecedor |
providerHint | enum | não | Força um fornecedor específico |
includeRaw | booleano | não | Padrã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
{
"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
| Status | Código | Quando |
|---|---|---|
400 | VALIDATION | purpose ausente, dígito verificador inválido, kind incompatível com o tipo de documento |
403 | FORBIDDEN | Token sem organizationId ou sem a permissão |
500 | INTERNAL | Falha 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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /bureaus/api/v1/providers | Cadastra 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/providers | Lista | BUREAUS_READ |
GET | /bureaus/api/v1/providers/:id | Detalhe | BUREAUS_READ |
PATCH | /bureaus/api/v1/providers/:id | Atualiza. 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 hosts | BUREAUS_ADMIN |
DELETE | /bureaus/api/v1/providers/:id | Remove | BUREAUS_ADMIN |
POST | /bureaus/api/v1/providers/:id/test-connection | Testa 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:
{
"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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
GET | /bureaus/api/v1/admin/platform/organizations/:organizationId/simulated-provider | O 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 é seguro | operador da plataforma |
DELETE | …/simulated-provider | Revoga 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_UPDATEe organização do token emBANKING_PLATFORM_ORGANIZATION_IDS— a mesma noção (e a mesma variável) dobankinge dobaas, gravada também no serviço dobureaus. Lista vazia:403para todos. Chave de subconta recebe403. - 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 existeforcepara conceder. - O motivo vai à trilha do operador, não à do cliente.
…grant.createdé gravado na trilha da organização alvo, que o cliente lê porGET /audit-trail/api/v1/logs: levagrantId,grantedBy,grantedAteoperatorOrganizationId, e não leva oreason. 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), comgrantId,targetOrganizationId,reason,grantedByegrantedAt. Depois de revogada, a concessão some doGET; é esse registro — e a linha da concessão, que não é apagada — que responde "por que esta organização teve o simulado?". Oreasoné 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,503e nada gravado. Token de operador sem organização: o motivo fica só na linha da concessão (logwarn). O evento da revogação não repete o motivo: leva osgrantIds. - Revogar não apaga nem desativa nada. A configuração
MOCKque a organização já criou continua ativa e respondendo consulta. A trava é de criação e de ativação — a mesma semântica dobaas. 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`: oEventPublishergrava esses eventos em outro stream (platform-operator-events), que só oaudit-traillê. Vale também para a recusa da trava (bureaus.simulated-provider.refused), que é ato do cliente: ele vê o403, 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, comtargetOrganizationId. Desfechos:refused(401/403/409),not_found(404),invalid(400) efailed(5xx). O401fica só no log. O429do 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çaRATE_LIMIT_EXCEEDED. - O
GETé o que mostra o ambiente que a trava está considerando.allowedByEnvironment: truepara uma organização que não está na variável quer dizer que o serviço não está emNODE_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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
GET | /bureaus/api/v1/catalog | O que dá para perguntar e a que TTL | BUREAUS_READ |
GET | /bureaus/api/v1/usage | Consumo, custo e taxa de acerto | BUREAUS_READ |
POST | /bureaus/api/v1/cache/invalidate | Invalida por kind ou por documento | BUREAUS_ADMIN |
POST | /bureaus/api/v1/retention/purge-payloads | Apaga o dado pessoal, preserva a trilha | BUREAUS_ADMIN |
POST | /bureaus/api/v1/retention/cleanup-cache | Remove entradas vencidas | BUREAUS_ADMIN |
Início rápido
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.
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.
Integração com outros building blocks
| Bloco | Como se encaixa |
|---|---|
| Decision Platform | Fonte de dados do tipo BUREAU. A esteira herda cache, custo e trilha sem que a política saiba disso |
| Billing | Consulta cobrada vira UsageEvent, via fachada, com o identificador da consulta como chave de idempotência |
| Audit Trail | O 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ê |
| Customers | Guarda o resultado como enriquecimento do cadastro |
| IAM | Escopo por organização e as permissões BUREAUS_* |
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".
Configuração e operação
Variáveis de ambiente
| Variável | Obrigatória | Padrão | Descrição |
|---|---|---|---|
BUREAUS_CREDENTIAL_MASTER_KEY | sim | — | 64 caracteres hex. Cifra a credencial e deriva o HMAC do documento |
BUREAUS_USAGE_CONSUMER_ENABLED | não | false | Liga o faturamento das consultas |
BUREAUS_CACHE_CLEANUP_ENABLED | não | true | Limpeza automática de cache vencido |
BUREAUS_RETENTION_PURGE_ENABLED | não | false | Purga automática do payload em toda a plataforma. Desligada por padrão: apagar dado pessoal é irreversível |
BUREAUS_RETENTION_DAYS | não | 365 | Retençã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_HOURS | não | 24 | Cadência da purga |
BUREAUS_CACHE_CLEANUP_INTERVAL_MINUTES | não | 60 | Cadência da limpeza |
BUREAUS_SIMULATED_PROVIDER_ORGANIZATION_IDS | não | vazio | Reserva 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_IDS | não | vazio | Organizaçõ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 settings | Para quê |
|---|---|
datasetOverrides | O nome do dataset do fornecedor mudou ou diverge do padrão |
priceOverrides | O preço negociado, para o custo deixar de ser estimativa |
baseUrl | Apontar 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
| Driver | O que é |
|---|---|
BIGDATACORP | Plataforma BigBoost. POST /pessoas e /empresas, headers AccessToken e TokenId |
MOCK | Sinté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çãoBIGDATACORPde staging cujabaseUrlaponta para um dublê (mock externo, homologação) para de responder consulta com403 PROVIDER_BASE_URL_NOT_ALLOWEDquando esta versão subir, a menos que o host esteja emBUREAUS_PROVIDER_EXTRA_HOSTS, gravada no serviçobb-bureausantes (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 oMOCK; 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 deBUREAUS_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.
| Onde | O que acontece com baseUrl fora da lista |
|---|---|
POST /providers | 400, antes do teste de conexão — a credencial não é enviada ao host informado; nada é gravado |
PATCH /providers/:id | 400 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-connection | 403, 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:
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. SemBUREAUS_SIMULATED_PROVIDER_ORGANIZATION_IDS="*"gravada no serviçobb-bureausde staging antes de esta versão subir, criar (ou ativar) configuraçãoMOCKem staging passa a ser recusado com403 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çõesMOCKque 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):
| Ambiente | Quem cria ou ativa configuração MOCK |
|---|---|
NODE_ENV ≠ production | Qualquer organização com BUREAUS_ADMIN |
production, variável com * | Qualquer organização (é o caso de staging) |
production, variável com o id | A organização listada |
production, concessão ativa | A organização concedida (§9, Operador da plataforma) |
production, sem nada disso | Ninguém — 403 SIMULATED_PROVIDER_NOT_GRANTED |
Onde vale
| Operação | Trava? |
|---|---|
POST /providers com providerType: MOCK | Sim |
PATCH /providers/:id que ativa (isActive: false → true) ou torna padrão (isDefault: false → true) uma configuração MOCK | Sim — é quando ela passa a poder responder consulta |
PATCH de nome, settings, credencial, desativação, ou reenviando o estado que já vale | Não |
POST /queries resolvendo uma configuração MOCK que já existe | Não — a trava é de criação, como no baas: revogar a concessão não derruba o que existe |
Qualquer operação com BIGDATACORP | Nã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:
| Perfil | Score (0–1000) | Restrições | Cobrança (PF) | Processos (PJ) |
|---|---|---|---|---|
GOOD | 700–950 | nenhuma | nunca cobrado | 0 |
LOW_SCORE | 150–399 | nenhuma ativa | já foi cobrado, não está | 1–2 |
RESTRICTED | 500–699 | 1–3 protestos e 0–2 dívidas | em cobrança | 2–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:
| Final | Desfecho | O que sai | CPF válido | CNPJ válido |
|---|---|---|---|---|
00 | NOT_FOUND (todo tipo, como sempre) | data: null | 123.456.010-00 | 11.222.386/0001-00 |
11 | aprovado — GOOD | score 850, nenhuma restrição, sem cobrança, 0 processos | 123.456.046-11 | 11.222.583/0001-11 |
22 | recusado por score — LOW_SCORE | score 250, nenhuma restrição ativa, 1 processo | 123.456.071-22 | 11.222.581/0001-22 |
33 | com restrição — RESTRICTED | score 600, 2 protestos (R$ 5.400,00) + 1 dívida (R$ 950,00), em cobrança, 3 processos | 123.456.188-33 | 11.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):
| Final | taxIdStatus | deceased | CPF válido |
|---|---|---|---|
44 | SUSPENSA | false | 123.456.022-44 |
55 | TITULAR_FALECIDO | true (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 comraw.generatedFrom) até a retenção purgar o payload (BUREAUS_RETENTION_DAYS, padrão 365 — e só comBUREAUS_RETENTION_PURGE_ENABLEDligado, que nasce desligado) ou o cache expirar. Este PR não reescreve linha antiga; - o canônico de
person.basicecompany.basicsegue trazendotaxId— é o contrato do tipo, igual ao do fornecedor real, e não é oraw; - o
rawde fornecedor real (BIGDATACORP) é a resposta literal dele e pode conter o documento e outros dados pessoais. Quem não precisa do cru pedeincludeRaw: false.
Formato de cada tipo (o data do envelope; todos com cost.amount: "0.0000")
person.credit_score e company.credit_score:
{ "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": [] }.
{
"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:
{ "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: []):
{ "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.
# 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.sh2. 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ável | Staging | Produção |
|---|---|---|
BUREAUS_SIMULATED_PROVIDER_ORGANIZATION_IDS | * — obrigatório, ou criar MOCK passa a dar 403 | vazio (só concessão), ou os ids de reserva |
BUREAUS_PROVIDER_EXTRA_HOSTS | só 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_IDS | o mesmo valor do bb-baas/bb-banking | idem |
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:
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.
Segurança e compliance
O documento nunca é gravado em claro. São três representações, cada uma com um trabalho:
| Representação | Como | Para quê |
|---|---|---|
| Chave de cache | HMAC-SHA256 com a master key | Determinística, e não revela o documento a quem lê o banco |
| Trilha legível | Máscara ***.***.247-25 | Suporte e auditoria reconhecem sem expor |
| Documento completo | Cifrado, opcional por organização | Só 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.
Limitações conhecidas
| Limitação | Situação |
|---|---|
| Um fornecedor real | Só BIGDATACORP. Cascata entre fornecedores não existe: com um driver não há o que cascatear |
| Consulta ao simulado não é cobrável | Toda 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 lista | A 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íveis | A 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 processo | Uma 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 é livre | Decisã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 único | A 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ônico | person.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ção | O 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 contrato | owners (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 cara | Um 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ão | Sai com estimated: true até a organização gravar o preço negociado |
| Purga de payload precisa de cron | Não há agendador embutido, por decisão |
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.