Customers

O Customers guarda quem é o seu cliente pessoa física. Nome, CPF, contato, data de nascimento, nome da mãe, estado civil, vínculo de trabalho, renda mensal, endereço completo e conta bancária — os campos que uma operação de crédito brasileira pede no primeiro formulário e usa em todas as etapas seguintes.

Na prática ele resolve o momento em que a sua plataforma passa de um serviço para cinco. Sem um cadastro central, o motor de decisão tem uma cópia da pessoa, a esteira de contrato tem outra, o faturamento tem uma terceira, e o dia em que o cliente troca de telefone você descobre que existem três telefones diferentes e nenhum deles é o certo. Aqui a pessoa tem um identificador só, e os outros building blocks apontam para ele.

Está em produção, publicado em staging e em produção como serviço próprio (customers.bb.stg.catalisa.app), com cobertura de testes unitários e de integração. É um building block pequeno de propósito: cinco rotas, uma tabela, nenhuma integração externa. O que ele entrega não é funcionalidade, é o cadastro certo no lugar certo — leia a §15 antes de assumir que ele faz KYC, porque ele não faz.

O cenário. Uma fintech de crédito começa com um produto e um banco de dados. O tomador é cadastrado na tela de originação e a vida segue. Dois anos depois existem uma esteira de proposta, um motor de decisão, um contrato eletrônico, uma régua de cobrança e um faturamento — e cada um deles guarda a própria versão da mesma pessoa.

O que trava hoje.

• A pessoa existe cinco vezes. Cada serviço tem a própria tabela de cliente, com o próprio nome de coluna e a própria regra de obrigatoriedade. Responder "qual é o telefone atual do cliente" vira uma pergunta com cinco respostas.
• A validação de CPF é copiada e colada. O algoritmo do dígito verificador está em três repositórios, em versões que divergiram. Um deles aceita 111.111.111-11, e ninguém sabe qual até um cadastro fantasma aparecer na carteira.
• O isolamento entre empresas clientes é disciplina, não garantia. "Todo mundo lembra de filtrar por organization_id" funciona até o dia em que alguém não lembra. Em cadastro com CPF, esse esquecimento é incidente de dado pessoal, não bug de listagem.
• Apagar cliente apaga histórico. Um DELETE físico resolve o pedido do cliente e destrói a rastreabilidade da operação de crédito que ele contratou — que precisa sobreviver por anos.
• O formulário brasileiro não cabe em modelo genérico. Nome da mãe, faixa de renda, tipo de vínculo empregatício, agência com dígito e tipo de conta não são campos de um cadastro internacional. Ou você modela isso, ou empurra tudo para um metadata que ninguém consegue consultar.

O custo de não resolver. O custo visível é o retrabalho: cada produto novo começa reescrevendo o cadastro, a validação e o isolamento. O custo invisível é maior. Dado pessoal duplicado em cinco lugares é dado pessoal que você não consegue corrigir, exportar nem eliminar de forma completa quando o titular pedir — e a LGPD dá ao titular exatamente esses direitos (Lei 13.709/2018, art. 18). Uma base fragmentada transforma um pedido de dez minutos em um projeto.

O CPF é conferido, não só armazenado. A criação sanitiza a máscara, valida os dois dígitos verificadores e recusa sequências repetidas. Cadastro com CPF impossível não entra.

O tenant vem do token. Nenhuma rota lê organizationId do corpo ou da query. Ele sai do JWT assinado pelo IAM, e o requireOrganization devolve 403 quando o token não o carrega.

O modelo de dados fala português. Estado civil, tipo de vínculo, faixa de renda, UF e tipo de conta bancária são enumerações fechadas. Isso é o que permite filtrar, agregar e mandar para o motor de decisão sem tratamento no meio.

Cada mudança vira evento. Criar, atualizar e excluir publicam customers.person.created, .updated e .deleted no fluxo de eventos da plataforma. Quem quiser reagir — webhook, auditoria, sincronização — se inscreve, e o Customers não precisa saber que existe.

Panorama

Panorama. Não existe uma categoria de mercado chamada "cadastro de pessoa física para fintech brasileira", e é por isso que quase todo mundo escreve o seu. Mas o conceito é padrão consolidado: os provedores de core banking e de BaaS tratam o cadastro de pessoa como recurso de primeira classe, separado da conta. A Pismo tem um domínio Customers próprio, com tipos pessoa e empresa e busca por documento. A Celcoin separa a proposta de cadastro de pessoa física da abertura de conta. A Zoop expõe busca de pessoa por CPF.

E há um vocabulário oficial: a API Dados Cadastrais do Open Finance Brasil padroniza identificação de pessoa natural com cpfNumber, nome civil, nome social, data de nascimento, estado civil, nacionalidade, endereços, telefones e filiação (especificação OAS 3.0 no repositório oficial). O conjunto de campos do Customers é próximo desse vocabulário, e isso não é coincidência: é o mesmo domínio.

As três alternativas reais

As alternativas reais, então, são três, e nenhuma é concorrente direto.

flowchart TD
  N["Preciso de um cadastro de pessoa física<br/>compartilhado por vários serviços"] --> A1["1. Construir do zero"]
  N --> A2["2. Usar o cadastro do core banking ou do BaaS"]
  N --> A3["3. Usar o CRM que já está contratado"]
  A1 --> C1["envelhece em cada serviço novo"]
  A2 --> C2["vem embutido: você contrata o core, não o cadastro"]
  A3 --> C3["cobra por vendedor e não trata CPF como chave transacional"]

A primeira: construir do zero. A primeira é construir do zero: uma tabela, um validador de CPF copiado da internet e a promessa de sempre filtrar por tenant. É a opção mais escolhida e a que envelhece pior, porque cada serviço novo repete o exercício.

