Skip to content
API/
Pessoas
/
/
Retornar a pessoa por leg...

Pessoas (v1)

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

Download OpenAPI description
open-api-person.json
open-api-person.yaml
Overview
Languages
Servers
https://api-v2.contaazul.com
Mock server
https://developers.contaazul.com/_mock/open-api-docs/open-api-person

v1

Operações relacionadas a pessoas

Operations

Retornar as pessoas por filtro

Request

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.

Security
BearerAuth
Query
paginainteger

Página

Default 1
tamanho_paginainteger

Tamanho da página

Default 10
Enum1020501002005001000
tipo_ordenacaostring

Tipo de ordenação

Default "NOME"
Enum"NOME""EMAIL""DOCUMENTO""ATIVO"
ordem_ordenacaostring

Ordem de ordenação

Default "ASC"
Enum"ASC""DESC"
buscastring

Busca textual pelo documento ou nome do cliente/empresa

idsstring

IDs das pessoas

documentosstring

Documentos das pessoas (CPF/CNPJ)

paisesstring

Países das pessoas

cidadesstring

Cidades das pessoas

ufsstring

Abreviações das unidades federativas (estados) das pessoas

codigos_pessoastring

Códigos de cadastro das pessoas

emailsstring

Emails das pessoas

tipos_pessoastring

Tipos de pessoa

Default "Física"
Enum"Física""Jurídica""Estrangeira"
nomesstring

Nomes das pessoas, pode ser pessoa física, jurídica ou estrangeira

telefonesstring

Telefones das pessoas

data_criacao_iniciostring

Data de início para filtrar pessoas criadas a partir dessa data, obrigatório se data_criacao_fim for preenchido

data_criacao_fimstring

Data de fim para filtrar pessoas criadas até essa data, obrigatório se data_criacao_inicio for preenchido

data_alteracao_destring

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

data_alteracao_atestring

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

tipo_perfilstring

Tipo de perfil da pessoa

Default "Cliente"
Enum"Cliente""Fornecedor""Transportadora"
com_enderecoboolean

Indica se deve retornar pessoas com endereço

Default false
curl -i -X GET \
  'https://api-v2.contaazul.com/v1/pessoas?pagina=1&tamanho_pagina=10&tipo_ordenacao=NOME&ordem_ordenacao=ASC&busca=string&ids=string&documentos=string&paises=string&cidades=string&ufs=string&codigos_pessoa=string&emails=string&tipos_pessoa=F%C3%ADsica&nomes=string&telefones=string&data_criacao_inicio=string&data_criacao_fim=string&data_alteracao_de=string&data_alteracao_ate=string&tipo_perfil=Cliente&com_endereco=false' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
itemsArray of objects(ItemResumoDePessoasPorFiltro)

Lista de itens do resumo de pessoas

totalItemsinteger

Total de itens encontrados

Example: 150
Response
application/json
{
  "items": [
    { … }
  ],
  "totalItems": 150
}

Criar uma nova pessoa

Request

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.

Security
BearerAuth
Bodyapplication/jsonrequired

Dados da pessoa a ser criada

agencia_publicaboolean

Indica se a pessoa é uma agência pública

Example: true
ativoboolean

Indica se a pessoa está ativa

Example: true
cnpjstring

CNPJ da pessoa jurídica

Example: "12.345.678/0001-90"
codigostring<= 20 characters

Código da pessoa

Example: "CLI001"
contato_cobranca_faturamentoobject

Contato de cobrança e faturamento

cpfstring

CPF da pessoa física

Example: "123.456.789-00"
data_nascimentostring

Data de nascimento da pessoa física

Example: "1990-01-01"
emailstring<= 100 characters

Emails da pessoa separados por vírgula

Example: "joao.silva@email.com, maria.silva@email.com"
enderecosArray of objects(CriacaoEnderecoPessoa)

Lista de endereços

inscricoesArray of objects(CriacaoInscricaoPessoa)

Lista de inscrições estaduais e municipais

nomestring<= 200 charactersrequired

Nome da pessoa

