@comando.one/mcp-server 0.11.0 → 0.11.1

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 (2) hide show
  1. package/dist/index.js +32 -11
  2. package/package.json +3 -1
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 },
@@ -1714,7 +1715,7 @@ var OPENAPI_SPEC = {
1714
1715
  info: {
1715
1716
  title: "Comando1 API",
1716
1717
  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.",
1718
+ 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
1719
  contact: { email: "contato@comando.one", url: "https://comando.one" },
1719
1720
  license: { name: "Propriet\xE1rio" }
1720
1721
  },
@@ -2326,6 +2327,26 @@ var OPENAPI_SPEC = {
2326
2327
  ...COMMON_ERRORS
2327
2328
  }
2328
2329
  },
2330
+ patch: {
2331
+ tags: ["Faturas"],
2332
+ summary: "Corrigir fatura",
2333
+ operationId: "patchInvoice",
2334
+ 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.",
2335
+ security: [{ ApiKeyAuth: ["invoices:create"] }],
2336
+ requestBody: {
2337
+ content: { "application/json": { schema: { type: "object", properties: {
2338
+ status: { type: "string", enum: ["rascunho", "enviada", "aceita", "ativa"] },
2339
+ title: { type: ["string", "null"] }
2340
+ } } } }
2341
+ },
2342
+ responses: {
2343
+ "200": { description: "Fatura atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/Invoice" } } } },
2344
+ "400": errorResponse("Nenhum campo aceito foi enviado, ou status inv\xE1lido"),
2345
+ "404": errorResponse("Fatura n\xE3o encontrada"),
2346
+ "409": errorResponse('status "cancelada" (use /cancel), ou a fatura j\xE1 est\xE1 cancelada'),
2347
+ ...COMMON_ERRORS
2348
+ }
2349
+ },
2329
2350
  delete: {
2330
2351
  tags: ["Faturas"],
2331
2352
  summary: "Excluir fatura",
@@ -3051,10 +3072,10 @@ var OPENAPI_SPEC = {
3051
3072
  tags: ["NFS-e"],
3052
3073
  summary: "Emitir NFS-e",
3053
3074
  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.",
3075
+ 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
3076
  security: [{ ApiKeyAuth: ["nfse:emitir"] }],
3056
3077
  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 }
3078
+ 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"), "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
3079
  }
3059
3080
  },
3060
3081
  "/nfse/{id}/cancel": {
@@ -3065,7 +3086,7 @@ var OPENAPI_SPEC = {
3065
3086
  operationId: "cancelNfse",
3066
3087
  security: [{ ApiKeyAuth: ["nfse:cancelar"] }],
3067
3088
  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 }
3089
+ 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
3090
  }
3070
3091
  },
3071
3092
  "/nfse/{id}": {
@@ -3089,7 +3110,7 @@ var OPENAPI_SPEC = {
3089
3110
  summary: "Sincronizar status da NFS-e com o provedor",
3090
3111
  operationId: "syncNfse",
3091
3112
  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 }
3113
+ 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
3114
  }
3094
3115
  },
3095
3116
  "/nfse/{id}/files": {
@@ -3100,7 +3121,7 @@ var OPENAPI_SPEC = {
3100
3121
  operationId: "getNfseFiles",
3101
3122
  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
3123
  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 }
3124
+ 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
3125
  }
3105
3126
  },
3106
3127
  // -----------------------------------------------------------------------
@@ -3426,11 +3447,11 @@ var OPENAPI_SPEC = {
3426
3447
  tags: ["Webhooks"],
3427
3448
  summary: "Criar webhook",
3428
3449
  operationId: "createWebhook",
3429
- description: "Cria um webhook. O secret HMAC-SHA256 \xE9 retornado apenas na cria\xE7\xE3o (guarde-o).",
3450
+ 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
3451
  security: [{ ApiKeyAuth: ["webhooks:manage"] }],
3431
3452
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/WebhookCreate" } } } },
3432
3453
  responses: {
3433
- "201": { description: "Webhook criado (inclui secret \xFAnico)", content: { "application/json": { schema: { type: "object", properties: { webhook: { $ref: "#/components/schemas/Webhook" }, secret: { type: "string" } } } } } },
3454
+ "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
3455
  "400": errorResponse("Dados inv\xE1lidos"),
3435
3456
  ...COMMON_ERRORS
3436
3457
  }
@@ -3494,12 +3515,12 @@ var OPENAPI_SPEC = {
3494
3515
  tags: ["Webhooks"],
3495
3516
  summary: "Registrar/atualizar webhook",
3496
3517
  operationId: "upsertWebhook",
3497
- description: "Cria ou atualiza a URL de callback. O secret HMAC-SHA256 \xE9 retornado apenas na cria\xE7\xE3o.",
3518
+ 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
3519
  security: [{ ApiKeyAuth: ["webhooks:manage"] }],
3499
3520
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/WebhookCreate" } } } },
3500
3521
  responses: {
3501
3522
  "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" } } } } } },
3523
+ "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
3524
  "400": errorResponse("URL inv\xE1lida ou eventos inv\xE1lidos"),
3504
3525
  ...COMMON_ERRORS
3505
3526
  }
@@ -3987,7 +4008,7 @@ var OPENAPI_SPEC = {
3987
4008
  "400": errorResponse("Dados inv\xE1lidos / alvo ausente"),
3988
4009
  "404": errorResponse("Conta banc\xE1ria, parcela ou fornecedor n\xE3o encontrado"),
3989
4010
  "422": errorResponse("Integra\xE7\xE3o n\xE3o configurada ou provider amb\xEDguo"),
3990
- "502": errorResponse("Erro retornado pelo banco"),
4011
+ "424": errorResponse("Erro retornado pelo banco"),
3991
4012
  ...COMMON_ERRORS
3992
4013
  }
3993
4014
  }
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.11.1",
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": {