Pessoas

Gerenciamento de pessoas físicas (clientes) na Catalisa Platform.

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`

Criar Pessoa

POST /api/v1/people

Cria uma nova pessoa no sistema.

Request

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo
`taxId`	object	Sim	Documento (CPF)
`taxId.type`	string	Sim	`BR_CPF`
`taxId.value`	string	Sim	Número do CPF
`email`	string	Não	Email de contato
`phone`	object	Não	Telefone
`phone.areaCode`	string	Sim*	DDD (2 dígitos)
`phone.number`	string	Sim*	Número (8-9 dígitos)
`phone.countryCode`	string	Não	Código do país (default: +55)
`birthDate`	string	Não	Data de nascimento (ISO 8601)
`motherName`	string	Não	Nome da mãe
`maritalStatus`	string	Não	Estado civil
`employmentType`	string	Não	Tipo de emprego
`monthlyIncome`	object	Não	Renda mensal
`incomeRange`	string	Não	Faixa de renda
`address`	object	Não	Endereço completo
`bankAccount`	object	Não	Dados bancários
`active`	boolean	Não	Ativo (default: true)

cURL
JavaScript

curl -X POST 'https://customers.stg.catalisa.app/api/v1/people' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "people",
      "attributes": {
        "name": "Joao da Silva Santos",
        "taxId": {
          "type": "BR_CPF",
          "value": "123.456.789-00"
        },
        "email": "joao.silva@exemplo.com",
        "phone": {
          "countryCode": "+55",
          "areaCode": "11",
          "number": "999887766"
        },
        "birthDate": "1990-05-15",
        "motherName": "Maria da Silva",
        "maritalStatus": "SINGLE",
        "employmentType": "CLT",
        "monthlyIncome": {
          "amount": 5000.00,
          "currency": "BRL"
        },
        "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"
        }
      }
    }
  }'

const response = await fetch('https://customers.stg.catalisa.app/api/v1/people', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'people',
      attributes: {
        name: 'Joao da Silva Santos',
        taxId: {
          type: 'BR_CPF',
          value: '123.456.789-00',
        },
        email: 'joao.silva@exemplo.com',
        phone: {
          countryCode: '+55',
          areaCode: '11',
          number: '999887766',
        },
        birthDate: '1990-05-15',
        motherName: 'Maria da Silva',
        maritalStatus: 'SINGLE',
        employmentType: 'CLT',
        monthlyIncome: {
          amount: 5000.0,
          currency: 'BRL',
        },
        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',
        },
      },
    },
  }),
});

const pessoa = await response.json();

Response (201 Created)

{
  "data": {
    "type": "people",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "Joao da Silva Santos",
      "taxId": {
        "type": "BR_CPF",
        "value": "123.456.789-00"
      },
      "email": "joao.silva@exemplo.com",
      "phone": {
        "countryCode": "+55",
        "areaCode": "11",
        "number": "999887766"
      },
      "birthDate": "1990-05-15T00:00:00.000Z",
      "motherName": "Maria da Silva",
      "maritalStatus": "SINGLE",
      "employmentType": "CLT",
      "monthlyIncome": {
        "amount": 5000.0,
        "currency": "BRL"
      },
      "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"
    },
    "links": {
      "self": "/api/v1/people/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Listar Pessoas

GET /api/v1/people

Lista pessoas com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[active]`	boolean	Filtrar por status ativo
`filter[name]`	string	Filtrar por nome (parcial)
`filter[taxId]`	string	Filtrar por CPF

cURL
JavaScript

curl 'https://customers.stg.catalisa.app/api/v1/people?page[number]=1&page[size]=20&filter[active]=true' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'page[number]': '1',
  'page[size]': '20',
  'filter[active]': 'true',
});

const response = await fetch(`https://customers.stg.catalisa.app/api/v1/people?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta, links } = await response.json();

Response (200 OK)

{
  "data": [
    {
      "type": "people",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "name": "Joao da Silva Santos",
        "taxId": {
          "type": "BR_CPF",
          "value": "123.456.789-00"
        },
        "email": "joao.silva@exemplo.com",
        "active": true
      }
    }
  ],
  "meta": {
    "totalItems": 50,
    "totalPages": 3,
    "currentPage": 1,
    "itemsPerPage": 20
  },
  "links": {
    "self": "/api/v1/people?page[number]=1&page[size]=20",
    "next": "/api/v1/people?page[number]=2&page[size]=20"
  }
}

Obter Pessoa

GET /api/v1/people/:personId

Obtém detalhes de uma pessoa específica.

cURL
JavaScript

curl 'https://customers.stg.catalisa.app/api/v1/people/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

const personId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://customers.stg.catalisa.app/api/v1/people/${personId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const pessoa = await response.json();

Response (200 OK)

{
  "data": {
    "type": "people",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "Joao da Silva Santos",
      "taxId": {
        "type": "BR_CPF",
        "value": "123.456.789-00"
      },
      "email": "joao.silva@exemplo.com",
      "active": true,
      "createdAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/people/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Atualizar Pessoa

PATCH /api/v1/people/:personId

Atualiza dados de uma pessoa.

informação

Apenas os campos name e active podem ser atualizados. Para alterar outros dados (CPF, endereço, etc.), é necessário excluir e recriar o registro.

Request

Campo	Tipo	Obrigatório	Descrição
`name`	string	Não	Novo nome
`active`	boolean	Não	Status ativo

cURL
JavaScript

curl -X PATCH 'https://customers.stg.catalisa.app/api/v1/people/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Joao da Silva Santos Junior",
    "active": false
  }'

const personId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://customers.stg.catalisa.app/api/v1/people/${personId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Joao da Silva Santos Junior',
    active: false,
  }),
});

const pessoa = await response.json();

Response (200 OK)

{
  "data": {
    "type": "people",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "Joao da Silva Santos Junior",
      "taxId": {
        "type": "BR_CPF",
        "value": "123.456.789-00"
      },
      "active": false,
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Excluir Pessoa

DELETE /api/v1/people/:personId

Remove uma pessoa do sistema.

cURL
JavaScript

curl -X DELETE 'https://customers.stg.catalisa.app/api/v1/people/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

const personId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://customers.stg.catalisa.app/api/v1/people/${personId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

// Status 204 No Content = sucesso

Response (204 No Content)

Sem corpo de resposta.

Validação de CPF

O sistema valida automaticamente o formato do CPF. Formatos aceitos:

123.456.789-00 (com pontuação)
12345678900 (sem pontuação)

Atenção

O sistema valida apenas o formato do CPF, não a validade junto a Receita Federal.

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	CPF inválido ou campos obrigatórios ausentes
404	`NOT_FOUND`	Pessoa não encontrada
409	`CONFLICT`	CPF já cadastrado na organização

Endpoints​

Criar Pessoa​

Request​

Response (201 Created)​

Listar Pessoas​

Query Parameters​

Response (200 OK)​

Obter Pessoa​

Response (200 OK)​

Atualizar Pessoa​

Request​

Response (200 OK)​

Excluir Pessoa​

Response (204 No Content)​

Validação de CPF​

Erros Comuns​

Endpoints

Criar Pessoa

Request

Response (201 Created)

Listar Pessoas

Query Parameters

Response (200 OK)

Obter Pessoa

Response (200 OK)

Atualizar Pessoa

Request

Response (200 OK)

Excluir Pessoa

Response (204 No Content)

Validação de CPF

Erros Comuns