Example: "João Silva"
nome_fantasiastring<= 200 characters

Nome fantasia da pessoa jurídica

Example: "Empresa LTDA"
observacaostring<= 2000 characters

Observações sobre a pessoa

Example: "Cliente preferencial"
optante_simplesboolean

Indica se a pessoa é optante pelo Simples Nacional

Example: true
outros_contatosArray of objects(CriacaoOutroContatoPessoa)

Lista de outros contatos da pessoa

perfisArray of objects(CriacaoPerfilPessoa)

Lista de perfis associados à pessoa

rgstring<= 50 characters

Registro Geral (RG) da pessoa

Example: "12.345.678-9"
telefone_celularstring

Telefone celular

Example: "11983899529"
telefone_comercialstring

Telefone comercial da pessoa

Example: "1138185004"
tipo_pessoastringrequired

Tipo de pessoa: Física, Jurídica ou Estrangeira

Enum"Física""Jurídica""Estrangeira"
Example: "Física"
curl -i -X POST \
  https://api-v2.contaazul.com/v1/pessoas \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "agencia_publica": true,
    "ativo": true,
    "cnpj": "12.345.678/0001-90",
    "codigo": "CLI001",
    "contato_cobranca_faturamento": {
      "emails": [
        "carlos.oliveira@email.com",
        "joao.silva@email.com"
      ],
      "whatsapp": "5511999999999"
    },
    "cpf": "123.456.789-00",
    "data_nascimento": "1990-01-01",
    "email": "joao.silva@email.com, maria.silva@email.com",
    "enderecos": [
      {
        "bairro": "Centro",
        "cep": "12345-678",
        "cidade": "São Paulo",
        "complemento": "Apto 45",
        "estado": "SP",
        "logradouro": "Rua das Flores",
        "numero": "123",
        "pais": "Brasil"
      }
    ],
    "inscricoes": [
      {
        "indicador_inscricao_estadual": "NAO CONTRIBUINTE",
        "inscricao_estadual": "123456789",
        "inscricao_municipal": "123456789",
        "inscricao_suframa": "123456789"
      }
    ],
    "nome": "João Silva",
    "nome_fantasia": "Empresa LTDA",
    "observacao": "Cliente preferencial",
    "optante_simples": true,
    "outros_contatos": [
      {
        "cargo": "Gerente",
        "email": "maria.silva@email.com",
        "nome": "Maria Silva",
        "telefone_celular": "11983899529",
        "telefone_comercial": "1138185004"
      }
    ],
    "perfis": [
      {
        "tipo_perfil": "Cliente"
      }
    ],
    "rg": "12.345.678-9",
    "telefone_celular": "11983899529",
    "telefone_comercial": "1138185004",
    "tipo_pessoa": "Física"
  }'

Responses

Created

Bodyapplication/json
agencia_publicaboolean

Indica se a pessoa é uma agência pública

Example: false
ativoboolean

Indica se a pessoa está ativa

Example: true
cnpjstring

CNPJ da pessoa jurídica

Example: "12.345.678/0001-90"
codigostring

Código da pessoa

Example: "CLI001"
contato_cobranca_faturamentoobject

Contato para cobrança e faturamento

cpfstring

CPF da pessoa física

Example: "123.456.789-00"
data_nascimentostring

Data de nascimento da pessoa física

Example: "1990-01-01"
emailstring

Emails da pessoa separados por vírgula

Example: "joao.silva@email.com, maria.silva@email.com "
enderecosArray of objects(EnderecoPessoa)

Lista de endereços

estrangeiroboolean

Indica se a pessoa é estrangeira

Example: false
idstring

ID da pessoa

Example: "550e8400-e29b-41d4-a716-446655440000"
inscricoesArray of objects(InscricaoPessoa)

Lista de inscrições

nomestring

Nome da pessoa

Example: "João Silva"
nome_fantasiastring

Nome fantasia da pessoa jurídica

Example: "Empresa LTDA"
observacaostring

Observações sobre a pessoa

Example: "Cliente preferencial"
optante_simplesboolean

