Clientes

Use este recurso para criar, consultar, atualizar e desativar clientes do time vinculado à sua chave de API. Um cliente pode ser Pessoa Física (PF) ou Pessoa Jurídica (PJ).

GET /clients

Lista os clientes do seu time. A busca procura em nome, email, CPF e CNPJ.

Parâmetros de consulta

Parâmetro	Tipo	Padrão	Descrição
`page`	number	`1`	Página a retornar.
`limit`	number	`20`	Itens por página, entre `1` e `100`.
`type`	string	—	Tipo do cliente: `PF` ou `PJ`.
`status`	string	—	Situação: `active` ou `inactive`.
`search`	string	—	Busca parcial em nome, email, CPF ou CNPJ.
`sort`	string	`-created_at`	Campo de ordenação; prefixe com `-` para ordem descendente.

Os únicos campos aceitos em sort são full_name, email, created_at, updated_at e is_active. Por exemplo, use sort=full_name ou sort=-updated_at; name não é um campo de ordenação aceito.

curl "https://app.usecolmeia.com/api/v1/clients?type=PJ&status=active&sort=-created_at" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Resposta

{
  "success": true,
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "type": "PJ",
      "name": "Acme Serviços Digitais Ltda.",
      "display_name": "Acme Digital",
      "email": "contato@acme-exemplo.test",
      "phone": "+551130000000",
      "mobile_phone": null,
      "whatsapp": "+5511999990000",
      "cpf": null,
      "rg": null,
      "birth_date": null,
      "gender": null,
      "marital_status": null,
      "nationality": null,
      "cnpj": "00.000.000/0001-00",
      "legal_name": "Acme Serviços Digitais Ltda.",
      "trade_name": "Acme Digital",
      "state_registration": null,
      "municipal_registration": null,
      "source": "indicacao",
      "status": "active",
      "notes": null,
      "tags": ["servicos"],
      "address": {
        "street": "Rua Exemplo",
        "number": "100",
        "complement": null,
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01000-000",
        "country": "Brasil"
      },
      "created_at": "2026-08-01T10:30:00.000Z",
      "updated_at": "2026-08-01T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

POST /clients

Cria um cliente. Os únicos campos obrigatórios são name e type.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo ou razão social.
`type`	string	Sim	`PF` para pessoa física ou `PJ` para pessoa jurídica.
`display_name`	string	Não	Nome de exibição.
`email`	string	Não	Email do cliente.
`phone`	string	Não	Telefone.
`mobile_phone`	string	Não	Telefone celular.
`whatsapp`	string	Não	Número de WhatsApp.
`cpf`	string	Não	CPF, aplicável a `PF`.
`rg`	string	Não	RG, aplicável a `PF`.
`birth_date`	string	Não	Data de nascimento em `YYYY-MM-DD`, aplicável a `PF`.
`gender`	string	Não	Gênero, aplicável a `PF`.
`marital_status`	string	Não	Estado civil, aplicável a `PF`.
`nationality`	string	Não	Nacionalidade, aplicável a `PF`.
`cnpj`	string	Não	CNPJ, aplicável a `PJ`.
`legal_name`	string	Não	Razão social, aplicável a `PJ`.
`trade_name`	string	Não	Nome fantasia, aplicável a `PJ`.
`state_registration`	string	Não	Inscrição estadual, aplicável a `PJ`.
`municipal_registration`	string	Não	Inscrição municipal, aplicável a `PJ`.
`address`	object	Não	Endereço com os campos descritos abaixo.
`source`	string	Não	Origem do cliente.
`notes`	string	Não	Observações internas.
`tags`	array	Não	Lista de tags; quando omitida, inicia vazia.

O objeto opcional address aceita street, number, complement, neighborhood, city, state, zip_code e country.

curl -X POST "https://app.usecolmeia.com/api/v1/clients" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Serviços Digitais Ltda.",
    "type": "PJ",
    "email": "contato@acme-exemplo.test",
    "cnpj": "00.000.000/0001-00",
    "phone": "+55 11 3000-0000",
    "whatsapp": "+55 11 99999-0000",
    "source": "indicacao",
    "tags": ["servicos"],
    "address": {
      "street": "Rua Exemplo",
      "number": "100",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01000-000",
      "country": "Brasil"
    }
  }'

O retorno bem-sucedido é 201 Created e usa o mesmo objeto de cliente mostrado na listagem.

A criação pode retornar 403 com o código PLAN_LIMIT_REACHED quando o plano do time atingir a cota de clientes ativos. Desative clientes que não são mais usados ou ajuste o plano antes de tentar novamente.

Se um CPF ou CNPJ já estiver cadastrado para o time, a criação retorna 422 com o código DUPLICATE_ENTRY.

GET /clients/:id

Retorna um cliente pelo seu UUID.

curl "https://app.usecolmeia.com/api/v1/clients/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

A resposta contém { "success": true, "data": { ... } }, com o mesmo formato de cliente da listagem. Se o UUID não pertencer ao seu time ou não existir, a API retorna 404 com o código NOT_FOUND.

PUT /clients/:id

Atualiza somente os campos enviados. Os campos escalares aceitos são name, display_name, email, phone, mobile_phone, whatsapp, cpf, rg, birth_date, gender, marital_status, nationality, cnpj, legal_name, trade_name, state_registration, municipal_registration, source, notes e tags.

Você também pode enviar address de forma parcial; cada um destes campos é atualizado independentemente: street, number, complement, neighborhood, city, state, zip_code e country.

curl -X PUT "https://app.usecolmeia.com/api/v1/clients/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp": "+55 11 98888-0000",
    "address": {
      "city": "Campinas",
      "state": "SP"
    }
  }'

Enviar um corpo JSON sem nenhum campo aceito resulta em 400 com o código VALIDATION_ERROR.

DELETE /clients/:id

Desativa o cliente; a operação não remove o registro fisicamente. Depois da chamada, o cliente passa a ter status: "inactive" e pode ser localizado com status=inactive.

curl -X DELETE "https://app.usecolmeia.com/api/v1/clients/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

{
  "success": true,
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "inactive",
    "deactivated_at": "2026-08-01T11:00:00.000Z"
  }
}

Clientes

On this page