A segunda: o cadastro do core banking ou do BaaS. A segunda é usar o cadastro do core banking ou do BaaS. Ele é maduro e aderente ao regulatório — mas vem embutido. Você não contrata o cadastro, contrata o core, e o ciclo de evolução do seu modelo de dados passa a ser o do fornecedor. Pior: usar o cadastro do seu provedor bancário como cadastro geral da sua plataforma amarra o seu dado de cliente ao fornecedor que você talvez queira trocar.

A terceira: o CRM que já está contratado. A terceira é usar um CRM, tipicamente Salesforce ou HubSpot, porque já está contratado. É a comparação que mais aparece em reunião e a menos adequada: CRM foi desenhado para gerir relacionamento comercial, cobra por vendedor e não trata CPF como chave transacional. Cadastro de tomador de crédito não é oportunidade de venda.

Comparativo

Comparativo montado em 2026-08-16 a partir do código deste building block e da documentação pública de Pismo, Celcoin e Zoop. Nenhum dos três publica preço em página aberta para este recorte, e este documento não estima nenhum. Não conseguimos abrir documentação de produto suficiente de Dock, Matera e Sinqia — a última foi absorvida pela Evertec e o site redireciona —, então elas não entram no comparativo.

Nossos diferenciais

1. O isolamento não é opcional em nenhum ponto do caminho. As cinco rotas exigem requireOrganization, e as consultas do repositório recebem o organizationId como parâmetro obrigatório. Isso é difícil de copiar não pela ideia, mas pela consistência: é o mesmo middleware nos 32 building blocks, então auditar o isolamento da plataforma inteira é auditar um arquivo.
2. O modelo é brasileiro por dentro, não por tradução. Faixa de renda, tipo de vínculo, UF, CEP, código de banco e tipo de conta são enumerações e colunas. Um cadastro internacional adaptado guarda isso como texto, e texto não filtra nem alimenta motor de decisão sem uma camada de limpeza que ninguém quer manter.
3. A pessoa é a mesma em todo o catálogo. O personId é o que o Decision Platform, o Pricing Engine, o Billing e o E-Signature carregam. Um cadastro isolado resolve o cadastro; este resolve a identidade compartilhada entre os blocos.

Quando escolher o concorrente

Quatro situações em que a resposta honesta é "não use o Customers".

O Customers ganha quando o problema é um cadastro de pessoa física, compartilhado por vários serviços seus, com separação rígida entre empresas clientes.

Precificação em definição

Precificação em definição. O Customers não tem preço fechado. Ele é um bloco de fundação: quase nunca é contratado sozinho, e sim junto com os blocos que consomem o cadastro — Decision Platform, Pricing Engine, Billing, E-Signature. Não há valor a divulgar, e este documento não estima nenhum.

O que dispara custo

O que dispara custo.

Comparação de custo

Comparação de custo. Não há comparação de preço a fazer, por dois motivos honestos.

• Primeiro, a alternativa mais comum é construir do zero, cujo custo é de engenharia e não de licença.
• Segundo, o cadastro de core banking e de BaaS não é vendido separado do produto bancário — Pismo, Celcoin e Zoop não publicam preço para esse recorte, e comparar o preço de um cadastro com o de uma plataforma bancária inteira produziria um número sem significado.

ROI — a conta de guardanapo

ROI. A conta de guardanapo tem duas linhas.

A primeira é o que não se escreve. Um cadastro de pessoa física com validação de CPF, enumerações brasileiras, exclusão lógica, paginação, filtros e isolamento por tenant é uma ou duas semanas de trabalho de um desenvolvedor experiente — por serviço que precisar dele. Com cinco serviços, isso são de cinco a dez semanas, mais a manutenção de cinco cópias que divergem.

A segunda é o incidente que não acontece. Vazamento de cadastro entre empresas clientes é incidente de dado pessoal com dever de comunicação à ANPD e ao titular (Lei 13.709/2018, art. 48). Não colocamos número nessa linha porque não existe número defensável — mas ela é a razão pela qual o isolamento é middleware obrigatório e não convenção de equipe.

As camadas e o caminho da requisição

flowchart TD
  CL["Cliente HTTP<br/>Bearer JWT emitido pelo IAM"] --> APP

  APP["Hono app · basePath /customers · applyCommonMiddleware<br/>bodyLimit 1MB · CORS · security headers · rate limit global"]
  APP --> RT["/api/v1/people → peopleRouter, 5 rotas"]
  APP --> HL["/health → status estático do serviço"]

  RT --> M1["authMiddleware"]
  M1 --> M2["requirePermission CUSTOMERS_PEOPLE_*"]
  M2 --> M3["requireOrganization<br/>403 sem organizationId"]
  M3 --> M4["Zod parse do corpo"]

  M4 --> SVC["services/PersonService<br/>valida CPF: sanitiza máscara e confere o dígito verificador<br/>checa unicidade do CPF<br/>grava → publica evento → devolve"]

  SVC --> REPO["repositories/PersonRepository<br/>Prisma → PostgreSQL · schema customers<br/>organizationId em toda leitura<br/>deletedAt = exclusão lógica"]
  SVC --> EVP["EventPublisher<br/>Redis Stream iam-events"]

  REPO --> PG[("PostgreSQL<br/>customers.people")]
  EVP --> EVT["customers.person.created<br/>customers.person.updated<br/>customers.person.deleted"]
  EVT --> CONS["Consumidores do stream<br/>audit-trail · webhooks-engine"]

O caminho de uma criação, ponta a ponta

O diagrama acima mostra as camadas paradas. Abaixo, as mesmas camadas em movimento — uma criação de pessoa, da autenticação no IAM até o consumo do evento por quem escuta o fluxo.

