@comando.one/mcp-server 0.1.0

package/dist/index.js

@@ -0,0 +1,2901 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync } from "fs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+// src/comando-api.ts
+var ComandoApiError = class extends Error {
+  status;
+  body;
+  constructor(status, body, method, path) {
+    const errMsg = body && typeof body === "object" && "error" in body ? String(body.error) : JSON.stringify(body);
+    super(`${method} ${path} \u2192 ${status}: ${errMsg}`);
+    this.name = "ComandoApiError";
+    this.status = status;
+    this.body = body;
+  }
+};
+function qs(params) {
+  if (!params) return "";
+  const u = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== void 0 && v !== null && v !== "") u.set(k, String(v));
+  }
+  const s = u.toString();
+  return s ? `?${s}` : "";
+}
+var _autoCounter = 0;
+function genIdemKey() {
+  try {
+    return `auto-${crypto.randomUUID()}`;
+  } catch {
+    return `auto-${Date.now()}-${_autoCounter++}`;
+  }
+}
+var ComandoApi = class _ComandoApi {
+  apiKey;
+  baseUrl;
+  companyId;
+  autoIdempotency;
+  constructor({ apiKey, baseUrl = "https://api.comando.one/v1", companyId, autoIdempotency = false }) {
+    if (!apiKey) throw new Error("apiKey \xE9 obrigat\xF3rio (cmd_live_...).");
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.companyId = companyId || null;
+    this.autoIdempotency = autoIdempotency;
+  }
+  /** Clona o client fixando uma empresa (header X-Company-Id). */
+  withCompany(companyId) {
+    return new _ComandoApi({
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl,
+      companyId,
+      autoIdempotency: this.autoIdempotency
+    });
+  }
+  async request(method, path, opts = {}) {
+    const headers = {
+      "x-api-key": this.apiKey,
+      "Content-Type": "application/json"
+    };
+    const company = opts.companyId ?? this.companyId;
+    if (company) headers["X-Company-Id"] = company;
+    let idem = opts.idempotencyKey;
+    if (!idem && this.autoIdempotency && method === "POST") idem = genIdemKey();
+    if (idem) headers["Idempotency-Key"] = idem;
+    const init = { method, headers };
+    if (opts.body !== void 0) init.body = JSON.stringify(opts.body);
+    const res = await fetch(`${this.baseUrl}${path}`, init);
+    const text = await res.text();
+    let body = null;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = { raw: text };
+    }
+    if (opts.raw) {
+      return { status: res.status, body, replayed: res.headers.get("idempotent-replayed") === "true" };
+    }
+    if (!res.ok) throw new ComandoApiError(res.status, body, method, path);
+    return body;
+  }
+  get(path, opts) {
+    return this.request("GET", path, opts);
+  }
+  post(path, body, opts) {
+    return this.request("POST", path, { ...opts, body });
+  }
+  patch(path, body, opts) {
+    return this.request("PATCH", path, { ...opts, body });
+  }
+  delete(path, opts) {
+    return this.request("DELETE", path, opts);
+  }
+  /** Paginação automática: itera ?page= até cobrir meta.total. Retorna array achatado. */
+  async listAll(path, params = {}, opts) {
+    const perPage = params.per_page ?? 100;
+    let page = 1;
+    let all = [];
+    let total = Infinity;
+    while (all.length < total) {
+      const r = await this.get(`${path}${qs({ ...params, page, per_page: perPage })}`, opts);
+      const data = r.data ?? [];
+      all = all.concat(data);
+      total = r.meta?.total ?? all.length;
+      if (data.length === 0) break;
+      page++;
+      if (page > 1e3) break;
+    }
+    return all;
+  }
+  me(opts) {
+    return this.get("/me", opts);
+  }
+};
+
+// src/manifest.ts
+var MANIFEST = [
+  // ----- Identidade -----
+  { operationId: "listCompanies", tool: "companies_list" },
+  // ----- Clientes -----
+  { operationId: "listCustomers", tool: "customers_list" },
+  { operationId: "getCustomer", tool: "customers_get" },
+  { operationId: "createCustomer", tool: "customers_create", write: true },
+  { operationId: "updateCustomer", tool: "customers_update", write: true },
+  { operationId: "deleteCustomer", tool: "customers_delete", write: true, destructive: true },
+  { operationId: "listCustomerInvoices", tool: "customers_list_invoices" },
+  { operationId: "createCustomerAddress", tool: "customers_add_address", write: true },
+  { operationId: "createCustomerContact", tool: "customers_add_contact", write: true },
+  // ----- Propostas -----
+  { operationId: "listProposals", tool: "proposals_list" },
+  { operationId: "getProposal", tool: "proposals_get" },
+  { operationId: "createProposal", tool: "proposals_create", write: true },
+  { operationId: "sendProposal", tool: "proposals_send", write: true },
+  // ----- Contratos -----
+  { operationId: "listContracts", tool: "contracts_list" },
+  { operationId: "getContract", tool: "contracts_get" },
+  { operationId: "createContract", tool: "contracts_create", write: true },
+  // ----- Faturas -----
+  { operationId: "listInvoices", tool: "invoices_list" },
+  { operationId: "getInvoice", tool: "invoices_get" },
+  { operationId: "createInvoice", tool: "invoices_create", write: true },
+  { operationId: "cancelInvoice", tool: "invoices_cancel", write: true, destructive: true },
+  // ----- Cobranças -----
+  { operationId: "listCharges", tool: "charges_list" },
+  { operationId: "getCharge", tool: "charges_get" },
+  { operationId: "createCharge", tool: "charges_create", write: true },
+  { operationId: "confirmCharge", tool: "charges_confirm", write: true },
+  { operationId: "cancelCharge", tool: "charges_cancel", write: true, destructive: true },
+  { operationId: "refundCharge", tool: "charges_refund", write: true, destructive: true },
+  // ----- NFS-e -----
+  { operationId: "listNfse", tool: "nfse_list" },
+  { operationId: "getNfse", tool: "nfse_get" },
+  { operationId: "emitNfse", tool: "nfse_emit", write: true },
+  { operationId: "cancelNfse", tool: "nfse_cancel", write: true, destructive: true },
+  // ----- Pagamentos a fornecedor (payouts) -----
+  { operationId: "listPayouts", tool: "payouts_list" },
+  { operationId: "getPayout", tool: "payouts_get" },
+  { operationId: "createPayout", tool: "payouts_create", write: true, destructive: true },
+  { operationId: "cancelPayout", tool: "payouts_cancel", write: true, destructive: true },
+  // ----- Financeiro -----
+  { operationId: "getFinanceLedger", tool: "finance_ledger" },
+  { operationId: "createFinancialMovement", tool: "finance_create_movement", write: true },
+  // ----- Fornecedores -----
+  { operationId: "listSuppliers", tool: "suppliers_list" },
+  { operationId: "getSupplier", tool: "suppliers_get" },
+  { operationId: "createSupplier", tool: "suppliers_create", write: true },
+  // ----- Contas a pagar -----
+  { operationId: "listPurchaseInvoices", tool: "purchase_invoices_list" },
+  { operationId: "getPurchaseInvoice", tool: "purchase_invoices_get" },
+  { operationId: "createPurchaseInvoice", tool: "purchase_invoices_create", write: true },
+  { operationId: "cancelPurchaseInvoice", tool: "purchase_invoices_cancel", write: true, destructive: true },
+  // ----- Despesas & Serviços -----
+  { operationId: "listExpenses", tool: "expenses_list" },
+  { operationId: "createExpense", tool: "expenses_create", write: true },
+  { operationId: "listServices", tool: "services_list" },
+  { operationId: "createService", tool: "services_create", write: true },
+  // ----- Webhooks -----
+  { operationId: "listWebhooks", tool: "webhooks_list" },
+  { operationId: "getWebhookById", tool: "webhooks_get" },
+  { operationId: "createWebhook", tool: "webhooks_create", write: true }
+];
+
+// ../../src/lib/openApiSpec.ts
+var PAGINATION_PARAMS = [
+  {
+    name: "page",
+    in: "query",
+    schema: { type: "integer", default: 1, minimum: 1 },
+    description: "N\xFAmero da p\xE1gina (default: 1)"
+  },
+  {
+    name: "per_page",
+    in: "query",
+    schema: { type: "integer", default: 20, minimum: 1, maximum: 100 },
+    description: "Itens por p\xE1gina (default: 20, m\xE1x: 100)"
+  }
+];
+var API_KEY_SECURITY = [{ ApiKeyAuth: [] }];
+var WEBHOOK_EVENT_KEYS = [
+  "charge.paid",
+  "charge.cancelled",
+  "charge.expired",
+  "charge.failed",
+  "charge.refunded",
+  "payout.completed",
+  "payout.failed",
+  "payout.scheduled",
+  "payout.cancelled",
+  "invoice.created",
+  "invoice.paid",
+  "invoice.cancelled",
+  "proposal.created",
+  "proposal.sent",
+  "proposal.accepted",
+  "proposal.rejected",
+  "contract.created",
+  "contract.cancelled",
+  "contract.finished",
+  "nfse.issued",
+  "nfse.rejected",
+  "nfse.cancelled",
+  "purchase_invoice.created",
+  "purchase_invoice.paid",
+  "expense.paid",
+  "customer.created",
+  "customer.updated",
+  "customer.deleted",
+  "supplier.created",
+  "supplier.updated",
+  "supplier.deleted"
+];
+var SCHEMAS = {
+  Error: {
+    type: "object",
+    required: ["error"],
+    properties: {
+      error: { type: "string", description: "Descri\xE7\xE3o do erro" }
+    }
+  },
+  PaginatedMeta: {
+    type: "object",
+    required: ["page", "per_page", "total"],
+    properties: {
+      page: { type: "integer", description: "P\xE1gina atual" },
+      per_page: { type: "integer", description: "Itens por p\xE1gina" },
+      total: { type: "integer", description: "Total de itens" }
+    }
+  },
+  Customer: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      email: { type: ["string", "null"] },
+      phone: { type: ["string", "null"] },
+      document: { type: ["string", "null"], description: "CPF ou CNPJ" },
+      type: { type: "string", enum: ["fisica", "juridica", "estrangeira"] },
+      company_name: { type: ["string", "null"] },
+      trade_name: { type: ["string", "null"] },
+      status: { type: "string" },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  CustomerCreate: {
+    type: "object",
+    required: ["name"],
+    properties: {
+      name: { type: "string" },
+      email: { type: "string" },
+      phone: { type: "string" },
+      document: { type: "string" },
+      type: { type: "string", enum: ["fisica", "juridica", "estrangeira"], default: "fisica" },
+      company_name: { type: "string" },
+      trade_name: { type: "string" },
+      status: { type: "string", default: "ativo" }
+    }
+  },
+  CustomerUpdate: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      email: { type: ["string", "null"] },
+      phone: { type: ["string", "null"] },
+      document: { type: ["string", "null"] },
+      type: { type: "string", enum: ["fisica", "juridica", "estrangeira"] },
+      company_name: { type: ["string", "null"] },
+      trade_name: { type: ["string", "null"] },
+      status: { type: "string" }
+    }
+  },
+  ProposalItem: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      description: { type: ["string", "null"] },
+      unit: { type: ["string", "null"] },
+      quantity: { type: "number" },
+      unit_price: { type: "number" },
+      subtotal: { type: "number" }
+    }
+  },
+  Proposal: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      customer_id: { type: "string", format: "uuid" },
+      customers: { type: "object", properties: { name: { type: "string" } } },
+      status: { type: "string", enum: ["rascunho", "enviada", "aceita", "recusada", "cancelada", "faturada"] },
+      total_amount: { type: "number" },
+      valid_until: { type: ["string", "null"], format: "date" },
+      notes: { type: ["string", "null"] },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  ProposalDetail: {
+    allOf: [
+      { $ref: "#/components/schemas/Proposal" },
+      {
+        type: "object",
+        properties: {
+          proposal_items: { type: "array", items: { $ref: "#/components/schemas/ProposalItem" } }
+        }
+      }
+    ]
+  },
+  ContractItem: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      description: { type: ["string", "null"] },
+      unit: { type: ["string", "null"] },
+      quantity: { type: "number" },
+      unit_price: { type: "number" },
+      subtotal: { type: "number" }
+    }
+  },
+  ContractSection: {
+    type: "object",
+    properties: {
+      title: { type: "string" },
+      content: { type: "string" }
+    }
+  },
+  Contract: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      customer_id: { type: "string", format: "uuid" },
+      customers: { type: "object", properties: { name: { type: "string" } } },
+      title: { type: ["string", "null"] },
+      status: { type: "string", enum: ["ativo", "suspenso", "cancelado", "finalizado"] },
+      frequency: { type: "string", enum: ["semanal", "quinzenal", "mensal", "bimestral", "trimestral", "semestral", "anual"] },
+      start_date: { type: "string", format: "date" },
+      end_date: { type: ["string", "null"], format: "date" },
+      amount: { type: "number" },
+      due_days: { type: "integer" },
+      next_generation_date: { type: ["string", "null"], format: "date" },
+      notes: { type: ["string", "null"] },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  ContractDetail: {
+    allOf: [
+      { $ref: "#/components/schemas/Contract" },
+      {
+        type: "object",
+        properties: {
+          contract_items: { type: "array", items: { $ref: "#/components/schemas/ContractItem" } },
+          contract_sections: { type: ["array", "null"], items: { $ref: "#/components/schemas/ContractSection" } }
+        }
+      }
+    ]
+  },
+  ProposalCreate: {
+    type: "object",
+    required: ["customer_id"],
+    properties: {
+      customer_id: { type: "string", format: "uuid" },
+      status: { type: "string", enum: ["rascunho", "enviada", "aceita", "recusada", "cancelada"], default: "rascunho" },
+      total_amount: { type: "number" },
+      valid_until: { type: "string", format: "date" },
+      notes: { type: "string" }
+    }
+  },
+  ContractCreate: {
+    type: "object",
+    required: ["customer_id"],
+    properties: {
+      customer_id: { type: "string", format: "uuid" },
+      title: { type: "string" },
+      status: { type: "string", enum: ["ativo", "suspenso", "cancelado", "finalizado"], default: "ativo" },
+      frequency: { type: "string", enum: ["semanal", "quinzenal", "mensal", "bimestral", "trimestral", "semestral", "anual"], default: "mensal" },
+      start_date: { type: "string", format: "date" },
+      end_date: { type: "string", format: "date" },
+      due_days: { type: "integer", default: 10 },
+      amount: { type: "number" },
+      payment_method_id: { type: "string", format: "uuid" },
+      notes: { type: "string" }
+    }
+  },
+  InvoiceItem: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      service_id: { type: ["string", "null"], format: "uuid", description: "Servi\xE7o vinculado (null se item avulso)." },
+      name: { type: "string" },
+      description: { type: ["string", "null"] },
+      unit: { type: ["string", "null"] },
+      quantity: { type: "number" },
+      unit_price: { type: "number" },
+      subtotal: { type: "number" },
+      is_manual: { type: "boolean", description: "true = item avulso; false = vindo de um servi\xE7o cadastrado." }
+    }
+  },
+  InvoiceCharge: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      due_date: { type: "string", format: "date" },
+      amount: { type: "number" },
+      payment_status: { type: "string" }
+    }
+  },
+  Invoice: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      customer_id: { type: "string", format: "uuid" },
+      customers: { type: "object", properties: { name: { type: "string" }, legal_name: { type: ["string", "null"] } } },
+      invoice_number: { type: ["string", "null"] },
+      title: { type: ["string", "null"] },
+      amount: { type: "number" },
+      status: { type: "string", enum: ["rascunho", "enviada", "aceita", "cancelada"] },
+      payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] },
+      due_date: { type: ["string", "null"], format: "date" },
+      proposal_id: { type: ["string", "null"], format: "uuid" },
+      contract_id: { type: ["string", "null"], format: "uuid" },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  InvoiceDetail: {
+    allOf: [
+      { $ref: "#/components/schemas/Invoice" },
+      {
+        type: "object",
+        properties: {
+          invoice_items: { type: "array", items: { $ref: "#/components/schemas/InvoiceItem" } },
+          invoice_charges: { type: "array", items: { $ref: "#/components/schemas/InvoiceCharge" } }
+        }
+      }
+    ]
+  },
+  FinanceLedgerEntry: {
+    type: "object",
+    properties: {
+      origin_id: { type: "string", format: "uuid" },
+      origin: { type: "string", enum: ["payment", "supplier_payment", "expense", "financial_movement"] },
+      direction: { type: "string", enum: ["entrada", "saida"] },
+      entry_date: { type: "string", format: "date" },
+      amount: { type: "number" },
+      signed_amount: { type: "number" },
+      counterparty_name: { type: ["string", "null"] },
+      description: { type: ["string", "null"] },
+      document_numbers: { type: ["string", "null"] },
+      bank_account_name: { type: ["string", "null"] },
+      payment_method_name: { type: ["string", "null"] },
+      created_at: { type: "string", format: "date-time" }
+    }
+  },
+  NfseHistory: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      invoice_id: { type: "string", format: "uuid" },
+      invoice_number: { type: ["string", "null"] },
+      numero_nfse: { type: ["string", "null"] },
+      status: { type: "string", enum: ["rascunho", "transmitindo", "autorizada", "rejeitada", "cancelada"] },
+      protocolo: { type: ["string", "null"] },
+      chave_acesso: { type: ["string", "null"] },
+      danfse_url: { type: ["string", "null"] },
+      artifact_source: { type: ["string", "null"] },
+      cancelada_at: { type: ["string", "null"], format: "date-time" },
+      created_at: { type: "string", format: "date-time" }
+    }
+  },
+  NfseHistoryDetail: {
+    allOf: [
+      { $ref: "#/components/schemas/NfseHistory" },
+      {
+        type: "object",
+        properties: {
+          cancel_motivo: { type: ["integer", "null"] },
+          cancel_justificativa: { type: ["string", "null"] },
+          cancel_protocolo: { type: ["string", "null"] },
+          updated_at: { type: "string", format: "date-time" }
+        }
+      }
+    ]
+  },
+  Supplier: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      email: { type: ["string", "null"] },
+      phone: { type: ["string", "null"] },
+      document: { type: ["string", "null"], description: "CPF ou CNPJ" },
+      type: { type: "string", enum: ["fisica", "juridica", "estrangeira"] },
+      company_name: { type: ["string", "null"] },
+      trade_name: { type: ["string", "null"] },
+      state_registration: { type: ["string", "null"] },
+      municipal_registration: { type: ["string", "null"] },
+      payment_terms_label: { type: ["string", "null"] },
+      payment_terms_days: { type: ["integer", "null"] },
+      status: { type: "string", enum: ["ativo", "inativo"] },
+      notes: { type: ["string", "null"] },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  SupplierCreate: {
+    type: "object",
+    required: ["name"],
+    properties: {
+      name: { type: "string" },
+      email: { type: "string" },
+      phone: { type: "string" },
+      document: { type: "string" },
+      type: { type: "string", enum: ["fisica", "juridica", "estrangeira"], default: "juridica" },
+      company_name: { type: "string" },
+      trade_name: { type: "string" },
+      state_registration: { type: "string" },
+      municipal_registration: { type: "string" },
+      payment_terms_label: { type: "string" },
+      payment_terms_days: { type: "integer" },
+      status: { type: "string", enum: ["ativo", "inativo"], default: "ativo" },
+      notes: { type: "string" }
+    }
+  },
+  Service: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      description: { type: ["string", "null"] },
+      price: { type: "number" },
+      unit: { type: "string", description: "Unidade (texto livre, ex: hora, unidade, mensal)" },
+      item_type: { type: "string", enum: ["venda", "compra", "ambos"] },
+      categories: { type: "array", items: { type: "string" } },
+      active: { type: "boolean" },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  ServiceCreate: {
+    type: "object",
+    required: ["name", "price"],
+    properties: {
+      name: { type: "string" },
+      description: { type: "string" },
+      price: { type: "number" },
+      unit: { type: "string", default: "hora" },
+      item_type: { type: "string", enum: ["venda", "compra", "ambos"], default: "venda" },
+      categories: { type: "array", items: { type: "string" } },
+      active: { type: "boolean", default: true }
+    }
+  },
+  Expense: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      supplier_id: { type: "string", format: "uuid" },
+      description: { type: "string" },
+      amount: { type: "number" },
+      expense_date: { type: "string", format: "date" },
+      payment_date: { type: ["string", "null"], format: "date" },
+      category_id: { type: ["string", "null"], format: "uuid" },
+      status: { type: "string", enum: ["pendente", "pago", "cancelado"] },
+      bank_account_id: { type: ["string", "null"], format: "uuid" },
+      payment_method_id: { type: ["string", "null"], format: "uuid" },
+      notes: { type: ["string", "null"] },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  ExpenseCreate: {
+    type: "object",
+    required: ["supplier_id", "description", "amount", "expense_date"],
+    properties: {
+      supplier_id: { type: "string", format: "uuid" },
+      description: { type: "string" },
+      amount: { type: "number" },
+      expense_date: { type: "string", format: "date" },
+      payment_date: { type: "string", format: "date" },
+      category_id: { type: "string", format: "uuid" },
+      status: { type: "string", enum: ["pendente", "pago", "cancelado"], default: "pendente" },
+      bank_account_id: { type: "string", format: "uuid" },
+      payment_method_id: { type: "string", format: "uuid" },
+      notes: { type: "string" }
+    }
+  },
+  PurchaseInvoice: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      supplier_id: { type: "string", format: "uuid" },
+      status: { type: "string", enum: ["rascunho", "recebida", "aprovada", "cancelada"] },
+      payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] },
+      invoice_number: { type: ["string", "null"] },
+      amount: { type: "number" },
+      issue_date: { type: ["string", "null"], format: "date" },
+      notes: { type: ["string", "null"] },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" },
+      purchase_invoice_charges: {
+        type: "array",
+        description: "Parcelas a pagar (o vencimento mora aqui, n\xE3o na fatura).",
+        items: {
+          type: "object",
+          properties: {
+            id: { type: "string", format: "uuid" },
+            sequence: { type: "integer" },
+            description: { type: "string" },
+            amount: { type: "number" },
+            due_date: { type: "string", format: "date" },
+            payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] }
+          }
+        }
+      }
+    }
+  },
+  PurchaseInvoiceCreate: {
+    type: "object",
+    required: ["supplier_id"],
+    properties: {
+      supplier_id: { type: "string", format: "uuid" },
+      status: { type: "string", enum: ["rascunho", "recebida", "aprovada", "cancelada"], default: "recebida" },
+      payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"], default: "pendente" },
+      invoice_number: { type: "string" },
+      amount: { type: "number" },
+      issue_date: { type: "string", format: "date" },
+      due_date: { type: "string", format: "date", description: "Atalho: cria uma \xFAnica parcela com este vencimento e o valor de 'amount'. Ignorado se 'charges' for informado." },
+      charges: {
+        type: "array",
+        description: "Parcelas a pagar. Cada uma exige 'due_date'.",
+        items: {
+          type: "object",
+          required: ["due_date"],
+          properties: {
+            sequence: { type: "integer" },
+            description: { type: "string" },
+            amount: { type: "number" },
+            due_date: { type: "string", format: "date" },
+            payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"], default: "pendente" }
+          }
+        }
+      },
+      notes: { type: "string" }
+    }
+  },
+  Charge: {
+    type: "object",
+    description: "Cobran\xE7a normalizada (independente do provider).",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      status: { type: "string", enum: ["pending", "paid", "cancelled", "expired", "failed"] },
+      status_raw: { type: "string", description: "Status bruto do provider" },
+      method: { type: "string", enum: ["pix", "boleto", "checkout"] },
+      provider: { type: "string", enum: ["inter", "c6bank", "pix_offline"], description: "Provedor resolvido. 'pix_offline' = Pix est\xE1tico (BR Code gerado localmente, sem API banc\xE1ria)." },
+      invoice_id: { type: ["string", "null"], format: "uuid" },
+      customer_id: { type: ["string", "null"], format: "uuid" },
+      amount: { type: ["number", "null"] },
+      due_date: { type: ["string", "null"], format: "date" },
+      pix: { type: ["object", "null"], properties: { qr_code: { type: ["string", "null"] }, qr_url: { type: ["string", "null"] }, txid: { type: ["string", "null"] } } },
+      boleto: { type: ["object", "null"], properties: { digitable_line: { type: ["string", "null"] }, pdf_url: { type: ["string", "null"] } } },
+      checkout: { type: ["object", "null"], properties: { url: { type: ["string", "null"] } } },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  ChargeCreate: {
+    type: "object",
+    required: ["method"],
+    properties: {
+      method: { type: "string", enum: ["pix", "boleto", "checkout"], description: "Canal de pagamento" },
+      invoice_id: { type: "string", format: "uuid", description: "Fatura existente (opcional)" },
+      customer_id: { type: "string", format: "uuid", description: "Obrigat\xF3rio se invoice_id omitido" },
+      amount: { type: "number", description: "Obrigat\xF3rio se invoice_id omitido" },
+      due_date: { type: "string", format: "date", description: "Obrigat\xF3rio se invoice_id omitido" },
+      description: { type: "string" }
+    }
+  },
+  Webhook: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: ["string", "null"], description: "R\xF3tulo opcional do webhook" },
+      url: { type: "string", format: "uri" },
+      events: { type: "array", items: { type: "string", enum: WEBHOOK_EVENT_KEYS } },
+      active: { type: "boolean" },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  WebhookCreate: {
+    type: "object",
+    required: ["url"],
+    properties: {
+      name: { type: "string", description: "R\xF3tulo opcional" },
+      url: { type: "string", format: "uri", description: "Deve come\xE7ar com https://" },
+      events: { type: "array", items: { type: "string", enum: WEBHOOK_EVENT_KEYS }, description: "Eventos assinados (default: charge.paid, charge.cancelled, charge.expired)" },
+      active: { type: "boolean", default: true }
+    }
+  },
+  BankAccount: {
+    type: "object",
+    description: "Conta banc\xE1ria (campos sens\xEDveis como ag\xEAncia, conta, chave Pix e documento do titular s\xE3o omitidos da API p\xFAblica).",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      bank_name: { type: "string" },
+      bank_code: { type: ["string", "null"] },
+      account_type: { type: ["string", "null"] },
+      is_primary: { type: "boolean" },
+      active: { type: "boolean" },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  Payout: {
+    type: "object",
+    description: "Pagamento a fornecedor normalizado (independente do banco).",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      status: { type: "string", enum: ["pending", "processing", "completed", "failed", "cancelled"] },
+      provider: { type: "string", enum: ["inter", "c6bank"] },
+      method: { type: "string", enum: ["pix", "boleto"] },
+      amount: { type: "number" },
+      scheduled_for: { type: ["string", "null"], format: "date" },
+      bank_account_id: { type: "string", format: "uuid" },
+      purchase_invoice_charge_id: { type: ["string", "null"], format: "uuid" },
+      supplier_payment_method_id: { type: ["string", "null"], format: "uuid" },
+      provider_reference: { type: ["string", "null"], description: "codigoSolicitacao (Inter) ou group_id (C6)" },
+      error_message: { type: ["string", "null"] },
+      executed_at: { type: ["string", "null"], format: "date-time" },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  PayoutCreate: {
+    type: "object",
+    required: ["bank_account_id", "method"],
+    properties: {
+      bank_account_id: { type: "string", format: "uuid", description: "Conta banc\xE1ria de origem" },
+      method: { type: "string", enum: ["pix", "boleto"] },
+      provider: { type: "string", enum: ["inter", "c6bank"], description: "Opcional \u2014 detectado se houver uma \xFAnica integra\xE7\xE3o ativa" },
+      amount: { type: "number", description: "Obrigat\xF3rio se n\xE3o vier de purchase_invoice_charge_id" },
+      purchase_invoice_charge_id: { type: "string", format: "uuid", description: "Parcela a quitar (settlement autom\xE1tico)" },
+      supplier_payment_method_id: { type: "string", format: "uuid", description: "Forma de pagamento do fornecedor (Pix)" },
+      pix_key: { type: "string" },
+      pix_key_type: { type: "string", enum: ["cpf", "cnpj", "email", "phone", "random"] },
+      pix_copia_e_cola: { type: "string", description: "QR Pix copia e cola (EMV)" },
+      boleto_barcode: { type: "string" },
+      scheduled_for: { type: "string", format: "date", description: "Data de agendamento (YYYY-MM-DD); omitir paga \xE0 vista" },
+      description: { type: "string" }
+    }
+  },
+  SupplierPaymentMethod: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      supplier_id: { type: "string", format: "uuid" },
+      label: { type: "string" },
+      type: { type: "string", enum: ["pix", "transfer", "boleto", "other"] },
+      is_default: { type: "boolean" },
+      notes: { type: ["string", "null"] },
+      pix_key_type: { type: ["string", "null"], enum: ["cpf", "cnpj", "email", "phone", "random", null] },
+      pix_key: { type: ["string", "null"] },
+      bank_code: { type: ["string", "null"] },
+      bank_name: { type: ["string", "null"] },
+      agency: { type: ["string", "null"] },
+      account_number: { type: ["string", "null"] },
+      account_type: { type: ["string", "null"], enum: ["corrente", "poupanca", null] },
+      holder_name: { type: ["string", "null"] },
+      holder_document: { type: ["string", "null"] },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  SupplierPaymentMethodCreate: {
+    type: "object",
+    required: ["type"],
+    properties: {
+      type: { type: "string", enum: ["pix", "transfer", "boleto", "other"], default: "pix" },
+      label: { type: "string" },
+      is_default: { type: "boolean" },
+      notes: { type: "string" },
+      pix_key_type: { type: "string", enum: ["cpf", "cnpj", "email", "phone", "random"] },
+      pix_key: { type: "string", description: "Obrigat\xF3rio para type=pix" },
+      bank_code: { type: "string" },
+      bank_name: { type: "string" },
+      agency: { type: "string" },
+      account_number: { type: "string" },
+      account_type: { type: "string", enum: ["corrente", "poupanca"] },
+      holder_name: { type: "string" },
+      holder_document: { type: "string" }
+    }
+  },
+  PaymentMethod: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      system_key: { type: ["string", "null"], description: "Ex: inter_pix, c6bank_boleto" },
+      channel_key: { type: ["string", "null"], enum: ["pix", "boleto", "checkout", null] },
+      provider_name: { type: ["string", "null"], enum: ["inter", "c6bank", null] },
+      active: { type: "boolean" }
+    }
+  },
+  InvoiceCreate: {
+    type: "object",
+    required: ["customer_id"],
+    properties: {
+      customer_id: { type: "string", format: "uuid" },
+      title: { type: "string" },
+      amount: { type: "number", description: "Ignorado se 'items' for enviado (calculado dos itens)" },
+      status: { type: "string", enum: ["rascunho", "enviada", "aceita", "ativa"], default: "rascunho" },
+      due_date: { type: "string", format: "date" },
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            service_id: { type: "string", format: "uuid", description: "Vincula um servi\xE7o cadastrado (GET /v1/services). Se omitido, o item \xE9 avulso (is_manual)." },
+            name: { type: "string" },
+            description: { type: "string" },
+            unit: { type: "string", default: "un" },
+            quantity: { type: "number", default: 1 },
+            unit_price: { type: "number" },
+            subtotal: { type: "number", description: "Opcional \u2014 calculado como quantity*unit_price se omitido" }
+          }
+        }
+      }
+    }
+  },
+  FinancialMovement: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      nature_id: { type: "string", format: "uuid" },
+      direction: { type: "string", enum: ["entrada", "saida"] },
+      amount: { type: "number" },
+      movement_date: { type: "string", format: "date" },
+      description: { type: "string" },
+      counterparty_name: { type: ["string", "null"] },
+      bank_account_id: { type: ["string", "null"], format: "uuid" },
+      payment_method_id: { type: ["string", "null"], format: "uuid" },
+      notes: { type: ["string", "null"] },
+      status: { type: "string", enum: ["realizado", "previsto", "cancelado"] },
+      source_type: { type: "string", enum: ["manual", "reconciliation", "rule"] },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  FinancialMovementCreate: {
+    type: "object",
+    required: ["nature_id", "direction", "amount", "movement_date", "description"],
+    properties: {
+      nature_id: { type: "string", format: "uuid", description: "Natureza financeira (financial_movement_natures)" },
+      direction: { type: "string", enum: ["entrada", "saida"] },
+      amount: { type: "number" },
+      movement_date: { type: "string", format: "date" },
+      description: { type: "string" },
+      counterparty_name: { type: "string" },
+      bank_account_id: { type: "string", format: "uuid" },
+      payment_method_id: { type: "string", format: "uuid" },
+      notes: { type: "string" },
+      status: { type: "string", enum: ["realizado", "previsto", "cancelado"], default: "realizado" }
+    }
+  },
+  NfseEmit: {
+    type: "object",
+    required: ["invoice_id"],
+    properties: {
+      invoice_id: { type: "string", format: "uuid", description: "Fatura a partir da qual emitir a NFS-e" }
+    }
+  },
+  NfseCancel: {
+    type: "object",
+    required: ["motivo", "justificativa"],
+    properties: {
+      motivo: { type: "integer", enum: [1, 2, 3, 4, 9], description: "1=n\xE3o realizada, 2=duplica\xE7\xE3o, 3=erro de emiss\xE3o, 4=servi\xE7o n\xE3o prestado, 9=outros" },
+      justificativa: { type: "string", minLength: 15, maxLength: 255 }
+    }
+  },
+  CustomerAddress: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      customer_id: { type: "string", format: "uuid" },
+      label: { type: ["string", "null"] },
+      street: { type: ["string", "null"] },
+      number: { type: ["string", "null"] },
+      complement: { type: ["string", "null"] },
+      neighborhood: { type: ["string", "null"] },
+      city: { type: ["string", "null"] },
+      state: { type: ["string", "null"], description: "UF (2 letras)" },
+      zip: { type: ["string", "null"] },
+      country: { type: ["string", "null"] },
+      ibge_code: { type: ["string", "null"] },
+      is_default: { type: "boolean" },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  CustomerAddressCreate: {
+    type: "object",
+    description: "Para emitir boleto, street, number, city, state e zip s\xE3o necess\xE1rios.",
+    properties: {
+      label: { type: "string" },
+      street: { type: "string" },
+      number: { type: "string" },
+      complement: { type: "string" },
+      neighborhood: { type: "string" },
+      city: { type: "string" },
+      state: { type: "string" },
+      zip: { type: "string" },
+      country: { type: "string" },
+      ibge_code: { type: "string" },
+      is_default: { type: "boolean" }
+    }
+  },
+  CustomerContact: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      customer_id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      email: { type: ["string", "null"] },
+      phone: { type: ["string", "null"] },
+      role: { type: ["string", "null"] },
+      department: { type: ["string", "null"] },
+      notes: { type: ["string", "null"] },
+      is_primary: { type: "boolean" },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  CustomerContactCreate: {
+    type: "object",
+    required: ["name"],
+    properties: {
+      name: { type: "string" },
+      email: { type: "string" },
+      phone: { type: "string" },
+      role: { type: "string" },
+      department: { type: "string" },
+      notes: { type: "string" },
+      is_primary: { type: "boolean" }
+    }
+  },
+  FinancialNature: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      code: { type: "string" },
+      name: { type: "string" },
+      description: { type: ["string", "null"] },
+      allowed_direction: { type: "string", enum: ["credit", "debit", "both"] },
+      is_active: { type: "boolean" },
+      sort_order: { type: "integer" }
+    }
+  },
+  CostCenter: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      active: { type: "boolean" },
+      color: { type: ["string", "null"] },
+      icon: { type: ["string", "null"] },
+      dre_group: { type: ["string", "null"] },
+      sort_order: { type: "integer" }
+    }
+  },
+  PaymentCondition: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      active: { type: "boolean" },
+      installments: { type: "array", items: { type: "object" }, description: "[{sequence, label, days, percentage}]" }
+    }
+  },
+  ServiceUnit: {
+    type: "object",
+    properties: { id: { type: "string", format: "uuid" }, name: { type: "string" } }
+  },
+  WebhookDelivery: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      webhook_id: { type: "string", format: "uuid" },
+      event: { type: "string" },
+      status: { type: "string", enum: ["pending", "delivering", "delivered", "failed"] },
+      attempts: { type: "integer" },
+      max_attempts: { type: "integer" },
+      http_status: { type: ["integer", "null"] },
+      last_error: { type: ["string", "null"] },
+      next_retry_at: { type: ["string", "null"], format: "date-time" },
+      delivered_at: { type: ["string", "null"], format: "date-time" },
+      created_at: { type: "string", format: "date-time" },
+      updated_at: { type: "string", format: "date-time" }
+    }
+  },
+  Company: {
+    type: "object",
+    properties: {
+      id: { type: "string", format: "uuid" },
+      name: { type: "string" },
+      trade_name: { type: ["string", "null"] },
+      document: { type: ["string", "null"], description: "CNPJ/CPF" },
+      active: { type: "boolean" },
+      is_default: { type: "boolean", description: "Empresa padr\xE3o da chave (usada quando X-Company-Id \xE9 omitido)" }
+    }
+  }
+};
+function paginatedResponse(schemaRef) {
+  return {
+    description: "Listagem paginada",
+    content: {
+      "application/json": {
+        schema: {
+          type: "object",
+          properties: {
+            data: { type: "array", items: { $ref: schemaRef } },
+            meta: { $ref: "#/components/schemas/PaginatedMeta" }
+          }
+        }
+      }
+    }
+  };
+}
+function errorResponse(description) {
+  return {
+    description,
+    content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }
+  };
+}
+var COMMON_ERRORS = {
+  "401": errorResponse("API key n\xE3o fornecida, inv\xE1lida ou revogada"),
+  "403": errorResponse("Scope insuficiente"),
+  "429": errorResponse("Rate limit excedido (60 req/min por padr\xE3o)"),
+  "500": errorResponse("Erro interno")
+};
+var OPENAPI_SPEC = {
+  openapi: "3.1.0",
+  info: {
+    title: "Comando.One API",
+    version: "1.1.0",
+    description: "API REST p\xFAblica do Comando.One \u2014 ERP SaaS para empresas de servi\xE7o brasileiras.\n\nAutentique com uma API key no header `x-api-key` ou `Authorization: Bearer <key>`.\n\n**Idempot\xEAncia:** envie o header `Idempotency-Key` (string \xFAnica) em requisi\xE7\xF5es POST. Repeti\xE7\xF5es com a mesma chave retornam a resposta original (header `Idempotent-Replayed: true`), evitando cobran\xE7as/pagamentos duplicados em caso de retry.\n\n**Rate limit:** 60 requisi\xE7\xF5es/minuto por chave (429 ao exceder).\n\n**Multi-empresa:** chaves podem ter acesso a v\xE1rias empresas. Use `GET /v1/companies` para list\xE1-las e o header `X-Company-Id` para escolher o tenant de cada request (omitido = empresa padr\xE3o da chave).\n\nGere sua chave em **Configura\xE7\xF5es \u2192 API Keys** dentro da plataforma.",
+    contact: { email: "contato@comando.one", url: "https://comando.one" },
+    license: { name: "Propriet\xE1rio" }
+  },
+  servers: [
+    { url: "https://api.comando.one/v1", description: "Produ\xE7\xE3o" },
+    { url: "https://pecdxlrbutkrtxvjsquf.supabase.co/functions/v1/public-api/v1", description: "Supabase direto" }
+  ],
+  security: API_KEY_SECURITY,
+  tags: [
+    { name: "Auth", description: "Verifica\xE7\xE3o de conectividade e identidade" },
+    { name: "Clientes", description: "Gerenciamento de clientes e contatos" },
+    { name: "Propostas", description: "Propostas comerciais" },
+    { name: "Contratos", description: "Contratos recorrentes" },
+    { name: "Faturas", description: "Faturas e cobran\xE7as" },
+    { name: "Financeiro", description: "Raz\xE3o financeiro \u2014 entradas e sa\xEDdas" },
+    { name: "NFS-e", description: "Notas Fiscais de Servi\xE7o Eletr\xF4nicas" },
+    { name: "Fornecedores", description: "Cadastro de fornecedores" },
+    { name: "Servi\xE7os", description: "Cat\xE1logo de servi\xE7os" },
+    { name: "Despesas", description: "Despesas operacionais" },
+    { name: "Contas a Pagar", description: "Notas fiscais de entrada / contas a pagar" },
+    { name: "Cobran\xE7as", description: "Gateway de pagamentos \u2014 Pix, boleto e checkout" },
+    { name: "Webhooks", description: "Notifica\xE7\xF5es de eventos (cobran\xE7a/pagamento) com retry e log" },
+    { name: "Cat\xE1logos", description: "Listagens de refer\xEAncia (naturezas, centros de custo, condi\xE7\xF5es, unidades)" },
+    { name: "Contas banc\xE1rias", description: "Contas banc\xE1rias (somente leitura)" },
+    { name: "Pagamentos a Fornecedor", description: "Payouts \u2014 pagar/agendar Pix e boleto a fornecedores" },
+    { name: "M\xE9todos de pagamento", description: "Formas de recebimento dispon\xEDveis" },
+    { name: "Formas de pagamento do fornecedor", description: "Cadastro de destinos de pagamento por fornecedor" }
+  ],
+  components: {
+    securitySchemes: {
+      ApiKeyAuth: {
+        type: "apiKey",
+        in: "header",
+        name: "x-api-key",
+        description: "Chave de API no formato `cmd_live_...`. Pode tamb\xE9m ser enviada como `Authorization: Bearer cmd_live_...`"
+      }
+    },
+    schemas: SCHEMAS
+  },
+  paths: {
+    // -----------------------------------------------------------------------
+    // Auth
+    // -----------------------------------------------------------------------
+    "/me": {
+      get: {
+        tags: ["Auth"],
+        summary: "Verificar conectividade",
+        operationId: "getMe",
+        description: "Retorna os dados da empresa e da chave autenticada. N\xE3o exige scope espec\xEDfico \u2014 qualquer chave v\xE1lida funciona.",
+        security: API_KEY_SECURITY,
+        responses: {
+          "200": {
+            description: "Empresa e chave autenticada",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    company: {
+                      type: "object",
+                      properties: {
+                        id: { type: "string", format: "uuid" },
+                        name: { type: "string" },
+                        trade_name: { type: ["string", "null"] },
+                        document: { type: "string" }
+                      }
+                    },
+                    api_key: {
+                      type: "object",
+                      properties: {
+                        name: { type: "string" },
+                        scopes: { type: "array", items: { type: "string" } },
+                        last_used_at: { type: ["string", "null"], format: "date-time" }
+                      }
+                    }
+                  }
+                },
+                example: {
+                  company: { id: "18fc359b-...", name: "Acme Servi\xE7os", trade_name: "Acme", document: "12345678000195" },
+                  api_key: { name: "Integra\xE7\xE3o ERP", scopes: ["customers:read", "invoices:read"], last_used_at: "2026-06-04T18:17:47+00:00" }
+                }
+              }
+            }
+          },
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/companies": {
+      get: {
+        tags: ["Auth"],
+        summary: "Listar empresas acess\xEDveis pela chave",
+        operationId: "listCompanies",
+        description: "Lista as empresas que a chave pode acessar. Keys single-company retornam apenas a sua; keys multi-empresa retornam todas as permitidas. Use o id em **X-Company-Id** para escolher o tenant de cada request.",
+        security: API_KEY_SECURITY,
+        responses: {
+          "200": { description: "Empresas acess\xEDveis", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Company" } } } } } } },
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/companies/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Auth"],
+        summary: "Obter empresa acess\xEDvel",
+        operationId: "getCompany",
+        security: API_KEY_SECURITY,
+        responses: { "200": { description: "Empresa", content: { "application/json": { schema: { $ref: "#/components/schemas/Company" } } } }, "404": errorResponse("Empresa n\xE3o encontrada ou n\xE3o acess\xEDvel pela chave"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Customers
+    // -----------------------------------------------------------------------
+    "/customers": {
+      get: {
+        tags: ["Clientes"],
+        summary: "Listar clientes",
+        operationId: "listCustomers",
+        security: [{ ApiKeyAuth: ["customers:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "search", in: "query", schema: { type: "string" }, description: "Busca por nome, e-mail ou documento" },
+          { name: "status", in: "query", schema: { type: "string" }, description: "Filtrar por status" }
+        ],
+        responses: {
+          "200": paginatedResponse("#/components/schemas/Customer"),
+          ...COMMON_ERRORS
+        }
+      },
+      post: {
+        tags: ["Clientes"],
+        summary: "Criar cliente",
+        operationId: "createCustomer",
+        security: [{ ApiKeyAuth: ["customers:write"] }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: { $ref: "#/components/schemas/CustomerCreate" },
+              example: { name: "Acme Servi\xE7os Ltda", email: "contato@acme.com.br", type: "juridica", document: "12345678000195" }
+            }
+          }
+        },
+        responses: {
+          "201": {
+            description: "Cliente criado",
+            content: { "application/json": { schema: { $ref: "#/components/schemas/Customer" } } }
+          },
+          "400": errorResponse("Par\xE2metros inv\xE1lidos"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/customers/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Clientes"],
+        summary: "Obter cliente",
+        operationId: "getCustomer",
+        security: [{ ApiKeyAuth: ["customers:read"] }],
+        responses: {
+          "200": { description: "Cliente", content: { "application/json": { schema: { $ref: "#/components/schemas/Customer" } } } },
+          "404": errorResponse("Cliente n\xE3o encontrado"),
+          ...COMMON_ERRORS
+        }
+      },
+      patch: {
+        tags: ["Clientes"],
+        summary: "Atualizar cliente",
+        operationId: "updateCustomer",
+        security: [{ ApiKeyAuth: ["customers:write"] }],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerUpdate" } } }
+        },
+        responses: {
+          "200": { description: "Cliente atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Customer" } } } },
+          "400": errorResponse("Par\xE2metros inv\xE1lidos"),
+          "404": errorResponse("Cliente n\xE3o encontrado"),
+          ...COMMON_ERRORS
+        }
+      },
+      delete: {
+        tags: ["Clientes"],
+        summary: "Excluir cliente",
+        operationId: "deleteCustomer",
+        security: [{ ApiKeyAuth: ["customers:delete"] }],
+        responses: {
+          "204": { description: "Cliente exclu\xEDdo (sem corpo)" },
+          "404": errorResponse("Cliente n\xE3o encontrado"),
+          "409": errorResponse("H\xE1 registros vinculados (faturas, contratos, etc.) que impedem a exclus\xE3o"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/customers/{id}/invoices": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Clientes"],
+        summary: "Faturas do cliente",
+        operationId: "listCustomerInvoices",
+        security: [{ ApiKeyAuth: ["customers:read", "invoices:read"] }],
+        parameters: PAGINATION_PARAMS,
+        responses: {
+          "200": {
+            description: "Faturas do cliente",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    data: { type: "array", items: { type: "object" } },
+                    meta: { $ref: "#/components/schemas/PaginatedMeta" }
+                  }
+                }
+              }
+            }
+          },
+          "404": errorResponse("Cliente n\xE3o encontrado"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/customers/{id}/contracts": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Clientes"],
+        summary: "Contratos do cliente",
+        operationId: "listCustomerContracts",
+        security: [{ ApiKeyAuth: ["customers:read", "contracts:read"] }],
+        parameters: PAGINATION_PARAMS,
+        responses: {
+          "200": paginatedResponse("#/components/schemas/Contract"),
+          "404": errorResponse("Cliente n\xE3o encontrado"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/customers/{id}/proposals": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Clientes"],
+        summary: "Propostas do cliente",
+        operationId: "listCustomerProposals",
+        security: [{ ApiKeyAuth: ["customers:read", "proposals:read"] }],
+        parameters: PAGINATION_PARAMS,
+        responses: {
+          "200": paginatedResponse("#/components/schemas/Proposal"),
+          "404": errorResponse("Cliente n\xE3o encontrado"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/customers/{id}/addresses": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Clientes"],
+        summary: "Listar endere\xE7os do cliente",
+        operationId: "listCustomerAddresses",
+        security: [{ ApiKeyAuth: ["customers:read"] }],
+        responses: { "200": { description: "Endere\xE7os", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/CustomerAddress" } } } } } } }, "404": errorResponse("Cliente n\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Clientes"],
+        summary: "Adicionar endere\xE7o",
+        operationId: "createCustomerAddress",
+        security: [{ ApiKeyAuth: ["customers:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerAddressCreate" } } } },
+        responses: { "201": { description: "Criado", content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerAddress" } } } }, "404": errorResponse("Cliente n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/customers/{id}/addresses/{addressId}": {
+      parameters: [
+        { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
+        { name: "addressId", in: "path", required: true, schema: { type: "string", format: "uuid" } }
+      ],
+      patch: {
+        tags: ["Clientes"],
+        summary: "Atualizar endere\xE7o",
+        operationId: "updateCustomerAddress",
+        security: [{ ApiKeyAuth: ["customers:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerAddressCreate" } } } },
+        responses: { "200": { description: "Atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerAddress" } } } }, "404": errorResponse("N\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Clientes"],
+        summary: "Excluir endere\xE7o",
+        operationId: "deleteCustomerAddress",
+        security: [{ ApiKeyAuth: ["customers:delete"] }],
+        responses: { "204": { description: "Exclu\xEDdo" }, "404": errorResponse("N\xE3o encontrado"), "409": errorResponse("H\xE1 registros vinculados que impedem a exclus\xE3o"), ...COMMON_ERRORS }
+      }
+    },
+    "/customers/{id}/contacts": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Clientes"],
+        summary: "Listar contatos do cliente",
+        operationId: "listCustomerContacts",
+        security: [{ ApiKeyAuth: ["customers:read"] }],
+        responses: { "200": { description: "Contatos", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/CustomerContact" } } } } } } }, "404": errorResponse("Cliente n\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Clientes"],
+        summary: "Adicionar contato",
+        operationId: "createCustomerContact",
+        security: [{ ApiKeyAuth: ["customers:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerContactCreate" } } } },
+        responses: { "201": { description: "Criado", content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerContact" } } } }, "400": errorResponse("name obrigat\xF3rio"), "404": errorResponse("Cliente n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/customers/{id}/contacts/{contactId}": {
+      parameters: [
+        { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
+        { name: "contactId", in: "path", required: true, schema: { type: "string", format: "uuid" } }
+      ],
+      patch: {
+        tags: ["Clientes"],
+        summary: "Atualizar contato",
+        operationId: "updateCustomerContact",
+        security: [{ ApiKeyAuth: ["customers:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerContactCreate" } } } },
+        responses: { "200": { description: "Atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/CustomerContact" } } } }, "404": errorResponse("N\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Clientes"],
+        summary: "Excluir contato",
+        operationId: "deleteCustomerContact",
+        security: [{ ApiKeyAuth: ["customers:delete"] }],
+        responses: { "204": { description: "Exclu\xEDdo" }, "404": errorResponse("N\xE3o encontrado"), "409": errorResponse("H\xE1 registros vinculados que impedem a exclus\xE3o"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Proposals
+    // -----------------------------------------------------------------------
+    "/proposals": {
+      get: {
+        tags: ["Propostas"],
+        summary: "Listar propostas",
+        operationId: "listProposals",
+        security: [{ ApiKeyAuth: ["proposals:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "status", in: "query", schema: { type: "string", enum: ["rascunho", "enviada", "aceita", "recusada", "cancelada", "faturada"] }, description: "Filtrar por status" },
+          { name: "customer_id", in: "query", schema: { type: "string", format: "uuid" }, description: "Filtrar por cliente" }
+        ],
+        responses: {
+          "200": paginatedResponse("#/components/schemas/Proposal"),
+          ...COMMON_ERRORS
+        }
+      },
+      post: {
+        tags: ["Propostas"],
+        summary: "Criar proposta",
+        operationId: "createProposal",
+        security: [{ ApiKeyAuth: ["proposals:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ProposalCreate" } } } },
+        responses: { "201": { description: "Proposta criada", content: { "application/json": { schema: { $ref: "#/components/schemas/Proposal" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Cliente n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/proposals/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Propostas"],
+        summary: "Obter proposta",
+        operationId: "getProposal",
+        security: [{ ApiKeyAuth: ["proposals:read"] }],
+        responses: {
+          "200": { description: "Proposta com itens", content: { "application/json": { schema: { $ref: "#/components/schemas/ProposalDetail" } } } },
+          "404": errorResponse("Proposta n\xE3o encontrada"),
+          ...COMMON_ERRORS
+        }
+      },
+      patch: {
+        tags: ["Propostas"],
+        summary: "Atualizar proposta",
+        operationId: "updateProposal",
+        security: [{ ApiKeyAuth: ["proposals:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ProposalCreate" } } } },
+        responses: { "200": { description: "Proposta atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/Proposal" } } } }, "404": errorResponse("Proposta n\xE3o encontrada"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Propostas"],
+        summary: "Excluir proposta",
+        operationId: "deleteProposal",
+        security: [{ ApiKeyAuth: ["proposals:delete"] }],
+        responses: { "204": { description: "Exclu\xEDda" }, "404": errorResponse("Proposta n\xE3o encontrada"), "409": errorResponse("H\xE1 registros vinculados que impedem a exclus\xE3o"), ...COMMON_ERRORS }
+      }
+    },
+    "/proposals/{id}/send": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      post: {
+        tags: ["Propostas"],
+        summary: "Enviar proposta",
+        operationId: "sendProposal",
+        description: "Marca a proposta como enviada.",
+        security: [{ ApiKeyAuth: ["proposals:send"] }],
+        responses: { "200": { description: "Proposta enviada", content: { "application/json": { schema: { $ref: "#/components/schemas/Proposal" } } } }, "404": errorResponse("Proposta n\xE3o encontrada"), "409": errorResponse("Proposta cancelada"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Contracts
+    // -----------------------------------------------------------------------
+    "/contracts": {
+      get: {
+        tags: ["Contratos"],
+        summary: "Listar contratos",
+        operationId: "listContracts",
+        security: [{ ApiKeyAuth: ["contracts:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "search", in: "query", schema: { type: "string" }, description: "Busca por t\xEDtulo ou notas" },
+          { name: "status", in: "query", schema: { type: "string", enum: ["ativo", "suspenso", "cancelado", "finalizado"] } },
+          { name: "frequency", in: "query", schema: { type: "string", enum: ["semanal", "quinzenal", "mensal", "bimestral", "trimestral", "semestral", "anual"] } },
+          { name: "customer_id", in: "query", schema: { type: "string", format: "uuid" } }
+        ],
+        responses: {
+          "200": paginatedResponse("#/components/schemas/Contract"),
+          ...COMMON_ERRORS
+        }
+      },
+      post: {
+        tags: ["Contratos"],
+        summary: "Criar contrato",
+        operationId: "createContract",
+        security: [{ ApiKeyAuth: ["contracts:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContractCreate" } } } },
+        responses: { "201": { description: "Contrato criado", content: { "application/json": { schema: { $ref: "#/components/schemas/Contract" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Cliente n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/contracts/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Contratos"],
+        summary: "Obter contrato",
+        operationId: "getContract",
+        security: [{ ApiKeyAuth: ["contracts:read"] }],
+        responses: {
+          "200": { description: "Contrato com itens e se\xE7\xF5es", content: { "application/json": { schema: { $ref: "#/components/schemas/ContractDetail" } } } },
+          "404": errorResponse("Contrato n\xE3o encontrado"),
+          ...COMMON_ERRORS
+        }
+      },
+      patch: {
+        tags: ["Contratos"],
+        summary: "Atualizar contrato",
+        operationId: "updateContract",
+        security: [{ ApiKeyAuth: ["contracts:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContractCreate" } } } },
+        responses: { "200": { description: "Contrato atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Contract" } } } }, "404": errorResponse("Contrato n\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Contratos"],
+        summary: "Excluir contrato",
+        operationId: "deleteContract",
+        security: [{ ApiKeyAuth: ["contracts:delete"] }],
+        responses: { "204": { description: "Exclu\xEDdo" }, "404": errorResponse("Contrato n\xE3o encontrado"), "409": errorResponse("H\xE1 registros vinculados que impedem a exclus\xE3o"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Invoices
+    // -----------------------------------------------------------------------
+    "/invoices": {
+      get: {
+        tags: ["Faturas"],
+        summary: "Listar faturas",
+        operationId: "listInvoices",
+        security: [{ ApiKeyAuth: ["invoices:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "search", in: "query", schema: { type: "string" }, description: "Busca por n\xFAmero ou t\xEDtulo" },
+          { name: "status", in: "query", schema: { type: "string", enum: ["rascunho", "enviada", "aceita", "cancelada"] } },
+          { name: "payment_status", in: "query", schema: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] } },
+          { name: "customer_id", in: "query", schema: { type: "string", format: "uuid" } },
+          { name: "due_date_from", in: "query", schema: { type: "string", format: "date" }, description: "Vencimento a partir de (YYYY-MM-DD)" },
+          { name: "due_date_to", in: "query", schema: { type: "string", format: "date" }, description: "Vencimento at\xE9 (YYYY-MM-DD)" }
+        ],
+        responses: {
+          "200": paginatedResponse("#/components/schemas/Invoice"),
+          ...COMMON_ERRORS
+        }
+      },
+      post: {
+        tags: ["Faturas"],
+        summary: "Criar fatura",
+        operationId: "createInvoice",
+        description: "Cria uma fatura. Se 'items' for enviado, o valor \xE9 calculado a partir deles.",
+        security: [{ ApiKeyAuth: ["invoices:create"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/InvoiceCreate" } } } },
+        responses: { "201": { description: "Fatura criada", content: { "application/json": { schema: { $ref: "#/components/schemas/Invoice" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Cliente n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/invoices/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Faturas"],
+        summary: "Obter fatura",
+        operationId: "getInvoice",
+        security: [{ ApiKeyAuth: ["invoices:read"] }],
+        responses: {
+          "200": { description: "Fatura com itens e cobran\xE7as", content: { "application/json": { schema: { $ref: "#/components/schemas/InvoiceDetail" } } } },
+          "404": errorResponse("Fatura n\xE3o encontrada"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/invoices/{id}/cancel": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      patch: {
+        tags: ["Faturas"],
+        summary: "Cancelar fatura",
+        operationId: "cancelInvoice",
+        security: [{ ApiKeyAuth: ["invoices:cancel"] }],
+        responses: {
+          "200": {
+            description: "Fatura cancelada",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string", format: "uuid" },
+                    invoice_number: { type: ["string", "null"] },
+                    title: { type: ["string", "null"] },
+                    status: { type: "string", enum: ["cancelada"] },
+                    payment_status: { type: "string" },
+                    amount: { type: "number" },
+                    updated_at: { type: "string", format: "date-time" }
+                  }
+                }
+              }
+            }
+          },
+          "404": errorResponse("Fatura n\xE3o encontrada"),
+          "409": errorResponse("Fatura j\xE1 est\xE1 cancelada"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Finance
+    // -----------------------------------------------------------------------
+    "/finance/ledger": {
+      get: {
+        tags: ["Financeiro"],
+        summary: "Raz\xE3o financeiro",
+        operationId: "getFinanceLedger",
+        description: "Retorna entradas e sa\xEDdas consolidadas: recebimentos de clientes, pagamentos a fornecedores e despesas.",
+        security: [{ ApiKeyAuth: ["finance:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "start_date", in: "query", schema: { type: "string", format: "date" }, description: "Data inicial (YYYY-MM-DD)" },
+          { name: "end_date", in: "query", schema: { type: "string", format: "date" }, description: "Data final (YYYY-MM-DD)" },
+          { name: "direction", in: "query", schema: { type: "string", enum: ["all", "entrada", "saida"], default: "all" } }
+        ],
+        responses: {
+          "200": paginatedResponse("#/components/schemas/FinanceLedgerEntry"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/finance/movements": {
+      post: {
+        tags: ["Financeiro"],
+        summary: "Lan\xE7ar movimenta\xE7\xE3o manual",
+        operationId: "createFinancialMovement",
+        security: [{ ApiKeyAuth: ["finance:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/FinancialMovementCreate" } } } },
+        responses: { "201": { description: "Movimenta\xE7\xE3o criada", content: { "application/json": { schema: { $ref: "#/components/schemas/FinancialMovement" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Natureza financeira n\xE3o encontrada"), ...COMMON_ERRORS }
+      }
+    },
+    "/finance/movements/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      delete: {
+        tags: ["Financeiro"],
+        summary: "Excluir movimenta\xE7\xE3o manual",
+        operationId: "deleteFinancialMovement",
+        security: [{ ApiKeyAuth: ["finance:delete"] }],
+        responses: { "204": { description: "Exclu\xEDda" }, "404": errorResponse("Movimenta\xE7\xE3o n\xE3o encontrada"), "409": errorResponse("Apenas movimenta\xE7\xF5es manuais podem ser exclu\xEDdas"), ...COMMON_ERRORS }
+      }
+    },
+    "/finance/natures": {
+      get: {
+        tags: ["Cat\xE1logos"],
+        summary: "Listar naturezas financeiras",
+        operationId: "listFinancialNatures",
+        description: "IDs usados em POST /v1/finance/movements (nature_id).",
+        security: [{ ApiKeyAuth: ["finance:read", "finance:write"] }],
+        parameters: [...PAGINATION_PARAMS, { name: "is_active", in: "query", schema: { type: "string", enum: ["true", "false"] } }, { name: "direction", in: "query", schema: { type: "string", enum: ["credit", "debit", "both"] } }],
+        responses: { "200": paginatedResponse("#/components/schemas/FinancialNature"), ...COMMON_ERRORS }
+      }
+    },
+    "/cost-centers": {
+      get: {
+        tags: ["Cat\xE1logos"],
+        summary: "Listar centros de custo",
+        operationId: "listCostCenters",
+        description: "IDs usados em despesas (category_id).",
+        security: [{ ApiKeyAuth: ["expenses:read", "expenses:write", "finance:read"] }],
+        parameters: [...PAGINATION_PARAMS, { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } }],
+        responses: { "200": paginatedResponse("#/components/schemas/CostCenter"), ...COMMON_ERRORS }
+      }
+    },
+    "/payment-conditions": {
+      get: {
+        tags: ["Cat\xE1logos"],
+        summary: "Listar condi\xE7\xF5es de pagamento",
+        operationId: "listPaymentConditions",
+        security: [{ ApiKeyAuth: ["invoices:read", "contracts:read"] }],
+        parameters: [...PAGINATION_PARAMS, { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } }],
+        responses: { "200": paginatedResponse("#/components/schemas/PaymentCondition"), ...COMMON_ERRORS }
+      }
+    },
+    "/service-units": {
+      get: {
+        tags: ["Cat\xE1logos"],
+        summary: "Listar unidades de servi\xE7o",
+        operationId: "listServiceUnits",
+        security: [{ ApiKeyAuth: ["services:read", "services:write"] }],
+        parameters: [...PAGINATION_PARAMS],
+        responses: { "200": paginatedResponse("#/components/schemas/ServiceUnit"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // NFS-e
+    // -----------------------------------------------------------------------
+    "/nfse": {
+      get: {
+        tags: ["NFS-e"],
+        summary: "Listar NFS-e",
+        operationId: "listNfse",
+        security: [{ ApiKeyAuth: ["nfse:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "status", in: "query", schema: { type: "string", enum: ["rascunho", "transmitindo", "autorizada", "rejeitada", "cancelada"] } },
+          { name: "invoice_id", in: "query", schema: { type: "string", format: "uuid" }, description: "Filtrar por fatura" }
+        ],
+        responses: {
+          "200": paginatedResponse("#/components/schemas/NfseHistory"),
+          ...COMMON_ERRORS
+        }
+      },
+      post: {
+        tags: ["NFS-e"],
+        summary: "Emitir NFS-e",
+        operationId: "emitNfse",
+        description: "Emite uma NFS-e a partir de uma fatura. O m\xE9todo (certificado/portal) vem da configura\xE7\xE3o da empresa. Pode levar alguns segundos.",
+        security: [{ ApiKeyAuth: ["nfse:emitir"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/NfseEmit" } } } },
+        responses: { "201": { description: "Emiss\xE3o solicitada", content: { "application/json": { schema: { type: "object", properties: { invoice_id: { type: "string" }, status: { type: "string" }, numero_nfse: { type: ["string", "null"] }, chave_acesso: { type: ["string", "null"] }, history_id: { type: ["string", "null"] } } } } } }, "400": errorResponse("invoice_id ausente"), "404": errorResponse("Fatura n\xE3o encontrada"), "422": errorResponse("NFS-e n\xE3o configurada"), "502": errorResponse("Erro do provedor de NFS-e"), ...COMMON_ERRORS }
+      }
+    },
+    "/nfse/{id}/cancel": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      patch: {
+        tags: ["NFS-e"],
+        summary: "Cancelar NFS-e",
+        operationId: "cancelNfse",
+        security: [{ ApiKeyAuth: ["nfse:cancelar"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/NfseCancel" } } } },
+        responses: { "200": { description: "Cancelamento solicitado", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" }, cancel_protocolo: { type: ["string", "null"] } } } } } }, "400": errorResponse("motivo/justificativa inv\xE1lidos"), "404": errorResponse("NFS-e n\xE3o encontrada"), "409": errorResponse("NFS-e n\xE3o est\xE1 autorizada"), "502": errorResponse("Erro do provedor de NFS-e"), ...COMMON_ERRORS }
+      }
+    },
+    "/nfse/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["NFS-e"],
+        summary: "Obter NFS-e",
+        operationId: "getNfse",
+        security: [{ ApiKeyAuth: ["nfse:read"] }],
+        responses: {
+          "200": { description: "NFS-e com detalhes de cancelamento", content: { "application/json": { schema: { $ref: "#/components/schemas/NfseHistoryDetail" } } } },
+          "404": errorResponse("NFS-e n\xE3o encontrada"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Fornecedores
+    // -----------------------------------------------------------------------
+    "/suppliers": {
+      get: {
+        tags: ["Fornecedores"],
+        summary: "Listar fornecedores",
+        operationId: "listSuppliers",
+        security: [{ ApiKeyAuth: ["suppliers:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "search", in: "query", schema: { type: "string" }, description: "Busca por nome, e-mail ou documento" },
+          { name: "status", in: "query", schema: { type: "string", enum: ["ativo", "inativo"] } },
+          { name: "type", in: "query", schema: { type: "string", enum: ["fisica", "juridica", "estrangeira"] } }
+        ],
+        responses: { "200": paginatedResponse("#/components/schemas/Supplier"), ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Fornecedores"],
+        summary: "Criar fornecedor",
+        operationId: "createSupplier",
+        security: [{ ApiKeyAuth: ["suppliers:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/SupplierCreate" } } } },
+        responses: {
+          "201": { description: "Fornecedor criado", content: { "application/json": { schema: { $ref: "#/components/schemas/Supplier" } } } },
+          "400": errorResponse("Dados inv\xE1lidos"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/suppliers/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Fornecedores"],
+        summary: "Obter fornecedor",
+        operationId: "getSupplier",
+        security: [{ ApiKeyAuth: ["suppliers:read"] }],
+        responses: { "200": { description: "Fornecedor", content: { "application/json": { schema: { $ref: "#/components/schemas/Supplier" } } } }, "404": errorResponse("Fornecedor n\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      patch: {
+        tags: ["Fornecedores"],
+        summary: "Atualizar fornecedor",
+        operationId: "updateSupplier",
+        security: [{ ApiKeyAuth: ["suppliers:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/SupplierCreate" } } } },
+        responses: { "200": { description: "Fornecedor atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Supplier" } } } }, "404": errorResponse("Fornecedor n\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Fornecedores"],
+        summary: "Excluir fornecedor",
+        operationId: "deleteSupplier",
+        security: [{ ApiKeyAuth: ["suppliers:delete"] }],
+        responses: { "204": { description: "Exclu\xEDdo" }, "404": errorResponse("Fornecedor n\xE3o encontrado"), "409": errorResponse("H\xE1 registros vinculados (contas a pagar, despesas, etc.) que impedem a exclus\xE3o"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Serviços
+    // -----------------------------------------------------------------------
+    "/services": {
+      get: {
+        tags: ["Servi\xE7os"],
+        summary: "Listar servi\xE7os",
+        operationId: "listServices",
+        security: [{ ApiKeyAuth: ["services:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "search", in: "query", schema: { type: "string" }, description: "Busca por nome ou descri\xE7\xE3o" },
+          { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } }
+        ],
+        responses: { "200": paginatedResponse("#/components/schemas/Service"), ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Servi\xE7os"],
+        summary: "Criar servi\xE7o",
+        operationId: "createService",
+        security: [{ ApiKeyAuth: ["services:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ServiceCreate" } } } },
+        responses: { "201": { description: "Servi\xE7o criado", content: { "application/json": { schema: { $ref: "#/components/schemas/Service" } } } }, "400": errorResponse("Dados inv\xE1lidos"), ...COMMON_ERRORS }
+      }
+    },
+    "/services/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Servi\xE7os"],
+        summary: "Obter servi\xE7o",
+        operationId: "getService",
+        security: [{ ApiKeyAuth: ["services:read"] }],
+        responses: { "200": { description: "Servi\xE7o", content: { "application/json": { schema: { $ref: "#/components/schemas/Service" } } } }, "404": errorResponse("Servi\xE7o n\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      patch: {
+        tags: ["Servi\xE7os"],
+        summary: "Atualizar servi\xE7o",
+        operationId: "updateService",
+        security: [{ ApiKeyAuth: ["services:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ServiceCreate" } } } },
+        responses: { "200": { description: "Servi\xE7o atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Service" } } } }, "404": errorResponse("Servi\xE7o n\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Servi\xE7os"],
+        summary: "Excluir servi\xE7o",
+        operationId: "deleteService",
+        security: [{ ApiKeyAuth: ["services:delete"] }],
+        responses: { "204": { description: "Exclu\xEDdo" }, "404": errorResponse("Servi\xE7o n\xE3o encontrado"), "409": errorResponse("H\xE1 registros vinculados que impedem a exclus\xE3o"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Despesas
+    // -----------------------------------------------------------------------
+    "/expenses": {
+      get: {
+        tags: ["Despesas"],
+        summary: "Listar despesas",
+        operationId: "listExpenses",
+        security: [{ ApiKeyAuth: ["expenses:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "status", in: "query", schema: { type: "string", enum: ["pendente", "pago", "cancelado"] } },
+          { name: "supplier_id", in: "query", schema: { type: "string", format: "uuid" } },
+          { name: "category_id", in: "query", schema: { type: "string", format: "uuid" } },
+          { name: "expense_date_from", in: "query", schema: { type: "string", format: "date" } },
+          { name: "expense_date_to", in: "query", schema: { type: "string", format: "date" } }
+        ],
+        responses: { "200": paginatedResponse("#/components/schemas/Expense"), ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Despesas"],
+        summary: "Criar despesa",
+        operationId: "createExpense",
+        security: [{ ApiKeyAuth: ["expenses:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ExpenseCreate" } } } },
+        responses: { "201": { description: "Despesa criada", content: { "application/json": { schema: { $ref: "#/components/schemas/Expense" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Fornecedor n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/expenses/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Despesas"],
+        summary: "Obter despesa",
+        operationId: "getExpense",
+        security: [{ ApiKeyAuth: ["expenses:read"] }],
+        responses: { "200": { description: "Despesa", content: { "application/json": { schema: { $ref: "#/components/schemas/Expense" } } } }, "404": errorResponse("Despesa n\xE3o encontrada"), ...COMMON_ERRORS }
+      },
+      patch: {
+        tags: ["Despesas"],
+        summary: "Atualizar despesa",
+        operationId: "updateExpense",
+        security: [{ ApiKeyAuth: ["expenses:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ExpenseCreate" } } } },
+        responses: { "200": { description: "Despesa atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/Expense" } } } }, "404": errorResponse("Despesa n\xE3o encontrada"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Despesas"],
+        summary: "Excluir despesa",
+        operationId: "deleteExpense",
+        security: [{ ApiKeyAuth: ["expenses:delete"] }],
+        responses: { "204": { description: "Exclu\xEDda" }, "404": errorResponse("Despesa n\xE3o encontrada"), "409": errorResponse("H\xE1 registros vinculados que impedem a exclus\xE3o"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Contas a Pagar
+    // -----------------------------------------------------------------------
+    "/purchase-invoices": {
+      get: {
+        tags: ["Contas a Pagar"],
+        summary: "Listar contas a pagar",
+        operationId: "listPurchaseInvoices",
+        security: [{ ApiKeyAuth: ["purchase_invoices:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "status", in: "query", schema: { type: "string", enum: ["rascunho", "recebida", "aprovada", "cancelada"] } },
+          { name: "payment_status", in: "query", schema: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] } },
+          { name: "supplier_id", in: "query", schema: { type: "string", format: "uuid" } },
+          { name: "invoice_number", in: "query", schema: { type: "string" } },
+          { name: "due_date_from", in: "query", schema: { type: "string", format: "date" } },
+          { name: "due_date_to", in: "query", schema: { type: "string", format: "date" } }
+        ],
+        responses: { "200": paginatedResponse("#/components/schemas/PurchaseInvoice"), ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Contas a Pagar"],
+        summary: "Criar conta a pagar",
+        operationId: "createPurchaseInvoice",
+        security: [{ ApiKeyAuth: ["purchase_invoices:create"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseInvoiceCreate" } } } },
+        responses: { "201": { description: "Conta a pagar criada", content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseInvoice" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Fornecedor n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/purchase-invoices/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Contas a Pagar"],
+        summary: "Obter conta a pagar (com itens e parcelas)",
+        operationId: "getPurchaseInvoice",
+        security: [{ ApiKeyAuth: ["purchase_invoices:read"] }],
+        responses: { "200": { description: "Conta a pagar", content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseInvoice" } } } }, "404": errorResponse("Conta a pagar n\xE3o encontrada"), ...COMMON_ERRORS }
+      }
+    },
+    "/purchase-invoices/{id}/cancel": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      patch: {
+        tags: ["Contas a Pagar"],
+        summary: "Cancelar conta a pagar",
+        operationId: "cancelPurchaseInvoice",
+        security: [{ ApiKeyAuth: ["purchase_invoices:cancel"] }],
+        responses: { "200": { description: "Cancelada", content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseInvoice" } } } }, "404": errorResponse("Conta a pagar n\xE3o encontrada"), "409": errorResponse("J\xE1 cancelada"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Cobranças (Gateway)
+    // -----------------------------------------------------------------------
+    "/charges": {
+      get: {
+        tags: ["Cobran\xE7as"],
+        summary: "Listar cobran\xE7as",
+        operationId: "listCharges",
+        security: [{ ApiKeyAuth: ["charges:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "status", in: "query", schema: { type: "string", enum: ["pending", "paid", "cancelled", "expired", "failed"] } },
+          { name: "method", in: "query", schema: { type: "string", enum: ["pix", "boleto", "checkout"] } },
+          { name: "customer_id", in: "query", schema: { type: "string", format: "uuid" } },
+          { name: "invoice_id", in: "query", schema: { type: "string", format: "uuid" } }
+        ],
+        responses: { "200": paginatedResponse("#/components/schemas/Charge"), ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Cobran\xE7as"],
+        summary: "Criar cobran\xE7a (Pix, boleto ou checkout)",
+        operationId: "createCharge",
+        description: "Gera uma cobran\xE7a no provider ativo da empresa (Inter ou C6 Bank). Forne\xE7a invoice_id ou customer_id+amount+due_date.",
+        security: [{ ApiKeyAuth: ["charges:create"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChargeCreate" } } } },
+        responses: {
+          "201": { description: "Cobran\xE7a criada", content: { "application/json": { schema: { $ref: "#/components/schemas/Charge" } } } },
+          "400": errorResponse("Dados inv\xE1lidos"),
+          "409": errorResponse("Fatura j\xE1 paga"),
+          "422": errorResponse("Integra\xE7\xE3o banc\xE1ria n\xE3o configurada"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/charges/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Cobran\xE7as"],
+        summary: "Obter cobran\xE7a",
+        operationId: "getCharge",
+        security: [{ ApiKeyAuth: ["charges:read"] }],
+        responses: { "200": { description: "Cobran\xE7a", content: { "application/json": { schema: { $ref: "#/components/schemas/Charge" } } } }, "404": errorResponse("Cobran\xE7a n\xE3o encontrada"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Cobran\xE7as"],
+        summary: "Cancelar cobran\xE7a",
+        operationId: "cancelCharge",
+        security: [{ ApiKeyAuth: ["charges:cancel"] }],
+        responses: { "200": { description: "Cancelamento solicitado" }, "404": errorResponse("Cobran\xE7a n\xE3o encontrada"), "409": errorResponse("Cobran\xE7a n\xE3o pode ser cancelada no estado atual"), ...COMMON_ERRORS }
+      }
+    },
+    "/charges/{id}/refund": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      post: {
+        tags: ["Cobran\xE7as"],
+        summary: "Estornar cobran\xE7a (devolu\xE7\xE3o Pix)",
+        operationId: "refundCharge",
+        description: "Estorna (devolve) uma cobran\xE7a Pix paga. Dispon\xEDvel apenas para Pix \u2014 boleto e checkout retornam 422. Requer que o endToEndId do pagamento tenha sido capturado.",
+        security: [{ ApiKeyAuth: ["charges:refund"] }],
+        responses: {
+          "200": { description: "Devolu\xE7\xE3o solicitada", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" }, provider: { type: "string" }, amount: { type: "number" }, message: { type: "string" } } } } } },
+          "404": errorResponse("Cobran\xE7a n\xE3o encontrada"),
+          "409": errorResponse("Cobran\xE7a n\xE3o est\xE1 paga ou j\xE1 estornada"),
+          "422": errorResponse("M\xE9todo n\xE3o suportado (apenas Pix) ou endToEndId indispon\xEDvel"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/charges/{id}/confirm": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      post: {
+        tags: ["Cobran\xE7as"],
+        summary: "Confirmar pagamento (Pix est\xE1tico/offline)",
+        operationId: "confirmCharge",
+        description: "Marca manualmente uma cobran\xE7a Pix est\xE1tico (provider 'pix_offline') como paga e dispara o webhook charge.paid. Para Inter/C6 a baixa vem do banco (n\xE3o use este endpoint).",
+        security: [{ ApiKeyAuth: ["charges:create"] }],
+        responses: {
+          "200": { description: "Cobran\xE7a confirmada (paga)", content: { "application/json": { schema: { $ref: "#/components/schemas/Charge" } } } },
+          "404": errorResponse("Cobran\xE7a n\xE3o encontrada"),
+          "409": errorResponse("Cobran\xE7a j\xE1 paga ou em estado terminal"),
+          "422": errorResponse("Confirma\xE7\xE3o manual s\xF3 vale para Pix est\xE1tico/offline"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Webhooks
+    // -----------------------------------------------------------------------
+    "/webhooks": {
+      get: {
+        tags: ["Webhooks"],
+        summary: "Listar webhooks da empresa",
+        operationId: "listWebhooks",
+        description: "Lista todos os webhooks da empresa. Webhooks s\xE3o por empresa (n\xE3o por API key) e voc\xEA pode ter v\xE1rios, cada um com seus eventos.",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        responses: { "200": { description: "Lista", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Webhook" } } } } } } }, ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Webhooks"],
+        summary: "Criar webhook",
+        operationId: "createWebhook",
+        description: "Cria um webhook. O secret HMAC-SHA256 \xE9 retornado apenas na cria\xE7\xE3o (guarde-o).",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/WebhookCreate" } } } },
+        responses: {
+          "201": { description: "Webhook criado (inclui secret \xFAnico)", content: { "application/json": { schema: { type: "object", properties: { webhook: { $ref: "#/components/schemas/Webhook" }, secret: { type: "string" } } } } } },
+          "400": errorResponse("Dados inv\xE1lidos"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/webhooks/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Webhooks"],
+        summary: "Obter webhook",
+        operationId: "getWebhookById",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        responses: { "200": { description: "Webhook", content: { "application/json": { schema: { $ref: "#/components/schemas/Webhook" } } } }, "404": errorResponse("N\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      patch: {
+        tags: ["Webhooks"],
+        summary: "Atualizar webhook",
+        operationId: "updateWebhook",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/WebhookCreate" } } } },
+        responses: { "200": { description: "Atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Webhook" } } } }, "404": errorResponse("N\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Webhooks"],
+        summary: "Excluir webhook",
+        operationId: "deleteWebhook",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        responses: { "204": { description: "Exclu\xEDdo" }, "404": errorResponse("N\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/webhooks/events": {
+      get: {
+        tags: ["Webhooks"],
+        summary: "Cat\xE1logo de eventos dispon\xEDveis",
+        operationId: "listWebhookEvents",
+        description: "Lista todos os eventos que um webhook pode assinar (key, label, group).",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        responses: { "200": { description: "Cat\xE1logo", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { type: "object", properties: { key: { type: "string" }, label: { type: "string" }, group: { type: "string" } } } } } } } } }, ...COMMON_ERRORS }
+      }
+    },
+    "/webhooks/{id}/test": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      post: {
+        tags: ["Webhooks"],
+        summary: "Enviar evento de teste",
+        operationId: "testWebhook",
+        description: "Enfileira um evento `webhook.test` direcionado apenas a este webhook (para validar a URL e a verifica\xE7\xE3o de assinatura).",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        responses: { "202": { description: "Teste enfileirado", content: { "application/json": { schema: { type: "object", properties: { message: { type: "string" }, delivery: { type: "object" } } } } } }, "404": errorResponse("Webhook n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/webhooks/payments": {
+      get: {
+        tags: ["Webhooks"],
+        summary: "Obter configura\xE7\xE3o de webhook",
+        operationId: "getWebhook",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        responses: { "200": { description: "Configura\xE7\xE3o atual", content: { "application/json": { schema: { type: "object", properties: { webhook: { oneOf: [{ $ref: "#/components/schemas/Webhook" }, { type: "null" }] } } } } } }, ...COMMON_ERRORS }
+      },
+      put: {
+        tags: ["Webhooks"],
+        summary: "Registrar/atualizar webhook",
+        operationId: "upsertWebhook",
+        description: "Cria ou atualiza a URL de callback. O secret HMAC-SHA256 \xE9 retornado apenas na cria\xE7\xE3o.",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/WebhookCreate" } } } },
+        responses: {
+          "200": { description: "Webhook atualizado", content: { "application/json": { schema: { type: "object", properties: { webhook: { $ref: "#/components/schemas/Webhook" } } } } } },
+          "201": { description: "Webhook criado (inclui secret \xFAnico)", content: { "application/json": { schema: { type: "object", properties: { webhook: { $ref: "#/components/schemas/Webhook" }, secret: { type: "string" } } } } } },
+          "400": errorResponse("URL inv\xE1lida ou eventos inv\xE1lidos"),
+          ...COMMON_ERRORS
+        }
+      },
+      delete: {
+        tags: ["Webhooks"],
+        summary: "Remover webhook",
+        operationId: "deleteWebhook",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        responses: { "200": { description: "Removido" }, "404": errorResponse("Nenhum webhook configurado"), ...COMMON_ERRORS }
+      }
+    },
+    "/webhooks/deliveries": {
+      get: {
+        tags: ["Webhooks"],
+        summary: "Listar entregas de webhook (log)",
+        operationId: "listWebhookDeliveries",
+        description: "Hist\xF3rico de entregas com status, tentativas e erro. Entregas s\xE3o reprocessadas automaticamente com backoff.",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        parameters: [...PAGINATION_PARAMS, { name: "status", in: "query", schema: { type: "string", enum: ["pending", "delivering", "delivered", "failed"] } }, { name: "event", in: "query", schema: { type: "string" } }],
+        responses: { "200": paginatedResponse("#/components/schemas/WebhookDelivery"), ...COMMON_ERRORS }
+      }
+    },
+    "/webhooks/deliveries/{id}/redeliver": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      post: {
+        tags: ["Webhooks"],
+        summary: "Reenviar entrega",
+        operationId: "redeliverWebhook",
+        security: [{ ApiKeyAuth: ["webhooks:manage"] }],
+        responses: { "200": { description: "Re-enfileirada", content: { "application/json": { schema: { $ref: "#/components/schemas/WebhookDelivery" } } } }, "404": errorResponse("Entrega n\xE3o encontrada"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Contas bancárias (read-only)
+    // -----------------------------------------------------------------------
+    "/bank-accounts": {
+      get: {
+        tags: ["Contas banc\xE1rias"],
+        summary: "Listar contas banc\xE1rias",
+        operationId: "listBankAccounts",
+        security: [{ ApiKeyAuth: ["bank_accounts:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } },
+          { name: "account_type", in: "query", schema: { type: "string" } }
+        ],
+        responses: { "200": paginatedResponse("#/components/schemas/BankAccount"), ...COMMON_ERRORS }
+      }
+    },
+    "/bank-accounts/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Contas banc\xE1rias"],
+        summary: "Obter conta banc\xE1ria",
+        operationId: "getBankAccount",
+        security: [{ ApiKeyAuth: ["bank_accounts:read"] }],
+        responses: { "200": { description: "Conta banc\xE1ria", content: { "application/json": { schema: { $ref: "#/components/schemas/BankAccount" } } } }, "404": errorResponse("Conta banc\xE1ria n\xE3o encontrada"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Pagamentos a Fornecedor (Payouts)
+    // -----------------------------------------------------------------------
+    "/payouts": {
+      get: {
+        tags: ["Pagamentos a Fornecedor"],
+        summary: "Listar pagamentos a fornecedor",
+        operationId: "listPayouts",
+        security: [{ ApiKeyAuth: ["payouts:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "status", in: "query", schema: { type: "string", enum: ["pending", "processing", "completed", "failed", "cancelled"] } },
+          { name: "provider", in: "query", schema: { type: "string", enum: ["inter", "c6bank"] } },
+          { name: "method", in: "query", schema: { type: "string", enum: ["pix", "boleto"] } },
+          { name: "bank_account_id", in: "query", schema: { type: "string", format: "uuid" } },
+          { name: "scheduled_from", in: "query", schema: { type: "string", format: "date" } },
+          { name: "scheduled_to", in: "query", schema: { type: "string", format: "date" } }
+        ],
+        responses: { "200": paginatedResponse("#/components/schemas/Payout"), ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Pagamentos a Fornecedor"],
+        summary: "Pagar ou agendar pagamento (Pix/boleto)",
+        operationId: "createPayout",
+        description: "Executa ou agenda um pagamento a fornecedor no provider ativo (Inter/C6). Informe o alvo via purchase_invoice_charge_id, supplier_payment_method_id, pix_key/pix_copia_e_cola ou boleto_barcode.",
+        security: [{ ApiKeyAuth: ["payouts:create"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/PayoutCreate" } } } },
+        responses: {
+          "201": { description: "Pagamento criado/executado", content: { "application/json": { schema: { $ref: "#/components/schemas/Payout" } } } },
+          "400": errorResponse("Dados inv\xE1lidos / alvo ausente"),
+          "404": errorResponse("Conta banc\xE1ria, parcela ou fornecedor n\xE3o encontrado"),
+          "422": errorResponse("Integra\xE7\xE3o n\xE3o configurada ou provider amb\xEDguo"),
+          "502": errorResponse("Erro retornado pelo banco"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/payouts/{id}": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Pagamentos a Fornecedor"],
+        summary: "Obter pagamento",
+        operationId: "getPayout",
+        security: [{ ApiKeyAuth: ["payouts:read"] }],
+        responses: { "200": { description: "Pagamento", content: { "application/json": { schema: { $ref: "#/components/schemas/Payout" } } } }, "404": errorResponse("Pagamento n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/payouts/{id}/cancel": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      post: {
+        tags: ["Pagamentos a Fornecedor"],
+        summary: "Cancelar pagamento agendado",
+        operationId: "cancelPayout",
+        description: "Cancela um pagamento agendado. Pix agendado no Inter n\xE3o \xE9 cancel\xE1vel pela API (retorna 422 \u2014 cancele no Internet Banking).",
+        security: [{ ApiKeyAuth: ["payouts:cancel"] }],
+        responses: { "200": { description: "Cancelado", content: { "application/json": { schema: { $ref: "#/components/schemas/Payout" } } } }, "404": errorResponse("Pagamento n\xE3o encontrado"), "409": errorResponse("N\xE3o pode ser cancelado no estado atual"), "422": errorResponse("Pix Inter \u2014 cancele no Internet Banking"), ...COMMON_ERRORS }
+      }
+    },
+    "/payouts/{id}/sync": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      post: {
+        tags: ["Pagamentos a Fornecedor"],
+        summary: "Sincronizar status com o banco",
+        operationId: "syncPayout",
+        security: [{ ApiKeyAuth: ["payouts:read"] }],
+        responses: { "200": { description: "Status sincronizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Payout" } } } }, "404": errorResponse("Pagamento n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Formas de pagamento do fornecedor
+    // -----------------------------------------------------------------------
+    "/suppliers/{id}/payment-methods": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Formas de pagamento do fornecedor"],
+        summary: "Listar formas de pagamento do fornecedor",
+        operationId: "listSupplierPaymentMethods",
+        security: [{ ApiKeyAuth: ["suppliers:read"] }],
+        responses: { "200": { description: "Formas de pagamento", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/SupplierPaymentMethod" } } } } } } }, "404": errorResponse("Fornecedor n\xE3o encontrado"), ...COMMON_ERRORS }
+      },
+      post: {
+        tags: ["Formas de pagamento do fornecedor"],
+        summary: "Cadastrar forma de pagamento",
+        operationId: "createSupplierPaymentMethod",
+        security: [{ ApiKeyAuth: ["suppliers:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/SupplierPaymentMethodCreate" } } } },
+        responses: { "201": { description: "Criada", content: { "application/json": { schema: { $ref: "#/components/schemas/SupplierPaymentMethod" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Fornecedor n\xE3o encontrado"), ...COMMON_ERRORS }
+      }
+    },
+    "/suppliers/{id}/payment-methods/{methodId}": {
+      parameters: [
+        { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
+        { name: "methodId", in: "path", required: true, schema: { type: "string", format: "uuid" } }
+      ],
+      patch: {
+        tags: ["Formas de pagamento do fornecedor"],
+        summary: "Atualizar forma de pagamento",
+        operationId: "updateSupplierPaymentMethod",
+        security: [{ ApiKeyAuth: ["suppliers:write"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/SupplierPaymentMethodCreate" } } } },
+        responses: { "200": { description: "Atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/SupplierPaymentMethod" } } } }, "404": errorResponse("N\xE3o encontrada"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Formas de pagamento do fornecedor"],
+        summary: "Excluir forma de pagamento",
+        operationId: "deleteSupplierPaymentMethod",
+        security: [{ ApiKeyAuth: ["suppliers:delete"] }],
+        responses: { "204": { description: "Exclu\xEDda" }, "404": errorResponse("N\xE3o encontrada"), "409": errorResponse("H\xE1 registros vinculados que impedem a exclus\xE3o"), ...COMMON_ERRORS }
+      }
+    },
+    // -----------------------------------------------------------------------
+    // Métodos de pagamento (read-only — reusa charges:read)
+    // -----------------------------------------------------------------------
+    "/payment-methods": {
+      get: {
+        tags: ["M\xE9todos de pagamento"],
+        summary: "Listar m\xE9todos de pagamento dispon\xEDveis",
+        operationId: "listPaymentMethods",
+        description: "Lista as formas de recebimento configuradas (Pix, boleto, checkout) por provider. \xDAtil antes de criar uma cobran\xE7a.",
+        security: [{ ApiKeyAuth: ["charges:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } },
+          { name: "provider", in: "query", schema: { type: "string", enum: ["inter", "c6bank"] } },
+          { name: "channel", in: "query", schema: { type: "string", enum: ["pix", "boleto", "checkout"] } }
+        ],
+        responses: { "200": paginatedResponse("#/components/schemas/PaymentMethod"), ...COMMON_ERRORS }
+      }
+    },
+    "/payment-methods/ap": {
+      get: {
+        tags: ["M\xE9todos de pagamento"],
+        summary: "Listar m\xE9todos de pagamento a fornecedor (AP)",
+        operationId: "listPaymentMethodsAp",
+        description: "Formas de pagamento usadas em payouts (contas a pagar).",
+        security: [{ ApiKeyAuth: ["payouts:read"] }],
+        parameters: [
+          ...PAGINATION_PARAMS,
+          { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } },
+          { name: "provider", in: "query", schema: { type: "string", enum: ["inter", "c6bank"] } }
+        ],
+        responses: { "200": paginatedResponse("#/components/schemas/PaymentMethod"), ...COMMON_ERRORS }
+      }
+    }
+  }
+};
+
+// ../../src/lib/apiScopes.ts
+var API_MODULES = [
+  {
+    key: "customers",
+    label: "Clientes",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar clientes e contatos" },
+      { key: "write", label: "Criar e editar", description: "Criar novos clientes e editar dados" },
+      { key: "delete", label: "Excluir", description: "Excluir clientes permanentemente" }
+    ]
+  },
+  {
+    key: "proposals",
+    label: "Propostas",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar propostas comerciais" },
+      { key: "write", label: "Criar e editar", description: "Criar e editar propostas" },
+      { key: "send", label: "Enviar", description: "Enviar propostas por e-mail ou WhatsApp" },
+      { key: "delete", label: "Excluir", description: "Excluir propostas" }
+    ]
+  },
+  {
+    key: "invoices",
+    label: "Faturas / Cobran\xE7as",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar faturas e cobran\xE7as" },
+      { key: "create", label: "Criar cobran\xE7a", description: "Gerar boletos, Pix e cobran\xE7as" },
+      { key: "cancel", label: "Cancelar cobran\xE7a", description: "Cancelar cobran\xE7as em aberto" }
+    ]
+  },
+  {
+    key: "nfse",
+    label: "NFS-e",
+    permissions: [
+      { key: "read", label: "Consultar notas", description: "Listar e visualizar notas fiscais" },
+      { key: "emitir", label: "Emitir nota", description: "Emitir notas fiscais de servi\xE7o" },
+      { key: "cancelar", label: "Cancelar nota", description: "Cancelar notas fiscais emitidas" }
+    ]
+  },
+  {
+    key: "finance",
+    label: "Financeiro",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar lan\xE7amentos e extratos" },
+      { key: "write", label: "Criar e editar", description: "Lan\xE7ar e editar movimenta\xE7\xF5es" },
+      { key: "delete", label: "Excluir", description: "Excluir lan\xE7amentos" }
+    ]
+  },
+  {
+    key: "contracts",
+    label: "Contratos",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar contratos" },
+      { key: "write", label: "Criar e editar", description: "Criar e editar contratos" },
+      { key: "delete", label: "Excluir", description: "Excluir contratos" }
+    ]
+  },
+  {
+    key: "suppliers",
+    label: "Fornecedores",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar fornecedores" },
+      { key: "write", label: "Criar e editar", description: "Criar e editar fornecedores" },
+      { key: "delete", label: "Excluir", description: "Excluir fornecedores" }
+    ]
+  },
+  {
+    key: "services",
+    label: "Servi\xE7os",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar o cat\xE1logo de servi\xE7os" },
+      { key: "write", label: "Criar e editar", description: "Criar e editar servi\xE7os" },
+      { key: "delete", label: "Excluir", description: "Excluir servi\xE7os" }
+    ]
+  },
+  {
+    key: "expenses",
+    label: "Despesas",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar despesas" },
+      { key: "write", label: "Criar e editar", description: "Lan\xE7ar e editar despesas" },
+      { key: "delete", label: "Excluir", description: "Excluir despesas" }
+    ]
+  },
+  {
+    key: "purchase_invoices",
+    label: "Contas a Pagar",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar contas a pagar" },
+      { key: "create", label: "Criar", description: "Lan\xE7ar contas a pagar" },
+      { key: "cancel", label: "Cancelar", description: "Cancelar contas a pagar" }
+    ]
+  },
+  {
+    key: "charges",
+    label: "Cobran\xE7as / Gateway",
+    permissions: [
+      { key: "read", label: "Consultar cobran\xE7as", description: "Listar e visualizar cobran\xE7as geradas via API" },
+      { key: "create", label: "Criar cobran\xE7a", description: "Gerar Pix, boleto ou checkout de pagamento" },
+      { key: "cancel", label: "Cancelar cobran\xE7a", description: "Cancelar cobran\xE7as em aberto" },
+      { key: "refund", label: "Estornar cobran\xE7a", description: "Devolver (estornar) cobran\xE7as Pix pagas" }
+    ]
+  },
+  {
+    key: "webhooks",
+    label: "Webhooks",
+    permissions: [
+      { key: "manage", label: "Gerenciar webhooks", description: "Registrar e configurar URLs de callback para eventos de pagamento" }
+    ]
+  },
+  {
+    key: "bank_accounts",
+    label: "Contas banc\xE1rias",
+    permissions: [
+      { key: "read", label: "Listar e visualizar", description: "Consultar contas banc\xE1rias (somente leitura, sem dados sens\xEDveis)" }
+    ]
+  },
+  {
+    key: "payouts",
+    label: "Pagamentos a Fornecedor",
+    permissions: [
+      { key: "read", label: "Consultar pagamentos", description: "Listar e visualizar pagamentos a fornecedores" },
+      { key: "create", label: "Pagar / agendar", description: "Executar ou agendar pagamentos Pix e boleto a fornecedores" },
+      { key: "cancel", label: "Cancelar agendamento", description: "Cancelar pagamentos agendados" }
+    ]
+  }
+];
+var ALL_SCOPES = API_MODULES.flatMap(
+  (m) => m.permissions.map((p) => `${m.key}:${p.key}`)
+);
+
+// src/spec.ts
+var spec = OPENAPI_SPEC;
+var HTTP_METHODS = ["get", "post", "patch", "put", "delete"];
+function indexByOperationId() {
+  const map = /* @__PURE__ */ new Map();
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    for (const method of HTTP_METHODS) {
+      const operation = methods[method];
+      if (!operation?.operationId) continue;
+      if (!map.has(operation.operationId)) {
+        map.set(operation.operationId, { method: method.toUpperCase(), path, operation });
+      }
+    }
+  }
+  return map;
+}
+
+// src/schema-from-spec.ts
+var SCHEMA_REF_PREFIX = "#/components/schemas/";
+function resolveRef(ref) {
+  if (!ref.startsWith(SCHEMA_REF_PREFIX)) {
+    throw new Error(`Ref n\xE3o suportado: ${ref}`);
+  }
+  const name = ref.slice(SCHEMA_REF_PREFIX.length);
+  const schema = spec.components.schemas[name];
+  if (!schema) throw new Error(`Schema n\xE3o encontrado em components: ${name}`);
+  return schema;
+}
+function extractScopes(operation) {
+  const sec = operation.security;
+  if (!Array.isArray(sec) || sec.length === 0) return [];
+  const first = sec[0];
+  const scopes = first?.ApiKeyAuth;
+  return Array.isArray(scopes) ? scopes.filter(Boolean) : [];
+}
+function describeOperation(operationId) {
+  const idx = indexByOperationId();
+  const found = idx.get(operationId);
+  if (!found) throw new Error(`operationId n\xE3o encontrado no spec: ${operationId}`);
+  const { method, path, operation } = found;
+  const properties = {};
+  const required = [];
+  const pathParams = [];
+  const queryParams = [];
+  const pathItem = spec.paths[path];
+  const declared = [
+    ...(Array.isArray(pathItem.parameters) ? pathItem.parameters : []) ?? [],
+    ...operation.parameters ?? []
+  ];
+  const declaredByName = new Map(declared.map((p) => [p.name, p]));
+  for (const m of path.matchAll(/\{([^}]+)\}/g)) {
+    const name = m[1];
+    if (pathParams.includes(name)) continue;
+    pathParams.push(name);
+    const d = declaredByName.get(name);
+    properties[name] = {
+      ...d?.schema ?? { type: "string" },
+      description: d?.description ?? `Identificador (${name}).`
+    };
+    required.push(name);
+  }
+  for (const p of declared) {
+    if (p.in !== "query" || queryParams.includes(p.name)) continue;
+    queryParams.push(p.name);
+    properties[p.name] = { ...p.schema, ...p.description ? { description: p.description } : {} };
+  }
+  let hasBody = false;
+  const rb = operation.requestBody;
+  const bodySchemaRef = rb?.content?.["application/json"]?.schema;
+  if (bodySchemaRef) {
+    hasBody = true;
+    let bodySchema;
+    if (bodySchemaRef.$ref) {
+      bodySchema = resolveRef(bodySchemaRef.$ref);
+    } else {
+      bodySchema = bodySchemaRef;
+    }
+    properties.body = {
+      ...bodySchema,
+      description: "Corpo da requisi\xE7\xE3o (JSON)."
+    };
+    if (rb?.required) required.push("body");
+  }
+  const inputSchema = {
+    type: "object",
+    properties,
+    ...required.length ? { required } : {}
+  };
+  return {
+    operationId,
+    method,
+    pathTemplate: path,
+    pathParams,
+    queryParams,
+    hasBody,
+    scopes: extractScopes(operation),
+    inputSchema,
+    summary: operation.summary,
+    description: operation.description
+  };
+}
+function buildPath(desc, args) {
+  let path = desc.pathTemplate;
+  for (const name of desc.pathParams) {
+    const val = args[name];
+    if (val === void 0 || val === null || val === "") {
+      throw new Error(`Par\xE2metro de path obrigat\xF3rio ausente: ${name}`);
+    }
+    path = path.replace(`{${name}}`, encodeURIComponent(String(val)));
+  }
+  const query = [];
+  for (const name of desc.queryParams) {
+    const val = args[name];
+    if (val !== void 0 && val !== null && val !== "") {
+      query.push(`${encodeURIComponent(name)}=${encodeURIComponent(String(val))}`);
+    }
+  }
+  return query.length ? `${path}?${query.join("&")}` : path;
+}
+
+// src/safety.ts
+function ok(payload) {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function fail(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function errorResult(err) {
+  if (err instanceof ComandoApiError) {
+    const payload = { error: true, status: err.status, body: err.body };
+    if (err.status === 429) {
+      payload.hint = "Rate limit excedido (60 req/min). Aguarde a janela reabrir antes de tentar de novo.";
+    }
+    if (err.status === 403) {
+      payload.hint = "Acesso negado: a chave de API n\xE3o tem o scope necess\xE1rio para esta opera\xE7\xE3o.";
+    }
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], isError: true };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return fail(message);
+}
+function augmentInputSchema(schema, opts) {
+  const properties = { ...schema.properties };
+  if (!properties.company_id) {
+    properties.company_id = {
+      type: "string",
+      description: "Opcional: UUID da empresa para esta chamada (sobrescreve a empresa padr\xE3o)."
+    };
+  }
+  if (opts.write) {
+    properties.idempotency_key = {
+      type: "string",
+      description: "Opcional: chave de idempot\xEAncia para evitar duplica\xE7\xE3o em retentativas."
+    };
+    properties.dry_run = {
+      type: "boolean",
+      description: "Se true, n\xE3o executa \u2014 apenas retorna o m\xE9todo, path e corpo que seriam enviados."
+    };
+  }
+  if (opts.destructive) {
+    properties.confirm = {
+      type: "boolean",
+      description: "OBRIGAT\xD3RIO ser true para executar esta a\xE7\xE3o destrutiva. Sem isso, a chamada \xE9 recusada."
+    };
+  }
+  return { ...schema, properties };
+}
+function destructiveBlocked(args) {
+  if (args.confirm === true) return null;
+  return fail(
+    "A\xE7\xE3o destrutiva bloqueada. Passe confirm: true para executar, ou dry_run: true para ver o que seria enviado sem executar."
+  );
+}
+
+// src/tool-def.ts
+function asInputSchema(schema) {
+  return schema;
+}
+
+// src/tools/curated.ts
+function buildCuratedTools(api, heldScopes) {
+  const tools = [];
+  const skipped = [];
+  for (const entry of MANIFEST) {
+    let desc;
+    try {
+      desc = describeOperation(entry.operationId);
+    } catch (err) {
+      process.stderr.write(`[comando-mcp] aviso: ${entry.operationId} n\xE3o est\xE1 no spec (${String(err)})
+`);
+      continue;
+    }
+    const missing = desc.scopes.filter((s) => !heldScopes.has(s));
+    if (missing.length > 0) {
+      skipped.push({ tool: entry.tool, missingScopes: missing });
+      continue;
+    }
+    const inputSchema = augmentInputSchema(desc.inputSchema, {
+      write: entry.write,
+      destructive: entry.destructive
+    });
+    const scopeNote = desc.scopes.length ? ` Scopes: ${desc.scopes.join(", ")}.` : "";
+    const prefix = entry.destructive ? "[DESTRUTIVA] " : "";
+    const description = `${prefix}${desc.summary ?? entry.operationId}.${scopeNote}`;
+    tools.push({
+      name: entry.tool,
+      description,
+      inputSchema: asInputSchema(inputSchema),
+      handler: async (args) => {
+        try {
+          if (entry.destructive) {
+            const blocked = destructiveBlocked(args);
+            if (blocked && args.dry_run !== true) return blocked;
+          }
+          const path = buildPath(desc, args);
+          const body = desc.hasBody ? args.body : void 0;
+          if (args.dry_run === true) {
+            return ok({
+              dry_run: true,
+              method: desc.method,
+              path,
+              body: body ?? null
+            });
+          }
+          const result = await api.request(desc.method, path, {
+            body,
+            companyId: typeof args.company_id === "string" ? args.company_id : void 0,
+            idempotencyKey: typeof args.idempotency_key === "string" ? args.idempotency_key : void 0
+          });
+          return ok(result ?? { ok: true });
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    });
+  }
+  return { tools, skipped };
+}
+
+// src/tools/request.ts
+var METHODS = ["GET", "POST", "PATCH", "PUT", "DELETE"];
+function buildRequestTool(api) {
+  return {
+    name: "comando_request",
+    description: "Chamada gen\xE9rica \xE0 API do Comando.One (cobre qualquer endpoint /v1/*). Use quando n\xE3o houver uma tool espec\xEDfica. Ex.: method=GET, path=/webhooks/deliveries. Os scopes da chave s\xE3o validados pelo servidor.",
+    inputSchema: {
+      type: "object",
+      required: ["method", "path"],
+      properties: {
+        method: { type: "string", enum: [...METHODS], description: "M\xE9todo HTTP." },
+        path: {
+          type: "string",
+          description: "Path relativo iniciando em /, ex.: /customers ou /charges/uuid. N\xC3O inclua /v1."
+        },
+        query: {
+          type: "object",
+          description: "Par\xE2metros de query (pares chave/valor). Ex.: { page: 1, per_page: 20 }.",
+          additionalProperties: true
+        },
+        body: { type: "object", description: "Corpo JSON (para POST/PATCH/PUT).", additionalProperties: true },
+        company_id: { type: "string", description: "Opcional: UUID da empresa (header X-Company-Id)." },
+        idempotency_key: { type: "string", description: "Opcional: chave de idempot\xEAncia (POST)." },
+        dry_run: { type: "boolean", description: "Se true, n\xE3o executa \u2014 s\xF3 mostra o que seria enviado." }
+      }
+    },
+    handler: async (args) => {
+      try {
+        const method = String(args.method ?? "").toUpperCase();
+        if (!METHODS.includes(method)) {
+          return fail(`M\xE9todo inv\xE1lido: ${args.method}. Use um de: ${METHODS.join(", ")}.`);
+        }
+        let path = String(args.path ?? "");
+        if (!path.startsWith("/")) return fail("path deve come\xE7ar com / (ex.: /customers).");
+        if (args.query && typeof args.query === "object") {
+          const u = new URLSearchParams();
+          for (const [k, v] of Object.entries(args.query)) {
+            if (v !== void 0 && v !== null && v !== "") u.set(k, String(v));
+          }
+          const s = u.toString();
+          if (s) path += (path.includes("?") ? "&" : "?") + s;
+        }
+        const body = args.body && typeof args.body === "object" ? args.body : void 0;
+        if (args.dry_run === true) {
+          return ok({ dry_run: true, method, path, body: body ?? null });
+        }
+        const result = await api.request(method, path, {
+          body,
+          companyId: typeof args.company_id === "string" ? args.company_id : void 0,
+          idempotencyKey: typeof args.idempotency_key === "string" ? args.idempotency_key : void 0
+        });
+        return ok(result ?? { ok: true });
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  };
+}
+
+// src/tools/lookups.ts
+var KINDS = {
+  "cost-centers": "/cost-centers",
+  "payment-conditions": "/payment-conditions",
+  "service-units": "/service-units",
+  "payment-methods": "/payment-methods",
+  "payment-methods-ap": "/payment-methods/ap",
+  natures: "/finance/natures",
+  "bank-accounts": "/bank-accounts"
+};
+function buildLookupsTool(api) {
+  return {
+    name: "lookups",
+    description: "Consulta cat\xE1logos read-only do ERP: centros de custo, condi\xE7\xF5es/m\xE9todos de pagamento, unidades de servi\xE7o, naturezas financeiras e contas banc\xE1rias.",
+    inputSchema: {
+      type: "object",
+      required: ["kind"],
+      properties: {
+        kind: {
+          type: "string",
+          enum: Object.keys(KINDS),
+          description: "Qual cat\xE1logo consultar."
+        },
+        page: { type: "integer", minimum: 1, description: "P\xE1gina (default 1)." },
+        per_page: { type: "integer", minimum: 1, maximum: 100, description: "Itens por p\xE1gina (default 20)." },
+        company_id: { type: "string", description: "Opcional: UUID da empresa (X-Company-Id)." }
+      }
+    },
+    handler: async (args) => {
+      try {
+        const kind = String(args.kind ?? "");
+        const base = KINDS[kind];
+        if (!base) return fail(`kind inv\xE1lido: ${kind}. Use um de: ${Object.keys(KINDS).join(", ")}.`);
+        const u = new URLSearchParams();
+        if (args.page) u.set("page", String(args.page));
+        if (args.per_page) u.set("per_page", String(args.per_page));
+        const q = u.toString();
+        const path = q ? `${base}?${q}` : base;
+        const result = await api.get(path, {
+          companyId: typeof args.company_id === "string" ? args.company_id : void 0
+        });
+        return ok(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  };
+}
+
+// src/tools/whoami.ts
+function buildWhoamiTool(api) {
+  return {
+    name: "whoami",
+    description: "Retorna a identidade da chave de API: empresa atual, empresas acess\xEDveis, scopes concedidos e se \xE9 multi-empresa.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => {
+      try {
+        return ok(await api.me());
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  };
+}
+
+// src/index.ts
+function loadDotEnv() {
+  try {
+    const raw = readFileSync(new URL("../.env", import.meta.url), "utf8");
+    for (const line of raw.split("\n")) {
+      const m = line.match(/^\s*([\w.-]+)\s*=\s*(.*)\s*$/);
+      if (!m) continue;
+      const key = m[1];
+      let val = m[2];
+      if (val.startsWith('"') && val.endsWith('"') || val.startsWith("'") && val.endsWith("'")) {
+        val = val.slice(1, -1);
+      }
+      if (process.env[key] === void 0) process.env[key] = val;
+    }
+  } catch {
+  }
+}
+function die(msg) {
+  process.stderr.write(`[comando-mcp] ${msg}
+`);
+  process.exit(1);
+}
+async function main() {
+  loadDotEnv();
+  const apiKey = process.env.COMANDO_API_KEY;
+  const baseUrl = process.env.COMANDO_BASE_URL || "https://api.comando.one/v1";
+  const companyId = process.env.COMANDO_COMPANY_ID || void 0;
+  if (!apiKey) {
+    die("COMANDO_API_KEY ausente. Defina a vari\xE1vel de ambiente com sua chave cmd_live_...");
+  }
+  const api = new ComandoApi({ apiKey, baseUrl, companyId, autoIdempotency: true });
+  let heldScopes = /* @__PURE__ */ new Set();
+  let companyName = "?";
+  try {
+    const me = await api.me();
+    heldScopes = new Set(me.api_key?.scopes ?? []);
+    companyName = me.company?.name ?? "?";
+  } catch (err) {
+    die(`Falha ao validar a chave em ${baseUrl}/me \u2014 ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const tools = [];
+  tools.push(buildWhoamiTool(api));
+  const { tools: curated, skipped } = buildCuratedTools(api, heldScopes);
+  tools.push(...curated);
+  tools.push(buildLookupsTool(api));
+  tools.push(buildRequestTool(api));
+  const byName = new Map(tools.map((t) => [t.name, t]));
+  process.stderr.write(
+    `[comando-mcp] empresa="${companyName}" scopes=${heldScopes.size} tools=${tools.length} (curadas=${curated.length}, ocultas-por-scope=${skipped.length})
+`
+  );
+  const server = new Server(
+    { name: "comando-one", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = byName.get(req.params.name);
+    if (!tool) {
+      return { content: [{ type: "text", text: `Tool desconhecida: ${req.params.name}` }], isError: true };
+    }
+    const args = req.params.arguments ?? {};
+    const result = await tool.handler(args);
+    return result;
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("[comando-mcp] pronto (stdio).\n");
+}
+main().catch((err) => die(err instanceof Error ? err.message : String(err)));