API de Contratos

Contratos recorrentes

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

GET/contracts

Listar contratos

contracts: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 título ou notas
`status`(query)	"ativo" \| "suspenso" \| "cancelado" \| "finalizado"
`frequency`(query)	"semanal" \| "quinzenal" \| "mensal" \| "bimestral" \| "trimestral" \| "semestral" \| "anual"
`customer_id`(query)	string (uuid)

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/contracts" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

POST/contracts

Criar contrato

contracts:write

Parâmetros, corpo, resposta e exemplo

Corpo (JSON)

`customer_id`obrigatório	string (uuid)
`title`	string
`status`	"ativo" \| "suspenso" \| "cancelado" \| "finalizado"
`frequency`	"semanal" \| "quinzenal" \| "mensal" \| "bimestral" \| "trimestral" \| "semestral" \| "anual"
`start_date`	string (date)
`end_date`	string (date)
`due_days`	integer
`amount`	number
`payment_method_id`	string (uuid)
`next_generation_date`	string (date)	Data da próxima geração de fatura. Omitido, usa 'start_date'.
`notes`	string

Resposta 201 — Contrato criado

`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 POST "https://api.comando.one/v1/contracts" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"<string (uuid)>"}'

DELETE/contracts/{id}

Excluir contrato

contracts:delete

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 204 — Excluído

Sem corpo.

Exemplo

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

GET/contracts/{id}

Obter contrato

contracts:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — Contrato com itens e seções

`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)
`contract_items`	array de ContractItem
`contract_sections`	array \| null

Exemplo

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

PATCH/contracts/{id}

Atualizar contrato

contracts:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Corpo (JSON)

`customer_id`	string (uuid)	Troca o cliente do contrato. Precisa ser cliente desta empresa (404). Recusado com 409 se o contrato tem autorização de débito recorrente ativa (cartão salvo ou Pix Automático) — ela é do pagador atual; revogue-a antes. Faturas já geradas continuam no cliente antigo.
`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)
`due_days`	integer
`amount`	number
`payment_method_id`	string \| null (uuid)
`next_generation_date`	string (date)	Reagenda a próxima geração de fatura (rodada diária das 03:00). Só hoje (fuso de Brasília) em diante: data no passado é 400, porque o gerador emitiria de uma vez uma fatura por ciclo atrasado. Para gerar um ciclo agora use POST /contracts/{id}/generate-invoices.
`notes`	string \| null

Resposta 200 — Contrato atualizado

`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 PATCH "https://api.comando.one/v1/contracts/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

POST/contracts/{id}/generate-invoices

Gerar as faturas devidas do contrato

Gera fatura do contrato. Por padrão (mode=extra) cria uma fatura AVULSA fora do ciclo: não avança o agendamento, então chamar duas vezes gera DUAS faturas. Use mode=cycle para antecipar a fatura do ciclo corrente — é esse modo que avança next_generation_date e evita duplicar a competência. mode=skip pula o ciclo sem gerar nada. Contrato cancelado ou suspenso é recusado.

invoices:create

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Corpo (JSON)

mode "extra" | "cycle" | "skip" extra = avulsa (repetível) · cycle = fatura do ciclo, avança o agendamento · skip = só avança

Resposta 200 — Geração executada

`contract_id`	string (uuid)
`created`	integer	Quantas faturas nasceram nesta chamada.

Exemplo

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

POST/contracts/{id}/pause

Pausar contrato (status → suspenso)

contracts:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — Contrato pausado

