# Pessoas

A API de Pessoas (v1) tem como objetivo permitir o cadastro, consulta, ativação, desativação, exclusão e atualização dos registros de pessoas (clientes, fornecedores, transportadoras) no sistema da Conta Azul.

Por meio dessa funcionalidade, sistemas externos podem manter seus cadastros sincronizados, automatizar a gestão de perfis de pessoas e garantir que os dados estejam sempre atualizados entre plataformas.

---

Se desejar aprofundar o entendimento das regras de negócio aplicadas pelo ERP, recomendamos, de forma opcional a consulta à nossa Central de Ajuda:

Clientes: [https://ajuda.contaazul.com/hc/pt-br/articles/115007916448-Clientes-como-cadastrar](https://ajuda.contaazul.com/hc/pt-br/articles/115007916448-Clientes-como-cadastrar)


Version: v1

## Servers

```
https://api-v2.contaazul.com
```

## Security

### BearerAuth

Digite **'Bearer <JWT>'**, onde JWT é o access_token recebido no login (passo 2 do fluxo de autenticação).

Type: apiKey
In: header
Name: Authorization

## Download OpenAPI description

[Pessoas](https://developers.contaazul.com/_bundle/open-api-docs/open-api-person.yaml)

## v1

Operações relacionadas a pessoas

### Retornar as pessoas por filtro

 - [GET /v1/pessoas](https://developers.contaazul.com/open-api-docs/open-api-person/v1/retornapessoasporfiltros.md): 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.

### Criar uma nova pessoa

 - [POST /v1/pessoas](https://developers.contaazul.com/open-api-docs/open-api-person/v1/criarpessoa.md): Permite criar uma nova pessoa, informando dados como nome, tipo de pessoa (Física, Jurídica ou Estrangeira), documentos (CPF, CNPJ), email, perfis associados, endereços e outros parâmetros. Esse endpoint viabiliza a automação de cadastro de clientes, fornecedores e transportadoras.

### Ativar pessoas em lote

 - [POST /v1/pessoas/ativar](https://developers.contaazul.com/open-api-docs/open-api-person/v1/ativarpessoasemlote.md): Permite ativar em lote um conjunto de pessoas previamente inativadas ou que estejam com status desativado. Essa funcionalidade é útil para reativar perfis inativos de forma massiva.

### Retornar dados da empresa conectada

 - [GET /v1/pessoas/conta-conectada](https://developers.contaazul.com/open-api-docs/open-api-person/v1/retornaempresadacontaconectada.md): Permite consultar as informações cadastrais e de contato da empresa vinculada ao token de autenticação utilizado na requisição. Use este endpoint para exibir ou validar os dados da empresa parceira conectada à sua integração, como razão social e CNPJ.

### Excluir pessoas em lote

 - [POST /v1/pessoas/excluir](https://developers.contaazul.com/open-api-docs/open-api-person/v1/excluirpessoasemlote.md): Permite excluir pessoas em lote, a partir de seus identificadores.

### Desativar pessoas em lote

 - [POST /v1/pessoas/inativar](https://developers.contaazul.com/open-api-docs/open-api-person/v1/desativarpessoasemlote.md): Permite inativar em lote pessoas, alterando seu status para "inativo". Útil para automações de limpeza de cadastros ou para perfis que não precisam mais estar ativos.

### Retornar a pessoa por legacyid

 - [GET /v1/pessoas/legado/{id}](https://developers.contaazul.com/open-api-docs/open-api-person/v1/retornapessoaporlegacyid.md): Esse endpoint existe para garantir compatibilidade entre a API antiga (V1 legada) e a API nova de Pessoas. Quando você faz requisições na API nova, cada pessoa passa a ter um UUID, que é o novo identificador usado pelo ERP e pelas integrações atuais. Ao mesmo tempo, algumas aplicações antigas ainda usam o id_legado, que era o identificador utilizado na API V1. Importante saber - Relação entre os IDs: uuid → ID novo da pessoa (padrão atual), id_legado → ID antigo, usado na primeira versão da API.

### Retornar a pessoa por id

 - [GET /v1/pessoas/{id}](https://developers.contaazul.com/open-api-docs/open-api-person/v1/retornapessoaporid.md): Permite consultar os detalhes de uma pessoa específica pelo seu identificador (id). A resposta inclui campos completos como nome, tipo de pessoa, documentos, perfis, contatos, endereços e demais informações pertinentes ao cadastro.

### Atualizar uma pessoa por id

 - [PUT /v1/pessoas/{id}](https://developers.contaazul.com/open-api-docs/open-api-person/v1/atualizarpessoaporid.md): Permite substituir ou atualizar integralmente o cadastro de uma pessoa existente identificada por id. Indicada quando há necessidade de modificar vários campos de uma vez.

### Atualizar parcialmente uma pessoa por id

 - [PATCH /v1/pessoas/{id}](https://developers.contaazul.com/open-api-docs/open-api-person/v1/atualizarparcialmentepessoa.md): Permite atualizar parcialmente o cadastro de uma pessoa existente (por exemplo: alterar email, telefone, tipo de perfil ou endereço) identificada por id. Essa abordagem garante menor impacto e maior controle na atualização dos dados.