sequenceDiagram
  participant C as Cliente
  participant I as IAM
  participant CU as Customers
  participant PG as PostgreSQL
  participant RS as Redis stream iam-events
  participant CO as audit-trail e webhooks-engine

  C->>I: POST /iam/api/v1/users/login
  I-->>C: JWT assinado com organizationId e permissões
  C->>CU: POST /customers/api/v1/people com Bearer
  CU->>CU: authMiddleware verifica a assinatura HS256
  CU->>CU: requirePermission CUSTOMERS_PEOPLE_CREATE
  CU->>CU: requireOrganization, 403 se faltar organizationId
  CU->>CU: Zod valida o corpo aninhado em data.attributes
  CU->>CU: sanitizeCpf e isValidCpf, 400 VALIDATION se reprovar
  CU->>PG: taxIdExists, o CPF já está cadastrado?
  PG-->>CU: não existe
  CU->>PG: INSERT em customers.people
  PG-->>CU: pessoa gravada, com id
  CU->>RS: XADD customers.person.created
  RS-->>CU: evento publicado
  CU-->>C: 201 com data.attributes
  RS->>CO: entrega do evento aos consumidores
  CO->>CO: linha do tempo da auditoria e webhook externo

Decisões não óbvias

Decisões não óbvias. Cinco escolhas deste building block que não são as óbvias, cada uma com o trade-off que ela cobra.

A pessoa é uma tabela larga, não um grafo de tabelas

A pessoa é uma tabela larga, não um grafo de tabelas. Endereço, telefone e conta bancária são colunas de people, não tabelas relacionadas. O trade-off é explícito: a pessoa tem um endereço e uma conta bancária, não uma lista. Ganha-se leitura sem JOIN e escrita atômica; perde-se histórico de endereço. Para operação de crédito brasileira, o endereço atual é o que a esteira usa, e o histórico de endereço quem guarda é o Audit Trail — através do changes de cada evento.

O CPF é guardado sem máscara

O CPF é guardado sem máscara. sanitizeCpf remove pontos e traço antes de gravar. Isso torna a busca por filter[taxId] determinística: você pode consultar com ou sem máscara, porque o filtro sanitiza a entrada do mesmo jeito. A formatação é responsabilidade da interface.

O PATCH altera dois campos, e só

O PATCH altera dois campos, e só. updatePersonSchema aceita name e active. Não é limitação de implementação: alterar CPF, data de nascimento ou nome da mãe de um cadastro que já originou crédito é o tipo de mudança que precisa de processo, não de um PATCH. Se o seu fluxo exige alterar endereço ou renda por API, isso está na §15 como lacuna reconhecida.

A publicação de evento faz parte da transação lógica da escrita

A publicação de evento faz parte da transação lógica da escrita. createPerson, updatePerson e deletePerson encadeiam a publicação com andThen: se o Redis estiver fora, a chamada devolve 500 com INTERNAL. A escolha é deliberada — cadastro gravado sem evento produz um Audit Trail com buraco e um webhook que nunca dispara, e um erro visível é melhor que uma inconsistência silenciosa. O custo é que o Redis vira dependência de escrita, não só de leitura.

A exclusão é lógica em toda parte

A exclusão é lógica em toda parte. deletedAt preenchido, linha preservada. Todas as consultas filtram deletedAt: null. É o que a rastreabilidade de crédito e a auditoria exigem — e é também o motivo de o CPF de uma pessoa excluída continuar ocupando a restrição de unicidade (ver §15).

Monolito vs. standalone

Monolito vs. standalone. O app.ts é montado no monolito em src/app.ts e responde em http://localhost:3000/customers. O main.ts sobe o mesmo app com Bun.serve na porta 3003 quando DEPLOYMENT_MODE=standalone — que é o modo usado em staging e produção. Não há diferença de comportamento entre os modos: o BB não chama nenhum outro building block por HTTP. O que muda é que, em standalone, o applyCommonMiddleware é a única fonte de limite de corpo, CORS, cabeçalhos de segurança e limite de taxa.

Glossário

Glossário

Modelo de dados

Modelo de dados — schema customers no PostgreSQL. 1 modelo.

Uma entidade, duas relações: a Organization que a possui, no IAM, e as BillingAccount que podem apontar para ela, no Billing.