`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 POST "https://api.comando.one/v1/contracts/{id}/pause" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/contracts/{id}/readjustments

Histórico de reajustes do contrato

contracts:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — Reajustes aplicados (mais recente primeiro)

`id`	string (uuid)
`contract_id`	string (uuid)
`applied_at`	string (date-time)
`applied_by`	string \| null (uuid)
`period_start`	string \| null (date)	Início do período coberto (último reajuste anterior)
`period_end`	string \| null (date)
`previous_amount`	number
`new_amount`	number
`applied_percent`	number	Percentual efetivamente aplicado
`suggested_percent`	number \| null	Sugestão do índice preferido no momento da aplicação
`suggested_index`	"ipca" \| "igpm" \| "inpc" \| "usd" \| "eur" \| null
`notes`	string \| null

Exemplo

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

POST/contracts/{id}/readjustments

Aplicar reajuste no contrato

Atualiza o valor do contrato (e escala os itens proporcionalmente), grava o histórico e avança a data do próximo reajuste. Informe 'new_amount' OU 'percent'. Faturas já geradas não são alteradas.

contracts:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Corpo (JSON)

`new_amount`	number	Novo valor do contrato (R$)
`percent`	number	Percentual de reajuste (ex.: 4.62)
`suggested_percent`	number	Sugestão exibida no momento (para o histórico sugerido × aplicado)
`suggested_index`	"ipca" \| "igpm" \| "inpc" \| "usd" \| "eur"
`notes`	string

Resposta 201 — Reajuste aplicado

`id`	string (uuid)
`contract_id`	string (uuid)
`applied_at`	string (date-time)
`applied_by`	string \| null (uuid)
`period_start`	string \| null (date)	Início do período coberto (último reajuste anterior)
`period_end`	string \| null (date)
`previous_amount`	number
`new_amount`	number
`applied_percent`	number	Percentual efetivamente aplicado
`suggested_percent`	number \| null	Sugestão do índice preferido no momento da aplicação
`suggested_index`	"ipca" \| "igpm" \| "inpc" \| "usd" \| "eur" \| null
`notes`	string \| null

Exemplo

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

DELETE/contracts/{id}/readjustments/{readjustmentId}

Desfazer um reajuste aplicado

Devolve o contrato ao valor anterior, restaura os itens ao estado gravado no momento da aplicação e recalcula a data do próximo reajuste. Só o reajuste mais recente ainda vigente pode ser desfeito, e apenas se o valor do contrato não tiver sido alterado depois. A linha permanece no histórico marcada como desfeita; faturas já geradas não são alteradas.

contracts:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

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

Resposta 200 — Reajuste desfeito

`reverted`	boolean
`contract_id`	string (uuid)
`restored_amount`	number
`items_exact`	boolean	false quando os itens voltaram por escala inversa (aproximada), por ausência do registro anterior

Exemplo

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

POST/contracts/{id}/resume

Retomar contrato (status → ativo)

contracts:write

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — Contrato retomado

`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 POST "https://api.comando.one/v1/contracts/{id}/resume" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/contracts/readjustments/due

Fila de reajuste (contratos atrasados + janela)

Contratos ativos, não isentos, com reajuste vencido ou vencendo na janela informada. Campo 'overdue' indica atraso.

contracts:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

days(query) integer Janela em dias além dos atrasados

Resposta 200 — Fila de reajuste

`id`	string (uuid)
`customer_id`	string (uuid)
`customers`	object
`title`	string \| null
`status`	string
`frequency`	string
`amount`	number
`readjustment_index`	"ipca" \| "igpm" \| "inpc" \| "usd" \| "eur" \| "manual"
`readjustment_period_months`	integer
`last_readjustment_date`	string \| null (date)
`next_readjustment_date`	string \| null (date)
`next_generation_date`	string \| null (date)	Quando a próxima fatura será gerada — se antes do reajuste, ela sai no valor antigo
`overdue`	boolean

Exemplo

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

GET/market-indices

Índices de mercado acumulados no período (BCB)

Acumulado de IPCA/IGP-M/INPC (composto mensal) e variação da PTAX de dólar/euro entre 'from' e 'to'. Fonte: Banco Central (SGS e PTAX), sincronizada diariamente.

contracts:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

`from`obrigatório(query)	string (date)	Início do período (ex.: data do último reajuste)
`to`(query)	string (date)	Fim do período (padrão: hoje)

Resposta 200 — Acumulados por índice

`index_code`	"ipca" \| "igpm" \| "inpc" \| "usd" \| "eur"
`accumulated_pct`	number \| null	Acumulado em pontos percentuais (4.62 = 4,62%); null = sem cobertura de dados
`coverage_start`	string \| null (date)
`coverage_end`	string \| null (date)
`last_ref_date`	string \| null (date)	Até onde o índice cobre (IPCA sai com ~15 dias de atraso)

Exemplo

curl -X GET "https://api.comando.one/v1/market-indices" \
  -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

Clientes (16)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