@comando.one/mcp-server 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +12 -7
  2. package/dist/index.js +93 -41
  3. package/package.json +3 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @comando.one/mcp-server
2
2
 
3
- Servidor **MCP (Model Context Protocol)** para a API pública do **Comando1**. Conecte o Claude (Desktop, Code ou qualquer cliente MCP) ao seu ERP e **opere tudo por linguagem natural**: clientes, propostas, contratos, faturas, cobranças Pix/boleto, NFS-e, contas a pagar, financeiro e webhooks.
3
+ Servidor **MCP (Model Context Protocol)** para a API pública do **Comando1**. Conecte o Claude (Desktop, Code ou qualquer cliente MCP) ao seu ERP e **opere tudo por linguagem natural**: clientes, propostas, contratos e reajustes, faturas e baixas, cobranças Pix/boleto, NFS-e, contas a pagar, pagamentos a fornecedor e split, financeiro e conciliação, caixa de entrada, DDA, recorrências, insumos, lembretes, notificações, relatórios e webhooks.
4
4
 
5
5
  ## Instalação rápida (Claude Desktop)
6
6
 
@@ -25,7 +25,11 @@ Gere sua chave em **Configurações → API Keys** no app. Reinicie o Claude Des
25
25
 
26
26
  ## Alternativa: MCP remoto (sem instalar nada)
27
27
 
28
- Além deste pacote stdio, existe um **endpoint MCP remoto (streaming)** em `https://api.comando.one/mcp` (transporte MCP Streamable HTTP). Para clientes com conector remoto:
28
+ Além deste pacote stdio, existe um **endpoint MCP remoto (streaming)** em `https://api.comando.one/mcp` (transporte MCP Streamable HTTP).
29
+
30
+ **Com OAuth (recomendado):** no Claude (Desktop ou web), ChatGPT e outros clientes com conector remoto, basta colar a URL `https://api.comando.one/mcp` — o cliente abre o navegador, você entra no Comando1, escolhe a empresa e autoriza. Não há chave para copiar.
31
+
32
+ **Com chave de API**, para clientes que aceitam cabeçalho fixo:
29
33
 
30
34
  ```json
31
35
  {
@@ -39,7 +43,7 @@ Além deste pacote stdio, existe um **endpoint MCP remoto (streaming)** em `http
39
43
  }
40
44
  ```
41
45
 
42
- Ambos expõem o **mesmo conjunto de ferramentas** (131 curadas + `lookups` + `comando_request` = cobertura total da API).
46
+ Ambos expõem as mesmas ferramentas: **169 tools curadas** (uma por operação da API) + `lookups` + `comando_request`. Só o stdio tem `whoami`.
43
47
 
44
48
  ## Variáveis de ambiente
45
49
 
@@ -51,8 +55,8 @@ Ambos expõem o **mesmo conjunto de ferramentas** (131 curadas + `lookups` + `co
51
55
 
52
56
  ## Como funciona
53
57
 
54
- - **136 tools curadas** (gerados a partir do OpenAPI canônico, zero drift) cobrindo as operações de maior valor — `customers_list`, `invoices_create`/`invoices_delete`, `charges_create`, `nfse_emit`, `payouts_create`, `contracts_pause`/`contracts_resume`, `service_categories_create`, `reports_aging_actions`/`reports_cashflow_forecast`, `audit_timeline`, `documents_analyze` (lê boleto/guia/NF anexada e extrai valor, vencimento e emitente), `cost_centers_create`, `invoices_settle_charge` (dá baixa numa parcela — registra o recebimento), etc.
55
- - **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`) que cobre 100% dos endpoints restantes.
58
+ - **169 tools curadas** (geradas a partir do OpenAPI canônico, zero drift) — uma por operação da API, por exemplo `customers_list`, `invoices_create`/`invoices_delete`, `charges_create`, `nfse_emit`, `payouts_create`, `contracts_pause`/`contracts_resume`, `service_categories_create`, `reports_aging_actions`/`reports_cashflow_forecast`, `audit_timeline`, `documents_analyze` (lê boleto/guia/NF anexada e extrai valor, vencimento e emitente), `cost_centers_create`, `invoices_settle_charge` (dá baixa numa parcela — registra o recebimento), etc.
59
+ - **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`) para qualquer rota; as destrutivas continuam exigindo `confirm`.
56
60
  - **`lookups`** — catálogos read-only (centros de custo, condições/métodos de pagamento, naturezas, contas bancárias).
57
61
  - **`whoami`** — identidade, empresas acessíveis e scopes da chave.
58
62
  - **Nomes em português** — cada tool viaja com `title` (e `annotations.title`) vindo do