Indica se a pessoa é optante pelo Simples Nacional

Example: false
origemstring

Origem da criação da pessoa

Example: "API"
outros_contatosArray of objects(OutrosContatos)

Lista de outros contatos

perfisArray of objects(PerfilPessoa)

Lista de perfis

rgstring

Registro Geral (RG) da pessoa

Example: "12.345.678-9"
telefone_celularstring

Telefone celular

Example: "11987654321"
telefone_comercialstring

Telefone comercial da pessoa

Example: "1112345678"
tipo_pessoastring

Tipo de pessoa: Física, Jurídica ou Estrangeira

Example: "FISICA"
Response
application/json
{
  "agencia_publica": false,
  "ativo": true,
  "cnpj": "12.345.678/0001-90",
  "codigo": "CLI001",
  "contato_cobranca_faturamento": {
    "emails": [ … ],
    "whatsapp": "5511999999999"
  },
  "cpf": "123.456.789-00",
  "data_nascimento": "1990-01-01",
  "email": "joao.silva@email.com, maria.silva@email.com ",
  "enderecos": [
    { … }
  ],
  "estrangeiro": false,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inscricoes": [
    { … }
  ],
  "nome": "João Silva",
  "nome_fantasia": "Empresa LTDA",
  "observacao": "Cliente preferencial",
  "optante_simples": false,
  "origem": "API",
  "outros_contatos": [
    { … }
  ],
  "perfis": [
    { … }
  ],
  "rg": "12.345.678-9",
  "telefone_celular": "11987654321",
  "telefone_comercial": "1112345678",
  "tipo_pessoa": "FISICA"
}

Ativar pessoas em lote

Request

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.

Security
BearerAuth
Bodyapplication/jsonrequired

IDs das pessoas a serem ativadas

uuidsArray of strings[ 1 .. 10 ] itemsrequired

máximo de 10 IDs

Example: ["4BBDAE00-2242-4703-9310-9946D6C2D0A3","B6270060-3AB7-4E66-A99B-71084E385F47"]
curl -i -X POST \
  https://api-v2.contaazul.com/v1/pessoas/ativar \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "uuids": [
      "4BBDAE00-2242-4703-9310-9946D6C2D0A3",
      "B6270060-3AB7-4E66-A99B-71084E385F47"
    ]
  }'

Responses

OK

Bodyapplication/jsonArray [
ativosArray of strings

Lista de IDs das pessoas ativadas

Example: ["4BBDAE00-2242-4703-9310-9946D6C2D0A3"]
inativosArray of strings

Lista de IDs das pessoas inativadas

Example: ["B6270060-3AB7-4E66-A99B-71084E385F47"]
todosArray of strings

Lista de todos os IDs das pessoas fornecidos na requisição

Example: ["4BBDAE00-2242-4703-9310-9946D6C2D0A3","B6270060-3AB7-4E66-A99B-71084E385F47"]
]
Response
application/json
[
  {
    "ativos": [ … ],
    "inativos": [ … ],
    "todos": [ … ]
  }
]

Excluir pessoas em lote

Request

Permite excluir pessoas em lote, a partir de seus identificadores.

Security
BearerAuth
Bodyapplication/jsonrequired

IDs das pessoas a serem deletadas

uuidsArray of stringsrequired
Example: ["4BBDAE00-2242-4703-9310-9946D6C2D0A3","B6270060-3AB7-4E66-A99B-71084E385F47"]
curl -i -X POST \
  https://api-v2.contaazul.com/v1/pessoas/excluir \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "uuids": [
      "4BBDAE00-2242-4703-9310-9946D6C2D0A3",
      "B6270060-3AB7-4E66-A99B-71084E385F47"
    ]
  }'

Responses

No Content

Response
No content

Desativar pessoas em lote

Request

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.

Security
BearerAuth
Bodyapplication/jsonrequired

IDs das pessoas a serem desativadas

uuidsArray of strings[ 1 .. 10 ] itemsrequired

máximo de 10 IDs

