Referência da APIClientes

Clientes

Os tomadores de serviço de cada empresa. Mantenha o cadastro aqui e use os dados no objeto tomador na hora de emitir.

Escoposcadastros:ler · cadastros:escrever

Linguagem dos exemplos
URL base
# Produçãohttps://api.emissordenota.com/v1# Sandboxhttps://sandbox.api.emissordenota.com/v1

Endpoints

  • GET/v1/clientesLista os clientes de uma empresa
  • POST/v1/clientesCadastra um cliente
  • GET/v1/clientes/{id}Consulta um cliente
  • POST/v1/clientes/{id}Atualiza um cliente
  • DELETE/v1/clientes/{id}Remove um cliente

O objeto cliente

idstring
Identificador do cliente, com o prefixo cli_.
empresa_idstring
A empresa a que o cliente pertence.
documentostring
CNPJ ou CPF, só com dígitos.
nomestring
Razão social ou nome completo.
emailstring
Endereço que recebe as notas do cliente.
enderecoobject
Endereço completo, preenchido a partir do CEP.
criado_emstring
Data e hora do cadastro, em ISO 8601.
O objeto cliente
{  "id": "cli_6Pz3nKd8Wm",  "empresa_id": "emp_8Kq2mXv41c",  "documento": "98765432000198",  "nome": "Clínica Bem Viver Ltda",  "email": "financeiro@bemviver.com.br",  "endereco": {    "cep": "01310100",    "logradouro": "Avenida Paulista",    "numero": "1578",    "bairro": "Bela Vista",    "municipio": "São Paulo",    "uf": "SP"  },  "criado_em": "2026-10-14T16:05:48-03:00"}

Cadastrar um cliente

POST/v1/clientes

Cria o cliente na carteira de uma empresa. O mesmo documento não se repete dentro da empresa.

Corpo da requisição

empresa_idstringobrigatório
A empresa dona do cadastro.
documentostringobrigatório
CNPJ ou CPF, só com dígitos.
nomestringobrigatório
Razão social ou nome completo.
emailstringopcional
Endereço que recebe as notas do cliente.
enderecoobjectopcional
Exigido por algumas prefeituras para tomador pessoa jurídica.
cepstringobrigatório
8 dígitos.
numerostringobrigatório
Número do endereço.
complementostringopcional
Sala, andar ou bloco.
POST /v1/clientes
curl -X POST https://api.emissordenota.com/v1/clientes \  -H "Authorization: Bearer $EDN_KEY" \  -H "Content-Type: application/json" \  -d '{    "empresa_id": "emp_8Kq2mXv41c",    "documento": "98765432000198",    "nome": "Clínica Bem Viver Ltda",    "email": "financeiro@bemviver.com.br",    "endereco": {      "cep": "01310100",      "numero": "1578"    }  }'

Listar clientes

GET/v1/clientes

Devolve os clientes de uma empresa, do mais recente para o mais antigo.

Parâmetros de consulta

empresa_idstringobrigatório
A empresa dona dos clientes.
documentostringopcional
Busca exata por CNPJ ou CPF.
buscastringopcional
Trecho do nome.
limiteintegeropcional
Itens por página. O padrão e o máximo são 50.
cursorstringopcional
O proximo_cursor da página anterior.

Remover um cliente

DELETE/v1/clientes/{id}

Remove o cadastro e responde 204, sem corpo. As notas já emitidas para o cliente não são alteradas.

DELETE /v1/clientes/{id}
# API=https://api.emissordenota.com/v1curl -X DELETE $API/clientes/cli_6Pz3nKd8Wm \  -H "Authorization: Bearer $EDN_KEY"# 204 No Content

Erros

StatusCódigoQuando

  • 404cliente_nao_encontrado
    O id não existe nesse ambiente.
  • 409cliente_ja_cadastrado
    O documento já existe na empresa.
  • 422dados_invalidos
    Documento ou CEP inválidos.