erDiagram
  Organization ||--o{ Person : possui
  Person ||--o{ BillingAccount : "é cobrada em"

  Person {
    uuid id PK
    uuid organizationId FK
    string name
    string taxIdType
    string taxIdValue UK
    boolean active
    string email
    string phoneCountryCode
    string phoneAreaCode
    string phoneNumber
    datetime birthDate
    string motherName
    string maritalStatus
    string employmentType
    decimal monthlyIncome
    string incomeRange
    string addressStreet
    string addressNumber
    string addressComplement
    string addressNeighborhood
    string addressCity
    string addressState
    string addressZipCode
    string addressCountry
    string bankCode
    string bankBranch
    string bankAccount
    string bankAccountType
    datetime createdAt
    datetime updatedAt
    datetime deletedAt
  }

Leia o diagrama junto com a tabela abaixo: taxIdValue é UK porque a restrição de unicidade é da coluna e vale para a plataforma inteira, não para a organização; monthlyIncome é Decimal(15, 2) no Prisma, com quinze dígitos e duas casas decimais; e deletedAt preenchido é o que tira a linha de todas as consultas sem apagá-la.

Campos por grupo:

Índices: organizationId, taxIdValue, name, active, deletedAt.

Enumerações

Enumerações

Os valores são em inglês e em caixa alta. Uma versão anterior desta documentação listava SOLTEIRO, CASADO, CLT/PJ/AUTONOMO e ATE_1_SALARIO — nenhum desses existe no código. Confira sempre contra src/customers/types/index.ts.

Ciclo de vida de uma pessoa

Ciclo de vida de uma pessoa

stateDiagram-v2
  [*] --> ativa: POST /people
  ativa --> inativa: PATCH com active false
  inativa --> ativa: PATCH com active true
  ativa --> excluida: DELETE /people/:id
  inativa --> excluida: DELETE /people/:id
  excluida --> [*]

  state "ativa · active=true" as ativa
  state "inativa · active=false" as inativa
  state "excluída logicamente · deletedAt preenchido" as excluida

O estado excluída logicamente é terminal: o registro sai de TODAS as consultas, não há rota de restauração e o CPF continua ocupado (§15). Já ativa e inativa são um par reversível — active é marcador de negócio, e a pessoa inativa continua consultável.

Prefixo: /customers. Em monolito, a base é http://localhost:3000. Em staging, https://customers.bb.stg.catalisa.app.

Todas as 5 rotas exigem, sem exceção: authMiddleware (Bearer JWT do IAM), requirePermission(...) e o middleware local requireOrganization, que devolve 403 quando o token não carrega organizationId.

Pessoas — /customers/api/v1/people

Saúde do serviço

A sonda de saúde não consulta o banco: responde {"status":"ok","service":"customers","version":...} enquanto o processo estiver de pé. Para orquestrador ela serve; para detectar Postgres indisponível, não.

POST /customers/api/v1/people

Atenção ao envelope. O corpo é aninhado em data.attributes — não é um objeto plano.

Request

{
  "data": {
    "type": "people",
    "attributes": {
      "name": "Maria Aparecida de Souza",
      "taxId": { "type": "BR_CPF", "value": "529.982.247-25" },
      "email": "maria@exemplo.com.br",
      "phone": { "countryCode": "+55", "areaCode": "11", "number": "998877665" },
      "birthDate": "1988-04-12T00:00:00.000Z",
      "motherName": "Joana de Souza",
      "maritalStatus": "MARRIED",
      "employmentType": "CLT",
      "monthlyIncome": { "amount": 7200.00, "currency": "BRL" },
      "incomeRange": "FROM_5K_TO_10K",
      "address": {
        "street": "Rua das Acácias", "number": "1200", "complement": "Apto 71",
        "neighborhood": "Vila Mariana", "city": "São Paulo",
        "state": "SP", "zipCode": "04101-300", "country": "BR"
      },
      "bankAccount": {
        "bankCode": "341", "branch": "0987",
        "accountNumber": "123456-7", "accountType": "CHECKING"
      },
      "active": true
    }
  }
}

{
  "data": {
    "type": "people",
    "attributes": {
      "name": "Maria Aparecida de Souza",
      "taxId": { "type": "BR_CPF", "value": "529.982.247-25" },
      "email": "maria@exemplo.com.br",
      "phone": { "countryCode": "+55", "areaCode": "11", "number": "998877665" },
      "birthDate": "1988-04-12T00:00:00.000Z",
      "motherName": "Joana de Souza",
      "maritalStatus": "MARRIED",
      "employmentType": "CLT",
      "monthlyIncome": { "amount": 7200.00, "currency": "BRL" },
      "incomeRange": "FROM_5K_TO_10K",
      "address": {
        "street": "Rua das Acácias", "number": "1200", "complement": "Apto 71",
        "neighborhood": "Vila Mariana", "city": "São Paulo",
        "state": "SP", "zipCode": "04101-300", "country": "BR"
      },
      "bankAccount": {
        "bankCode": "341", "branch": "0987",
        "accountNumber": "123456-7", "accountType": "CHECKING"
      },
      "active": true
    }
  }
}

Quando você informa address ou bankAccount, os campos internos marcados como obrigatórios no schema Zod passam a valer — street, number, neighborhood, city, state e zipCode no endereço; os quatro campos da conta bancária. É tudo ou nada por bloco.

Resposta 201

{
  "data": {
    "type": "people",
    "id": "6a5c3f21-9f0e-4a1c-9b76-2c1f4b8d0e33",
    "links": { "self": "/api/v1/people/6a5c3f21-9f0e-4a1c-9b76-2c1f4b8d0e33" },
    "attributes": {
      "name": "Maria Aparecida de Souza",
      "taxId": { "type": "BR_CPF", "value": "52998224725" },
      "email": "maria@exemplo.com.br",
      "active": true,
      "createdAt": "2026-08-16T13:22:41.001Z",
      "updatedAt": "2026-08-16T13:22:41.001Z"
    }
  },
  "links": { "self": "/api/v1/people/6a5c3f21-9f0e-4a1c-9b76-2c1f4b8d0e33" }
}

{
  "data": {
    "type": "people",
    "id": "6a5c3f21-9f0e-4a1c-9b76-2c1f4b8d0e33",
    "links": { "self": "/api/v1/people/6a5c3f21-9f0e-4a1c-9b76-2c1f4b8d0e33" },
    "attributes": {
      "name": "Maria Aparecida de Souza",
      "taxId": { "type": "BR_CPF", "value": "52998224725" },
      "email": "maria@exemplo.com.br",
      "active": true,
      "createdAt": "2026-08-16T13:22:41.001Z",
      "updatedAt": "2026-08-16T13:22:41.001Z"
    }
  },
  "links": { "self": "/api/v1/people/6a5c3f21-9f0e-4a1c-9b76-2c1f4b8d0e33" }
}

O taxId.value volta sem máscara, do jeito que foi gravado. O campo links.self é relativo e não inclui o prefixo /customers — some-o você mesmo ao montar URL absoluta.

Erros

GET /customers/api/v1/people

Parâmetros de consulta

Ordenação fixa: createdAt decrescente. Não há parâmetro para alterá-la.

Resposta 200

{
  "data": [ { "type": "people", "id": "...", "attributes": { "...": "..." } } ],
  "meta": {
    "totalItems": 137, "totalPages": 7, "currentPage": 1,
    "itemsPerPage": 20, "hasNextPage": true, "hasPreviousPage": false
  },
  "links": {
    "self":  "/api/v1/people?page[number]=1&page[size]=20",
    "first": "/api/v1/people?page[number]=1&page[size]=20",
    "next":  "/api/v1/people?page[number]=2&page[size]=20",
    "last":  "/api/v1/people?page[number]=7&page[size]=20"
  }
}

{
  "data": [ { "type": "people", "id": "...", "attributes": { "...": "..." } } ],
  "meta": {
    "totalItems": 137, "totalPages": 7, "currentPage": 1,
    "itemsPerPage": 20, "hasNextPage": true, "hasPreviousPage": false
  },
  "links": {
    "self":  "/api/v1/people?page[number]=1&page[size]=20",
    "first": "/api/v1/people?page[number]=1&page[size]=20",
    "next":  "/api/v1/people?page[number]=2&page[size]=20",
    "last":  "/api/v1/people?page[number]=7&page[size]=20"
  }
}

PATCH /customers/api/v1/people/:personId

Aceita apenas name e active. Qualquer outro campo é ignorado em silêncio pelo schema.

Request — as duas formas funcionam:

{ "data": { "attributes": { "active": false } } }

{ "data": { "attributes": { "active": false } } }

{ "active": false }

{ "active": false }

Responde 200 com a pessoa atualizada, ou 404 NOT_FOUND quando o personId não existe na sua organização — inclusive quando ele existe em outra. Um personId que não seja UUID válido devolve 400.

DELETE /customers/api/v1/people/:personId

Exclusão lógica. Responde 204 sem corpo. Chamar de novo no mesmo personId devolve 404, porque o registro já saiu das consultas.

Do zero ao primeiro cadastro consultável. Use as credenciais de AMBIENTES.md — nunca credencial de produção.

Os comandos abaixo não foram executados na redação deste documento. As respostas mostradas são as previstas pelo código.

1. Autenticar no IAM

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

echo "${TOKEN:0:24}..."

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

echo "${TOKEN:0:24}..."

Resposta esperada — o começo do JWT, prova de que a variável foi preenchida:

eyJhbGciOiJIUzI1NiIsInR5...

eyJhbGciOiJIUzI1NiIsInR5...

2. Confirmar que o token carrega a organização

echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq '.organizationId'

echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq '.organizationId'

Resposta esperada:

"b0000000-0000-0000-0000-000000000001"

"b0000000-0000-0000-0000-000000000001"

Sem esse claim, todas as rotas do Customers respondem 403.

3. Criar a primeira pessoa

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

PERSON=$(curl -s -X POST $API/people \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "people",
      "attributes": {
        "name": "Maria Aparecida de Souza",
        "taxId": { "type": "BR_CPF", "value": "529.982.247-25" },
        "email": "maria@exemplo.com.br",
        "employmentType": "CLT",
        "incomeRange": "FROM_5K_TO_10K"
      }
    }
  }')

PERSON_ID=$(echo "$PERSON" | jq -r '.data.id')
echo "$PERSON" | jq '.data.attributes.taxId'

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

PERSON=$(curl -s -X POST $API/people \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "people",
      "attributes": {
        "name": "Maria Aparecida de Souza",
        "taxId": { "type": "BR_CPF", "value": "529.982.247-25" },
        "email": "maria@exemplo.com.br",
        "employmentType": "CLT",
        "incomeRange": "FROM_5K_TO_10K"
      }
    }
  }')

