Customers

O Building Block Customers fornece funcionalidades para cadastro e gestão de clientes (pessoas físicas) na Catalisa Platform.

Visão Geral

O módulo Customers e tenant-scoped, ou seja, requer um token com organizationId. Todos os recursos são isolados por organização.

Funcionalidades principais:

• Cadastro de pessoas físicas (CPF)
• Dados completos para mercado brasileiro (endereço, banco, renda)
• Validação de CPF
• Busca e filtragem de clientes

Base URL

https://api.catalisa.io/customers

Recursos

Recurso	Descrição
Pessoas	Gerenciamento de pessoas físicas

Endpoints

Método	Endpoint	Descrição	Permissão
POST	/api/v1/people	Criar pessoa	CUSTOMERS_PEOPLE_CREATE
GET	/api/v1/people	Listar pessoas	CUSTOMERS_PEOPLE_READ
GET	/api/v1/people/:id	Obter pessoa	CUSTOMERS_PEOPLE_READ
PATCH	/api/v1/people/:id	Atualizar pessoa	CUSTOMERS_PEOPLE_UPDATE
DELETE	/api/v1/people/:id	Excluir pessoa	CUSTOMERS_PEOPLE_DELETE

Dados Brasileiros

O módulo foi projetado específicamente para o mercado brasileiro, com suporte a:

Tipos de Documento

Tipo	Descrição	Formato
BR_CPF	CPF (pessoa fisica)	XXX.XXX.XXX-XX
BR_CNPJ	CNPJ (pessoa juridica)	XX.XXX.XXX/XXXX-XX

Estados Brasileiros

Todos os 27 estados: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, PR, RJ, RN, RO, RR, RS, SC, SE, SP, TO

Estado Civil

Valor	Descrição
SINGLE	Solteiro(a)
MARRIED	Casado(a)
DIVORCED	Divorciado(a)
WIDOWED	Viuvo(a)
SEPARATED	Separado(a)
CIVIL_UNION	Uniao estavel

Tipo de Emprego

Valor	Descrição
CLT	Trabalhador CLT
PUBLIC_SERVANT	Servidor público
SELF_EMPLOYED	Autonomo
BUSINESS_OWNER	Empresario
RETIRED	Aposentado
PENSIONER	Pensionista
LIBERAL_PROFESSIONAL	Profissional liberal
UNEMPLOYED	Desempregado
STUDENT	Estudante

Faixa de Renda

Valor	Faixa
UP_TO_2K	Ate R$ 2.000
FROM_2K_TO_5K	R$ 2.000 a R$ 5.000
FROM_5K_TO_10K	R$ 5.000 a R$ 10.000
FROM_10K_TO_20K	R$ 10.000 a R$ 20.000
FROM_20K_TO_50K	R$ 20.000 a R$ 50.000
ABOVE_50K	Acima de R$ 50.000

Tipo de Conta Bancaria

Valor	Descrição
CHECKING	Conta corrente
SAVINGS	Conta poupanca
PAYMENT	Conta de pagamento

Estrutura de Dados

Pessoa

{
  "data": {
    "type": "people",
    "id": "uuid",
    "attributes": {
      "name": "Nome Completo",
      "taxId": {
        "type": "BR_CPF",
        "value": "123.456.789-00"
      },
      "email": "email@exemplo.com",
      "phone": {
        "countryCode": "+55",
        "areaCode": "11",
        "number": "999887766"
      },
      "birthDate": "1990-01-15",
      "motherName": "Nome da Mae",
      "maritalStatus": "SINGLE",
      "employmentType": "CLT",
      "monthlyIncome": {
        "amount": 5000.00,
        "currency": "BRL"
      },
      "incomeRange": "FROM_2K_TO_5K",
      "address": {
        "street": "Rua das Flores",
        "number": "123",
        "complement": "Apto 45",
        "neighborhood": "Centro",
        "city": "Sao Paulo",
        "state": "SP",
        "zipCode": "01234-567"
      },
      "bankAccount": {
        "bankCode": "001",
        "branch": "1234",
        "accountNumber": "12345-6",
        "accountType": "CHECKING"
      },
      "active": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Multi-tenancy

Todos os recursos são automaticamente filtrados pelo organizationId presente no token JWT. Isso garante isolamento completo entre organizacoes.

Org A ──► Pessoas da Org A
Org B ──► Pessoas da Org B

informação

O organizationId e extraido automaticamente do token. Voce nao precisa (e nao pode) especifica-lo nas requisições.