# Retornar as pessoas por filtro

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

## Query parameters:

  - `pagina` (integer)
    Página

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

  - `tipo_ordenacao` (string)
    Tipo de ordenação (nome, email, documento e ativo)

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

  - `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 (Física, Jurídica ou Estrangeira)

  - `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 (Cliente, Fornecedor, Transportadora)

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

## 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 fields (application/json):

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

## Response 401 fields (application/json):

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

## Response 429 fields (application/json):

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

## Response 500 fields (application/json):

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