@@ -62,8 +66,9 @@ Ambos expõem o **mesmo conjunto de ferramentas** (131 curadas + `lookups` + `co
62
66
 
63
67
  ### Segurança
64
68
 
65
- - **Scope-gating**: ao iniciar, o servidor chama `/me` e **só expõe as tools cujos scopes a chave possui**.
66
- - **Ações destrutivas** (`*_delete`, `*_cancel`, `charges_refund`, `payouts_create`) exigem `confirm: true` para executar e aceitam `dry_run: true` para pré-visualizar a requisição sem enviá-la.
69
+ - **Scope-gating**: ao iniciar, o servidor chama `/me` e **só expõe as tools cujos scopes a chave possui**. Quando a operação aceita mais de um scope (ex.: `cost_centers_list` com `expenses:read` **ou** `finance:read`), basta um deles.
70
+ - **Ações destrutivas** — exclusões e cancelamentos, estornos (`charges_refund`, `invoices_reverse_payment`, `split_reverse`), pagamentos (`payouts_create`), reajustes (`contracts_readjustments_apply`/`_revert`), `reconciliation_unmatch` e afins; a descrição da tool começa com `[DESTRUTIVA]` — exigem `confirm: true` para executar e aceitam `dry_run: true` para pré-visualizar a requisição sem enviá-la.
71
+ - **2FA de pagamento**: se a empresa exige 2FA para movimentar dinheiro, pagamentos, estornos e liberação de repasse feitos só com chave de API são recusados (403) — a verificação é humana.
67
72
  - **Idempotência** automática em POSTs (evita cobrança/pagamento duplicado); aceita `idempotency_key` explícito.
68
73
  - **Multi-empresa**: qualquer tool aceita `company_id` para sobrescrever a empresa por chamada.
69
74
 
package/dist/index.js CHANGED
@@ -142,6 +142,7 @@ var MANIFEST = [
142
142
  { operationId: "listInvoices", tool: "invoices_list" },
143
143
  { operationId: "getInvoice", tool: "invoices_get" },
144
144
  { operationId: "createInvoice", tool: "invoices_create", write: true },
145
+ { operationId: "patchInvoice", tool: "invoices_update", write: true },
145
146
  { operationId: "cancelInvoice", tool: "invoices_cancel", write: true, destructive: true },
146
147
  { operationId: "sendInvoiceSecondCopy", tool: "invoices_send", write: true },
147
148
  { operationId: "setInvoiceAutoSend", tool: "invoices_set_auto_send", write: true },
@@ -277,7 +278,8 @@ var MANIFEST = [
277
278
  { operationId: "listFinancialNatures", tool: "finance_list_natures" },
278
279
  { operationId: "deleteFinancialMovement", tool: "finance_delete_movement", write: true, destructive: true },
279
280
  // Módulos operacionais que tinham tela e nenhuma exposição (COBERTURA.md item 1).
280
- // Somente leitura — escrever em conciliação/cartão/DDA mexe em dinheiro e entra depois.
281
+ // As escritas destes módulos (status da caixa, conciliar/desfazer, triagem do DDA, insumos,
282
+ // notificação lida) vêm primeiro; a leitura, em seguida.
281
283
  { operationId: "updateInboxMessageStatus", tool: "inbox_messages_update_status", write: true },
282
284
  { operationId: "resolveStatementEntry", tool: "reconciliation_resolve", write: true },
283
285
  { operationId: "deleteReconciliationMatch", tool: "reconciliation_unmatch", write: true, destructive: true },
@@ -949,6 +951,7 @@ var SCHEMAS = {
949
951
  method: { type: "string", enum: ["pix", "boleto", "checkout", "credit_card"], description: "Canal de pagamento" },
950
952
  provider: { type: "string", enum: ["inter", "c6bank", "pix_offline", "pagarme", "cora"], description: "Opcional. Desambigua quando a empresa tem mais de um provedor no mesmo canal (ex.: Pix Inter x Pix Pagar.me x Pix Cora). Se omitido, usa o provedor ativo do canal." },
951
953
  invoice_id: { type: "string", format: "uuid", description: "Fatura existente (opcional)" },
954
+ charge_id: { type: "string", format: "uuid", description: "PARCELA da fatura a cobrar (invoice_charges.id \u2014 veja GET /v1/invoices/{id}/charges). S\xF3 vale com invoice_id. Quando informado, a cobran\xE7a sai com o VALOR e o VENCIMENTO da parcela e fica amarrada a ela, que \xE9 o que d\xE1 baixa certa quando o dinheiro entra. Omitido, a cobran\xE7a \xE9 no n\xEDvel da fatura (valor cheio) \u2014 numa fatura parcelada isso normalmente n\xE3o \xE9 o que se quer." },
952
955
  customer_id: { type: "string", format: "uuid", description: "Obrigat\xF3rio se invoice_id omitido" },
953
956
  amount: { type: "number", description: "Obrigat\xF3rio se invoice_id omitido" },
954
957
  due_date: { type: "string", format: "date", description: "Obrigat\xF3rio se invoice_id omitido" },
@@ -1226,6 +1229,19 @@ var SCHEMAS = {
1226
1229
  account_type: { type: ["string", "null"] },
1227
1230
  is_primary: { type: "boolean" },
1228
1231
  active: { type: "boolean" },
1232
+ opening_balance: { type: ["number", "null"], description: "Saldo de fechamento conhecido no dia opening_balance_date. \xC2ncora do saldo calculado." },
1233
+ opening_balance_date: { type: ["string", "null"], format: "date", description: "Data do saldo informado em opening_balance." },
1234
+ saldo_calculado: {
1235
+ type: ["object", "null"],
1236
+ description: "S\xF3 no detalhe (GET /v1/bank-accounts/{id}). Saldo da \xE2ncora somado ao extrato importado a partir do dia seguinte. \xC9 nulo quando a conta n\xE3o tem \xE2ncora \u2014 sem ela n\xE3o existe saldo, e a API n\xE3o devolve um n\xFAmero que seria mentira. Serve aos bancos que n\xE3o publicam saldo (o C6 n\xE3o exp\xF5e saldo em nenhuma das suas APIs).",
1237
+ properties: {
1238
+ saldo: { type: "number" },
1239
+ base: { type: "number" },
1240
+ base_date: { type: "string", format: "date" },
1241
+ qtd_lancamentos: { type: "integer" },
1242
+ ultimo_lancamento: { type: ["string", "null"], format: "date" }
1243
+ }
1244
+ },
1229
1245
  created_at: { type: "string", format: "date-time" },
1230
1246
  updated_at: { type: "string", format: "date-time" }
1231
1247
  }
@@ -1709,12 +1725,17 @@ var COMMON_ERRORS = {
1709
1725
  "429": errorResponse("Rate limit excedido (60 req/min por padr\xE3o)"),
1710
1726
  "500": errorResponse("Erro interno")
1711
1727
  };
1728
+ var STEP_UP_NOTE = " 2FA: se a empresa exige verifica\xE7\xE3o em duas etapas para movimentar dinheiro (Configura\xE7\xF5es \u2192 Seguran\xE7a), uma chave de API sem usu\xE1rio recebe 403; pelo chat ou por OAuth \xE9 preciso enviar o cabe\xE7alho X-Payment-Step-Up-Grant, emitido pela verifica\xE7\xE3o 2FA no app.";
1729
+ var STEP_UP_ERRORS = {
1730
+ ...COMMON_ERRORS,
1731
+ "403": errorResponse("Scope insuficiente, ou a empresa exige 2FA para movimentar dinheiro (ver descri\xE7\xE3o)")
1732
+ };
1712
1733
  var OPENAPI_SPEC = {
1713
1734
  openapi: "3.1.0",
1714
1735
  info: {
1715
1736
  title: "Comando1 API",
1716
1737
  version: "1.1.0",
1717
- description: "API REST p\xFAblica do Comando1 \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.",
1738
+ description: "API REST p\xFAblica do Comando1 \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**Erros:** toda falha devolve JSON com `error` (texto acion\xE1vel, em portugu\xEAs). `424 Failed Dependency` = a requisi\xE7\xE3o estava correta, mas um terceiro falhou \u2014 o fisco, o banco, o gateway de pagamento; o motivo do terceiro vem em `error`. A API nunca responde 502/504: a borda da Cloudflare substituiria o corpo pela p\xE1gina HTML dela e o motivo se perderia.\n\n**N\xE3o existe ambiente de homologa\xE7\xE3o.** S\xF3 h\xE1 chaves `cmd_live_`, e toda emiss\xE3o de NFS-e \xE9 documento fiscal real. Para ensaiar a integra\xE7\xE3o sem gerar documento, exercite os caminhos que RECUSAM (payload incompleto, fatura inexistente) e confira o XML antes pela tela do sistema.\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.",
1718
1739
  contact: { email: "contato@comando.one", url: "https://comando.one" },
1719
1740
  license: { name: "Propriet\xE1rio" }
1720
1741
  },
@@ -1839,7 +1860,8 @@ var OPENAPI_SPEC = {
1839
1860
  parameters: [
1840
1861
  ...PAGINATION_PARAMS,
1841
1862
  { name: "search", in: "query", schema: { type: "string" }, description: "Busca por nome, e-mail ou documento" },
1842
- { name: "status", in: "query", schema: { type: "string" }, description: "Filtrar por status" }
1863
+ { name: "status", in: "query", schema: { type: "string" }, description: "Filtrar por status" },
1864
+ { name: "type", in: "query", schema: { type: "string", enum: ["fisica", "juridica", "estrangeira"] }, description: "Filtrar por tipo de pessoa" }
1843
1865
  ],
1844
1866
  responses: {
1845
1867
  "200": paginatedResponse("#/components/schemas/Customer"),
@@ -2326,6 +2348,26 @@ var OPENAPI_SPEC = {
2326
2348
  ...COMMON_ERRORS
2327
2349
  }
2328
2350
  },
2351
+ patch: {
2352
+ tags: ["Faturas"],
2353
+ summary: "Corrigir fatura",
2354
+ operationId: "patchInvoice",
2355
+ description: "Corrige o cabe\xE7alho de uma fatura j\xE1 criada. Existe para n\xE3o ser preciso APAGAR a fatura (e estornar a baixa antes) s\xF3 para trocar um status.\n\nEscopo estreito de prop\xF3sito: para cancelar use `PATCH /v1/invoices/{id}/cancel` \u2014 o cancelamento tem efeitos que uma troca de status n\xE3o dispara. O vencimento n\xE3o muda aqui: quem cobra \xE9 a parcela (`invoice_charges`), e mexer s\xF3 no cabe\xE7alho daria a impress\xE3o de ter mudado a cobran\xE7a sem mudar nada do que \xE9 cobrado.",
2356
+ security: [{ ApiKeyAuth: ["invoices:create"] }],
2357
+ requestBody: {
2358
+ content: { "application/json": { schema: { type: "object", properties: {
2359
+ status: { type: "string", enum: ["rascunho", "enviada", "aceita", "ativa"] },
2360
+ title: { type: ["string", "null"] }
2361
+ } } } }
2362
+ },
2363
+ responses: {
2364
+ "200": { description: "Fatura atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/Invoice" } } } },
2365
+ "400": errorResponse("Nenhum campo aceito foi enviado, ou status inv\xE1lido"),
2366
+ "404": errorResponse("Fatura n\xE3o encontrada"),
2367
+ "409": errorResponse('status "cancelada" (use /cancel), ou a fatura j\xE1 est\xE1 cancelada'),
2368
+ ...COMMON_ERRORS
2369
+ }
2370
+ },
2329
2371
  delete: {
2330
2372
  tags: ["Faturas"],
2331
2373
  summary: "Excluir fatura",
@@ -2663,7 +2705,7 @@ var OPENAPI_SPEC = {
2663
2705
  summary: "Listar naturezas financeiras",
2664
2706
  operationId: "listFinancialNatures",
2665
2707
  description: "IDs usados em POST /v1/finance/movements (nature_id).",
2666
- security: [{ ApiKeyAuth: ["finance:read", "finance:write"] }],
2708
+ security: [{ ApiKeyAuth: ["finance:read"] }, { ApiKeyAuth: ["finance:write"] }],
2667
2709
  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"] } }],
2668
2710
  responses: { "200": paginatedResponse("#/components/schemas/FinancialNature"), ...COMMON_ERRORS }
2669
2711
  }
@@ -2674,7 +2716,7 @@ var OPENAPI_SPEC = {
2674
2716
  summary: "Listar centros de custo",
2675
2717
  operationId: "listCostCenters",
2676
2718
  description: "IDs usados em despesas (category_id).",
2677
- security: [{ ApiKeyAuth: ["expenses:read", "expenses:write", "finance:read"] }],
2719
+ security: [{ ApiKeyAuth: ["expenses:read"] }, { ApiKeyAuth: ["expenses:write"] }, { ApiKeyAuth: ["finance:read"] }],
2678
2720
  parameters: [...PAGINATION_PARAMS, { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } }],
2679
2721
  responses: { "200": paginatedResponse("#/components/schemas/CostCenter"), ...COMMON_ERRORS }
2680
2722
  },
@@ -2740,7 +2782,9 @@ var OPENAPI_SPEC = {
2740
2782
  body: { type: "string" },
2741
2783
  template_key: { type: "string", description: "Obrigat\xF3rio para kind=digest." },
2742
2784
  remind_in_minutes: { type: "integer", description: "Atalho RELATIVO: minutos a partir de agora (servidor calcula). Ex.: 'daqui 30min' \u2192 30. Preferir para lembretes relativos." },
2785
+ remind_in_hours: { type: "number", description: "Atalho RELATIVO em horas (somado a remind_in_minutes, se vier junto)." },
2743
2786
  remind_at: { type: "string", description: "Atalho ABSOLUTO: instante ISO (use 'Z' para UTC). Vira recurrence once + start_date + run_time no fuso." },
2787
+ due_date: { type: "string", format: "date", description: "Atalho S\xD3-DATA (YYYY-MM-DD): lembrete pontual nesse dia." },
2744
2788
  params: { type: "object" },
2745
2789
  audience: { type: "array", items: { type: "string", enum: ["admin", "operador", "visualizador"] } },
2746
2790
  channels: { type: "object", properties: { in_app: { type: "boolean" }, email: { type: "boolean" }, push: { type: "boolean" } } },
@@ -2763,6 +2807,8 @@ var OPENAPI_SPEC = {
2763
2807
  operationId: "updateReminder",
2764
2808
  security: [{ ApiKeyAuth: ["reminders:update"] }],
2765
2809
  requestBody: { required: true, content: { "application/json": { schema: { type: "object", properties: {
2810
+ kind: { type: "string", enum: ["manual", "digest"] },
2811
+ template_key: { type: "string" },
2766
2812
  title: { type: "string" },
2767
2813
  body: { type: "string" },
2768
2814
  params: { type: "object" },
@@ -2792,7 +2838,7 @@ var OPENAPI_SPEC = {
2792
2838
  tags: ["Cat\xE1logos"],
2793
2839
  summary: "Listar condi\xE7\xF5es de pagamento",
2794
2840
  operationId: "listPaymentConditions",
2795
- security: [{ ApiKeyAuth: ["invoices:read", "contracts:read"] }],
2841
+ security: [{ ApiKeyAuth: ["invoices:read"] }, { ApiKeyAuth: ["contracts:read"] }, { ApiKeyAuth: ["invoices:create"] }, { ApiKeyAuth: ["contracts:write"] }],
2796
2842
  parameters: [...PAGINATION_PARAMS, { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } }],
2797
2843
  responses: { "200": paginatedResponse("#/components/schemas/PaymentCondition"), ...COMMON_ERRORS }
2798
2844
  }
@@ -2802,7 +2848,7 @@ var OPENAPI_SPEC = {
2802
2848
  tags: ["Cat\xE1logos"],
2803
2849
  summary: "Listar unidades de servi\xE7o",
2804
2850
  operationId: "listServiceUnits",
2805
- security: [{ ApiKeyAuth: ["services:read", "services:write"] }],
2851
+ security: [{ ApiKeyAuth: ["services:read"] }, { ApiKeyAuth: ["services:write"] }],
2806
2852
  parameters: [...PAGINATION_PARAMS],
2807
2853
  responses: { "200": paginatedResponse("#/components/schemas/ServiceUnit"), ...COMMON_ERRORS }
2808
2854
  }
@@ -2894,6 +2940,7 @@ var OPENAPI_SPEC = {
2894
2940
  }
2895
2941
  } } }
2896
2942
  },
2943
+ "402": { description: "Saldo insuficiente para a leitura visual por IA (o texto do arquivo n\xE3o bastou). `code`: saldo_insuficiente | limite_de_gasto_atingido | carteira_inativa" },
2897
2944
  "404": { description: "Documento n\xE3o encontrado" }
2898
2945
  }
2899
2946
  }
@@ -2976,7 +3023,7 @@ var OPENAPI_SPEC = {
2976
3023
  tags: ["Relat\xF3rios"],
2977
3024
  summary: "Aging de inadimpl\xEAncia com a\xE7\xF5es sugeridas",
2978
3025
  operationId: "reportAgingActions",
2979
- security: [{ ApiKeyAuth: ["invoices:read", "finance:read"] }],
3026
+ security: [{ ApiKeyAuth: ["invoices:read"] }, { ApiKeyAuth: ["finance:read"] }],
2980
3027
  parameters: [
2981
3028
  { name: "limit", in: "query", schema: { type: "integer", minimum: 1, maximum: 40, default: 12 } },
2982
3029
  { name: "min_overdue_days", in: "query", schema: { type: "integer", minimum: 1, maximum: 365, default: 1 } },
@@ -3051,10 +3098,10 @@ var OPENAPI_SPEC = {
3051
3098
  tags: ["NFS-e"],
3052
3099
  summary: "Emitir NFS-e",
3053
3100
  operationId: "emitNfse",
3054
- 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. **201** = autorizada ou em transmiss\xE3o; **422** = o fisco REJEITOU (o motivo vem em `message`) \u2014 nesse caso n\xE3o existe nota, n\xE3o afirme ao usu\xE1rio que foi emitida.",
3101
+ 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.\n\n**Os itens da fatura N\xC3O precisam de `service_id`** \u2014 item avulso emite normalmente; a classifica\xE7\xE3o fiscal (cTribNac, cNBS, al\xEDquotas) vem da configura\xE7\xE3o fiscal da empresa e do CNAE padr\xE3o, n\xE3o do item.\n\nC\xF3digos: **201** = autorizada ou em transmiss\xE3o \u2014 o `id` devolvido \xE9 o mesmo `{id}` de `/v1/nfse/{id}`, `/files`, `/sync` e `/cancel`. **422 com `status: 'rejeitada'`** = o fisco REJEITOU (motivo em `message`) \u2014 n\xE3o existe nota, n\xE3o afirme ao usu\xE1rio que foi emitida. **422 sem `status`** = a EMPRESA n\xE3o est\xE1 configurada para emitir. **409** = esta fatura j\xE1 tem nota (o `error` traz o id da existente). **424** = o provedor fiscal falhou; o motivo dele vem em `error`.\n\nRetentativa \xE9 segura: mande o header `Idempotency-Key` (a mesma resposta volta, com `Idempotent-Replayed: true`), e mesmo sem ele o 409 impede uma segunda nota para a mesma fatura.",
3055
3102
  security: [{ ApiKeyAuth: ["nfse:emitir"] }],
3056
3103
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/NfseEmit" } } } },
3057
- 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 }
3104
+ responses: { "201": { description: "Emiss\xE3o solicitada", content: { "application/json": { schema: { type: "object", properties: { id: { type: ["string", "null"], description: "Id da NFS-e \u2014 use em /v1/nfse/{id}, /files, /sync e /cancel. Mesmo valor de history_id." }, invoice_id: { type: "string" }, status: { type: "string", description: "autorizada | transmitindo | rejeitada" }, numero_nfse: { type: ["string", "null"] }, chave_acesso: { type: ["string", "null"] }, history_id: { type: ["string", "null"], description: "Alias de `id`, mantido por compatibilidade." }, message: { type: ["string", "null"] } } } } } }, "400": errorResponse("invoice_id ausente"), "404": errorResponse("Fatura n\xE3o encontrada"), "409": errorResponse("A fatura j\xE1 tem NFS-e autorizada ou em transmiss\xE3o \u2014 o `error` traz o id da existente"), "402": errorResponse("Saldo insuficiente na carteira pr\xE9-paga (ou limite de gasto atingido) \u2014 nada foi transmitido. `code`: saldo_insuficiente | limite_de_gasto_atingido | carteira_inativa; recarregue em Cobran\xE7a da plataforma"), "422": errorResponse('Rejeitada pelo fisco (corpo traz `status: "rejeitada"` e `message`) OU empresa sem NFS-e configurada (corpo traz s\xF3 `error`)'), "424": errorResponse("O provedor de NFS-e falhou \u2014 o motivo dele vem em `error`"), ...COMMON_ERRORS }
3058
3105
  }
3059
3106
  },
3060
3107
  "/nfse/{id}/cancel": {
@@ -3065,7 +3112,7 @@ var OPENAPI_SPEC = {
3065
3112
  operationId: "cancelNfse",
3066
3113
  security: [{ ApiKeyAuth: ["nfse:cancelar"] }],
3067
3114
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/NfseCancel" } } } },
3068
- 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 }
3115
+ 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"), "424": errorResponse("Erro do provedor de NFS-e"), ...COMMON_ERRORS }
3069
3116
  }
3070
3117
  },
3071
3118
  "/nfse/{id}": {
@@ -3089,7 +3136,7 @@ var OPENAPI_SPEC = {
3089
3136
  summary: "Sincronizar status da NFS-e com o provedor",
3090
3137
  operationId: "syncNfse",
3091
3138
  security: [{ ApiKeyAuth: ["nfse:read"] }],
3092
- responses: { "200": { description: "Resultado da sincroniza\xE7\xE3o", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, invoice_id: { type: "string" }, processed: { type: "integer" }, updated: { type: "integer" }, attached: { type: "integer" } } } } } }, "404": errorResponse("NFS-e n\xE3o encontrada"), "502": errorResponse("Erro do provedor de NFS-e"), ...COMMON_ERRORS }
3139
+ responses: { "200": { description: "Resultado da sincroniza\xE7\xE3o", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, invoice_id: { type: "string" }, processed: { type: "integer" }, updated: { type: "integer" }, attached: { type: "integer" } } } } } }, "404": errorResponse("NFS-e n\xE3o encontrada"), "424": errorResponse("Erro do provedor de NFS-e"), ...COMMON_ERRORS }
3093
3140
  }
3094
3141
  },
3095
3142
  "/nfse/{id}/files": {
@@ -3100,7 +3147,7 @@ var OPENAPI_SPEC = {
3100
3147
  operationId: "getNfseFiles",
3101
3148
  description: "Retorna URLs tempor\xE1rias (30 min). `xml_signed_url` = XML autorizado. `danfse_signed_url` = DANFSe em PDF (gerada sob demanda a partir do XML se ainda n\xE3o existir). `danfse_html_signed_url` = HTML OFICIAL publicado pelo ADN, quando dispon\xEDvel \u2014 \xE9 outro documento, n\xE3o uma vers\xE3o pior do PDF. `danfse_formato` diz o que veio em `danfse_signed_url` (pdf|html).",
3102
3149
  security: [{ ApiKeyAuth: ["nfse:read"] }],
3103
- responses: { "200": { description: "URLs assinadas", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, invoice_id: { type: "string" }, status: { type: "string" }, xml_signed_url: { type: ["string", "null"] }, danfse_signed_url: { type: ["string", "null"] }, signed_url_ttl_seconds: { type: "integer" } } } } } }, "404": errorResponse("NFS-e n\xE3o encontrada"), ...COMMON_ERRORS }
3150
+ responses: { "200": { description: "URLs assinadas", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, invoice_id: { type: "string" }, status: { type: "string" }, xml_signed_url: { type: ["string", "null"] }, danfse_signed_url: { type: ["string", "null"] }, danfse_html_signed_url: { type: ["string", "null"], description: "HTML oficial publicado pelo ADN, quando existir. \xC9 outro documento, n\xE3o uma vers\xE3o pior do PDF \u2014 nulo aqui n\xE3o se substitui por danfse_signed_url." }, danfse_formato: { type: ["string", "null"], enum: ["pdf", "html", null], description: "O que veio em danfse_signed_url." }, signed_url_ttl_seconds: { type: "integer" } } } } } }, "404": errorResponse("NFS-e n\xE3o encontrada"), ...COMMON_ERRORS }
3104
3151
  }
3105
3152
  },
3106
3153
  // -----------------------------------------------------------------------
@@ -3347,7 +3394,7 @@ var OPENAPI_SPEC = {
3347
3394
  tags: ["Cobran\xE7as"],
3348
3395
  summary: "Criar cobran\xE7a (Pix, boleto, checkout ou cart\xE3o)",
3349
3396
  operationId: "createCharge",
3350
- description: "Gera uma cobran\xE7a no provider ativo da empresa (Inter, C6 Bank, Pix Offline ou Pagar.me). Forne\xE7a invoice_id ou customer_id+amount+due_date. Com Pagar.me, method=pix retorna o copia-e-cola e method=credit_card retorna 'checkout.url' (link da p\xE1gina de pagamento pr\xF3pria).",
3397
+ description: "Gera uma cobran\xE7a no provider ativo da empresa (Inter, C6 Bank, Pix Offline, Cora ou Pagar.me). Forne\xE7a invoice_id ou customer_id+amount+due_date. Com Pagar.me, method=pix retorna o copia-e-cola e method=credit_card retorna 'checkout.url' (link da p\xE1gina de pagamento pr\xF3pria).\n\nNuma fatura PARCELADA, informe `charge_id`: sem ele a cobran\xE7a sai no valor cheio da fatura e n\xE3o fica amarrada a nenhuma parcela \u2014 ent\xE3o a baixa n\xE3o fecha a parcela certa. Use GET /v1/invoices/{id}/charges para descobrir o charge_id.",
3351
3398
  security: [{ ApiKeyAuth: ["charges:create"] }],
3352
3399
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChargeCreate" } } } },
3353
3400
  responses: {
@@ -3382,14 +3429,14 @@ var OPENAPI_SPEC = {
3382
3429
  tags: ["Cobran\xE7as"],
3383
3430
  summary: "Estornar cobran\xE7a (devolu\xE7\xE3o Pix)",
3384
3431
  operationId: "refundCharge",
3385
- 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.",
3432
+ 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." + STEP_UP_NOTE,
3386
3433
  security: [{ ApiKeyAuth: ["charges:refund"] }],
3387
3434
  responses: {
3388
3435
  "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" } } } } } },
3389
3436
  "404": errorResponse("Cobran\xE7a n\xE3o encontrada"),
3390
3437
  "409": errorResponse("Cobran\xE7a n\xE3o est\xE1 paga ou j\xE1 estornada"),
3391
3438
  "422": errorResponse("M\xE9todo n\xE3o suportado (apenas Pix) ou endToEndId indispon\xEDvel"),
3392
- ...COMMON_ERRORS
3439
+ ...STEP_UP_ERRORS
3393
3440
  }
3394
3441
  }
3395
3442
  },
@@ -3426,11 +3473,11 @@ var OPENAPI_SPEC = {
3426
3473
  tags: ["Webhooks"],
3427
3474
  summary: "Criar webhook",
3428
3475
  operationId: "createWebhook",
3429
- description: "Cria um webhook. O secret HMAC-SHA256 \xE9 retornado apenas na cria\xE7\xE3o (guarde-o).",
3476
+ description: "Cria um webhook.\n\nO `secret` vem no corpo do 201 e **s\xF3 nessa vez** \u2014 guarde-o. \xC9 com ele que voc\xEA confere a assinatura de cada entrega.\n\nHeaders de toda entrega:\n- `x-signature` \u2014 HMAC-SHA256 do **corpo cru** (os bytes recebidos, antes de qualquer parse/reserializa\xE7\xE3o), em hexadecimal min\xFAsculo. Compare em tempo constante e rejeite o que n\xE3o bater: \xE9 o que distingue uma entrega nossa de qualquer POST na sua URL.\n- `x-event` \u2014 o evento (ex.: `invoice.paid`).\n- `x-delivery-id` \u2014 id da entrega; serve para voc\xEA deduplicar retentativas (h\xE1 at\xE9 3 tentativas, com backoff de 30s e 2min).",
3430
3477
  security: [{ ApiKeyAuth: ["webhooks:manage"] }],
3431
3478
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/WebhookCreate" } } } },
3432
3479
  responses: {
3433
- "201": { description: "Webhook criado (inclui secret \xFAnico)", content: { "application/json": { schema: { type: "object", properties: { webhook: { $ref: "#/components/schemas/Webhook" }, secret: { type: "string" } } } } } },
3480
+ "201": { description: "Webhook criado (inclui secret \xFAnico)", content: { "application/json": { schema: { type: "object", properties: { webhook: { $ref: "#/components/schemas/Webhook" }, secret: { type: "string", description: "Segredo HMAC-SHA256. Devolvido S\xD3 nesta resposta; assina o header x-signature de cada entrega." }, secret_note: { type: "string" } } } } } },
3434
3481
  "400": errorResponse("Dados inv\xE1lidos"),
3435
3482
  ...COMMON_ERRORS
3436
3483
  }
@@ -3494,12 +3541,12 @@ var OPENAPI_SPEC = {
3494
3541
  tags: ["Webhooks"],
3495
3542
  summary: "Registrar/atualizar webhook",
3496
3543
  operationId: "upsertWebhook",
3497
- description: "Cria ou atualiza a URL de callback. O secret HMAC-SHA256 \xE9 retornado apenas na cria\xE7\xE3o.",
3544
+ description: "Cria ou atualiza a URL de callback. O `secret` \xE9 retornado apenas na cria\xE7\xE3o \u2014 guarde-o. Cada entrega vai assinada no header `x-signature` = HMAC-SHA256 do corpo cru, em hexadecimal min\xFAsculo, junto de `x-event` e `x-delivery-id`.",
3498
3545
  security: [{ ApiKeyAuth: ["webhooks:manage"] }],
3499
3546
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/WebhookCreate" } } } },
3500
3547
  responses: {
3501
3548
  "200": { description: "Webhook atualizado", content: { "application/json": { schema: { type: "object", properties: { webhook: { $ref: "#/components/schemas/Webhook" } } } } } },
3502
- "201": { description: "Webhook criado (inclui secret \xFAnico)", content: { "application/json": { schema: { type: "object", properties: { webhook: { $ref: "#/components/schemas/Webhook" }, secret: { type: "string" } } } } } },
3549
+ "201": { description: "Webhook criado (inclui secret \xFAnico)", content: { "application/json": { schema: { type: "object", properties: { webhook: { $ref: "#/components/schemas/Webhook" }, secret: { type: "string", description: "Segredo HMAC-SHA256. Devolvido S\xD3 nesta resposta; assina o header x-signature de cada entrega." }, secret_note: { type: "string" } } } } } },
3503
3550
  "400": errorResponse("URL inv\xE1lida ou eventos inv\xE1lidos"),
3504
3551
  ...COMMON_ERRORS
3505
3552
  }
@@ -3979,7 +4026,7 @@ var OPENAPI_SPEC = {
3979
4026
  tags: ["Pagamentos a Fornecedor"],
3980
4027
  summary: "Pagar ou agendar pagamento (Pix/boleto)",
3981
4028
  operationId: "createPayout",
3982
- 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.",
4029
+ 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." + STEP_UP_NOTE,
3983
4030
  security: [{ ApiKeyAuth: ["payouts:create"] }],
3984
4031
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/PayoutCreate" } } } },
3985
4032
  responses: {
@@ -3987,8 +4034,8 @@ var OPENAPI_SPEC = {
3987
4034
  "400": errorResponse("Dados inv\xE1lidos / alvo ausente"),
3988
4035
  "404": errorResponse("Conta banc\xE1ria, parcela ou fornecedor n\xE3o encontrado"),
3989
4036
  "422": errorResponse("Integra\xE7\xE3o n\xE3o configurada ou provider amb\xEDguo"),
3990
- "502": errorResponse("Erro retornado pelo banco"),
3991
- ...COMMON_ERRORS
4037
+ "424": errorResponse("Erro retornado pelo banco"),
4038
+ ...STEP_UP_ERRORS
3992
4039
  }
3993
4040
  }
3994
4041
  },
@@ -4008,9 +4055,9 @@ var OPENAPI_SPEC = {
4008
4055
  tags: ["Pagamentos a Fornecedor"],
4009
4056
  summary: "Cancelar pagamento agendado",
4010
4057
  operationId: "cancelPayout",
4011
- description: "Cancela um pagamento agendado. Pix agendado no Inter n\xE3o \xE9 cancel\xE1vel pela API (retorna 422 \u2014 cancele no Internet Banking).",
4058
+ description: "Cancela um pagamento agendado. Pix agendado no Inter n\xE3o \xE9 cancel\xE1vel pela API (retorna 422 \u2014 cancele no Internet Banking)." + STEP_UP_NOTE,
4012
4059
  security: [{ ApiKeyAuth: ["payouts:cancel"] }],
4013
- 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 }
4060
+ 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"), ...STEP_UP_ERRORS }
4014
4061
  }
4015
4062
  },
4016
4063
  "/payouts/{id}/sync": {
@@ -4105,9 +4152,9 @@ var OPENAPI_SPEC = {
4105
4152
  tags: ["Split de Pagamentos"],
4106
4153
  summary: "Estornar execu\xE7\xE3o de split",
4107
4154
  operationId: "reverseSplitExecution",
4108
- description: "Marca a execu\xE7\xE3o e suas fatias como 'reversed'. Para cada fatia de fornecedor j\xE1 paga, registra um ajuste de recupera\xE7\xE3o (o fornecedor deve devolver o valor).",
4155
+ description: "Marca a execu\xE7\xE3o e suas fatias como 'reversed'. Para cada fatia de fornecedor j\xE1 paga, registra um ajuste de recupera\xE7\xE3o (o fornecedor deve devolver o valor)." + STEP_UP_NOTE,
4109
4156
  security: [{ ApiKeyAuth: ["split:update"] }],
4110
- responses: { "200": { description: "Estornada", content: { "application/json": { schema: { type: "object", properties: { execution_id: { type: "string" }, status: { type: "string" }, adjustments_created: { type: "integer" }, recover_amount_cents: { type: "integer" } } } } } }, "404": errorResponse("Execu\xE7\xE3o n\xE3o encontrada"), "409": errorResponse("J\xE1 estornada"), ...COMMON_ERRORS }
4157
+ responses: { "200": { description: "Estornada", content: { "application/json": { schema: { type: "object", properties: { execution_id: { type: "string" }, status: { type: "string" }, adjustments_created: { type: "integer" }, recover_amount_cents: { type: "integer" } } } } } }, "404": errorResponse("Execu\xE7\xE3o n\xE3o encontrada"), "409": errorResponse("J\xE1 estornada"), ...STEP_UP_ERRORS }
4111
4158
  }
4112
4159
  },
4113
4160
  "/split-items/{id}/release": {
@@ -4116,9 +4163,9 @@ var OPENAPI_SPEC = {
4116
4163
  tags: ["Split de Pagamentos"],
4117
4164
  summary: "Liberar fatia manualmente",
4118
4165
  operationId: "releaseSplitItem",
4119
- description: "Libera uma fatia (pending/awaiting_nota/failed \u2192 released), apta a virar payout.",
4166
+ description: "Libera uma fatia (pending/awaiting_nota/failed \u2192 released), apta a virar payout." + STEP_UP_NOTE,
4120
4167
  security: [{ ApiKeyAuth: ["split:update"] }],
4121
- responses: { "200": { description: "Liberada", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" } } } } } }, "404": errorResponse("Fatia n\xE3o encontrada"), ...COMMON_ERRORS }
4168
+ responses: { "200": { description: "Liberada", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" } } } } } }, "404": errorResponse("Fatia n\xE3o encontrada"), ...STEP_UP_ERRORS }
4122
4169
  }
4123
4170
  },
4124
4171
  // -----------------------------------------------------------------------
@@ -4189,7 +4236,7 @@ var OPENAPI_SPEC = {
4189
4236
  summary: "Listar m\xE9todos de pagamento a fornecedor (AP)",
4190
4237
  operationId: "listPaymentMethodsAp",
4191
4238
  description: "Formas de pagamento usadas em payouts (contas a pagar).",
4192
- security: [{ ApiKeyAuth: ["payouts:read"] }],
4239
+ security: [{ ApiKeyAuth: ["payouts:read"] }, { ApiKeyAuth: ["payouts:create"] }],
4193
4240
  parameters: [
4194
4241
  ...PAGINATION_PARAMS,
4195
4242
  { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } },
@@ -4454,12 +4501,17 @@ function resolveRef(ref) {
4454
4501
  if (!schema) throw new Error(`Schema n\xE3o encontrado em components: ${name}`);
4455
4502
  return schema;
4456
4503
  }
4457
- function extractScopes(operation) {
4504
+ function extractScopeAlternatives(operation) {
4458
4505
  const sec = operation.security;
4459
- if (!Array.isArray(sec) || sec.length === 0) return [];
4460
- const first = sec[0];
4461
- const scopes = first?.ApiKeyAuth;
4462
- return Array.isArray(scopes) ? scopes.filter(Boolean) : [];
4506
+ if (!Array.isArray(sec)) return [];
4507
+ return sec.map((alt) => Array.isArray(alt?.ApiKeyAuth) ? alt.ApiKeyAuth.filter(Boolean) : []).filter((alt) => alt.length > 0);
4508
+ }
4509
+ function temScopesPara(desc, held) {
4510
+ if (desc.scopeAlternatives.length === 0) return true;
4511
+ return desc.scopeAlternatives.some((alt) => alt.every((s) => held.has(s)));
4512
+ }
4513
+ function descreverScopes(desc) {
4514
+ return desc.scopeAlternatives.map((alt) => alt.join(" + ")).join(" ou ");
4463
4515
  }
4464
4516
  function describeOperation(operationId) {
4465
4517
  const idx = indexByOperationId();
@@ -4523,7 +4575,8 @@ function describeOperation(operationId) {
4523
4575
  pathParams,
4524
4576
  queryParams,
4525
4577
  hasBody,
4526
- scopes: extractScopes(operation),
4578
+ scopes: [...new Set(extractScopeAlternatives(operation).flat())],
4579
+ scopeAlternatives: extractScopeAlternatives(operation),
4527
4580
  inputSchema,
4528
4581
  summary: operation.summary,
4529
4582
  description: operation.description
@@ -4636,16 +4689,15 @@ function buildCuratedTools(api, heldScopes) {
4636
4689
  `);