Example: ["4BBDAE00-2242-4703-9310-9946D6C2D0A3","B6270060-3AB7-4E66-A99B-71084E385F47"]
curl -i -X POST \
  https://api-v2.contaazul.com/v1/pessoas/inativar \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "uuids": [
      "4BBDAE00-2242-4703-9310-9946D6C2D0A3",
      "B6270060-3AB7-4E66-A99B-71084E385F47"
    ]
  }'

Responses

OK

Bodyapplication/jsonArray [
ativosArray of strings

Lista de IDs das pessoas ativadas

Example: ["4BBDAE00-2242-4703-9310-9946D6C2D0A3"]
inativosArray of strings

Lista de IDs das pessoas inativadas

Example: ["B6270060-3AB7-4E66-A99B-71084E385F47"]
todosArray of strings

Lista de todos os IDs das pessoas fornecidos na requisição

Example: ["4BBDAE00-2242-4703-9310-9946D6C2D0A3","B6270060-3AB7-4E66-A99B-71084E385F47"]
]
Response
application/json
[
  {
    "ativos": [ … ],
    "inativos": [ … ],
    "todos": [ … ]
  }
]

Retornar a pessoa por legacyid

Request

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.

Security
BearerAuth
Path
idstringrequired

legacyId da pessoa

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/pessoas/legado/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
ativoboolean

Ativo

Example: true
atrasos_pagamentosnumber

Atrasos nos pagamentos

Example: 750.25
atrasos_recebimentosnumber

Atrasos nos recebimentos

Example: 1500.5
codigostring

Código da pessoa

Example: "CLI001"
criado_emstring(date)

Data de criação da pessoa (ISO 8601, São Paulo/GMT-3)

Example: "2024-01-15"
data_alteracaostring(date-time)

Data de alteração da pessoa (ISO 8601, São Paulo/GMT-3)

Example: "2024-01-15T10:30:00"
data_nascimentostring

Data de nascimento

Example: "1990-01-01"
documentostring

Documento da pessoa

Example: "123.456.789-00"
emailstring

Emails da pessoa separados por vírgula

Example: "joao.silva@email.com, maria.silva@email.com"
enderecosArray of objects(EnderecoPessoa)

Endereços da pessoa

idstring

ID da pessoa

Example: "550e8400-e29b-41d4-a716-446655440000"
inscricoesArray of objects(InformacoesFiscais)

Informações fiscais

lembretes_vencimentoArray of objects(LembretesVencimento)

Lembretes de vencimento

mensagem_pagamentos_abertosobject

Mensagens de pagamentos em aberto

nomestring

Nome da pessoa

Example: "João Silva"
nome_empresastring

Nome da empresa

Example: "Empresa LTDA"
observacaostring

Observações gerais da pessoa

Example: "Observação geral"
optante_simples_nacionalboolean

Optante do Simples Nacional

Example: true
orgao_publicoboolean

Órgão público

Example: true
outros_contatosArray of objects(OutrosContatos)

Outros contatos

pagamentos_mes_atualnumber

Pagamentos do mês atual

Example: 2500
perfisArray of objects(TipoPerfil)

Perfis da pessoa

pessoas_legadoArray of objects(PessoaLegada)

Pessoas legadas

recebimentos_mes_atualnumber

Recebimentos do mês atual

Example: 5000
rgstring

RG

Example: "12.345.678-9"
telefone_celularstring

Celular da pessoa

Example: "(11) 98765-4321"
telefone_comercialstring

Telefone comercial da pessoa

Example: "(11) 1234-5678"
tipo_pessoastring

Tipo de pessoa

