---
title: "Referência: Clientes"
description: "Referência do recurso Clientes da API: objeto cliente (tomador), cadastrar, listar, consultar, atualizar e remover clientes de uma empresa e erros possíveis."
url: https://docs.emissordenota.com/referencia/clientes
language: pt-BR
---
# Clientes

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

**Escopos**: cadastros:ler · cadastros:escrever

**URL base**

```bash
# Produção
https://api.emissordenota.com/v1

# Sandbox
https://sandbox.api.emissordenota.com/v1
```

## Endpoints

- `GET /v1/clientes`: Lista os clientes de uma empresa
- `POST /v1/clientes`: Cadastra 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

- `id` (string): Identificador do cliente, com o prefixo cli_.
- `empresa_id` (string): A empresa a que o cliente pertence.
- `documento` (string): CNPJ ou CPF, só com dígitos.
- `nome` (string): Razão social ou nome completo.
- `email` (string): Endereço que recebe as notas do cliente.
- `endereco` (object): Endereço completo, preenchido a partir do CEP.
- `criado_em` (string): Data e hora do cadastro, em ISO 8601.

**O objeto cliente**

```json
{
  "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_id` (string, obrigatório): A empresa dona do cadastro.
- `documento` (string, obrigatório): CNPJ ou CPF, só com dígitos.
- `nome` (string, obrigatório): Razão social ou nome completo.
- `email` (string, opcional): Endereço que recebe as notas do cliente.
- `endereco` (object, opcional): Exigido por algumas prefeituras para tomador pessoa jurídica.
  - `cep` (string, obrigatório): 8 dígitos.
  - `numero` (string, obrigatório): Número do endereço.
  - `complemento` (string, opcional): Sala, andar ou bloco.

**POST /v1/clientes**

```bash
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_id` (string, obrigatório): A empresa dona dos clientes.
- `documento` (string, opcional): Busca exata por CNPJ ou CPF.
- `busca` (string, opcional): Trecho do nome.
- `limite` (integer, opcional): Itens por página. O padrão e o máximo são 50.
- `cursor` (string, opcional): 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}**

```bash
# API=https://api.emissordenota.com/v1
curl -X DELETE $API/clientes/cli_6Pz3nKd8Wm \
  -H "Authorization: Bearer $EDN_KEY"

# 204 No Content
```

## Erros

| Status | Código | Quando |
| --- | --- | --- |
| 404 | cliente_nao_encontrado | O id não existe nesse ambiente. |
| 409 | cliente_ja_cadastrado | O documento já existe na empresa. |
| 422 | dados_invalidos | Documento ou CEP inválidos. |