4637
4690
  continue;
4638
4691
  }
4639
- const missing = desc.scopes.filter((s) => !heldScopes.has(s));
4640
- if (missing.length > 0) {
4641
- skipped.push({ tool: entry.tool, missingScopes: missing });
4692
+ if (!temScopesPara(desc, heldScopes)) {
4693
+ skipped.push({ tool: entry.tool, missingScopes: desc.scopes.filter((s) => !heldScopes.has(s)) });
4642
4694
  continue;
4643
4695
  }
4644
4696
  const inputSchema = augmentInputSchema(desc.inputSchema, {
4645
4697
  write: entry.write,
4646
4698
  destructive: entry.destructive
4647
4699
  });
4648
- const scopeNote = desc.scopes.length ? ` Scopes: ${desc.scopes.join(", ")}.` : "";
4700
+ const scopeNote = desc.scopes.length ? ` Scopes: ${descreverScopes(desc)}.` : "";
4649
4701
  const prefix = entry.destructive ? "[DESTRUTIVA] " : "";
4650
4702
  const description = `${prefix}${desc.summary ?? entry.operationId}.${scopeNote}`;
4651
4703
  tools.push({
@@ -4844,7 +4896,7 @@ function buildWhoamiTool(api) {
4844
4896
  // src/branding.ts
4845
4897
  var MCP_SERVER_NAME = "comando-one";
4846
4898
  var MCP_SERVER_TITLE = "Comando1";
4847
- var MCP_SERVER_VERSION = "0.5.0";
4899
+ var MCP_SERVER_VERSION = "0.12.0";
4848
4900
  var MCP_SERVER_DESCRIPTION = "ERP das empresas de servi\xE7o brasileiras: clientes, propostas, contratos, faturas, cobran\xE7as Pix e boleto, NFS-e, contas a pagar e financeiro.";
4849
4901
  var MCP_SERVER_WEBSITE = "https://comando.one";
4850
4902
  var MCP_SERVER_ICONS = [
package/package.json CHANGED
@@ -1,7 +1,9 @@
1
1
  {
2
2
  "name": "@comando.one/mcp-server",
3
- "version": "0.11.0",
3
+ "version": "0.12.0",
4
4
  "description": "Servidor MCP (Model Context Protocol) para a API pública do Comando1 — opere seu ERP por linguagem natural.",
5
+ "author": "Orbital Tecnologia e Desenvolvimento LTDA <contato@comando.one> (https://orbitaldev.com.br)",
6
+ "homepage": "https://comando.one",
5
7
  "type": "module",
6
8
  "license": "MIT",
7
9
  "bin": {