API de Clientes

Gerenciamento de clientes e contatos

16 endpoints · base https://api.comando.one/v1 · autenticação por chave cmd_live_…

GET/customers

Listar clientes

customers:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

`page`(query)	integer	Número da página (default: 1)
`per_page`(query)	integer	Itens por página (default: 20, máx: 100)
`search`(query)	string	Busca por nome, e-mail ou documento
`status`(query)	string	Filtrar por status
`type`(query)	"fisica" \| "juridica" \| "estrangeira"	Filtrar por tipo de pessoa
`include`(query)	"addresses"	addresses = traz os endereços de cada cliente no campo `addresses` (1 chamada em vez de 1 por cliente)

Resposta 200 — Listagem paginada

`id`	string (uuid)
`name`	string
`email`	string \| null
`phone`	string \| null
`document`	string \| null	CPF ou CNPJ
`type`	"fisica" \| "juridica" \| "estrangeira"	Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum.
`company_name`	string \| null
`trade_name`	string \| null
`status`	string
`created_at`	string (date-time)
`updated_at`	string (date-time)
`addresses`	array de CustomerAddress	Só vem com ?include=addresses. Endereço padrão primeiro; lista vazia = cliente sem endereço cadastrado.

Exemplo

curl -X GET "https://api.comando.one/v1/customers" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

POST/customers

Criar cliente

customers:write

Parâmetros, corpo, resposta e exemplo

Corpo (JSON)

`name`obrigatório	string
`email`	string
`phone`	string
`document`	string
`type`	"fisica" \| "juridica" \| "estrangeira"	Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum.
`company_name`	string
`trade_name`	string
`status`	string

Resposta 201 — Cliente criado

`id`	string (uuid)
`name`	string
`email`	string \| null
`phone`	string \| null
`document`	string \| null	CPF ou CNPJ
`type`	"fisica" \| "juridica" \| "estrangeira"	Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum.
`company_name`	string \| null
`trade_name`	string \| null
`status`	string
`created_at`	string (date-time)
`updated_at`	string (date-time)
`addresses`	array de CustomerAddress	Só vem com ?include=addresses. Endereço padrão primeiro; lista vazia = cliente sem endereço cadastrado.

Exemplo

curl -X POST "https://api.comando.one/v1/customers" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Serviços Ltda","email":"contato@acme.com.br","type":"juridica","document":"12345678000195"}'

DELETE/customers/{id}

Excluir cliente

customers:delete

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 204 — Cliente excluído (sem corpo)

Sem corpo.

Exemplo

curl -X DELETE "https://api.comando.one/v1/customers/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/customers/{id}

Obter cliente

customers:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

`id`obrigatório(path)	string (uuid)
`include`(query)	"addresses"	addresses = inclui os endereços do cliente no campo `addresses`

Resposta 200 — Cliente

`id`	string (uuid)
`name`	string
`email`	string \| null
`phone`	string \| null
`document`	string \| null	CPF ou CNPJ
`type`	"fisica" \| "juridica" \| "estrangeira"	Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum.
`company_name`	string \| null
`trade_name`	string \| null
`status`	string
`created_at`	string (date-time)
`updated_at`	string (date-time)
`addresses`	array de CustomerAddress	Só vem com ?include=addresses. Endereço padrão primeiro; lista vazia = cliente sem endereço cadastrado.

Exemplo

curl -X GET "https://api.comando.one/v1/customers/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

PATCH/customers/{id}

Atualizar cliente

customers:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Corpo (JSON)

`name`	string
`email`	string \| null
`phone`	string \| null
`document`	string \| null
`type`	"fisica" \| "juridica" \| "estrangeira"	Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum.
`company_name`	string \| null
`trade_name`	string \| null
`status`	string

Resposta 200 — Cliente atualizado