Example: "FISICA"
Response
application/json
{
  "ativo": true,
  "atrasos_pagamentos": 750.25,
  "atrasos_recebimentos": 1500.5,
  "codigo": "CLI001",
  "criado_em": "2024-01-15",
  "data_alteracao": "2024-01-15T10:30:00",
  "data_nascimento": "1990-01-01",
  "documento": "123.456.789-00",
  "email": "joao.silva@email.com, maria.silva@email.com",
  "enderecos": [
    { … }
  ],
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inscricoes": [
    { … }
  ],
  "lembretes_vencimento": [
    { … }
  ],
  "mensagem_pagamentos_abertos": {
    "numero": 10,
    "total": 10
  },
  "nome": "João Silva",
  "nome_empresa": "Empresa LTDA",
  "observacao": "Observação geral",
  "optante_simples_nacional": true,
  "orgao_publico": true,
  "outros_contatos": [
    { … }
  ],
  "pagamentos_mes_atual": 2500,
  "perfis": [
    { … }
  ],
  "pessoas_legado": [
    { … }
  ],
  "recebimentos_mes_atual": 5000,
  "rg": "12.345.678-9",
  "telefone_celular": "(11) 98765-4321",
  "telefone_comercial": "(11) 1234-5678",
  "tipo_pessoa": "FISICA"
}

Retornar a pessoa por id

Request

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.

Security
BearerAuth
Path
idstringrequired

id da pessoa

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/pessoas/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
ativoboolean

Ativo

Example: true
atrasos_pagamentosnumber

Atrasos nos pagamentos

Example: 750.25
atrasos_recebimentosnumber

Atrasos nos recebimentos

Example: 1500.5
codigostring

Código da pessoa

Example: "CLI001"
criado_emstring(date)

Data de criação da pessoa (ISO 8601, São Paulo/GMT-3)

Example: "2024-01-15"
data_alteracaostring(date-time)

Data de alteração da pessoa (ISO 8601, São Paulo/GMT-3)

Example: "2024-01-15T10:30:00"
data_nascimentostring

Data de nascimento

Example: "1990-01-01"
documentostring

Documento da pessoa

Example: "123.456.789-00"
emailstring

Emails da pessoa separados por vírgula

Example: "joao.silva@email.com, maria.silva@email.com"
enderecosArray of objects(EnderecoPessoa)

Endereços da pessoa

idstring

ID da pessoa

Example: "550e8400-e29b-41d4-a716-446655440000"
inscricoesArray of objects(InformacoesFiscais)

Informações fiscais

lembretes_vencimentoArray of objects(LembretesVencimento)

Lembretes de vencimento

mensagem_pagamentos_abertosobject

Mensagens de pagamentos em aberto

nomestring

Nome da pessoa

Example: "João Silva"
nome_empresastring

Nome da empresa

Example: "Empresa LTDA"
observacaostring

Observações gerais da pessoa

Example: "Observação geral"
optante_simples_nacionalboolean

Optante do Simples Nacional

Example: true
orgao_publicoboolean

Órgão público

Example: true
outros_contatosArray of objects(OutrosContatos)

Outros contatos

pagamentos_mes_atualnumber

Pagamentos do mês atual

Example: 2500
perfisArray of objects(TipoPerfil)

Perfis da pessoa

pessoas_legadoArray of objects(PessoaLegada)

Pessoas legadas

recebimentos_mes_atualnumber

Recebimentos do mês atual

Example: 5000
rgstring

RG

Example: "12.345.678-9"
telefone_celularstring

Celular da pessoa

Example: "(11) 98765-4321"
telefone_comercialstring

Telefone comercial da pessoa

Example: "(11) 1234-5678"
tipo_pessoastring

Tipo de pessoa

Example: "FISICA"
Response
application/json
{
  "ativo": true,
  "atrasos_pagamentos": 750.25,
  "atrasos_recebimentos": 1500.5,
  "codigo": "CLI001",
  "criado_em": "2024-01-15",
  "data_alteracao": "2024-01-15T10:30:00",
  "data_nascimento": "1990-01-01",
  "documento": "123.456.789-00",
  "email": "joao.silva@email.com, maria.silva@email.com",
  "enderecos": [
    { … }
  ],
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inscricoes": [
    { … }
  ],
  "lembretes_vencimento": [
    { … }
  ],
  "mensagem_pagamentos_abertos": {
    "numero": 10,
    "total": 10
  },
  "nome": "João Silva",
  "nome_empresa": "Empresa LTDA",
  "observacao": "Observação geral",
  "optante_simples_nacional": true,
  "orgao_publico": true,
  "outros_contatos": [
    { … }
  ],
  "pagamentos_mes_atual": 2500,
  "perfis": [
    { … }
  ],
  "pessoas_legado": [
    { … }
  ],
  "recebimentos_mes_atual": 5000,
  "rg": "12.345.678-9",
  "telefone_celular": "(11) 98765-4321",
  "telefone_comercial": "(11) 1234-5678",
  "tipo_pessoa": "FISICA"
}

