@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.
- package/README.md +12 -7
- package/dist/index.js +93 -41
- 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).
|
|
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
|
|
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
|
-
- **
|
|
55
|
-
- **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`)
|
|
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** (
|
|
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
|
-
//
|
|
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
|
|
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"), "
|
|
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"), "
|
|
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"), "
|
|
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
|
-
...
|
|
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.
|
|
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
|
|
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
|
-
"
|
|
3991
|
-
...
|
|
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"), ...
|
|
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"), ...
|
|
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"), ...
|
|
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
|
|
4504
|
+
function extractScopeAlternatives(operation) {
|
|
4458
4505
|
const sec = operation.security;
|
|
4459
|
-
if (!Array.isArray(sec)
|
|
4460
|
-
|
|
4461
|
-
|
|
4462
|
-
|
|
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:
|
|
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
|
-
|
|
4640
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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": {
|