# Documentação da API

> API REST pública do Comando1, SDK TypeScript e servidor MCP. Autenticação por chave, scopes por módulo, webhooks com reentrega e exemplos prontos para clientes, faturas, NFS-e e financeiro.

Fonte: https://comando.one/docs · Atualizado em 2026-09-11 · Comando.One (ORBITAL TECNOLOGIA E DESENVOLVIMENTO LTDA, CNPJ 29.383.276/0001-88)

---

Conteúdo

Introdução Início rápido Autenticação SDK & Bibliotecas MCP (IA / Agentes) Permissões (scopes) Erros Endpoints Autenticação & Empresas Clientes Fornecedores Serviços Despesas Contas a Pagar Propostas Contratos Faturas Financeiro Relatórios, Auditoria & Categorias NFS-e Catálogos / Lookups Gateway de Pagamentos Cobranças Webhooks Métodos de pagamento Contas bancárias Caixa de Entrada Conciliação Faturas de cartão DDA Recorrentes Insumos Notificações Pagamentos (Payouts) Split de Pagamentos Formas de pagto. fornecedor Rate limiting [Criar chave de API](https://comando.one/login)

Nesta página

Introdução Início rápido Autenticação SDK & Bibliotecas MCP (IA / Agentes) Permissões (scopes) Erros Endpoints Gateway de Pagamentos Rate limiting

API Pública v1

# Documentação da API

A API REST do Comando1 permite que sistemas externos leiam e manipulem dados da sua empresa de forma segura. Para integrações de sistema, autentique com uma chave de API estática (abaixo). Para conectar um assistente de IA, o servidor MCP também aceita OAuth 2.1 — nesse caso você cola a URL e autoriza pelo navegador, sem gerar chave.

URL base

`https://api.comando.one/v1`

Formato

REST / JSON

Autenticação

API Key (Bearer)

[OpenAPI 3.1 (JSON)](https://api.comando.one/openapi.json)[Abrir no Swagger Editor](https://editor.swagger.io/?url=https://api.comando.one/openapi.json)

## Início rápido

Em menos de 2 minutos você faz sua primeira chamada.

1

Crie uma chave de API

Acesse [Configurações → API Keys](https://comando.one/login) dentro da plataforma e crie uma chave com as permissões desejadas.

2

Guarde em local seguro

A chave `cmd_live_...` é exibida uma única vez. Use variáveis de ambiente — nunca no código-fonte.

3

Primeira chamada

cURL Copiar
`curl https://api.comando.one/v1/me \ -H "Authorization: Bearer cmd_live_sua_chave_aqui"`
Resposta JSON Copiar
`{ "company": { "id": "18fc359b-a460-4d5f-abfb-f493f153430f", "name": "Acme Serviços Ltda", "trade_name": "Acme", "document": "12345678000195" }, "api_key": { "name": "Integração ERP", "scopes": ["customers:read", "invoices:read"], "last_used_at": "2026-06-04T18:17:47.222+00:00" } }`

## Autenticação

Envie sua chave em um dos dois headers — ambos são equivalentes:

Opção A — `Authorization`

cURL Copiar
`curl https://api.comando.one/v1/me \ -H "Authorization: Bearer cmd_live_sua_chave_aqui"`

Opção B — `x-api-key`

cURL Copiar
`curl https://api.comando.one/v1/me \ -H "x-api-key: cmd_live_sua_chave_aqui"`

⚠️ Segurança

- • Nunca exponha a chave no frontend ou código-fonte.
- • Use variáveis de ambiente: `COMANDO_API_KEY=cmd_live_...`
- • Chaves não expiram automaticamente — revogue imediatamente se comprometidas.
- • Crie chaves com o mínimo de permissões necessário (princípio do mínimo privilégio).

## SDK & Bibliotecas

Bibliotecas oficiais publicadas no npm para acelerar a integração.

[@comando.one/sdkClient TypeScript/ESM, zero dependências. Todos os recursos da API com tipagem, paginação automática e idempotência. Browser + Node 18+.](https://www.npmjs.com/package/@comando.one/sdk)[@comando.one/mcp-serverServidor MCP (stdio) para conectar agentes de IA (Claude, etc.) ao seu ERP. 169 ferramentas curadas com guardas de segurança.](https://www.npmjs.com/package/@comando.one/mcp-server)

Instalação do SDK

bash Copiar
`npm install @comando.one/sdk`

Uso

TypeScript Copiar
`import { ComandoApi } from "@comando.one/sdk"; const api = new ComandoApi({ apiKey: "cmd_live_..." }); const me = await api.me(); const clientes = await api.customers.list({ status: "ativo" }); const todos = await api.customers.listAll(); // pagina sozinho const cobranca = await api.charges.create({ invoice_id, method: "pix" });`
[Exemplos prontos no GitHubAplicações completas usando o SDK e o MCP — checkout, portal do cliente, chatbot, conciliação, NFS-e em lote, webhooks e mais. Veja github.com/comando-one/api-examples.](https://github.com/comando-one/api-examples)

## MCP — Model Context Protocol

Conecte assistentes de IA (Claude Desktop, agentes, chatbots) ao seu ERP. As ferramentas operam a API real, respeitando os scopes da chave; ações destrutivas exigem confirmação. Há duas formas de usar:

1. Local (stdio) — via npm

Adicione ao `claude_desktop_config.json`:

JSON Copiar
`{ "mcpServers": { "comando": { "command": "npx", "args": ["-y", "@comando.one/mcp-server"], "env": { "COMANDO_API_KEY": "cmd_live_..." } } } }`

2. Remoto (streaming) — sem instalar nada

Endpoint MCP Streamable HTTP em `https://api.comando.one/mcp`. Autentique com `Authorization: Bearer cmd_live_…`.

cURL Copiar
`curl https://api.comando.one/mcp \ -H "Authorization: Bearer cmd_live_..." \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'`

No Claude Desktop (conector remoto):

JSON Copiar
`{ "mcpServers": { "comando-remoto": { "type": "http", "url": "https://api.comando.one/mcp", "headers": { "Authorization": "Bearer cmd_live_..." } } } }`

[💬 Chatbot de exemploUm chatbot funcional (Gemini + MCP remoto) está disponível nos exemplos — converse em português e ele opera o ERP. Veja o exemplo chatbot/ no repositório github.com/comando-one/api-examples.](https://github.com/comando-one/api-examples/tree/main/chatbot)

## Permissões (scopes)

Cada chave é criada com permissões específicas no formato `módulo:ação`. Sem o scope exigido, a API retorna `403`.

Documentos

| Scope | Descrição |
| --- | --- |
| `documents:read` | Ler anexos (boleto, guia, NF) e extrair valor, vencimento e emitente |

Clientes

| Scope | Descrição |
| --- | --- |
| `customers:read` | Consultar clientes e contatos |
| `customers:write` | Criar novos clientes e editar dados |
| `customers:delete` | Excluir clientes permanentemente |

Propostas

| Scope | Descrição |
| --- | --- |
| `proposals:read` | Consultar propostas comerciais |
| `proposals:write` | Criar e editar propostas |
| `proposals:send` | Enviar propostas por e-mail |
| `proposals:delete` | Excluir propostas |

Faturas / Cobranças

| Scope | Descrição |
| --- | --- |
| `invoices:read` | Consultar faturas e cobranças |
| `invoices:create` | Gerar boletos, Pix e cobranças |
| `invoices:cancel` | Cancelar cobranças em aberto |
| `invoices:send` | Enviar segunda via da fatura por e-mail ao cliente |
| `invoices:settle` | Registrar o recebimento de uma parcela (baixa total ou parcial) |
| `invoices:delete` | Excluir faturas permanentemente (itens e cobranças vinculadas) |

NFS-e

| Scope | Descrição |
| --- | --- |
| `nfse:read` | Listar e visualizar notas fiscais |
| `nfse:emitir` | Emitir notas fiscais de serviço |
| `nfse:cancelar` | Cancelar notas fiscais emitidas |

Financeiro

| Scope | Descrição |
| --- | --- |
| `finance:read` | Consultar lançamentos e extratos |
| `finance:write` | Lançar e editar movimentações |
| `finance:delete` | Excluir lançamentos |

Contratos

| Scope | Descrição |
| --- | --- |
| `contracts:read` | Consultar contratos |
| `contracts:write` | Criar e editar contratos |
| `contracts:delete` | Excluir contratos |

Fornecedores

| Scope | Descrição |
| --- | --- |
| `suppliers:read` | Consultar fornecedores |
| `suppliers:write` | Criar e editar fornecedores |
| `suppliers:delete` | Excluir fornecedores |

Serviços

| Scope | Descrição |
| --- | --- |
| `services:read` | Consultar o catálogo de serviços |
| `services:write` | Criar e editar serviços |
| `services:delete` | Excluir serviços |

Despesas

| Scope | Descrição |
| --- | --- |
| `expenses:read` | Consultar despesas |
| `expenses:write` | Lançar e editar despesas |
| `expenses:delete` | Excluir despesas |

Contas a Pagar

| Scope | Descrição |
| --- | --- |
| `purchase_invoices:read` | Consultar contas a pagar |
| `purchase_invoices:create` | Lançar contas a pagar |
| `purchase_invoices:cancel` | Cancelar contas a pagar |
| `purchase_invoices:delete` | Excluir contas a pagar definitivamente |

Cobranças / Gateway

| Scope | Descrição |
| --- | --- |
| `charges:read` | Listar e visualizar cobranças geradas via API |
| `charges:create` | Gerar Pix, boleto ou checkout de pagamento |
| `charges:cancel` | Cancelar cobranças em aberto |
| `charges:refund` | Devolver (estornar) cobranças Pix pagas |

Webhooks

| Scope | Descrição |
| --- | --- |
| `webhooks:manage` | Registrar e configurar URLs de callback para eventos de pagamento |

Contas bancárias

| Scope | Descrição |
| --- | --- |
| `bank_accounts:read` | Consultar contas bancárias (somente leitura, sem dados sensíveis) |

Pagamentos a Fornecedor

| Scope | Descrição |
| --- | --- |
| `payouts:read` | Listar e visualizar pagamentos a fornecedores |
| `payouts:create` | Executar ou agendar pagamentos Pix e boleto a fornecedores |
| `payouts:cancel` | Cancelar pagamentos agendados |

Split de Pagamentos

| Scope | Descrição |
| --- | --- |
| `split:list` | Consultar regras, execuções e repasses de split |
| `split:create` | Criar regras de divisão de recebimentos |
| `split:update` | Editar regras, liberar fatias e estornar repasses |
| `split:delete` | Remover regras de split |

Caixa de Entrada

| Scope | Descrição |
| --- | --- |
| `inbox:read` | Ver os e-mails recebidos e os boletos/notas extraídos deles |
| `inbox:update` | Devolver a mensagem ao processamento ou arquivá-la |

Conciliação Bancária

| Scope | Descrição |
| --- | --- |
| `reconciliation:read` | Ver lançamentos do extrato e os períodos de conciliação |
| `reconciliation:write` | Desconciliar um lançamento já casado (a conciliação em si é feita no aplicativo) |

Cartão de Crédito

| Scope | Descrição |
| --- | --- |
| `cards:read` | Ver as faturas de cartão, com fechamento, vencimento e total |

DDA

| Scope | Descrição |
| --- | --- |
| `dda:read` | Ver os boletos que o banco avisou por DDA e o status de casamento |
| `dda:triage` | Arquivar um boleto do DDA ou devolvê-lo à fila |

Recorrentes

| Scope | Descrição |
| --- | --- |
| `recurring:read` | Ver as regras que geram despesas e contas a pagar recorrentes |
| `recurring:update` | Pausar ou retomar uma regra recorrente |

Insumos

| Scope | Descrição |
| --- | --- |
| `insumos:read` | Consultar o catálogo de insumos |
| `insumos:write` | Criar e editar insumos |
| `insumos:delete` | Excluir insumos |

Notificações

| Scope | Descrição |
| --- | --- |
| `notifications:read` | Ver as notificações geradas para os usuários da empresa |
| `notifications:update` | Marcar notificação como lida ou não lida |

Auditoria

| Scope | Descrição |
| --- | --- |
| `audit:read` | Consultar a timeline de alterações de uma entidade (audit_logs) |

Lembretes

| Scope | Descrição |
| --- | --- |
| `reminders:list` | Consultar lembretes e resumos agendados |
| `reminders:create` | Criar lembretes e resumos recorrentes da empresa |
| `reminders:update` | Editar, ativar e pausar lembretes |
| `reminders:delete` | Excluir lembretes |

## Erros

A API usa HTTP padrão e sempre retorna `{ "error": "..." }` no corpo — inclusive quando quem falha é um terceiro. Falha de dependência externa é **424**, nunca 502: a borda da Cloudflare troca o corpo de todo 502/504 pela página HTML dela, e o motivo do erro não chegaria até você.

| Status | Código | Descrição |
| --- | --- | --- |
| 400 | Bad Request | Parâmetros inválidos ou ausentes na requisição. |
| 401 | Unauthorized | Chave não fornecida, inválida ou revogada. |
| 403 | Forbidden | A chave não possui o scope necessário para este endpoint. |
| 404 | Not Found | Recurso não encontrado. |
| 405 | Method Not Allowed | Método HTTP não suportado nesta rota. |
| 409 | Conflict | Conflito de estado (ex: cancelar fatura já cancelada) ou exclusão bloqueada por registros vinculados (ex: cliente com faturas, fornecedor com contas a pagar). |
| 422 | Unprocessable | A requisição está correta, mas o conteúdo não pode ser processado — ex.: NFS-e rejeitada pelo fisco (o corpo traz status: "rejeitada" e message) ou empresa sem NFS-e configurada. |
| 424 | Failed Dependency | A requisição estava correta, mas um terceiro falhou: o fisco, o banco, o gateway de pagamento. O motivo dele vem em error. A API nunca responde 502/504 — a borda substituiria o corpo pela página HTML dela e o motivo se perderia. |
| 429 | Too Many Requests | Rate limit excedido. Aguarde e tente novamente. |
| 500 | Server Error | Erro interno no servidor. |

Chave inválida (401)

JSON Copiar
`{ "error": "API key inválida." }`

Scope insuficiente (403)

JSON Copiar
`{ "error": "A chave não possui o scope necessário: customers:read." }`

## Endpoints

Todas as respostas de listagem seguem o envelope `{ data: [...], meta: { page, per_page, total } }`.

### Autenticação

GET `/v1/me` Retorna os dados da empresa e da chave autenticada. Ideal para verificar conectividade. (qualquer chave válida)

Retorna os dados da empresa e da chave autenticada. Ideal para verificar conectividade.

(qualquer chave válida)
Documentação Testar

Requisição

cURL Copiar
`curl https://api.comando.one/v1/me \ -H "Authorization: Bearer cmd_live_sua_chave_aqui"`

Resposta — 200 OK

JSON Copiar
`{ "company": { "id": "18fc359b-a460-4d5f-abfb-f493f153430f", "name": "Acme Serviços Ltda", "trade_name": "Acme", "document": "12345678000195" }, "api_key": { "name": "Integração ERP", "scopes": ["customers:read", "invoices:read"], "last_used_at": "2026-06-04T18:17:47.222+00:00" } }`

Campos

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `company.id` | uuid | ID único da empresa |
| `company.name` | string | Razão social |
| `company.trade_name` | string | null | Nome fantasia |
| `company.document` | string | CNPJ (somente dígitos) |
| `api_key.name` | string | Nome da chave |
| `api_key.scopes` | string[] | Permissões da chave |
| `api_key.last_used_at` | ISO 8601 | null | Último uso |
| `api_key.multi_company` | boolean | Se a chave acessa mais de uma empresa |
| `api_key.accessible_company_ids` | uuid[] | Empresas acessíveis pela chave |

**Multi-empresa:** uma chave pode acessar várias empresas. Liste-as em `GET /v1/companies` e escolha o tenant de cada request com o header `X-Company-Id`. Omitido = empresa padrão da chave.
GET `/v1/companies` Lista as empresas que a chave pode acessar. Use o id em X-Company-Id para escolher o tenant. (qualquer chave válida)
GET `/v1/customers (exemplo com X-Company-Id)` Qualquer endpoint aceita o header X-Company-Id para operar numa empresa específica acessível pela chave. customers:read

### Clientes

GET `/v1/customers` Lista todos os clientes da empresa, ordenados por nome. customers:read
GET `/v1/customers/:id` Retorna os dados de um cliente específico pelo seu ID. customers:read
GET `/v1/customers/:id/invoices` Lista as faturas de um cliente específico. customers:read + invoices:read
GET `/v1/customers/:id/contracts` Lista os contratos ativos de um cliente específico. customers:read + contracts:read
GET `/v1/customers/:id/proposals` Lista as propostas de um cliente específico. customers:read + proposals:read
POST `/v1/customers` Cria um novo cliente. Retorna 201 com o objeto criado. customers:write
PATCH `/v1/customers/:id` Atualiza parcialmente um cliente. Envie apenas os campos que deseja alterar. customers:write
DELETE `/v1/customers/:id` Exclui permanentemente um cliente. Retorna 204 sem corpo na resposta. Se o cliente tiver registros vinculados (faturas, contratos, etc.), a exclusão é bloqueada e retorna 409 Conflict. customers:delete
GET `/v1/customers/:id/addresses` Lista os endereços do cliente. Endereço é necessário para emitir boleto. customers:read
POST `/v1/customers/:id/addresses` Adiciona um endereço ao cliente. Para boleto, informe street, number, city, state e zip. customers:write
PATCH `/v1/customers/:id/addresses/:addressId` Atualiza um endereço do cliente. customers:write
DELETE `/v1/customers/:id/addresses/:addressId` Exclui um endereço. Retorna 204 sem corpo. customers:delete
GET `/v1/customers/:id/contacts` Lista os contatos do cliente. customers:read
POST `/v1/customers/:id/contacts` Adiciona um contato ao cliente. name é obrigatório. customers:write
PATCH `/v1/customers/:id/contacts/:contactId` Atualiza um contato do cliente. customers:write
DELETE `/v1/customers/:id/contacts/:contactId` Exclui um contato. Retorna 204 sem corpo. customers:delete

### Fornecedores

GET `/v1/suppliers` Lista os fornecedores da empresa, ordenados por nome. suppliers:read
GET `/v1/suppliers/:id` Retorna um fornecedor específico pelo ID. suppliers:read
POST `/v1/suppliers` Cria um novo fornecedor. Retorna 201 com o objeto criado. 'name' é o título de exibição; se omitido, é derivado de 'legal_name'. suppliers:write
PATCH `/v1/suppliers/:id` Atualiza parcialmente um fornecedor. Envie apenas os campos a alterar. suppliers:write
DELETE `/v1/suppliers/:id` Exclui permanentemente um fornecedor. Retorna 204 sem corpo. suppliers:delete

### Serviços

GET `/v1/services` Lista o catálogo de serviços da empresa. services:read
GET `/v1/services/:id` Retorna um serviço específico pelo ID. services:read
POST `/v1/services` Cria um novo serviço no catálogo. Retorna 201. services:write
PATCH `/v1/services/:id` Atualiza parcialmente um serviço. services:write
DELETE `/v1/services/:id` Exclui permanentemente um serviço. Retorna 204 sem corpo. services:delete

### Despesas

GET `/v1/expenses` Lista as despesas da empresa, mais recentes primeiro. expenses:read
GET `/v1/expenses/:id` Retorna uma despesa específica pelo ID. expenses:read
POST `/v1/expenses` Lança uma nova despesa. O fornecedor deve pertencer à empresa. Retorna 201. expenses:write
PATCH `/v1/expenses/:id` Atualiza parcialmente uma despesa (ex: marcar como paga). expenses:write
DELETE `/v1/expenses/:id` Exclui permanentemente uma despesa. Retorna 204 sem corpo. expenses:delete

### Contas a Pagar

GET `/v1/purchase-invoices` Lista as notas fiscais de entrada / contas a pagar. purchase_invoices:read
GET `/v1/purchase-invoices/:id` Retorna uma conta a pagar com seus itens e parcelas. purchase_invoices:read
POST `/v1/purchase-invoices` Lança uma nova conta a pagar. O fornecedor deve pertencer à empresa. O vencimento mora nas parcelas: informe um 'due_date' (atalho: cria 1 parcela) ou um array 'charges'. Retorna 201 com itens e parcelas. purchase_invoices:create
PATCH `/v1/purchase-invoices/:id/cancel` Cancela uma conta a pagar. Retorna 409 se já estiver cancelada. purchase_invoices:cancel
DELETE `/v1/purchase-invoices/:id` Exclui a conta a pagar definitivamente (204). Use quando o lançamento nunca deveria ter existido — duplicata, erro de digitação. Se já houver pagamento registrado na conta ou em alguma parcela, retorna 409: nesse caso o certo é cancelar, que preserva o histórico. Itens, parcelas, ajustes e centros de custo são excluídos junto; pagamento a fornecedor vinculado impede a exclusão. purchase_invoices:delete

### Propostas

GET `/v1/proposals` Lista propostas comerciais, da mais recente para a mais antiga. proposals:read
GET `/v1/proposals/:id` Retorna uma proposta com seus itens detalhados. proposals:read
POST `/v1/proposals` Cria uma nova proposta. O cliente deve pertencer à empresa. Retorna 201. proposals:write
PATCH `/v1/proposals/:id` Atualiza parcialmente uma proposta (ex: mudar status para enviada). proposals:write
POST `/v1/proposals/:id/send` Marca a proposta como enviada. proposals:send
DELETE `/v1/proposals/:id` Exclui uma proposta. Retorna 204 sem corpo. proposals:delete

### Contratos

GET `/v1/contracts` Lista contratos recorrentes, do mais recente para o mais antigo. contracts:read
GET `/v1/contracts/:id` Retorna um contrato com seus itens e seções de conteúdo. contracts:read
POST `/v1/contracts` Cria um novo contrato recorrente. O cliente deve pertencer à empresa. Retorna 201. contracts:write
PATCH `/v1/contracts/:id` Atualiza parcialmente um contrato (ex: suspender, alterar valor). contracts:write
DELETE `/v1/contracts/:id` Exclui um contrato. Retorna 204 sem corpo. contracts:delete

### Faturas / Cobranças

GET `/v1/invoices` Lista faturas da empresa, da mais recente para a mais antiga. invoices:read
GET `/v1/invoices/:id` Retorna uma fatura com seus itens e parcelas de cobrança. invoices:read
POST `/v1/invoices` Cria uma fatura já cobrável: nasce com uma parcela 1/1 no 'due_date' informado. Se 'items' for enviado, o valor é calculado a partir deles. invoices:create
PATCH `/v1/invoices/:id` Corrige o cabeçalho de uma fatura já criada. Existe para não ser preciso APAGAR a fatura (e estornar a baixa antes) só para trocar um status. Escopo estreito: para cancelar use /cancel — o cancelamento tem efeitos que uma troca de status não dispara; e o vencimento muda na parcela, não aqui. invoices:create
PATCH `/v1/invoices/:id/auto-send` Programa a cobrança automática nas parcelas em aberto. Sem isso a cobrança nunca sai sozinha: o disparo diário só envia com o automático ligado na parcela, e fatura criada pela API nasce desligada. days_before = dias ANTES do vencimento (0 = no dia). Desligar devolve o canal para manual. invoices:send
GET `/v1/invoices/:id/charges` As PARCELAS da fatura, com quanto já foi pago e quanto falta em cada uma. Não confunda com /v1/charges, que é a cobrança do GATEWAY (Pix/boleto emitido no banco): a parcela é o que manda no vencimento e no status de pagamento da fatura. Use para descobrir o charge_id antes de dar baixa. invoices:read
POST `/v1/invoices/:id/charges/:charge_id/pay` Dá baixa numa parcela: registra o recebimento e o aloca à parcela. A parcela e a fatura passam a pago (ou parcial) pelo próprio banco. Sem amount, quita o saldo restante; sem payment_date, usa hoje. Baixa parcial é permitida; acima do saldo, não. Campo de corpo que a rota não conhece devolve 400 em vez de ser ignorado em silêncio. invoices:settle
GET `/v1/invoices/:id/charges/:charge_id/payments` Os recebimentos já registrados na parcela. reconciled: true avisa que aquele pagamento está conciliado com o extrato — o estorno dele será recusado até a conciliação ser desfeita. invoices:read
DELETE `/v1/invoices/:id/charges/:charge_id/payments/:payment_id` Estorna uma baixa. A parcela e a fatura voltam a pendente/vencido/parcial pelo próprio banco. O pagamento é apagado quando existia só para esta baixa; cobrindo outras faturas, perde apenas esta alocação e tem o valor reduzido. RECUSA (409) se o pagamento estiver conciliado com o extrato, ou se a parcela tiver gerado repasse (split) já liberado ou pago — nos dois casos a resposta diz o que desfazer antes. invoices:settle
PATCH `/v1/invoices/:id/cancel` Cancela uma fatura. Retorna 409 se já estiver cancelada. invoices:cancel

### Financeiro

GET `/v1/finance/ledger` Razão financeiro — entradas e saídas de recebimentos, pagamentos a fornecedores e despesas. finance:read
POST `/v1/finance/movements` Lança uma movimentação financeira manual (entrada ou saída). Requer uma natureza financeira (nature_id). finance:write
DELETE `/v1/finance/movements/:id` Exclui uma movimentação manual. Retorna 409 se não for de origem manual. finance:delete

### Relatórios, Auditoria & Categorias

GET `/v1/reports/aging-actions` Faturas em atraso com dias de atraso e ação recomendada por nível. Exclui canceladas; os valores são o SALDO devedor, não o valor cheio da fatura. invoices:read
GET `/v1/reports/cashflow-forecast` Projeção diária de entradas e saídas com saldo acumulado. finance:read
POST `/v1/documents/analyze` Lê um anexo da empresa (PDF, imagem ou texto) e extrai os campos financeiros: tipo, valor, vencimento, número, emitente, linha digitável do boleto e chave Pix. Usa o texto do arquivo e, quando ele não basta (PDF escaneado), a leitura visual do modelo. documents:read
GET `/v1/audit/timeline` Histórico de alterações (audit_logs) de uma entidade, mais recente primeiro. audit:read
GET `/v1/service-categories` Lista as categorias de serviço da empresa. services:read
POST `/v1/service-categories` Cria uma ou várias categorias de serviço. Retorna 201. services:write
PATCH `/v1/service-categories/:id` Renomeia ou altera a cor de uma categoria. services:write
DELETE `/v1/service-categories/:id` Exclui uma categoria de serviço. Retorna 204. services:delete
POST `/v1/contracts/:id/pause` Pausa um contrato (status → suspenso). contracts:write
POST `/v1/contracts/:id/resume` Retoma um contrato suspenso (status → ativo). contracts:write
GET `/v1/contracts/readjustments/due` Fila de reajuste: contratos ativos com reajuste vencido ou vencendo na janela (?days=30). Campo 'overdue' indica atraso; 'next_generation_date' mostra quando a próxima fatura sai (no valor antigo, se você não reajustar antes). contracts:read
GET `/v1/contracts/:id/readjustments` Histórico de reajustes do contrato (mais recente primeiro), com % aplicado × % sugerido pelo índice. contracts:read
POST `/v1/contracts/:id/readjustments` Aplica um reajuste: atualiza o valor do contrato, 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 mudam. contracts:write
DELETE `/v1/contracts/:id/readjustments/:readjustmentId` Desfaz um reajuste: o contrato volta ao valor anterior, os itens voltam ao estado gravado na aplicação e a data do próximo reajuste é recalculada. Só o mais recente ainda vigente pode ser desfeito, e apenas se ninguém alterou o valor depois. A linha fica no histórico marcada como desfeita; faturas já geradas não mudam. contracts:write
GET `/v1/market-indices` Acumulado oficial dos índices no período (?from=YYYY-MM-DD&to=): IPCA/IGP-M/INPC compostos mês a mês + variação da PTAX de dólar/euro. Fonte: Banco Central, sincronizada diariamente. contracts:read
DELETE `/v1/invoices/:id` Exclusão física da fatura (itens e cobranças via cascade). Use PATCH /cancel para apenas cancelar. invoices:delete

### NFS-e

GET `/v1/nfse` Lista notas fiscais de serviço eletrônicas, da mais recente para a mais antiga. nfse:read
GET `/v1/nfse/:id` Retorna uma NFS-e específica com detalhes de cancelamento se aplicável. nfse:read
POST `/v1/nfse` Emite uma NFS-e a partir de uma fatura. O método (certificado ou portal) vem da configuração da empresa. Pode levar alguns segundos. nfse:emitir
PATCH `/v1/nfse/:id/cancel` Cancela uma NFS-e autorizada. motivo: 1=não realizada, 2=duplicação, 3=erro de emissão, 4=serviço não prestado, 9=outros. Justificativa entre 15 e 255 caracteres. nfse:cancelar
POST `/v1/nfse/:id/sync` Sincroniza o status da NFS-e com o provedor fiscal (consulta protocolo e baixa artefatos). nfse:read
GET `/v1/nfse/:id/files` URLs assinadas (30 min) para baixar o XML e o PDF (DANFSE). Gera o PDF sob demanda se a nota já estiver autorizada/cancelada. nfse:read

### Catálogos / Lookups

Listagens de referência para descobrir os IDs exigidos em writes (ex: `nature_id` em movimentações, `category_id` em despesas). Read-only.

GET `/v1/finance/natures` Naturezas financeiras — usadas em POST /v1/finance/movements (nature_id). finance:read | finance:write
GET `/v1/cost-centers` Centros de custo / categorias — usados em despesas (category_id). expenses:read | finance:read
POST `/v1/cost-centers` Cria um centro de custo. Retorna 201. finance:write
PATCH `/v1/cost-centers/:id` Atualiza um centro de custo. finance:write
DELETE `/v1/cost-centers/:id` Exclui um centro de custo. Retorna 204. finance:delete
GET `/v1/reminders` Lembretes e resumos agendados da empresa (recorrentes ou avulsos). reminders:list
POST `/v1/reminders` Cria um lembrete. scope=personal (só do usuário; via chave informe owner_user_id) ou scope=company (todos da empresa). Atalhos: remind_in_minutes (relativo, servidor calcula) ou remind_at (ISO). next_run_at é calculado automaticamente. Retorna 201. reminders:create
PATCH `/v1/reminders/:id` Atualiza, ativa ou pausa um lembrete. reminders:update
DELETE `/v1/reminders/:id` Exclui um lembrete. Retorna 204. reminders:delete
GET `/v1/payment-conditions` Condições de pagamento (parcelamentos) configuradas. invoices:read | contracts:read
GET `/v1/service-units` Unidades de serviço da empresa (hora, unidade, mensal...). services:read
GET `/v1/payment-methods/ap` Métodos de pagamento a fornecedor (contas a pagar). payouts:read

## Gateway de Pagamentos

Use a API como um gateway de pagamentos: gere cobranças (Pix, boleto, checkout) e seja notificado quando o pagamento for confirmado — sem depender do portal do banco. O provider é determinado automaticamente pela configuração da empresa.

Pix (QR dinâmico)

QR code e copia-e-cola em segundos.

Boleto bancário

Código de barras e linha digitável.

Webhooks HMAC

Notificação assinada quando o pagamento é confirmado.

### Cobranças

GET `/v1/charges` Lista cobranças geradas. Filtre por status, método ou cliente. charges:read
GET `/v1/charges/:id` Detalhes de uma cobrança específica, incluindo dados de pagamento (QR code, linha digitável, etc.). charges:read
POST `/v1/charges` Cria uma nova cobrança. Forneça invoice_id para vincular a uma fatura existente, ou customer_id + amount + due_date para criar automaticamente. O provedor é escolhido pela integração ativa do canal (use "provider" para desambiguar). Com Pagar.me: method=pix retorna o copia-e-cola e method=credit_card retorna "checkout.url" (link da página de pagamento própria). charges:create
POST `/v1/charges` Exemplo criando cobrança por boleto. charges:create
DELETE `/v1/charges/:id` Cancela uma cobrança em aberto. Retorna 409 se a cobrança já foi paga, cancelada ou expirada. charges:cancel
POST `/v1/charges/:id/refund` Estorna (devolução Pix) uma cobrança paga. Apenas Pix — boleto e checkout retornam 422. Requer que o endToEndId do pagamento tenha sido capturado no recebimento. charges:refund

### Webhooks

Registre uma URL para receber notificações quando o status de cobranças mudar. Cada notificação inclui o header `x-signature` com assinatura HMAC-SHA256.

### Disparar evento de teste

Cole a URL do seu endpoint, escolha um evento e clique em enviar. O Comando1 fará o POST assinado direto para o seu servidor e mostrará a resposta aqui.

URL do seu endpoint *

Deve ser https://. URLs internas não são permitidas.

Evento
Secret HMAC

Use o mesmo secret configurado no seu servidor.

Payload `(charge)` {
"id": "chg_demo",
"provider": "inter",
"invoice_id": "inv_demo",
"customer_id": "cus_demo",
"amount": 250,
"method": "pix",
"status": "paid",
"status_raw": "DEMO"
}
Enviar evento de teste

### Validar assinatura (HMAC-SHA256)

Veja o corpo exato que o Comando1 enviaria e calcule a assinatura esperada — útil para validar seu código de verificação *antes* de configurar o endpoint.

Secret
Corpo raw — assine exatamente este JSON {"event":"charge.paid","charge":{"id":"chg_demo","provider":"inter","invoice_id":"inv_demo","customer_id":"cus_demo","amount":250,"method":"pix","status":"paid","status_raw":"DEMO"},"timestamp":"2026-09-11T02:19:42.564Z"}
Header `X-Signature` esperado `—`

Como verificar no seu servidor:

const expected = hmacSHA256(secret, rawBody)
const ok = timingSafeEqual(expected, req.headers["x-signature"])

PUT `/v1/webhooks/payments` Registra ou atualiza a URL de webhook. O secret HMAC é exibido apenas na criação — guarde-o imediatamente. webhooks:manage
GET `/v1/webhooks/payments` Retorna a configuração atual do webhook. O secret não é retornado. webhooks:manage
DELETE `/v1/webhooks/payments` Remove a configuração de webhook. webhooks:manage
GET `/v1/webhooks/deliveries` Log das entregas de webhook. Entregas com falha são reprocessadas automaticamente com backoff exponencial (até 6 tentativas). webhooks:manage
POST `/v1/webhooks/deliveries/:id/redeliver` Reenfileira uma entrega para nova tentativa imediata. webhooks:manage

Exemplo de payload recebido

JSON Copiar
`// POST para https://seu-sistema.com/webhooks/pagamento // Headers: // Content-Type: application/json // x-event: charge.paid // x-signature: { "event": "charge.paid", "charge": { "id": "a3d2f1e0-1234-5678-abcd-ef0123456789", "provider": "inter", "invoice_id": "inv-uuid", "status": "paid", "status_raw": "RECEBIDO" }, "timestamp": "2026-06-04T15:30:00.000Z" }`

Verificar assinatura (Node.js)

JS Copiar
`// Node.js — verificar assinatura HMAC-SHA256 import crypto from 'crypto'; app.post('/webhooks/pagamento', (req, res) => { const sig = req.headers['x-signature']; const payload = JSON.stringify(req.body); const expected = crypto .createHmac('sha256', process.env.WEBHOOK_SECRET) .update(payload) .digest('hex'); if (sig !== expected) return res.status(401).send('Assinatura inválida'); const { event, charge } = req.body; if (event === 'charge.paid') { // Pagamento confirmado — liberar serviço } res.sendStatus(200); });`

### Métodos de pagamento

Descubra quais formas de recebimento (Pix, boleto, checkout) estão ativas na empresa antes de criar uma cobrança.

GET `/v1/payment-methods` Lista as formas de recebimento configuradas, por provider e canal. charges:read

### Contas bancárias

Somente leitura. Dados sensíveis (agência, conta, chave Pix, documento do titular) são omitidos da API pública.

GET `/v1/bank-accounts` Lista as contas bancárias da empresa. bank_accounts:read
GET `/v1/bank-accounts/:id` Retorna uma conta bancária específica pelo ID. bank_accounts:read

### Caixa de Entrada

Somente leitura. Os e-mails que chegaram no endereço da empresa e os documentos (boleto, NF-e, guia) extraídos deles. A senha do PDF, o caminho no storage e o corpo completo do e-mail ficam fora da listagem — o corpo volta no detalhe da mensagem.

GET `/v1/inbox/messages` Lista as mensagens recebidas. inbox:read
GET `/v1/inbox/messages/:id` Detalhe da mensagem, com o corpo do e-mail e os veredictos de SPF/DKIM/DMARC. inbox:read
GET `/v1/inbox/documents` Lista os documentos extraídos dos e-mails. inbox:read
GET `/v1/inbox/documents/:id` Detalhe do documento extraído. inbox:read
PATCH `/v1/inbox/messages/:id/status` Reprocessa (`recebido`, limpando o erro anterior) ou arquiva (`ignorado`). Os demais estados do CHECK são escritos pelo processamento, não pelo cliente. inbox:update

### Conciliação bancária

Somente leitura. Lançamentos do extrato importado e os períodos de conciliação. O `raw_data` do banco fica fora: é payload cru, grande e sem uso para integração.

GET `/v1/reconciliation/entries` Lista os lançamentos do extrato. reconciliation:read
GET `/v1/reconciliation/entries/:id` Detalhe de um lançamento. reconciliation:read
GET `/v1/reconciliation/periods` Lista os períodos de conciliação. reconciliation:read
GET `/v1/reconciliation/periods/:id` Detalhe de um período. reconciliation:read
POST `/v1/reconciliation/entries/:id/resolve` Concilia o lançamento pela mesma rotina da tela. Ações: match_existing (vincula a um recebimento, pagamento a fornecedor, despesa ou repasse JÁ existente) e as que criam o contrapartida (create_expense, create_payment_from_customer_charge, create_supplier_payment_from_purchase_charge, create_financial_movement). Omitindo period_id, usa o período do lançamento ou o aberto da conta. Recusas específicas: período fechado, lançamento já conciliado, destino já conciliado, e a direção do dinheiro por ação. reconciliation:write
DELETE `/v1/reconciliation/matches/:id` Desfaz uma conciliação, pela mesma rotina que o botão da tela usa. reconciliation:write

### Faturas de cartão

Somente leitura. As faturas de cartão de crédito, com fechamento, vencimento, total e o boleto quando houver.

GET `/v1/card-statements` Lista as faturas de cartão. cards:read
GET `/v1/card-statements/:id` Detalhe de uma fatura de cartão. cards:read

### DDA

Somente leitura. Boletos que o banco avisou por DDA, com o status de casamento com uma conta a pagar.

GET `/v1/dda-boletos` Lista os boletos do DDA. dda:read
GET `/v1/dda-boletos/:id` Detalhe de um boleto do DDA. dda:read
POST `/v1/dda-boletos/:id/triage` `ignore` arquiva (com nota opcional); `reopen` devolve à fila. Boleto que já virou conta a pagar é recusado com 409. As ações que criam ou vinculam documento ficam no aplicativo: registram quem fez, e uma chave de API não tem usuário. dda:triage

### Recorrentes

Somente leitura. As REGRAS que geram despesas e contas a pagar recorrentes — não os documentos gerados, que ficam em /v1/expenses e /v1/purchase-invoices.

GET `/v1/recurring-expenses` Lista as regras de despesa recorrente. recurring:read
GET `/v1/recurring-expenses/:id` Detalhe de uma regra de despesa recorrente. recurring:read
GET `/v1/recurring-purchase-invoices` Lista as regras de conta a pagar recorrente. recurring:read
GET `/v1/recurring-purchase-invoices/:id` Detalhe de uma regra de conta a pagar recorrente. recurring:read
PATCH `/v1/recurring-expenses/:id/status` Pausa ou retoma a regra. Só `ativo` ↔ `pausado`: regra finalizada é terminal e reativá-la ressuscitaria um ciclo encerrado — crie uma nova. Repetir o status atual não grava nada. recurring:update
PATCH `/v1/recurring-purchase-invoices/:id/status` Mesma regra para as contas a pagar recorrentes. recurring:update

### Insumos

Somente leitura. O catálogo de insumos da empresa.

GET `/v1/insumos` Lista os insumos. insumos:read
GET `/v1/insumos/:id` Detalhe de um insumo. insumos:read
POST `/v1/insumos` Cria um insumo. `name` é obrigatório. insumos:write
PATCH `/v1/insumos/:id` Edita os campos enviados. insumos:write
DELETE `/v1/insumos/:id` Exclui. Scope próprio, separado do de escrita. insumos:delete

### Notificações

Somente leitura. As notificações geradas para os usuários da empresa.

GET `/v1/notifications` Lista as notificações. notifications:read
GET `/v1/notifications/:id` Detalhe de uma notificação. notifications:read
PATCH `/v1/notifications/:id/read` Marca como lida. Enviar `read: false` no corpo marca como NÃO lida. notifications:update

### Pagamentos a Fornecedor

Pague ou agende Pix e boleto a fornecedores. O banco é escolhido pela integração ativa (Inter ou C6) ou pelo campo `provider`.

POST `/v1/payouts` Executa ou agenda um pagamento. Informe o alvo via purchase_invoice_charge_id (quita a parcela), supplier_payment_method_id, pix_key/pix_copia_e_cola ou boleto_barcode. Para agendar, envie scheduled_for. payouts:create
GET `/v1/payouts` Lista os pagamentos a fornecedores. payouts:read
GET `/v1/payouts/:id` Retorna um pagamento específico pelo ID. payouts:read
POST `/v1/payouts/:id/cancel` Cancela um pagamento agendado. Pix agendado no Inter não é cancelável pela API (422) — cancele no Internet Banking e use /sync. payouts:cancel
POST `/v1/payouts/:id/sync` Reconcilia o status do pagamento com o banco (útil para agendamentos e confirmações assíncronas). payouts:read

### Split de Pagamentos

Divida automaticamente cada recebimento entre a empresa e seus fornecedores. Defina uma regra com beneficiários (percentual, fixo ou combinado); ao confirmar o recebimento, o sistema calcula as fatias e repassa via Pix. Eventos: `split.calculated`, `repasse.released`, `repasse.paid`, `repasse.failed`, `repasse.reversed`.

POST `/v1/split-rules` Cria uma regra de divisão com seus beneficiários (recipients). Aplica-se o percentual sobre o bruto e depois soma o fixo; a soma dos percentuais não pode passar de 100%. split:create
GET `/v1/split-rules` Lista as regras de split. Filtre por scope. split:list
PATCH `/v1/split-rules/:id` Atualiza a regra. Se 'recipients' for enviado, substitui todos os beneficiários. split:update
DELETE `/v1/split-rules/:id` Remove a regra de split. split:delete
GET `/v1/split-executions` Lista as execuções de split (uma por cobrança recebida) com suas fatias. Filtre por status, invoice_id ou supplier_id. split:list
GET `/v1/split-executions/:id` Retorna uma execução com suas fatias (itens). split:list
POST `/v1/split-executions/:id/reverse` Estorna a execução: marca a execução e suas fatias como 'reversed'. Para cada fatia de fornecedor já paga, registra um ajuste de recuperação (o fornecedor deve devolver o valor). split:update
POST `/v1/split-items/:id/release` Libera manualmente uma fatia (pending/awaiting_nota/failed → released), apta a virar payout. split:update

### Formas de pagamento do fornecedor

Cadastre onde/como pagar cada fornecedor (Pix, transferência, boleto). Usado por `supplier_payment_method_id` nos payouts.

GET `/v1/suppliers/:id/payment-methods` Lista as formas de pagamento cadastradas de um fornecedor. suppliers:read
POST `/v1/suppliers/:id/payment-methods` Cadastra uma forma de pagamento. Para type pix, pix_key é obrigatório. suppliers:write
PATCH `/v1/suppliers/:id/payment-methods/:methodId` Atualiza parcialmente uma forma de pagamento. suppliers:write
DELETE `/v1/suppliers/:id/payment-methods/:methodId` Exclui uma forma de pagamento. Retorna 204 sem corpo. suppliers:delete

## Rate Limiting

A API limita o número de requisições por chave por minuto para garantir estabilidade do serviço. O limite padrão é **60 requisições/minuto** por chave de API.

Limite padrão

60 req/min

Quando excedido

429 Too Many Requests

Resposta quando o limite é excedido

{
"error": "Rate limit excedido: 60 requisições por minuto. Tente novamente em 34 segundos."
}

• O contador é por chave de API e reinicia a cada minuto completo.

• O limite pode variar por chave — entidades com necessidade maior podem solicitar aumento em [contato@comando.one](mailto:contato@comando.one).

• Implemente *exponential backoff* ao receber 429: aguarde e refaça a requisição após alguns segundos.

Pronto para integrar?

Acesse a plataforma, crie sua chave e comece a integrar em minutos.

[Criar chave de API →](https://comando.one/login)