PERSON_ID=$(echo "$PERSON" | jq -r '.data.id')
echo "$PERSON" | jq '.data.attributes.taxId'

Resposta esperada:

{ "type": "BR_CPF", "value": "52998224725" }

{ "type": "BR_CPF", "value": "52998224725" }

A máscara sumiu — é o comportamento esperado.

4. Ler de volta

curl -s "$API/people/$PERSON_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '.data.attributes | {name, taxId, employmentType}'

curl -s "$API/people/$PERSON_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '.data.attributes | {name, taxId, employmentType}'

Resposta esperada — o mesmo cadastro, agora vindo do banco:

{
  "name": "Maria Aparecida de Souza",
  "taxId": { "type": "BR_CPF", "value": "52998224725" },
  "employmentType": "CLT"
}

{
  "name": "Maria Aparecida de Souza",
  "taxId": { "type": "BR_CPF", "value": "52998224725" },
  "employmentType": "CLT"
}

5. Confirmar que o isolamento é real

curl -s -o /dev/null -w "%{http_code}\n" "$API/people" \
  -H "Authorization: Bearer token-invalido"

curl -s -o /dev/null -w "%{http_code}\n" "$API/people" \
  -H "Authorization: Bearer token-invalido"

Resposta esperada — só o código de status:

401

401

Retorna 401. Não há caminho em que ausência de token válido resulte em cadastro.

Encontrar uma pessoa pelo CPF

Objetivo. Descobrir se um CPF já está cadastrado na sua organização antes de abrir uma proposta.

1. Consultar pelo filtro de CPF

curl -s -G "$API/people" \
  --data-urlencode 'filter[taxId]=529.982.247-25' \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems, .data[0].id'

curl -s -G "$API/people" \
  --data-urlencode 'filter[taxId]=529.982.247-25' \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems, .data[0].id'

Resposta esperada quando o CPF já existe na sua organização:

1
"6a5c3f21-9f0e-4a1c-9b76-2c1f4b8d0e33"

1
"6a5c3f21-9f0e-4a1c-9b76-2c1f4b8d0e33"

2. Interpretar o resultado vazio

0
null

0
null

totalItems igual a 0 significa apenas que a sua organização não tem esse CPF. Vá para a receita "Descobrir por que o cadastro voltou 409" antes de concluir que ele está livre.

Armadilhas.

• O filtro sanitiza a máscara, então 529.982.247-25 e 52998224725 encontram o mesmo registro. Não normalize antes.
• Colchetes precisam de escape na maioria dos shells. Use -G --data-urlencode, como acima, em vez de montar a query na mão.
• totalItems: 0 não garante que o CPF esteja livre para cadastro: ele pode estar em uso por outra organização. Nesse caso o POST devolve 409 mesmo com a busca vazia — ver §15.

Cadastrar com endereço e conta bancária completos

Objetivo. Criar o cadastro pronto para crédito consignado, em que a conta de pagamento é obrigatória.

1. Enviar o cadastro completo