`id`	string (uuid)
`name`	string
`email`	string \| null
`phone`	string \| null
`document`	string \| null	CPF ou CNPJ
`type`	"fisica" \| "juridica" \| "estrangeira"	Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum.
`company_name`	string \| null
`trade_name`	string \| null
`status`	string
`created_at`	string (date-time)
`updated_at`	string (date-time)
`addresses`	array de CustomerAddress	Só vem com ?include=addresses. Endereço padrão primeiro; lista vazia = cliente sem endereço cadastrado.

Exemplo

curl -X PATCH "https://api.comando.one/v1/customers/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/customers/{id}/addresses

Listar endereços do cliente

Funciona também para cliente compartilhado com a sua empresa (somente leitura). Para os endereços de vários clientes de uma vez, use GET /customers?include=addresses.

customers:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — Endereços

`id`	string (uuid)
`customer_id`	string (uuid)
`label`	string \| null
`street`	string \| null
`number`	string \| null
`complement`	string \| null
`neighborhood`	string \| null
`city`	string \| null
`state`	string \| null	UF (2 letras)
`zip`	string \| null
`country`	string \| null
`ibge_code`	string \| null
`is_default`	boolean
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X GET "https://api.comando.one/v1/customers/{id}/addresses" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

POST/customers/{id}/addresses

Adicionar endereço

customers:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Corpo (JSON)

`label`	string
`street`	string
`number`	string
`complement`	string
`neighborhood`	string
`city`	string
`state`	string
`zip`	string
`country`	string
`ibge_code`	string
`is_default`	boolean

Resposta 201 — Criado

`id`	string (uuid)
`customer_id`	string (uuid)
`label`	string \| null
`street`	string \| null
`number`	string \| null
`complement`	string \| null
`neighborhood`	string \| null
`city`	string \| null
`state`	string \| null	UF (2 letras)
`zip`	string \| null
`country`	string \| null
`ibge_code`	string \| null
`is_default`	boolean
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X POST "https://api.comando.one/v1/customers/{id}/addresses" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

DELETE/customers/{id}/addresses/{addressId}

Excluir endereço

customers:delete

Parâmetros, corpo, resposta e exemplo

Parâmetros

`id`obrigatório(path)	string (uuid)
`addressId`obrigatório(path)	string (uuid)

Resposta 204 — Excluído

Sem corpo.

Exemplo

curl -X DELETE "https://api.comando.one/v1/customers/{id}/addresses/{addressId}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

PATCH/customers/{id}/addresses/{addressId}

Atualizar endereço

customers:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

`id`obrigatório(path)	string (uuid)
`addressId`obrigatório(path)	string (uuid)

Corpo (JSON)

`label`	string
`street`	string
`number`	string
`complement`	string
`neighborhood`	string
`city`	string
`state`	string
`zip`	string
`country`	string
`ibge_code`	string
`is_default`	boolean

Resposta 200 — Atualizado

`id`	string (uuid)
`customer_id`	string (uuid)
`label`	string \| null
`street`	string \| null
`number`	string \| null
`complement`	string \| null
`neighborhood`	string \| null
`city`	string \| null
`state`	string \| null	UF (2 letras)
`zip`	string \| null
`country`	string \| null
`ibge_code`	string \| null
`is_default`	boolean
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X PATCH "https://api.comando.one/v1/customers/{id}/addresses/{addressId}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/customers/{id}/contacts

Listar contatos do cliente

customers:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — Contatos

`id`	string (uuid)
`customer_id`	string (uuid)
`name`	string
`email`	string \| null
`phone`	string \| null
`role`	string \| null
`department`	string \| null
`notes`	string \| null
`is_primary`	boolean
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X GET "https://api.comando.one/v1/customers/{id}/contacts" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

POST/customers/{id}/contacts

Adicionar contato

customers:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Corpo (JSON)

`name`obrigatório	string
`email`	string
`phone`	string
`role`	string
`department`	string
`notes`	string
`is_primary`	boolean

Resposta 201 — Criado

