@comando.one/sdk

SDK oficial da API pública do Comando.One — ERP para empresas de serviço (clientes, propostas, contratos, faturas, cobranças Pix/boleto, NFS-e, contas a pagar, financeiro e webhooks).

• Zero dependências — usa fetch nativo. Funciona no Node 18+ e no navegador.
• Tipado — TypeScript com autocomplete em todos os recursos.
• Multi-empresa, paginação automática e idempotência embutidos.

Instalação

npm install @comando.one/sdk

Uso

import { ComandoApi } from "@comando.one/sdk";

const api = new ComandoApi({ apiKey: "cmd_live_..." });

// Identidade
const me = await api.me();

// Listar e paginar
const page = await api.customers.list({ status: "ativo", per_page: 50 });
const todos = await api.customers.listAll();          // pagina sozinho

// Criar
const cliente = await api.customers.create({ name: "ACME", type: "juridica" });
const fatura = await api.invoices.create({
  customer_id: cliente.id,
  title: "Mensalidade",
  due_date: "2026-07-01",
  items: [{ name: "Serviço", quantity: 1, unit_price: 250 }],
});

// Cobrança Pix
const cobranca = await api.charges.create({ invoice_id: fatura.id, method: "pix" });

// Multi-empresa
const filial = api.withCompany("uuid-da-empresa");
await filial.customers.list();

// Idempotência automática em POSTs
const apiIdem = new ComandoApi({ apiKey: "cmd_live_...", autoIdempotency: true });

Tratamento de erros

import { ComandoApi, ComandoApiError } from "@comando.one/sdk";

try {
  await api.customers.get("inexistente");
} catch (err) {
  if (err instanceof ComandoApiError) {
    console.error(err.status, err.body); // ex.: 404 { error: "..." }
  }
}

Recursos disponíveis

companies, customers (+ addresses, contacts, invoices, contracts, proposals), suppliers (+ paymentMethods), services, expenses, proposals (+ send), contracts, invoices (+ cancel), purchaseInvoices (+ cancel), charges (+ cancel/refund/confirm), payouts (+ cancel/sync), nfse (+ emit/cancel), finance (ledger/natures/createMovement/deleteMovement), lookups, bankAccounts, webhooks (+ deliveries).

Para endpoints não cobertos pelos namespaces, use api.request(method, path, opts).

Licença

MIT