curl -s -X POST $API/people \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "data": { "type": "people", "attributes": {
      "name": "João Carlos Pereira",
      "taxId": { "type": "BR_CPF", "value": "11144477735" },
      "birthDate": "1975-09-30T00:00:00.000Z",
      "motherName": "Terezinha Pereira",
      "maritalStatus": "MARRIED",
      "employmentType": "RETIRED",
      "monthlyIncome": { "amount": 3100.50, "currency": "BRL" },
      "incomeRange": "FROM_2K_TO_5K",
      "address": {
        "street": "Avenida Central", "number": "45",
        "neighborhood": "Centro", "city": "Belo Horizonte",
        "state": "MG", "zipCode": "30110-000"
      },
      "bankAccount": {
        "bankCode": "104", "branch": "1234",
        "accountNumber": "98765-4", "accountType": "SAVINGS"
      }
    }}
  }' | jq '.data.id'

curl -s -X POST $API/people \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "data": { "type": "people", "attributes": {
      "name": "João Carlos Pereira",
      "taxId": { "type": "BR_CPF", "value": "11144477735" },
      "birthDate": "1975-09-30T00:00:00.000Z",
      "motherName": "Terezinha Pereira",
      "maritalStatus": "MARRIED",
      "employmentType": "RETIRED",
      "monthlyIncome": { "amount": 3100.50, "currency": "BRL" },
      "incomeRange": "FROM_2K_TO_5K",
      "address": {
        "street": "Avenida Central", "number": "45",
        "neighborhood": "Centro", "city": "Belo Horizonte",
        "state": "MG", "zipCode": "30110-000"
      },
      "bankAccount": {
        "bankCode": "104", "branch": "1234",
        "accountNumber": "98765-4", "accountType": "SAVINGS"
      }
    }}
  }' | jq '.data.id'

Resposta esperada — 201, e o identificador da pessoa criada:

"9d3f7c10-2b8a-4e55-8f31-77b0c4a9e102"

"9d3f7c10-2b8a-4e55-8f31-77b0c4a9e102"

2. Conferir que o endereço e a conta foram gravados

curl -s "$API/people/9d3f7c10-2b8a-4e55-8f31-77b0c4a9e102" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes | {address, bankAccount}'

curl -s "$API/people/9d3f7c10-2b8a-4e55-8f31-77b0c4a9e102" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes | {address, bankAccount}'

Resposta esperada:

{
  "address": {
    "street": "Avenida Central", "number": "45", "neighborhood": "Centro",
    "city": "Belo Horizonte", "state": "MG", "zipCode": "30110-000", "country": "BR"
  },
  "bankAccount": {
    "bankCode": "104", "branch": "1234",
    "accountNumber": "98765-4", "accountType": "SAVINGS"
  }
}

{
  "address": {
    "street": "Avenida Central", "number": "45", "neighborhood": "Centro",
    "city": "Belo Horizonte", "state": "MG", "zipCode": "30110-000", "country": "BR"
  },
  "bankAccount": {
    "bankCode": "104", "branch": "1234",
    "accountNumber": "98765-4", "accountType": "SAVINGS"
  }
}

Armadilhas.

• address e bankAccount são blocos tudo-ou-nada. Mandar só city dentro de address reprova no Zod com erro em data.attributes.address.street.
• birthDate exige data e hora ISO 8601. "1975-09-30" sozinho é reprovado.
• bankCode tem exatamente 3 dígitos — "104", não "0104" nem 104 como número.
• monthlyIncome.amount precisa ser positivo. Zero é reprovado.

Inativar sem excluir

Objetivo. Tirar a pessoa dos fluxos ativos preservando consulta e histórico.

1. Marcar como inativa

curl -s -X PATCH "$API/people/$PERSON_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"active": false}' | jq '.data.attributes.active'

curl -s -X PATCH "$API/people/$PERSON_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"active": false}' | jq '.data.attributes.active'

Resposta esperada:

false

false

2. Conferir que ela sumiu da lista de ativos

# Confere que ela sumiu da lista de ativos
curl -s -G "$API/people" --data-urlencode 'filter[active]=true' \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems'

# Confere que ela sumiu da lista de ativos
curl -s -G "$API/people" --data-urlencode 'filter[active]=true' \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems'

Resposta esperada — o total de ativos, um a menos que antes:

136

136

Armadilhas. active=false é diferente de exclusão: a pessoa continua aparecendo em GET /people sem filtro e em GET /people/:id. Se o objetivo é sumir de tudo, use DELETE — que é irreversível pela API.

Descobrir por que o cadastro voltou 409

Objetivo. Separar "CPF duplicado na minha base" de "CPF em uso por outra organização".

1. O CPF está na sua organização?

# 1. O CPF está na sua organização?
curl -s -G "$API/people" --data-urlencode "filter[taxId]=$CPF" \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems'

# 1. O CPF está na sua organização?
curl -s -G "$API/people" --data-urlencode "filter[taxId]=$CPF" \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems'

Resposta esperada quando ele não está na sua base:

0

0

2. Reenviar a criação e ler o corpo do erro

curl -s -X POST $API/people \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"people\",\"attributes\":{\"name\":\"Teste\",\"taxId\":{\"type\":\"BR_CPF\",\"value\":\"$CPF\"}}}}" \
  | jq '{error, message, details}'

curl -s -X POST $API/people \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":{\"type\":\"people\",\"attributes\":{\"name\":\"Teste\",\"taxId\":{\"type\":\"BR_CPF\",\"value\":\"$CPF\"}}}}" \
  | jq '{error, message, details}'

Resposta esperada — 409, com o corpo de erro padrão da plataforma:

{
  "error": "CONFLICT",
  "message": "CPF already exists",
  "details": { "field": "taxId.value" }
}

{
  "error": "CONFLICT",
  "message": "CPF already exists",
  "details": { "field": "taxId.value" }
}