Atualizar uma pessoa por id

Request

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.

Security
BearerAuth
Path
idstringrequired

ID da pessoa a ser atualizada

Bodyapplication/jsonrequired

Dados da pessoa a ser atualizada

agencia_publicaboolean

Indica se a pessoa é uma agência pública

Example: false
ativoboolean

Indica se a pessoa está ativa

Example: true
cnpjstring

CNPJ da pessoa jurídica

Example: "12.345.678/0001-90"
codigostring<= 20 charactersrequired

Código da pessoa

Example: "CLI001"
cpfstring

CPF da pessoa física

Example: "123.456.789-00"
data_nascimentostringrequired

Data de nascimento da pessoa física

Example: "1990-01-01"
emailstring<= 100 charactersrequired

Emails da pessoa separados por vírgula

Example: "joao.silva@email.com, maria.silva@email.com"
enderecosArray of objects(AtualizacaoEnderecoPessoa)required

Lista de endereços

enderecos[].​bairrostring<= 100 characters

Bairro do endereço

Example: "Centro"
enderecos[].​cepstring

CEP do endereço

Example: "12345-678"
enderecos[].​cidadestring

Cidade do endereço

Example: "São Paulo"
enderecos[].​complementostring<= 200 characters

Complemento do endereço

Example: "Apto 45"
enderecos[].​estadostring

Estado do endereço

Example: "SP"
enderecos[].​idstring

ID do endereço

Example: "550e8400-e29b-41d4-a716-446655440000"
enderecos[].​logradourostring<= 100 characters

Logradouro do endereço

Example: "Rua das Flores"
enderecos[].​numerostring<= 10 characters

Número do endereço

Example: "123"
enderecos[].​paisstringrequired

País do endereço (Brasil se tipo_pessoa for Física ou Jurídica)

Example: "Brasil"
inscricoesArray of objects(AtualizacaoInscricaoPessoa)

Lista de inscrições estaduais e municipais

nomestring<= 200 charactersrequired

Nome da pessoa

Example: "João Silva"
nome_fantasiastring<= 200 characters

Nome fantasia da pessoa jurídica

Example: "Empresa LTDA"
observacaostring<= 2000 charactersrequired

Observações sobre a pessoa

Example: "Cliente preferencial"
optante_simplesboolean

Indica se a pessoa é optante pelo Simples Nacional

Example: false
outros_contatosArray of objects(AtualizacaoOutroContatoPessoa)required

Lista de outros contatos da pessoa

outros_contatos[].​cargostring<= 40 charactersrequired

Cargo do contato

Example: "Gerente"
outros_contatos[].​emailstring<= 100 charactersrequired

Email do contato

Example: "maria.silva@email.com"
outros_contatos[].​idstring

ID do contato

Example: "550e8400-e29b-41d4-a716-446655440000"
outros_contatos[].​nomestring<= 40 charactersrequired

Nome do contato

Example: "Maria Silva"
outros_contatos[].​telefone_celularstringrequired

Telefone celular

Example: "(11) 98765-4321"
outros_contatos[].​telefone_comercialstringrequired

Telefone comercial do contato

Example: "(11) 1234-5678"
perfisArray of objects(AtualizacaoTipoPerfil)required

Lista de perfis associados à pessoa

perfis[].​tipo_perfilstringrequired

Tipo de perfil: Cliente, Fornecedor ou Transportadora

Enum"Cliente""Fornecedor""Transportadora"
Example: "Cliente"
rgstring<= 50 characters