`id`	string (uuid)
`customer_id`	string (uuid)
`name`	string
`email`	string \| null
`phone`	string \| null
`role`	string \| null
`department`	string \| null
`notes`	string \| null
`is_primary`	boolean
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X POST "https://api.comando.one/v1/customers/{id}/contacts" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>"}'

DELETE/customers/{id}/contacts/{contactId}

Excluir contato

customers:delete

Parâmetros, corpo, resposta e exemplo

Parâmetros

`id`obrigatório(path)	string (uuid)
`contactId`obrigatório(path)	string (uuid)

Resposta 204 — Excluído

Sem corpo.

Exemplo

curl -X DELETE "https://api.comando.one/v1/customers/{id}/contacts/{contactId}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

PATCH/customers/{id}/contacts/{contactId}

Atualizar contato

customers:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

`id`obrigatório(path)	string (uuid)
`contactId`obrigatório(path)	string (uuid)

Corpo (JSON)

`name`obrigatório	string
`email`	string
`phone`	string
`role`	string
`department`	string
`notes`	string
`is_primary`	boolean

Resposta 200 — Atualizado

`id`	string (uuid)
`customer_id`	string (uuid)
`name`	string
`email`	string \| null
`phone`	string \| null
`role`	string \| null
`department`	string \| null
`notes`	string \| null
`is_primary`	boolean
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X PATCH "https://api.comando.one/v1/customers/{id}/contacts/{contactId}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>"}'

GET/customers/{id}/contracts

Contratos do cliente

customers:readcontracts:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

`id`obrigatório(path)	string (uuid)
`page`(query)	integer	Número da página (default: 1)
`per_page`(query)	integer	Itens por página (default: 20, máx: 100)

Resposta 200 — Listagem paginada

`id`	string (uuid)
`customer_id`	string (uuid)
`customers`	object
`title`	string \| null
`status`	"ativo" \| "suspenso" \| "cancelado" \| "finalizado"
`frequency`	"semanal" \| "quinzenal" \| "mensal" \| "bimestral" \| "trimestral" \| "semestral" \| "anual"
`start_date`	string (date)
`end_date`	string \| null (date)
`amount`	number
`due_days`	integer
`next_generation_date`	string \| null (date)
`notes`	string \| null
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X GET "https://api.comando.one/v1/customers/{id}/contracts" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/customers/{id}/invoices

Faturas do cliente

customers:readinvoices:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

`id`obrigatório(path)	string (uuid)
`page`(query)	integer	Número da página (default: 1)
`per_page`(query)	integer	Itens por página (default: 20, máx: 100)

Resposta 200 — Faturas do cliente

Sem corpo.

Exemplo

curl -X GET "https://api.comando.one/v1/customers/{id}/invoices" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/customers/{id}/proposals

Propostas do cliente

customers:readproposals:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

`id`obrigatório(path)	string (uuid)
`page`(query)	integer	Número da página (default: 1)
`per_page`(query)	integer	Itens por página (default: 20, máx: 100)

Resposta 200 — Listagem paginada

`id`	string (uuid)
`customer_id`	string (uuid)
`customers`	object
`status`	"rascunho" \| "enviada" \| "aceita" \| "recusada" \| "cancelada" \| "faturada"
`total_amount`	number
`valid_until`	string \| null (date)
`notes`	string \| null
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X GET "https://api.comando.one/v1/customers/{id}/proposals" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Início rápido, autenticação, SDK, servidor MCP e o playground para testar sem escrever código estão na documentação completa. A especificação em OpenAPI está em api.comando.one/openapi.json.

Outros recursos da API

Contratos (13)Faturas (12)Webhooks (12)Serviços (9)Split de Pagamentos (9)Catálogos (7)Propostas (6)NFS-e (6)

Ou deixe a IA usar a API por você

O servidor MCP expõe estes mesmos recursos ao ChatGPT, Claude ou Gemini — com OAuth, sem chave de API.

Conectar um assistente