flowchart TD
  P["POST /people devolve 409 CONFLICT"] --> B{"filter[taxId] na sua organização<br/>devolve totalItems maior que zero?"}
  B -->|"sim"| M["CPF duplicado na sua própria base<br/>reaproveite o cadastro que já existe"]
  B -->|"não"| O["CPF em uso por outra organização,<br/>ou por uma pessoa excluída logicamente"]
  O --> S["Sem endpoint para resolver — acione o suporte, §15"]

Se o resultado for 0 e o POST continuar devolvendo 409 CONFLICT, o CPF está cadastrado em outra organização da plataforma. A restrição de unicidade de taxIdValue é global, e a exclusão lógica não a libera: um CPF de pessoa excluída continua bloqueando novo cadastro. Não há endpoint para resolver isso — é a limitação registrada na §15, e o caminho é acionar o suporte.

Reagir a mudanças de cadastro em outro serviço

Objetivo. Manter um cache ou um índice de busca sincronizado sem carga noturna.

O Customers publica três eventos no fluxo Redis iam-events:

Todos carregam metadata.organizationId e metadata.timestamp.

flowchart LR
  W["POST · PATCH · DELETE<br/>no Customers"] --> S["Redis stream iam-events"]
  S --> AT["audit-trail<br/>linha do tempo do cadastro"]
  S --> WH["webhooks-engine<br/>entrega para fora da plataforma"]
  S --> MEU["seu consumidor<br/>cache ou índice de busca"]
  MEU -.->|"preferível ao acesso direto ao stream"| WH

Armadilhas.

• O evento de criação carrega CPF, nome, e-mail e telefone em texto puro na carga. Quem consome trata dado pessoal — trate o consumidor com o mesmo cuidado que trataria o banco.
• Se o Redis estiver indisponível, a escrita falha com 500. Isso é proposital (§7): não existe cadastro gravado sem evento publicado.
• Para receber os eventos fora da plataforma, use o Webhooks Engine em vez de ler o fluxo direto.

flowchart TD
  IAM["IAM<br/>organizationId + permissões"] -->|"Bearer JWT"| CU["CUSTOMERS<br/>quem compra"]

  CU -->|"personId · sua app liga os dois"| PR["Products<br/>o que vende"]
  CU -->|"personId"| FS["File Storage<br/>documentos"]

  PR --> DP["Decision Platform<br/>aprova/recusa"]
  CU -->|"eventos customers.person.*"| AT["Audit Trail<br/>linha do tempo"]
  CU -->|"eventos customers.person.*"| WH["Webhooks Engine<br/>entrega externa"]

  DP --> PE["Pricing Engine<br/>taxa por risco"]
  PE --> ES["E-Signature<br/>contrato"]
  ES --> BI["Billing<br/>cobrança"]

A pessoa é cadastrada UMA vez e atravessa a esteira inteira pelo mesmo id.

Este diagrama é o argumento comercial: o cadastro não é um fim, é a primeira peça de uma esteira que já está montada. Um cadastro isolado obrigaria você a construir cada seta.

Variáveis de ambiente

Não há nenhuma variável específica do Customers. Ele não tem chave de cifragem própria, não fala com provedor externo e não guarda segredo.

Dependências de infraestrutura

Limites

Catálogo de erros

Observabilidade

• GET /customers/health responde {"status":"ok","service":"customers","version":"..."}. É sonda de processo, não de banco.
• Todo erro passa pelo errorHandler e sai no log com logger.error({ err }, 'Request error').
• Cada evento publicado é contabilizado por recordEventPublished, com o tipo do evento e o building block de origem — dá para monitorar volume de cadastro por essa métrica.
• O EventPublisher injeta contexto de rastreamento (traceId, spanId) na metadata do evento, então a criação de uma pessoa e o registro dela no Audit Trail ficam ligados no mesmo trace.

Isolamento entre organizações

Isolamento entre organizações. O organizationId é claim assinado do JWT e chega ao serviço pelo c.get('user'). As cinco rotas aplicam o middleware local requireOrganization, que devolve 403 quando o claim está ausente. As três leituras do repositório — findById, findMany e a busca por identificador — recebem organizationId como parâmetro obrigatório e o incluem na cláusula where. Nenhuma rota lê organizationId do corpo, da query ou de cabeçalho. Uma pessoa de outra organização é indistinguível de uma pessoa inexistente: as duas devolvem 404.

Autenticação e permissões

Autenticação e permissões. Bearer JWT emitido pelo IAM, assinatura HS256 verificada localmente. Cada rota exige uma permissão nominal: CUSTOMERS_PEOPLE_CREATE, _READ, _UPDATE ou _DELETE. A organização é o teto — um papel que conceda CUSTOMERS_PEOPLE_DELETE numa organização que não contratou o Customers não concede nada.

Que dado pessoal este BB trata

Que dado pessoal este BB trata. Todos os campos de Person são dados pessoais na definição do art. 5º, I da LGPD: nome, CPF, data de nascimento, nome da mãe, e-mail, telefone, endereço, renda, vínculo empregatício e conta bancária. Não há dado pessoal sensível na definição do art. 5º, II — o BB não guarda origem racial, convicção religiosa, opinião política, filiação sindical, dado de saúde, vida sexual, genético ou biométrico.

Criptografia de campo: não há

Criptografia de campo: não há. O CPF, o nome, a renda e a conta bancária são gravados em texto no PostgreSQL. A proteção é de camada — TLS no transporte, credencial de banco em SOPS, rede fechada — e não de campo. Se o seu enquadramento exige cifragem em repouso por coluna, isso não está implementado e está registrado na §15. Cifragem de disco depende da infraestrutura em que o Postgres roda e não é garantida por este building block.

Mascaramento: parcial e só no caminho do log