Registro Geral (RG) da pessoa

Example: "12.345.678-9"
telefone_celularstringrequired

Telefone celular

Example: "(11) 98765-4321"
telefone_comercialstringrequired

Telefone comercial da pessoa

Example: "(11) 1234-5678"
tipo_pessoastringrequired

Tipo de pessoa: Física, Jurídica ou Estrangeira

Enum"Física""Jurídica""Estrangeira"
curl -i -X PUT \
  'https://api-v2.contaazul.com/v1/pessoas/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "agencia_publica": false,
    "ativo": true,
    "cnpj": "12.345.678/0001-90",
    "codigo": "CLI001",
    "cpf": "123.456.789-00",
    "data_nascimento": "1990-01-01",
    "email": "joao.silva@email.com, maria.silva@email.com",
    "enderecos": [
      {
        "bairro": "Centro",
        "cep": "12345-678",
        "cidade": "São Paulo",
        "complemento": "Apto 45",
        "estado": "SP",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "logradouro": "Rua das Flores",
        "numero": "123",
        "pais": "Brasil"
      }
    ],
    "inscricoes": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "indicador_inscricao_estadual": "NAO CONTRIBUINTE",
        "inscricao_estadual": "123456789",
        "inscricao_municipal": "123456789",
        "inscricao_suframa": "123456789"
      }
    ],
    "nome": "João Silva",
    "nome_fantasia": "Empresa LTDA",
    "observacao": "Cliente preferencial",
    "optante_simples": false,
    "outros_contatos": [
      {
        "cargo": "Gerente",
        "email": "maria.silva@email.com",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "nome": "Maria Silva",
        "telefone_celular": "(11) 98765-4321",
        "telefone_comercial": "(11) 1234-5678"
      }
    ],
    "perfis": [
      {
        "tipo_perfil": "Cliente"
      }
    ],
    "rg": "12.345.678-9",
    "telefone_celular": "(11) 98765-4321",
    "telefone_comercial": "(11) 1234-5678",
    "tipo_pessoa": "Física"
  }'

Responses

OK

Bodyapplication/json
agencia_publicaboolean

Indica se a pessoa é uma agência pública

Example: false
ativoboolean

Indica se a pessoa está ativa

Example: true
cnpjstring

CNPJ da pessoa jurídica

Example: "12.345.678/0001-90"
codigostring

Código da pessoa

Example: "CLI001"
cpfstring

CPF da pessoa física

Example: "123.456.789-00"
data_nascimentostring

Data de nascimento da pessoa física

Example: "1990-01-01"
emailstring

Emails da pessoa separados por vírgula

Example: "joao.silva@email.com, maria.silva@email.com"
enderecosArray of objects(EnderecoPessoa)

Lista de endereços

estrangeiroboolean

Indica se a pessoa é estrangeira

Example: false
idstring

ID da pessoa

Example: "550e8400-e29b-41d4-a716-446655440000"
inscricoesArray of objects(InscricaoPessoa)

Lista de inscrições

nomestring

Nome da pessoa

Example: "João Silva"
nome_fantasiastring

Nome fantasia da pessoa jurídica

Example: "Empresa LTDA"
observacaostring

Observações sobre a pessoa

Example: "Cliente preferencial"
optante_simplesboolean

Indica se a pessoa é optante pelo Simples Nacional

Example: false
origemstring

Origem da criação da pessoa

Example: "API"
outros_contatosArray of objects(OutrosContatos)

Lista de outros contatos

perfisArray of objects(PerfilPessoa)

Lista de perfis

rgstring

Registro Geral (RG) da pessoa

Example: "12.345.678-9"
telefone_celularstring

Telefone celular

Example: "(11) 98765-4321"
telefone_comercialstring

Telefone comercial da pessoa

Example: "(11) 1234-5678"
tipo_pessoastring

Tipo de pessoa: Física, Jurídica ou Estrangeira

