# Retornar as pessoas por filtro

Permite consultar as pessoas cadastradas, com suporte a filtros como página, tamanho, ordenação, busca por nome, documento, email, tipo de perfil, entre outros. Essa funcionalidade facilita a listagem, o monitoramento de pessoas no sistema.

Endpoint: GET /v1/pessoas
Version: v1
Security: BearerAuth

## Security:

  - `BearerAuth` (unknown)
    apiKey in header Authorization

## Query parameters:

  - `pagina` (integer)
    Página

  - `tamanho_pagina` (integer)
    Tamanho da página

  - `tipo_ordenacao` (string)
    Tipo de ordenação

  - `ordem_ordenacao` (string)
    Ordem de ordenação

  - `busca` (string)
    Busca textual pelo documento ou nome do cliente/empresa

  - `ids` (string)
    IDs das pessoas

  - `documentos` (string)
    Documentos das pessoas (CPF/CNPJ)

  - `paises` (string)
    Países das pessoas

  - `cidades` (string)
    Cidades das pessoas

  - `ufs` (string)
    Abreviações das unidades federativas (estados) das pessoas

  - `codigos_pessoa` (string)
    Códigos de cadastro das pessoas

  - `emails` (string)
    Emails das pessoas

  - `tipos_pessoa` (string)
    Tipos de pessoa

  - `nomes` (string)
    Nomes das pessoas, pode ser pessoa física, jurídica ou estrangeira

  - `telefones` (string)
    Telefones das pessoas

  - `data_criacao_inicio` (string)
    Data de início para filtrar pessoas criadas a partir dessa data, obrigatório se data_criacao_fim for preenchido

  - `data_criacao_fim` (string)
    Data de fim para filtrar pessoas criadas até essa data, obrigatório se data_criacao_inicio for preenchido

  - `data_alteracao_de` (string)
    Data de alteracao de (ISO 8601, São Paulo/GMT-3)

  - `data_alteracao_ate` (string)
    Data de alteracao até (ISO 8601, São Paulo/GMT-3)

  - `tipo_perfil` (string)
    Tipo de perfil da pessoa

  - `com_endereco` (boolean)
    Indica se deve retornar pessoas com endereço

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `items` (array)
    Lista de itens do resumo de pessoas

  - `items.ativo` (boolean)
    Indica se a pessoa está ativa ou inativa
    Example: true

  - `items.data_alteracao` (string)
    Data/hora da última alteração
    Example: 2024-01-15T10:30:00

  - `items.data_criacao` (string)
    Data/hora de criação
    Example: 2024-01-15T10:30:00

  - `items.documento` (string)
    Documento da pessoa (CPF/CNPJ)
    Example: 123.456.789-00

  - `items.email` (string)
    Email da pessoa
    Example: joao.silva@email.com

  - `items.endereco` (object)
    Endereço da pessoa

  - `items.endereco.bairro` (string)
    Bairro do endereço
    Example: Centro

  - `items.endereco.cep` (string)
    CEP do endereço
    Example: 12345-678

  - `items.endereco.cidade` (string)
    Cidade do endereço
    Example: São Paulo

  - `items.endereco.complemento` (string)
    Complemento do endereço
    Example: Apto 45

  - `items.endereco.estado` (string)
    Estado do endereço
    Example: SP

  - `items.endereco.id` (string)
    ID do endereço
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `items.endereco.id_cidade` (integer)
    ID da cidade
    Example: 3550308

  - `items.endereco.logradouro` (string)
    Logradouro do endereço
    Example: Rua das Flores

  - `items.endereco.numero` (string)
    Número do endereço
    Example: 123

  - `items.endereco.pais` (string)
    País do endereço
    Example: Brasil

  - `items.id` (string)
    ID da pessoa
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `items.id_legado` (integer)
    ID legado da pessoa
    Example: 12345

  - `items.nome` (string)
    Nome da pessoa (física, jurídica ou estrangeira)
    Example: João Silva

  - `items.observacoes_gerais` (string)
    Observações gerais sobre a pessoa
    Example: Cliente preferencial

  - `items.perfis` (array)
    Perfis associados à pessoa (Cliente, Fornecedor, Transportadora)
    Example: ["CLIENTE","FORNECEDOR","TRANSPORTADORA"]

  - `items.telefone` (string)
    Telefone da pessoa
    Example: (11) 1234-5678

  - `items.tipo_pessoa` (string)
    Tipo de pessoa (Física, Jurídica ou Estrangeira)
    Example: FISICA

  - `items.uuid_legado` (string)
    UUID legado da pessoa
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `totalItems` (integer)
    Total de itens encontrados
    Example: 150

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `error` (string)
    Mensagem de erro
    Example: Mensagem de erro detalhada

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

  - `error` (string)
    Mensagem de erro
    Example: Mensagem de erro detalhada

## Response 429:

  - `429` (unknown)
    Too Many Requests

## Response 429 fields (application/json):

  - `error` (string)
    Mensagem de erro
    Example: Mensagem de erro detalhada

## Response 500:

  - `500` (unknown)
    Internal Server Error

## Response 500 fields (application/json):

  - `error` (string)
    Mensagem de erro
    Example: Mensagem de erro detalhada