Mascaramento: parcial e só no caminho do log. O Person retornado pela API traz o CPF completo, sem máscara. Não há endpoint que devolva o CPF parcialmente ocultado. O mascaramento que existe é do Audit Trail, que substitui campos com nome parecido com password, secret, token e apiKey por [REDACTED] — a lista não inclui CPF, e o CPF publicado no evento customers.person.created chega ao log de auditoria em texto. Considere isso ao definir quem tem AUDIT_LOGS_READ.

Retenção e eliminação

Retenção e eliminação. Não há política de retenção automática: o registro fica enquanto a organização existir. DELETE faz exclusão lógica — deletedAt preenchido, linha preservada, registro fora de todas as consultas. Isso se apoia no art. 16, I da LGPD, que autoriza a conservação após o término do tratamento para cumprimento de obrigação legal ou regulatória; para instituição regulada pelo BACEN, os cinco anos de guarda do art. 23 da Resolução CMN 4.893/2021 são exatamente essa obrigação. Mas exclusão lógica não é eliminação: atender a um pedido do titular sob o art. 18, VI exige expurgo definitivo, que hoje é operação manual de banco, sem endpoint e sem registro próprio. E o § 6º do art. 18 exige comunicar de imediato os agentes com quem houve uso compartilhado — o que, aqui, significa notificar quem consome os eventos customers.person.*, e não há automação para isso. Ver §15.

Superfície de escrita

Superfície de escrita. O PATCH altera apenas name e active. CPF, data de nascimento, nome da mãe, renda, endereço e conta bancária não podem ser alterados por API depois da criação. Do ponto de vista de integridade isso é uma proteção; do ponto de vista do direito de correção do titular (art. 18, III), é uma lacuna operacional — registrada na §15.

Enquadramento regulatório

Enquadramento regulatório. O Customers é um cadastro, não um sistema regulado. Ele não é meio de pagamento, não movimenta recurso e não está sujeito por si só a exigência do BACEN. Quando ele alimenta uma operação de crédito de instituição autorizada, as obrigações de registro e de guarda recaem sobre a instituição, e a peça da plataforma que atende a rastreabilidade é o Audit Trail — que precisa estar efetivamente ligado, e cujo estado atual está descrito no README dele. Não há certificação PCI-DSS, SOC 2 ou ISO 27001 para este building block, e nenhuma deve ser afirmada em proposta.

O Customers faz KYC?

Não. Ele valida o CPF matematicamente — dígito verificador e sequência repetida — e nada além disso. Não consulta a Receita Federal, não checa bureau de crédito, não verifica lista de pessoa politicamente exposta e não faz prova de vida. Contrate um provedor de KYC para isso e guarde aqui o cadastro e o resultado. Vender KYC com base neste building block é venda errada e aparece na primeira due diligence.

Posso cadastrar empresa, com CNPJ?

Hoje não. O tipo BR_CNPJ existe na enumeração e as permissões CUSTOMERS_COMPANIES_* existem no IAM, mas não há rota, tabela nem validação de CNPJ. Qualquer tentativa devolve 400. Está na §15 como especificado e não implementado.

Duas empresas clientes minhas podem ter o mesmo cliente?

Não, e essa é a limitação mais importante deste building block. O CPF é único na plataforma inteira, não por organização. Se você opera correspondentes, marketplace de crédito ou qualquer modelo em que a mesma pessoa apareça em duas carteiras, o segundo cadastro recebe 409. Leia a §15 antes de fechar contrato nesse cenário.

Por que não consigo atualizar o endereço pela API?

Porque o PATCH aceita apenas name e active. A decisão original protege a integridade de um cadastro que já originou crédito — alterar CPF ou data de nascimento por API é o tipo de mudança que costuma ser um erro. O efeito colateral é que endereço e renda também ficaram de fora, o que é uma lacuna e está registrada na §15.

O CPF é criptografado no banco?

Não. Ele é gravado em texto, sem máscara, na coluna tax_id_value. A proteção é de camada: TLS no transporte, rede fechada, credencial de banco em SOPS e permissão por rota. Se o seu enquadramento exige cifragem por coluna, isso não existe hoje.

Como atendo a um pedido de eliminação de dados da LGPD?

DELETE /people/:personId faz exclusão lógica — o registro sai de todas as consultas e permanece na tabela. Para muitos casos isso é o correto, porque o art. 16 da LGPD admite a conservação para cumprimento de obrigação legal, e operação de crédito costuma se enquadrar. Para eliminação definitiva sob o art. 18, VI, hoje é operação manual de banco, sem endpoint. Trate como processo com dono, não como chamada de API.

O que acontece se o Redis cair?

A leitura continua funcionando. A escrita falha com 500, porque a publicação do evento faz parte da cadeia de criação, atualização e exclusão. É deliberado: um cadastro gravado sem evento produz um Audit Trail com buraco e um webhook que nunca dispara. Se a sua chamada de escrita voltou 500 sem erro de validação, cheque o Redis antes de procurar bug.

Qual a diferença entre active: false e DELETE?

active: false é estado de negócio: a pessoa continua consultável e continua aparecendo na listagem sem filtro. DELETE é exclusão lógica: some de tudo, não tem rota de volta, e o CPF continua ocupado. Use o primeiro para pausar relacionamento e o segundo para encerrar cadastro.

Como sei que outra empresa cliente não vê meus cadastros?

Porque não existe caminho no código em que a organização venha da requisição. Ela vem do claim assinado do token, o middleware requireOrganization recusa token sem ela, e as três consultas do repositório recebem organizationId como parâmetro obrigatório. O teste prático é o da §10: uma pessoa de outra organização devolve 404, igualzinho a uma pessoa inexistente.

Por que o cadastro só tem um endereço?

Porque a esteira de crédito usa o endereço atual, e modelar uma lista custaria uma tabela, um JOIN em toda leitura e uma regra de "qual é o principal". A troca de endereço fica registrada no changes do evento customers.person.updated, que o Audit Trail persiste — desde que o consumidor de auditoria esteja ligado. Confira isso no README dele antes de contar com o histórico.

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