Nesta página

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) Abrir no Swagger Editor

Início rápido

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

Crie uma chave de API

Acesse Configurações → API Keys dentro da plataforma e crie uma chave com as permissões desejadas.

Guarde em local seguro

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

Primeira chamada

cURL

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

Resposta JSON

{
  "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

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

Opção B — x-api-key

cURL

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/sdk

Client TypeScript/ESM, zero dependências. Todos os recursos da API com tipagem, paginação automática e idempotência. Browser + Node 18+.

@comando.one/mcp-server

Servidor MCP (stdio) para conectar agentes de IA (Claude, etc.) ao seu ERP. 169 ferramentas curadas com guardas de segurança.

Instalação do SDK

bash

npm install @comando.one/sdk

Uso

TypeScript

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 GitHub

Aplicaçõ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.

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

{
  "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

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

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

💬 Chatbot de exemplo

Um 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.

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

{ "error": "API key inválida." }

Scope insuficiente (403)

JSON

{ "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

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

(qualquer chave válida)

Requisição

cURL

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

Resposta — 200 OK

JSON

{
  "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.

Clientes

Fornecedores

Serviços

Despesas

Contas a Pagar

Propostas

Contratos

Faturas / Cobranças

Financeiro

Relatórios, Auditoria & Categorias

NFS-e

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.

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

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)

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"])

Exemplo de payload recebido

JSON

// POST para https://seu-sistema.com/webhooks/pagamento
// Headers:
//   Content-Type: application/json
//   x-event: charge.paid
//   x-signature: <hmac-sha256 do payload com seu secret>

{
  "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)

// 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.

Contas bancárias

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

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.

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.

Faturas de cartão

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

DDA

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

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.

Insumos

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

Notificações

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

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.

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.

Formas de pagamento do fornecedor

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

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.

• 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 →