Example: "FISICA"
Response
application/json
{
  "agencia_publica": false,
  "ativo": true,
  "cnpj": "12.345.678/0001-90",
  "codigo": "CLI001",
  "cpf": "123.456.789-00",
  "data_nascimento": "1990-01-01",
  "email": "joao.silva@email.com, maria.silva@email.com",
  "enderecos": [
    { … }
  ],
  "estrangeiro": false,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inscricoes": [
    { … }
  ],
  "nome": "João Silva",
  "nome_fantasia": "Empresa LTDA",
  "observacao": "Cliente preferencial",
  "optante_simples": false,
  "origem": "API",
  "outros_contatos": [
    { … }
  ],
  "perfis": [
    { … }
  ],
  "rg": "12.345.678-9",
  "telefone_celular": "(11) 98765-4321",
  "telefone_comercial": "(11) 1234-5678",
  "tipo_pessoa": "FISICA"
}

Atualizar parcialmente uma pessoa por id

Request

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.

Security
BearerAuth
Path
idstringrequired

ID da pessoa a ser atualizada

Bodyapplication/jsonrequired

Dados da pessoa a serem atualizados

agencia_publicaboolean

Indica se a pessoa é uma agência pública

Example: true
ativoboolean

Indica se a pessoa está ativa

Example: true
cnpjstring

CNPJ da pessoa jurídica

Example: "12.345.678/0001-90"
codigostring

Código da pessoa

Example: "CLI001"
cpfstring

CPF da pessoa física

Example: "123.456.789-00"
data_nascimentostring

Data de nascimento da pessoa física

Example: "1990-01-01"
emailstring

Emails da pessoa separados por vírgula

Example: "joao.silva@email.com, maria.silva@email.com"
enderecosArray of objects(EnderecoAtualizacaoParcial)

Lista de endereços

inscricoesArray of objects(InscricaoAtualizacaoParcial)

Lista de inscrições estaduais e municipais

nomestring

Nome da pessoa

Example: "João Silva"
nome_empresastring

Nome fantasia da pessoa jurídica

Example: "Empresa LTDA"
observacaostring

Observações sobre a pessoa

Example: "Cliente preferencial"
optante_simples_nacionalboolean

Indica se a pessoa é optante pelo Simples Nacional

Example: true
perfisArray of objects(AtualizacaoTipoPerfil)

Lista de perfis associados à pessoa

rgstring

Registro Geral (RG) da pessoa

Example: "12.345.678-9"
telefone_celularstring

Telefone celular

Example: "11987654321"
telefone_comercialstring

Telefone comercial da pessoa

Example: "1112345678"
tipo_pessoastring

Tipo de pessoa: Física, Jurídica ou Estrangeira

Enum"Física""Jurídica""Estrangeira"
Example: "Física"
curl -i -X PATCH \
  'https://api-v2.contaazul.com/v1/pessoas/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "agencia_publica": true,
    "ativo": true,
    "cnpj": "12.345.678/0001-90",
    "codigo": "CLI001",
    "cpf": "123.456.789-00",
    "data_nascimento": "1990-01-01",
    "email": "joao.silva@email.com, maria.silva@email.com",
    "enderecos": [
      {
        "bairro": "Centro",
        "cep": "12345-678",
        "cidade": "São Paulo",
        "complemento": "Apto 45",
        "estado": "SP",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "logradouro": "Rua das Flores",
        "numero": "123",
        "pais": "Brasil"
      }
    ],
    "inscricoes": [
      {
        "indicador_inscricao_estadual": "NAO CONTRIBUINTE",
        "inscricao_estadual": "123456789",
        "inscricao_municipal": "123456789",
        "inscricao_suframa": "123456789"
      }
    ],
    "nome": "João Silva",
    "nome_empresa": "Empresa LTDA",
    "observacao": "Cliente preferencial",
    "optante_simples_nacional": true,
    "perfis": [
      {
        "tipo_perfil": "Cliente"
      }
    ],
    "rg": "12.345.678-9",
    "telefone_celular": "11987654321",
    "telefone_comercial": "1112345678",
    "tipo_pessoa": "Física"
  }'

Responses

No Content

Response
No content