@comando.one/mcp-server 0.14.0 → 0.16.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 +2 -2
  2. package/dist/index.js +701 -22
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -43,7 +43,7 @@ Além deste pacote stdio, existe um **endpoint MCP remoto (streaming)** em `http
43
43
  }
44
44
  ```
45
45
 
46
- Ambos expõem as mesmas ferramentas: **169 tools curadas** (uma por operação da API) + `lookups` + `comando_request`. Só o stdio tem `whoami`.
46
+ Ambos expõem as mesmas ferramentas: **191 tools curadas** (uma por operação da API, em 17/11/2026) + `lookups` + `comando_request`. Só o stdio tem `whoami`.
47
47
 
48
48
  ## Variáveis de ambiente
49
49
 
@@ -55,7 +55,7 @@ Ambos expõem as mesmas ferramentas: **169 tools curadas** (uma por operação d
55
55
 
56
56
  ## Como funciona
57
57
 
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.
58
+ - **191 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
59
  - **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`) para qualquer rota; as destrutivas continuam exigindo `confirm`.
60
60
  - **`lookups`** — catálogos read-only (centros de custo, condições/métodos de pagamento, naturezas, contas bancárias).
61
61
  - **`whoami`** — identidade, empresas acessíveis e scopes da chave.
package/dist/index.js CHANGED
@@ -151,9 +151,12 @@ var MANIFEST = [
151
151
  { operationId: "listChargePayments", tool: "invoices_list_charge_payments" },
152
152
  { operationId: "reverseChargePayment", tool: "invoices_reverse_payment", write: true, destructive: true },
153
153
  { operationId: "generateContractInvoices", tool: "contracts_generate_invoices", write: true },
154
+ { operationId: "getContractPixAutomatico", tool: "contracts_pix_automatico_get" },
155
+ { operationId: "createContractPixAutomaticoLink", tool: "contracts_pix_automatico_link", write: true },
154
156
  // ----- Cobranças -----
155
157
  { operationId: "listCharges", tool: "charges_list" },
156
158
  { operationId: "getCharge", tool: "charges_get" },
159
+ { operationId: "getChargePdf", tool: "charges_pdf" },
157
160
  { operationId: "createCharge", tool: "charges_create", write: true },
158
161
  { operationId: "confirmCharge", tool: "charges_confirm", write: true },
159
162
  { operationId: "cancelCharge", tool: "charges_cancel", write: true, destructive: true },
@@ -181,6 +184,7 @@ var MANIFEST = [
181
184
  { operationId: "createPurchaseInvoice", tool: "purchase_invoices_create", write: true },
182
185
  { operationId: "cancelPurchaseInvoice", tool: "purchase_invoices_cancel", write: true, destructive: true },
183
186
  { operationId: "deletePurchaseInvoice", tool: "purchase_invoices_delete", write: true, destructive: true },
187
+ { operationId: "payPurchaseInvoice", tool: "purchase_invoices_pay", write: true },
184
188
  // ----- Despesas & Serviços -----
185
189
  { operationId: "listExpenses", tool: "expenses_list" },
186
190
  { operationId: "createExpense", tool: "expenses_create", write: true },
@@ -200,6 +204,27 @@ var MANIFEST = [
200
204
  { operationId: "getSplitExecution", tool: "split_executions_get" },
201
205
  { operationId: "reverseSplitExecution", tool: "split_reverse", write: true, destructive: true },
202
206
  { operationId: "releaseSplitItem", tool: "split_release_item", write: true },
207
+ // ----- Parcerias (caixa compartilhado com parceiro; specs/parcerias/) -----
208
+ { operationId: "listParcerias", tool: "parcerias_list" },
209
+ { operationId: "getParceria", tool: "parcerias_get" },
210
+ { operationId: "createParceria", tool: "parcerias_create", write: true },
211
+ { operationId: "updateParceria", tool: "parcerias_update", write: true },
212
+ { operationId: "closeParceria", tool: "parcerias_close", write: true, destructive: true },
213
+ { operationId: "listParceriaLancamentos", tool: "parcerias_lancamentos_list" },
214
+ { operationId: "createParceriaLancamento", tool: "parcerias_lancar", write: true },
215
+ { operationId: "reverseParceriaLancamento", tool: "parcerias_estornar", write: true, destructive: true },
216
+ { operationId: "createParceriaRetirada", tool: "parcerias_retirar", write: true, destructive: true },
217
+ { operationId: "resolveParceriaNota", tool: "parcerias_resolver_nota", write: true },
218
+ { operationId: "listParceriaVinculos", tool: "parcerias_vinculos_list" },
219
+ { operationId: "createParceriaVinculo", tool: "parcerias_vincular", write: true },
220
+ { operationId: "deleteParceriaVinculo", tool: "parcerias_desvincular", write: true, destructive: true },
221
+ { operationId: "updateParceriaVinculo", tool: "parcerias_vinculo_antecipar", write: true },
222
+ { operationId: "previewParceriaVinculo", tool: "parcerias_vinculo_previa" },
223
+ { operationId: "updateParceriaParticipantes", tool: "parcerias_participantes_update", write: true, destructive: true },
224
+ { operationId: "updateParceriaSaldoInicial", tool: "parcerias_saldo_inicial_update", write: true },
225
+ { operationId: "upsertParceriaEmpresa", tool: "parcerias_empresa_upsert", write: true },
226
+ { operationId: "deleteParceriaEmpresa", tool: "parcerias_empresa_remover", write: true, destructive: true },
227
+ { operationId: "getParceriaPrestacao", tool: "parcerias_prestacao_de_contas" },
203
228
  // Auditoria
204
229
  { operationId: "analyzeDocument", tool: "documents_analyze", write: true },
205
230
  { operationId: "listDocuments", tool: "documents_search" },
@@ -385,7 +410,9 @@ var WEBHOOK_EVENT_KEYS = [
385
410
  "repasse.reversed",
386
411
  "supplier_payout_request.created",
387
412
  "supplier_payout_request.approved",
388
- "plan.limit_near"
413
+ "plan.limit_near",
414
+ "parceria.entry_created",
415
+ "parceria.note_matched"
389
416
  ];
390
417
  var SCHEMAS = {
391
418
  Error: {
@@ -504,6 +531,32 @@ var SCHEMAS = {
504
531
  content: { type: "string" }
505
532
  }
506
533
  },
534
+ ContractPixAutomatico: {
535
+ type: "object",
536
+ description: "Autoriza\xE7\xE3o de Pix Autom\xE1tico de um contrato (d\xE9bito recorrente autorizado pelo pagador no app do banco).",
537
+ properties: {
538
+ contract_id: { type: "string", format: "uuid" },
539
+ banco: { type: ["string", "null"], enum: ["inter", "c6bank", null], description: "Banco da forma de cobran\xE7a do contrato. null = a forma n\xE3o \xE9 Pix Autom\xE1tico." },
540
+ apto: { type: "boolean", description: "O contrato cabe nas regras do Banco Central para Pix Autom\xE1tico." },
541
+ problemas: { type: "array", items: { type: "string" }, description: "O que impede o Pix Autom\xE1tico, em portugu\xEAs, quando apto = false." },
542
+ link: { type: ["string", "null"], description: "Link de autoriza\xE7\xE3o (https://comando.one/assinar/\u2026) para enviar ao pagador. null at\xE9 o POST criar." },
543
+ autorizacao: {
544
+ type: ["object", "null"],
545
+ description: "A autoriza\xE7\xE3o (Rec) mais recente. null enquanto o pagador n\xE3o abriu o link e pediu o QR Code.",
546
+ properties: {
547
+ id_rec: { type: "string", description: "Identificador da recorr\xEAncia no Banco Central." },
548
+ status: { type: "string", enum: ["CRIADA", "APROVADA", "REJEITADA", "CANCELADA", "EXPIRADA"] },
549
+ banco: { type: "string", enum: ["inter", "c6bank"] },
550
+ valor: { type: ["number", "null"], description: "Valor fixo autorizado por d\xE9bito, em reais." },
551
+ periodicidade: { type: ["string", "null"], enum: ["SEMANAL", "MENSAL", "TRIMESTRAL", "SEMESTRAL", "ANUAL", null] },
552
+ data_inicial: { type: ["string", "null"], format: "date", description: "1\xBA vencimento." },
553
+ data_final: { type: ["string", "null"], format: "date" },
554
+ criada_em: { type: "string", format: "date-time" },
555
+ atualizada_em: { type: "string", format: "date-time" }
556
+ }
557
+ }
558
+ }
559
+ },
507
560
  Contract: {
508
561
  type: "object",
509
562
  properties: {
@@ -685,7 +738,7 @@ var SCHEMAS = {
685
738
  invoice_number: { type: ["string", "null"] },
686
739
  title: { type: ["string", "null"] },
687
740
  amount: { type: "number" },
688
- status: { type: "string", enum: ["rascunho", "enviada", "aceita", "cancelada"] },
741
+ status: { type: "string", enum: ["rascunho", "enviada", "aceita", "ativa", "cancelada"] },
689
742
  payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] },
690
743
  due_date: { type: ["string", "null"], format: "date" },
691
744
  proposal_id: { type: ["string", "null"], format: "uuid" },
@@ -955,7 +1008,7 @@ var SCHEMAS = {
955
1008
  required: ["name"],
956
1009
  properties: {
957
1010
  name: { type: "string", description: "Nome do item (exibi\xE7\xE3o). Na NFS-e s\xF3 \xE9 usado se `description` vier vazio." },
958
- description: { type: "string", description: "Texto do item. \xC9 ele que comp\xF5e a discrimina\xE7\xE3o da NFS-e (uma linha por item)." },
1011
+ description: { type: "string", description: 'Detalhe do item. Na discrimina\xE7\xE3o da NFS-e vai abaixo do `name`, inteiro se couber na DANFS-e; se n\xE3o couber, s\xF3 o que couber, com "\u2026 (+N linhas)".' },
959
1012
  unit: { type: "string", default: "un" },
960
1013
  quantity: { type: "number", default: 1 },
961
1014
  unit_price: { type: "number" },
@@ -986,8 +1039,8 @@ var SCHEMAS = {
986
1039
  id: { type: "string", format: "uuid" },
987
1040
  status: { type: "string", enum: ["pending", "paid", "cancelled", "expired", "failed"] },
988
1041
  status_raw: { type: "string", description: "Status bruto do provider" },
989
- method: { type: "string", enum: ["pix", "boleto", "checkout", "credit_card"] },
990
- provider: { type: "string", enum: ["inter", "c6bank", "pix_offline", "pagarme", "cora"], description: "Provedor resolvido. 'pix_offline' = Pix est\xE1tico (BR Code local). 'pagarme' = Pix server-side ou cart\xE3o (method=credit_card retorna 'checkout.url' = link da p\xE1gina de pagamento). 'cora' = boleto ou Pix emitidos de forma s\xEDncrona (o boleto j\xE1 volta com 'pdf_url')." },
1042
+ method: { type: "string", enum: ["pix", "boleto", "checkout", "credit_card", "pix_automatico"], description: "Canal. 'pix_automatico' = cobran\xE7a do ciclo de uma recorr\xEAncia Pix Autom\xE1tico (Inter ou C6), criada pelo sistema \u2014 n\xE3o sai por POST /v1/charges." },
1043
+ provider: { type: "string", enum: ["inter", "c6bank", "pix_offline", "pagarme", "cora", "mercadopago"], description: "Provedor resolvido. 'pix_offline' = Pix est\xE1tico (BR Code local). 'pagarme' = Pix server-side ou cart\xE3o (method=credit_card retorna 'checkout.url' = link da p\xE1gina de pagamento). 'cora' = boleto ou Pix emitidos de forma s\xEDncrona (o boleto j\xE1 volta com 'pdf_url'). 'mercadopago' = cobran\xE7a feita pela tela/assinatura do Mercado Pago (s\xF3 leitura: POST /v1/charges n\xE3o emite por ele)." },
991
1044
  invoice_id: { type: ["string", "null"], format: "uuid" },
992
1045
  customer_id: { type: ["string", "null"], format: "uuid" },
993
1046
  amount: { type: ["number", "null"] },
@@ -1009,8 +1062,12 @@ var SCHEMAS = {
1009
1062
  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." },
1010
1063
  customer_id: { type: "string", format: "uuid", description: "Obrigat\xF3rio se invoice_id omitido" },
1011
1064
  amount: { type: "number", description: "Obrigat\xF3rio se invoice_id omitido" },
1012
- due_date: { type: "string", format: "date", description: "Obrigat\xF3rio se invoice_id omitido" },
1013
- description: { type: "string" }
1065
+ due_date: { type: "string", format: "date", description: "Obrigat\xF3rio se invoice_id omitido. Com invoice_id (+ charge_id), s\xF3 no Inter e no C6: vencimento do boleto NOVO, para cobrar parcela vencida sem alterar a fatura (n\xE3o pode estar no passado; se a parcela j\xE1 tem cobran\xE7a viva, 409 \u2014 cancele antes)." },
1066
+ description: { type: "string" },
1067
+ fine: { type: "object", description: "Boleto Inter ou C6: multa por atraso. Sem ele vale a configura\xE7\xE3o da empresa; value 0 desliga a da empresa nesta cobran\xE7a.", properties: { type: { type: "string", enum: ["percent", "amount"] }, value: { type: "number" } } },
1068
+ interest: { type: "object", description: "Boleto Inter ou C6: juros de mora (value 0 desliga). Use monthly_percent (% ao m\xEAs) OU daily_amount (R$/dia).", properties: { monthly_percent: { type: "number" }, daily_amount: { type: "number" } } },
1069
+ discount: { type: "object", description: "Boleto Inter ou C6: desconto por antecipa\xE7\xE3o (value 0 desliga).", properties: { type: { type: "string", enum: ["percent", "amount"] }, value: { type: "number" }, days_before: { type: "integer" } } },
1070
+ messages: { type: "array", maxItems: 5, items: { type: "string" }, description: "S\xF3 Inter (o C6 recusa com 422): at\xE9 5 linhas de instru\xE7\xE3o impressas no boleto." }
1014
1071
  }
1015
1072
  },
1016
1073
  Webhook: {
@@ -1500,9 +1557,9 @@ var SCHEMAS = {
1500
1557
  properties: {
1501
1558
  id: { type: "string", format: "uuid" },
1502
1559
  name: { type: "string" },
1503
- system_key: { type: ["string", "null"], description: "Ex: inter_pix, c6bank_boleto" },
1504
- channel_key: { type: ["string", "null"], enum: ["pix", "boleto", "checkout", null] },
1505
- provider_name: { type: ["string", "null"], enum: ["inter", "c6bank", null] },
1560
+ system_key: { type: ["string", "null"], description: "Ex: inter_pix, c6bank_boleto, pagarme_credit_card, inter_pix_automatico. Forma manual (sem integra\xE7\xE3o) volta null." },
1561
+ channel_key: { type: ["string", "null"], enum: ["pix", "boleto", "checkout", "credit_card", "pix_automatico", null], description: "Canal. null = forma manual (dinheiro, transfer\xEAncia\u2026)." },
1562
+ provider_name: { type: ["string", "null"], enum: ["inter", "c6bank", "cora", "pagarme", "mercadopago", "pix_offline", null], description: "Banco/gateway da forma. Em /v1/payment-methods/ap (pagamento a fornecedor) s\xF3 aparecem inter, c6bank e cora. null = forma manual." },
1506
1563
  active: { type: "boolean" }
1507
1564
  }
1508
1565
  },
@@ -1573,7 +1630,7 @@ var SCHEMAS = {
1573
1630
  required: ["invoice_id"],
1574
1631
  properties: {
1575
1632
  invoice_id: { type: "string", format: "uuid", description: "Fatura a partir da qual emitir a NFS-e" },
1576
- discriminacao: { type: "string", maxLength: 2e3, description: "Opcional. Texto integral da discrimina\xE7\xE3o do servi\xE7o (xDescServ) \u2014 substitui o montado dos itens. Nota autorizada n\xE3o se edita (s\xF3 cancela e reemite), ent\xE3o \xE9 aqui que se acerta o texto. Inclua o n\xFAmero da fatura se quiser que ele apare\xE7a. Sem o campo: n\xFAmero da fatura + a descri\xE7\xE3o de cada item." }
1633
+ discriminacao: { type: "string", maxLength: 2e3, description: "Opcional. Texto integral da discrimina\xE7\xE3o do servi\xE7o (xDescServ) \u2014 substitui o montado dos itens. Nota autorizada n\xE3o se edita (s\xF3 cancela e reemite), ent\xE3o \xE9 aqui que se acerta o texto. Inclua o n\xFAmero da fatura se quiser que ele apare\xE7a. Sem o campo: n\xFAmero da fatura + o `name` de cada item, com a `description` abaixo dele." }
1577
1634
  }
1578
1635
  },
1579
1636
  NfseCancel: {
@@ -1751,6 +1808,296 @@ var SCHEMAS = {
1751
1808
  active: { type: "boolean" },
1752
1809
  is_default: { type: "boolean", description: "Empresa padr\xE3o da chave (usada quando X-Company-Id \xE9 omitido)" }
1753
1810
  }
1811
+ },
1812
+ // ---------------------------------------------------------------- Parcerias (specs/parcerias/)
1813
+ Parceria: {
1814
+ type: "object",
1815
+ description: "Caixa de um trabalho feito em conjunto com quem n\xE3o \xE9 s\xF3cio: a receita entra, o imposto e as despesas comuns saem, e o resto \xE9 dividido entre os participantes.",
1816
+ properties: {
1817
+ id: { type: "string", format: "uuid" },
1818
+ company_id: { type: "string", format: "uuid", description: "Empresa gestora" },
1819
+ nome: { type: "string" },
1820
+ descricao: { type: ["string", "null"] },
1821
+ status: { type: "string", enum: ["ativa", "encerrada"] },
1822
+ data_corte: { type: "string", format: "date", description: "In\xEDcio do livro; antes dela s\xF3 o saldo inicial" },
1823
+ created_at: { type: "string", format: "date-time" },
1824
+ updated_at: { type: "string", format: "date-time" }
1825
+ }
1826
+ },
1827
+ ParceriaResumo: {
1828
+ type: "object",
1829
+ description: "Saldo de cada participante, onde est\xE1 o dinheiro e alertas. total_saldos = total_contas quando o livro fecha.",
1830
+ properties: {
1831
+ participantes: { type: "array", items: { type: "object", properties: {
1832
+ id: { type: "string", format: "uuid" },
1833
+ supplier_id: { type: "string", format: "uuid" },
1834
+ nome: { type: "string" },
1835
+ documento: { type: ["string", "null"] },
1836
+ user_id: { type: ["string", "null"] },
1837
+ percentual_padrao: { type: "number" },
1838
+ natureza_retirada: { type: "string", enum: ["repasse", "distribuicao_lucros"] },
1839
+ exige_nota: { type: "boolean" },
1840
+ ativo: { type: "boolean" },
1841
+ saldo: { type: "number" },
1842
+ notas_pendentes: { type: "number" }
1843
+ } } },
1844
+ onde_esta: { type: "array", items: { type: "object", properties: {
1845
+ bank_account_id: { type: ["string", "null"] },
1846
+ conta: { type: "string" },
1847
+ empresa_id: { type: ["string", "null"] },
1848
+ empresa: { type: ["string", "null"] },
1849
+ valor: { type: "number" }
1850
+ } } },
1851
+ total_saldos: { type: "number" },
1852
+ total_contas: { type: "number" },
1853
+ a_receber: { type: "number", description: "Parcelas em aberto dos contratos e faturas vinculados (informativo)" },
1854
+ impostos_provisorios: { type: "object", properties: { quantidade: { type: "integer" }, valor: { type: "number" } } },
1855
+ impostos_pendentes: { type: "integer", description: "Impostos sem al\xEDquota conhecida (empresa sem c\xE1lculo autom\xE1tico)" },
1856
+ retiradas_sem_despesa: { type: "integer" },
1857
+ eventos_com_erro: { type: "integer", description: "Lan\xE7amentos autom\xE1ticos que falharam e n\xE3o entraram no livro" },
1858
+ meses_fechados: { type: "array", items: { type: "string", format: "date" } }
1859
+ }
1860
+ },
1861
+ ParceriaDetalhe: {
1862
+ allOf: [{ $ref: "#/components/schemas/Parceria" }, { type: "object", properties: { resumo: { $ref: "#/components/schemas/ParceriaResumo" } } }]
1863
+ },
1864
+ ParceriaCreate: {
1865
+ type: "object",
1866
+ required: ["nome", "participantes"],
1867
+ properties: {
1868
+ nome: { type: "string" },
1869
+ descricao: { type: "string" },
1870
+ data_corte: { type: "string", format: "date", description: "Padr\xE3o: hoje" },
1871
+ participantes: {
1872
+ type: "array",
1873
+ minItems: 2,
1874
+ description: "Cada um \xE9 um fornecedor-favorecido da empresa gestora; os percentuais somam 100.",
1875
+ items: { type: "object", required: ["supplier_id", "percentual"], properties: {
1876
+ supplier_id: { type: "string", format: "uuid" },
1877
+ user_id: { type: "string", format: "uuid", description: "Quando o participante \xE9 um usu\xE1rio da empresa" },
1878
+ percentual: { type: "number", minimum: 0, maximum: 100 },
1879
+ saldo_inicial: { type: "number", description: "Saldo na data de corte (pode ser negativo)" },
1880
+ natureza_retirada: { type: "string", enum: ["repasse", "distribuicao_lucros"], description: "repasse = custo com nota do parceiro; distribuicao_lucros = fora do DRE" },
1881
+ exige_nota: { type: "boolean" }
1882
+ } }
1883
+ },
1884
+ empresas: {
1885
+ type: "array",
1886
+ description: "Outras empresas que faturam para a parceria (exige admin nas duas; com chave sem usu\xE1rio, s\xF3 a empresa da chave).",
1887
+ items: { type: "object", required: ["empresa_id"], properties: {
1888
+ empresa_id: { type: "string", format: "uuid" },
1889
+ modo_imposto: { type: "string", enum: ["automatico", "percentual"] },
1890
+ percentual_imposto: { type: "number", minimum: 0, maximum: 100 }
1891
+ } }
1892
+ },
1893
+ saldo_contas: {
1894
+ type: "array",
1895
+ description: "Onde est\xE1 o saldo inicial; a soma tem que ser igual \xE0 soma dos saldos iniciais.",
1896
+ items: { type: "object", required: ["bank_account_id", "valor"], properties: {
1897
+ bank_account_id: { type: "string", format: "uuid" },
1898
+ valor: { type: "number" }
1899
+ } }
1900
+ }
1901
+ }
1902
+ },
1903
+ ParceriaUpdate: {
1904
+ type: "object",
1905
+ properties: {
1906
+ nome: { type: "string" },
1907
+ descricao: { type: ["string", "null"] },
1908
+ status: { type: "string", enum: ["ativa", "encerrada"] }
1909
+ }
1910
+ },
1911
+ ParceriaLancamento: {
1912
+ type: "object",
1913
+ description: "Linha do livro. valor \xE9 o efeito no bolo, com sinal (receita +, imposto \u2212, despesa \u2212, retirada \u2212, transfer\xEAncia 0). O livro \xE9 imut\xE1vel: corre\xE7\xE3o \xE9 estorno.",
1914
+ properties: {
1915
+ id: { type: "string", format: "uuid" },
1916
+ tipo: { type: "string", enum: ["saldo_inicial", "receita", "imposto", "imposto_acerto", "despesa", "retirada", "transferencia", "ajuste", "estorno"] },
1917
+ origem: { type: "string", enum: ["automatico", "manual"] },
1918
+ data: { type: "string", format: "date" },
1919
+ competencia: { type: "string", format: "date" },
1920
+ valor: { type: "number" },
1921
+ descricao: { type: "string" },
1922
+ empresa_id: { type: ["string", "null"] },
1923
+ bank_account_id: { type: ["string", "null"] },
1924
+ bank_account_destino_id: { type: ["string", "null"] },
1925
+ valor_movimentado: { type: ["number", "null"] },
1926
+ participante_id: { type: ["string", "null"] },
1927
+ lancamento_pai_id: { type: ["string", "null"] },
1928
+ aliquota: { type: ["number", "null"] },
1929
+ aliquota_fonte: { type: ["string", "null"] },
1930
+ provisorio: { type: "boolean" },
1931
+ nota_status: { type: "string", enum: ["nao_se_aplica", "pendente", "casada", "dispensada"] },
1932
+ nfse_recebida_id: { type: ["string", "null"] },
1933
+ estornado: { type: "boolean" },
1934
+ motivo: { type: ["string", "null"] },
1935
+ created_at: { type: "string", format: "date-time" },
1936
+ rateio: { type: "array", items: { type: "object", properties: { participante_id: { type: "string", format: "uuid" }, valor: { type: "number" } } } }
1937
+ }
1938
+ },
1939
+ ParceriaLancamentoCreate: {
1940
+ type: "object",
1941
+ required: ["tipo", "data", "descricao"],
1942
+ properties: {
1943
+ tipo: { type: "string", enum: ["receita", "despesa", "transferencia", "ajuste"], description: "Retirada \xE9 POST /parcerias/{id}/retiradas." },
1944
+ valor: { type: "number", exclusiveMinimum: 0, description: "Positivo. N\xE3o se usa em ajuste (o valor \xE9 a soma do rateio)." },
1945
+ data: { type: "string", format: "date" },
1946
+ descricao: { type: "string" },
1947
+ empresa_id: { type: "string", format: "uuid", description: "Obrigat\xF3rio na receita: a empresa que emitiu define o imposto" },
1948
+ bank_account_id: { type: "string", format: "uuid", description: "Conta onde o dinheiro est\xE1; na transfer\xEAncia, a de origem" },
1949
+ bank_account_destino_id: { type: "string", format: "uuid", description: "S\xF3 transfer\xEAncia" },
1950
+ percentuais: { type: "object", additionalProperties: { type: "number" }, description: "Divis\xE3o diferente da padr\xE3o {participante_id: percentual}; exige parcerias:update" },
1951
+ aliquota: { type: "number", minimum: 0, maximum: 100, description: "S\xF3 receita: al\xEDquota \xE0 m\xE3o; exige parcerias:update" },
1952
+ rateio: { type: "object", additionalProperties: { type: "number" }, description: "S\xF3 ajuste: {participante_id: valor com sinal}" },
1953
+ motivo: { type: "string", description: "Obrigat\xF3rio no ajuste" }
1954
+ }
1955
+ },
1956
+ ParceriaRetiradaCreate: {
1957
+ type: "object",
1958
+ required: ["participante_id", "valor", "data", "empresa_id", "bank_account_id"],
1959
+ properties: {
1960
+ participante_id: { type: "string", format: "uuid" },
1961
+ valor: { type: "number", exclusiveMinimum: 0 },
1962
+ data: { type: "string", format: "date" },
1963
+ empresa_id: { type: "string", format: "uuid", description: "Empresa de onde o dinheiro sai (a NFS-e do parceiro tem que ser contra ela)" },
1964
+ bank_account_id: { type: "string", format: "uuid" },
1965
+ descricao: { type: "string" },
1966
+ confirmo_adiantamento: { type: "boolean", description: "Obrigat\xF3rio quando a retirada passa do saldo do participante" },
1967
+ pelo_banco: { type: "boolean", description: "true = pagar pelo banco: vira conta a pagar ao parceiro (Pix/boleto pelo fluxo de contas a pagar, com o 2FA de pagamento) e o lan\xE7amento nasce quando o pagamento \xE9 confirmado. A\xED 'data' \xE9 a data de pagamento (hoje ou depois) e a resposta \xE9 202." }
1968
+ }
1969
+ },
1970
+ ParceriaRetiradaAPagar: {
1971
+ type: "object",
1972
+ description: "Retirada paga pelo banco, ainda a pagar. Pague a parcela da conta a pagar (POST /payouts); o valor fica reservado no saldo do participante.",
1973
+ properties: {
1974
+ id: { type: "string", format: "uuid" },
1975
+ purchase_invoice_id: { type: "string", format: "uuid", description: "Conta a pagar ao parceiro na empresa de origem" },
1976
+ purchase_invoice_charge_id: { type: "string", format: "uuid", description: "Parcela a pagar" },
1977
+ status: { type: "string", enum: ["aguardando"] }
1978
+ }
1979
+ },
1980
+ ParceriaNotaResolve: {
1981
+ type: "object",
1982
+ description: "Casar a retirada com a NFS-e recebida do participante, ou dispensar a nota com motivo.",
1983
+ properties: {
1984
+ nfse_recebida_id: { type: "string", format: "uuid" },
1985
+ dispensar: { type: "boolean" },
1986
+ motivo: { type: "string" }
1987
+ }
1988
+ },
1989
+ ParceriaVinculo: {
1990
+ type: "object",
1991
+ properties: {
1992
+ id: { type: "string", format: "uuid" },
1993
+ tipo: { type: "string", enum: ["contrato", "fatura", "despesa", "despesa_recorrente", "conta_a_pagar", "conta_a_pagar_recorrente", "das_mei"], description: "das_mei: ref_id \xE9 a EMPRESA (MEI) \u2014 a guia do DAS de todo m\xEAs entra como despesa comum quando paga" },
1994
+ ref_id: { type: "string", format: "uuid" },
1995
+ ref_company_id: { type: "string", format: "uuid" },
1996
+ empresa: { type: "string" },
1997
+ titulo: { type: ["string", "null"] },
1998
+ percentuais: { type: ["object", "null"] },
1999
+ desde: { type: "string", format: "date" }
2000
+ }
2001
+ },
2002
+ ParceriaVinculoCreate: {
2003
+ type: "object",
2004
+ required: ["tipo", "ref_id"],
2005
+ properties: {
2006
+ tipo: { type: "string", enum: ["contrato", "fatura", "despesa", "despesa_recorrente", "conta_a_pagar", "conta_a_pagar_recorrente", "das_mei"], description: "das_mei: ref_id \xE9 a EMPRESA (MEI) \u2014 a guia do DAS de todo m\xEAs entra como despesa comum quando paga" },
2007
+ ref_id: { type: "string", format: "uuid" },
2008
+ desde: { type: "string", format: "date", description: "S\xF3 entra o que foi pago a partir daqui (padr\xE3o: a data de corte)" },
2009
+ percentuais: { type: "object", additionalProperties: { type: "number" }, description: "Divis\xE3o pr\xF3pria deste item {participante_id: percentual}" },
2010
+ incluir_antes_do_corte: { type: "boolean", default: false, description: "true deixa 'desde' ser ANTERIOR \xE0 data de corte e lan\xE7a esses pagamentos nas datas reais (s\xF3 admin). Quem pede declara que esse dinheiro N\xC3O est\xE1 no saldo inicial \u2014 o caso t\xEDpico \xE9 recebimento de outra empresa, fora das contas do saldo inicial. Sem ele, 'desde' antes do corte \xE9 empurrado para o corte. Confira antes com GET /parcerias/{id}/vinculos/previa." }
2011
+ }
2012
+ },
2013
+ ParceriaVinculoPrevia: {
2014
+ type: "object",
2015
+ description: "O que um v\xEDnculo traria se fosse feito agora (nada \xE9 gravado).",
2016
+ properties: {
2017
+ data_corte: { type: "string", format: "date" },
2018
+ desde: { type: "string", format: "date", description: "A partir de quando contaria (o 'desde' pedido ou a data de corte)" },
2019
+ quantidade: { type: "integer", description: "Pagamentos que entrariam no livro" },
2020
+ valor: { type: "number" },
2021
+ quantidade_antes_do_corte: { type: "integer", description: "Desses, quantos s\xE3o anteriores ao corte (s\xF3 entram com incluir_antes_do_corte)" },
2022
+ valor_antes_do_corte: { type: "number" },
2023
+ primeiro: { type: ["string", "null"], format: "date" },
2024
+ ultimo: { type: ["string", "null"], format: "date" },
2025
+ em_aberto_quantidade: { type: "integer", description: "Parcelas/despesas do item ainda N\xC3O pagas \u2014 entram sozinhas quando forem pagas" },
2026
+ em_aberto_valor: { type: "number" },
2027
+ em_aberto_proximo_vencimento: { type: ["string", "null"], format: "date" }
2028
+ }
2029
+ },
2030
+ ParceriaParticipantesUpdate: {
2031
+ type: "object",
2032
+ required: ["participantes"],
2033
+ properties: {
2034
+ participantes: {
2035
+ type: "array",
2036
+ minItems: 1,
2037
+ description: "S\xF3 os participantes que MUDAM (quem n\xE3o aparece fica como est\xE1). Depois de salvar, os ativos precisam somar 100%. Tirar quem tem hist\xF3rico (rateio ou lan\xE7amento) o deixa inativo \u2014 o saldo e o passado continuam dele; sem hist\xF3rico, ele \xE9 exclu\xEDdo. Recusado (422) se ainda tem parte numa divis\xE3o pr\xF3pria de v\xEDnculo.",
2038
+ items: { type: "object", properties: {
2039
+ id: { type: "string", format: "uuid", description: "Participante que j\xE1 est\xE1 na parceria (veja resumo.participantes em GET /parcerias/{id})" },
2040
+ supplier_id: { type: "string", format: "uuid", description: "Novo participante (fornecedor-favorecido da empresa gestora). Quem j\xE1 foi participante volta com o mesmo cadastro e o hist\xF3rico." },
2041
+ percentual: { type: "number", minimum: 0, maximum: 100 },
2042
+ natureza_retirada: { type: "string", enum: ["repasse", "distribuicao_lucros"] },
2043
+ exige_nota: { type: "boolean" },
2044
+ user_id: { type: ["string", "null"], description: "Usu\xE1rio da empresa ligado ao participante; '' ou null desliga" },
2045
+ ativo: { type: "boolean", description: "true reativa quem tinha sa\xEDdo; false tira (igual a excluir, mas nunca apaga)" },
2046
+ excluir: { type: "boolean", description: "Tira da parceria (inativo se tem hist\xF3rico, exclu\xEDdo se n\xE3o tem)" }
2047
+ } }
2048
+ }
2049
+ }
2050
+ },
2051
+ ParceriaSaldoInicialUpdate: {
2052
+ type: "object",
2053
+ description: `ESTADO FINAL das contas e do saldo inicial. As duas somas finais t\xEAm de fechar (como na cria\xE7\xE3o). O livro \xE9 imut\xE1vel: a diferen\xE7a de cada participante entra como um novo lan\xE7amento 'saldo_inicial' na data de corte ("Ajuste do saldo inicial"). M\xEAs da data de corte fechado recusa.`,
2054
+ properties: {
2055
+ contas: {
2056
+ type: "array",
2057
+ description: "Onde est\xE1 o saldo inicial. Conta ausente (ou com valor 0) sai.",
2058
+ items: { type: "object", required: ["bank_account_id", "valor"], properties: {
2059
+ bank_account_id: { type: "string", format: "uuid" },
2060
+ valor: { type: "number" }
2061
+ } }
2062
+ },
2063
+ participantes: {
2064
+ type: "array",
2065
+ description: "Saldo inicial de cada um. Participante n\xE3o listado mant\xE9m o que tem.",
2066
+ items: { type: "object", required: ["participante_id", "saldo"], properties: {
2067
+ participante_id: { type: "string", format: "uuid" },
2068
+ saldo: { type: "number" }
2069
+ } }
2070
+ }
2071
+ }
2072
+ },
2073
+ ParceriaEmpresaUpsert: {
2074
+ type: "object",
2075
+ required: ["empresa_id"],
2076
+ properties: {
2077
+ empresa_id: { type: "string", format: "uuid", description: "Empresa que fatura para a parceria. Incluir exige admin nas DUAS empresas \u2014 com chave cmd_live (sem usu\xE1rio) s\xF3 a empresa da chave; para incluir outra, use o chat, o OAuth do MCP ou o JWT de um admin das duas." },
2078
+ modo_imposto: { type: "string", enum: ["automatico", "percentual"], default: "automatico", description: "automatico = al\xEDquota efetiva da empresa; percentual = percentual_imposto fixo" },
2079
+ percentual_imposto: { type: "number", description: "Obrigat\xF3rio com modo_imposto = percentual" }
2080
+ }
2081
+ },
2082
+ ParceriaPrestacao: {
2083
+ type: "object",
2084
+ description: "Presta\xE7\xE3o de contas do m\xEAs: abertura + receitas + impostos + despesas + retiradas + ajustes = fechamento, por participante.",
2085
+ properties: {
2086
+ competencia: { type: "string", description: "AAAA-MM" },
2087
+ participantes: { type: "array", items: { type: "object", properties: {
2088
+ participante_id: { type: "string", format: "uuid" },
2089
+ nome: { type: "string" },
2090
+ abertura: { type: "number" },
2091
+ receitas: { type: "number" },
2092
+ impostos: { type: "number" },
2093
+ despesas: { type: "number" },
2094
+ retiradas: { type: "number" },
2095
+ ajustes: { type: "number" },
2096
+ fechamento: { type: "number" }
2097
+ } } },
2098
+ totais: { type: "object" },
2099
+ lancamentos: { type: "array", items: { type: "object" } }
2100
+ }
1754
2101
  }
1755
2102
  };
1756
2103
  function paginatedResponse(schemaRef) {
@@ -1838,7 +2185,8 @@ var OPENAPI_SPEC = {
1838
2185
  { name: "Pagamentos a Fornecedor", description: "Payouts \u2014 pagar/agendar Pix e boleto a fornecedores" },
1839
2186
  { name: "M\xE9todos de pagamento", description: "Formas de recebimento dispon\xEDveis" },
1840
2187
  { name: "Formas de pagamento do fornecedor", description: "Cadastro de destinos de pagamento por fornecedor" },
1841
- { name: "Lembretes", description: "Lembretes e resumos agendados (recorrentes ou avulsos)" }
2188
+ { name: "Lembretes", description: "Lembretes e resumos agendados (recorrentes ou avulsos)" },
2189
+ { name: "Parcerias", description: "Caixa compartilhado com parceiro que n\xE3o \xE9 s\xF3cio: receita, imposto, despesas comuns, retiradas e presta\xE7\xE3o de contas" }
1842
2190
  ],
1843
2191
  components: {
1844
2192
  securitySchemes: {
@@ -2295,7 +2643,7 @@ var OPENAPI_SPEC = {
2295
2643
  operationId: "createContract",
2296
2644
  security: [{ ApiKeyAuth: ["contracts:write"] }],
2297
2645
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContractCreate" } } } },
2298
- responses: { "201": { description: "Contrato criado", content: { "application/json": { schema: { $ref: "#/components/schemas/Contract" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Cliente n\xE3o encontrado"), ...COMMON_ERRORS }
2646
+ responses: { "201": { description: "Contrato criado", content: { "application/json": { schema: { $ref: "#/components/schemas/Contract" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Cliente n\xE3o encontrado"), "422": errorResponse("Forma Pix Autom\xE1tico com periodicidade, parcelas ou prazo de vencimento que o Banco Central n\xE3o aceita"), ...COMMON_ERRORS }
2299
2647
  }
2300
2648
  },
2301
2649
  "/contracts/{id}": {
@@ -2317,7 +2665,7 @@ var OPENAPI_SPEC = {
2317
2665
  operationId: "updateContract",
2318
2666
  security: [{ ApiKeyAuth: ["contracts:write"] }],
2319
2667
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContractUpdate" } } } },
2320
- responses: { "200": { description: "Contrato atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Contract" } } } }, "400": errorResponse("Dados inv\xE1lidos ou nenhum campo para atualizar"), "404": errorResponse("Contrato ou cliente n\xE3o encontrado"), "409": errorResponse("Troca de cliente com autoriza\xE7\xE3o de d\xE9bito recorrente ativa"), ...COMMON_ERRORS }
2668
+ responses: { "200": { description: "Contrato atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Contract" } } } }, "400": errorResponse("Dados inv\xE1lidos ou nenhum campo para atualizar"), "404": errorResponse("Contrato ou cliente n\xE3o encontrado"), "409": errorResponse("Troca de cliente com autoriza\xE7\xE3o de d\xE9bito recorrente ativa"), "422": errorResponse("Forma Pix Autom\xE1tico com periodicidade, parcelas ou prazo de vencimento que o Banco Central n\xE3o aceita"), ...COMMON_ERRORS }
2321
2669
  },
2322
2670
  delete: {
2323
2671
  tags: ["Contratos"],
@@ -2441,7 +2789,7 @@ var OPENAPI_SPEC = {
2441
2789
  parameters: [
2442
2790
  ...PAGINATION_PARAMS,
2443
2791
  { name: "search", in: "query", schema: { type: "string" }, description: "Busca por n\xFAmero ou t\xEDtulo" },
2444
- { name: "status", in: "query", schema: { type: "string", enum: ["rascunho", "enviada", "aceita", "cancelada"] } },
2792
+ { name: "status", in: "query", schema: { type: "string", enum: ["rascunho", "enviada", "aceita", "ativa", "cancelada"] } },
2445
2793
  { name: "payment_status", in: "query", schema: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] } },
2446
2794
  { name: "customer_id", in: "query", schema: { type: "string", format: "uuid" } },
2447
2795
  { name: "due_date_from", in: "query", schema: { type: "string", format: "date" }, description: "Vencimento a partir de (YYYY-MM-DD)" },
@@ -2508,6 +2856,35 @@ var OPENAPI_SPEC = {
2508
2856
  responses: { "204": { description: "Exclu\xEDda" }, "404": errorResponse("Fatura n\xE3o encontrada"), "409": errorResponse("H\xE1 registros vinculados que impedem a exclus\xE3o"), ...COMMON_ERRORS }
2509
2857
  }
2510
2858
  },
2859
+ "/contracts/{id}/pix-automatico": {
2860
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
2861
+ get: {
2862
+ tags: ["Contratos"],
2863
+ summary: "Consultar a autoriza\xE7\xE3o de Pix Autom\xE1tico do contrato",
2864
+ operationId: "getContractPixAutomatico",
2865
+ description: "Estado do Pix Autom\xE1tico do contrato: banco da forma de cobran\xE7a (inter ou c6bank), se o contrato cabe nas regras do Banco Central (apto/problemas), a autoriza\xE7\xE3o (Rec) mais recente com o status (CRIADA = aguardando o pagador, APROVADA = d\xE9bitos liberados, REJEITADA/CANCELADA/EXPIRADA = encerrada) e o link de autoriza\xE7\xE3o, se j\xE1 existe. N\xE3o cria nada. As cobran\xE7as de cada ciclo saem em GET /v1/charges?channel=pix_automatico e o pagamento chega pelo webhook charge.paid.",
2866
+ security: [{ ApiKeyAuth: ["contracts:read"] }],
2867
+ responses: {
2868
+ "200": { description: "Estado do Pix Autom\xE1tico", content: { "application/json": { schema: { $ref: "#/components/schemas/ContractPixAutomatico" } } } },
2869
+ "404": errorResponse("Contrato n\xE3o encontrado"),
2870
+ ...COMMON_ERRORS
2871
+ }
2872
+ },
2873
+ post: {
2874
+ tags: ["Contratos"],
2875
+ summary: "Gerar o link de autoriza\xE7\xE3o do Pix Autom\xE1tico",
2876
+ operationId: "createContractPixAutomaticoLink",
2877
+ description: "Devolve o link que o pagador abre para autorizar o d\xE9bito recorrente (/assinar): ele l\xEA os termos, recebe o QR Code e aprova no app do banco dele. Idempotente: se o contrato j\xE1 tem link ativo, devolve o mesmo. Recusa (422) se a forma de cobran\xE7a n\xE3o \xE9 Pix Autom\xE1tico ou se o contrato n\xE3o cabe nas regras do Banco Central (periodicidade semanal/mensal/trimestral/semestral/anual, uma parcela por ciclo, vencimento a 2+ dias da gera\xE7\xE3o), e (409) se o contrato n\xE3o est\xE1 ativo. Envie o link ao pagador pelo seu canal; depois acompanhe por GET at\xE9 autorizacao.status = APROVADA.",
2878
+ security: [{ ApiKeyAuth: ["contracts:write"] }],
2879
+ responses: {
2880
+ "200": { description: "Link de autoriza\xE7\xE3o e estado", content: { "application/json": { schema: { $ref: "#/components/schemas/ContractPixAutomatico" } } } },
2881
+ "404": errorResponse("Contrato n\xE3o encontrado"),
2882
+ "409": errorResponse("Contrato n\xE3o est\xE1 ativo"),
2883
+ "422": errorResponse("Forma de cobran\xE7a n\xE3o \xE9 Pix Autom\xE1tico ou contrato fora das regras do Banco Central"),
2884
+ ...COMMON_ERRORS
2885
+ }
2886
+ }
2887
+ },
2511
2888
  "/contracts/{id}/generate-invoices": {
2512
2889
  parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
2513
2890
  post: {
@@ -3242,7 +3619,7 @@ var OPENAPI_SPEC = {
3242
3619
  tags: ["NFS-e"],
3243
3620
  summary: "Emitir NFS-e",
3244
3621
  operationId: "emitNfse",
3245
- 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**Discrimina\xE7\xE3o do servi\xE7o (o texto que vai \xE0 prefeitura).** Por padr\xE3o \xE9 o n\xFAmero da fatura seguido, uma linha por item, do `description` de cada item \u2014 e, s\xF3 se o `description` estiver vazio, o `name`. Ou seja: com os dois preenchidos, o `name` \xE9 exibi\xE7\xE3o interna e N\xC3O chega ao documento fiscal. Para controlar o texto, mande `discriminacao` (at\xE9 2000 caracteres). Nota autorizada n\xE3o se edita: errou o texto, \xE9 cancelar e reemitir \u2014 por isso confira antes. Um 409 de nota anterior s\xF3 vale para nota `autorizada` ou `transmitindo`; fatura com nota **cancelada** pode ser emitida de novo.\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.",
3622
+ 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**Discrimina\xE7\xE3o do servi\xE7o (o texto que vai \xE0 prefeitura).** Por padr\xE3o \xE9 o n\xFAmero da fatura seguido, para cada item, do `name` (t\xEDtulo) e, abaixo dele, do `description`. O t\xEDtulo sempre vai; o `description` vai inteiro se o texto couber na caixa da DANFS-e (19 linhas) \u2014 se n\xE3o couber, entra o que couber e uma linha `\u2026 (+N linhas)` diz quanto ficou de fora. `description` igual ao `name` n\xE3o se repete. Para controlar o texto, mande `discriminacao` (at\xE9 2000 caracteres). Nota autorizada n\xE3o se edita: errou o texto, \xE9 cancelar e reemitir \u2014 por isso confira antes. Um 409 de nota anterior s\xF3 vale para nota `autorizada` ou `transmitindo`; fatura com nota **cancelada** pode ser emitida de novo.\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.",
3246
3623
  security: [{ ApiKeyAuth: ["nfse:emitir"] }],
3247
3624
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/NfseEmit" } } } },
3248
3625
  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 }
@@ -3515,6 +3892,52 @@ var OPENAPI_SPEC = {
3515
3892
  responses: { "200": { description: "Cancelada", content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseInvoice" } } } }, "404": errorResponse("Conta a pagar n\xE3o encontrada"), "409": errorResponse("J\xE1 cancelada"), ...COMMON_ERRORS }
3516
3893
  }
3517
3894
  },
3895
+ "/purchase-invoices/{id}/pay": {
3896
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
3897
+ post: {
3898
+ tags: ["Contas a Pagar"],
3899
+ summary: "Registrar pagamento (baixa manual) de uma parcela",
3900
+ operationId: "payPurchaseInvoice",
3901
+ description: 'O "Marcar como pago" da tela: grava que a parcela foi paga \u2014 de qual conta, por qual forma, em que data, parcial ou total, com juros, multa e desconto. N\xC3O move dinheiro no banco (para pagar pelo Inter/C6 use POST /v1/payouts). A parcela e a conta passam a `pago`/`parcial` pelo pr\xF3prio banco, a despesa vinculada a uma parceria entra no livro e o webhook purchase_invoice.paid dispara quando a conta quita. At\xF4mico: dois pedidos iguais n\xE3o baixam o mesmo saldo duas vezes. `amount` \xE9 quanto da PARCELA foi baixado; o que saiu da conta \xE9 amount + interest + fine \u2212 discount. Campo de corpo que a rota n\xE3o conhece devolve 400.',
3902
+ security: [{ ApiKeyAuth: ["purchase_invoices:settle"] }],
3903
+ requestBody: { required: true, content: { "application/json": { schema: { type: "object", required: ["bank_account_id"], properties: {
3904
+ charge_id: { type: "string", format: "uuid", description: "Parcela paga (purchase_invoice_charges.id, veja GET /v1/purchase-invoices/{id}). Obrigat\xF3rio quando a conta tem mais de uma parcela; com uma s\xF3, \xE9 ela." },
3905
+ amount: { type: "number", description: "Quanto da parcela est\xE1 sendo baixado. Omitido, quita o saldo em aberto. Acima do saldo: 409 (o excedente \xE9 juros ou multa)." },
3906
+ interest: { type: "number", minimum: 0, description: "Juros pagos al\xE9m do valor da parcela" },
3907
+ fine: { type: "number", minimum: 0, description: "Multa paga al\xE9m do valor da parcela" },
3908
+ discount: { type: "number", minimum: 0, description: "Desconto obtido sobre o valor baixado" },
3909
+ payment_date: { type: "string", format: "date", description: "Data do pagamento (YYYY-MM-DD). Padr\xE3o: hoje (America/Sao_Paulo)." },
3910
+ payment_method_id: { type: "string", format: "uuid", description: "Forma de PAGAMENTO a fornecedor (GET /v1/payment-methods/ap)" },
3911
+ bank_account_id: { type: "string", format: "uuid", description: "Conta de onde saiu o dinheiro (GET /v1/bank-accounts). Saldo de gateway e cart\xE3o de cr\xE9dito s\xE3o recusados." },
3912
+ notes: { type: "string" }
3913
+ } } } } },
3914
+ responses: {
3915
+ "201": { description: "Pagamento registrado", content: { "application/json": { schema: { type: "object", properties: {
3916
+ payment_id: { type: "string", format: "uuid" },
3917
+ purchase_invoice_id: { type: "string" },
3918
+ purchase_invoice_payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] },
3919
+ amount: { type: "number", description: "Baixado da parcela" },
3920
+ interest: { type: "number" },
3921
+ fine: { type: "number" },
3922
+ discount: { type: "number" },
3923
+ total_paid: { type: "number", description: "O que saiu da conta" },
3924
+ payment_date: { type: "string", format: "date" },
3925
+ charge: { type: ["object", "null"], properties: {
3926
+ id: { type: "string" },
3927
+ sequence: { type: ["integer", "null"] },
3928
+ amount: { type: "number" },
3929
+ paid_amount: { type: "number" },
3930
+ remaining_amount: { type: "number" },
3931
+ payment_status: { type: ["string", "null"] }
3932
+ } }
3933
+ } } } } },
3934
+ "400": errorResponse("Campo inv\xE1lido, parcela n\xE3o informada numa conta parcelada, conta banc\xE1ria ou forma de outra empresa"),
3935
+ "404": errorResponse("Conta a pagar ou parcela n\xE3o encontrada"),
3936
+ "409": errorResponse("Conta cancelada, parcela j\xE1 paga ou valor acima do saldo"),
3937
+ ...COMMON_ERRORS
3938
+ }
3939
+ }
3940
+ },
3518
3941
  // -----------------------------------------------------------------------
3519
3942
  // Cobranças (Gateway)
3520
3943
  // -----------------------------------------------------------------------
@@ -3544,6 +3967,7 @@ var OPENAPI_SPEC = {
3544
3967
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChargeCreate" } } } },
3545
3968
  responses: {
3546
3969
  "201": { description: "Cobran\xE7a criada", content: { "application/json": { schema: { $ref: "#/components/schemas/Charge" } } } },
3970
+ "200": { description: "A parcela j\xE1 tinha cobran\xE7a viva: ela foi devolvida (`reused: true`), sem emitir outra no banco. Para reemitir com outro valor/vencimento, cancele (DELETE) e crie de novo.", content: { "application/json": { schema: { $ref: "#/components/schemas/Charge" } } } },
3547
3971
  "400": errorResponse("Dados inv\xE1lidos"),
3548
3972
  "409": errorResponse("Fatura j\xE1 paga"),
3549
3973
  "422": errorResponse("Integra\xE7\xE3o banc\xE1ria n\xE3o configurada"),
@@ -3568,6 +3992,17 @@ var OPENAPI_SPEC = {
3568
3992
  responses: { "200": { description: "Cancelamento solicitado" }, "404": errorResponse("Cobran\xE7a n\xE3o encontrada"), "409": errorResponse("Cobran\xE7a n\xE3o pode ser cancelada no estado atual"), ...COMMON_ERRORS }
3569
3993
  }
3570
3994
  },
3995
+ "/charges/{id}/pdf": {
3996
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
3997
+ get: {
3998
+ tags: ["Cobran\xE7as"],
3999
+ summary: "PDF do boleto",
4000
+ operationId: "getChargePdf",
4001
+ description: "Devolve `pdf_url` (URL assinada). No Banco Inter o boleto nasce EM_PROCESSAMENTO e o PDF s\xF3 existe quando o banco conclui (minutos): enquanto isso responde 202 com `retry_after_seconds`; chamar a rota tamb\xE9m consulta o banco e avan\xE7a o status.",
4002
+ security: [{ ApiKeyAuth: ["charges:read"] }],
4003
+ responses: { "200": { description: "PDF pronto", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, status_raw: { type: "string" }, pdf_url: { type: "string" } } } } } }, "202": { description: "Banco ainda processando" }, "404": errorResponse("Cobran\xE7a sem PDF ou inexistente"), ...COMMON_ERRORS }
4004
+ }
4005
+ },
3571
4006
  "/charges/{id}/refund": {
3572
4007
  parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
3573
4008
  post: {
@@ -4314,6 +4749,238 @@ var OPENAPI_SPEC = {
4314
4749
  }
4315
4750
  },
4316
4751
  // -----------------------------------------------------------------------
4752
+ // Parcerias (specs/parcerias/)
4753
+ // -----------------------------------------------------------------------
4754
+ "/parcerias": {
4755
+ get: {
4756
+ tags: ["Parcerias"],
4757
+ summary: "Listar parcerias",
4758
+ operationId: "listParcerias",
4759
+ security: [{ ApiKeyAuth: ["parcerias:list"] }],
4760
+ parameters: [...PAGINATION_PARAMS, { name: "status", in: "query", schema: { type: "string", enum: ["ativa", "encerrada"] } }],
4761
+ responses: { "200": paginatedResponse("#/components/schemas/Parceria"), ...COMMON_ERRORS }
4762
+ },
4763
+ post: {
4764
+ tags: ["Parcerias"],
4765
+ summary: "Criar parceria",
4766
+ operationId: "createParceria",
4767
+ description: "Cria a parceria na empresa da chave, com os participantes (percentuais somam 100), as empresas vinculadas e o saldo inicial.",
4768
+ security: [{ ApiKeyAuth: ["parcerias:create"] }],
4769
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaCreate" } } } },
4770
+ responses: { "201": { description: "Criada", content: { "application/json": { schema: { $ref: "#/components/schemas/Parceria" } } } }, "422": errorResponse("Regra da parceria recusada (percentuais, saldo inicial, empresa)"), ...COMMON_ERRORS }
4771
+ }
4772
+ },
4773
+ "/parcerias/{id}": {
4774
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
4775
+ get: {
4776
+ tags: ["Parcerias"],
4777
+ summary: "Obter parceria com o resumo (saldos e onde est\xE1 o dinheiro)",
4778
+ operationId: "getParceria",
4779
+ security: [{ ApiKeyAuth: ["parcerias:list"] }],
4780
+ responses: { "200": { description: "Parceria", content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaDetalhe" } } } }, "404": errorResponse("Parceria n\xE3o encontrada"), ...COMMON_ERRORS }
4781
+ },
4782
+ patch: {
4783
+ tags: ["Parcerias"],
4784
+ summary: "Atualizar nome, descri\xE7\xE3o ou situa\xE7\xE3o",
4785
+ operationId: "updateParceria",
4786
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4787
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaUpdate" } } } },
4788
+ responses: { "200": { description: "Atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/Parceria" } } } }, "404": errorResponse("Parceria n\xE3o encontrada"), ...COMMON_ERRORS }
4789
+ },
4790
+ delete: {
4791
+ tags: ["Parcerias"],
4792
+ summary: "Encerrar parceria",
4793
+ operationId: "closeParceria",
4794
+ description: "N\xE3o apaga: o livro fica. A parceria para de receber lan\xE7amentos (reabra com PATCH status=ativa).",
4795
+ security: [{ ApiKeyAuth: ["parcerias:delete"] }],
4796
+ responses: { "200": { description: "Encerrada", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" } } } } } }, "404": errorResponse("Parceria n\xE3o encontrada"), ...COMMON_ERRORS }
4797
+ }
4798
+ },
4799
+ "/parcerias/{id}/lancamentos": {
4800
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
4801
+ get: {
4802
+ tags: ["Parcerias"],
4803
+ summary: "Livro de lan\xE7amentos (com o rateio de cada um)",
4804
+ operationId: "listParceriaLancamentos",
4805
+ security: [{ ApiKeyAuth: ["parcerias:list"] }],
4806
+ parameters: [
4807
+ ...PAGINATION_PARAMS,
4808
+ { name: "competencia", in: "query", schema: { type: "string", pattern: "^\\d{4}-\\d{2}$" }, description: "M\xEAs do caixa, AAAA-MM" },
4809
+ { name: "tipo", in: "query", schema: { type: "string", enum: ["saldo_inicial", "receita", "imposto", "imposto_acerto", "despesa", "retirada", "transferencia", "ajuste", "estorno"] } },
4810
+ { name: "participante_id", in: "query", schema: { type: "string", format: "uuid" }, description: "S\xF3 retiradas deste participante" }
4811
+ ],
4812
+ responses: { "200": paginatedResponse("#/components/schemas/ParceriaLancamento"), "404": errorResponse("Parceria n\xE3o encontrada"), ...COMMON_ERRORS }
4813
+ },
4814
+ post: {
4815
+ tags: ["Parcerias"],
4816
+ summary: "Lan\xE7amento manual (receita, despesa comum, transfer\xEAncia ou ajuste)",
4817
+ operationId: "createParceriaLancamento",
4818
+ description: "Receita, despesa e transfer\xEAncia na divis\xE3o padr\xE3o e na al\xEDquota da empresa: parcerias:create. Ajuste, al\xEDquota \xE0 m\xE3o ou divis\xE3o pr\xF3pria: parcerias:update.",
4819
+ security: [{ ApiKeyAuth: ["parcerias:create"] }, { ApiKeyAuth: ["parcerias:update"] }],
4820
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaLancamentoCreate" } } } },
4821
+ responses: { "201": { description: "Lan\xE7ado", content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaLancamento" } } } }, "422": errorResponse("Regra da parceria recusada (m\xEAs fechado, empresa, percentuais)"), ...COMMON_ERRORS }
4822
+ }
4823
+ },
4824
+ "/parcerias/{id}/lancamentos/{lancamento_id}/estornar": {
4825
+ parameters: [
4826
+ { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
4827
+ { name: "lancamento_id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
4828
+ ],
4829
+ post: {
4830
+ tags: ["Parcerias"],
4831
+ summary: "Estornar lan\xE7amento",
4832
+ operationId: "reverseParceriaLancamento",
4833
+ description: "Lan\xE7a o estorno (e o dos impostos filhos). Estornar retirada cancela a despesa gerada na empresa de origem.",
4834
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4835
+ requestBody: { required: true, content: { "application/json": { schema: { type: "object", required: ["motivo"], properties: { motivo: { type: "string" } } } } } },
4836
+ responses: { "200": { description: "Estornado", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, estornados: { type: "integer" } } } } } }, "422": errorResponse("N\xE3o pode estornar"), ...COMMON_ERRORS }
4837
+ }
4838
+ },
4839
+ "/parcerias/{id}/retiradas": {
4840
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
4841
+ post: {
4842
+ tags: ["Parcerias"],
4843
+ summary: "Registrar retirada de participante",
4844
+ operationId: "createParceriaRetirada",
4845
+ description: "Vira uma despesa paga na empresa de origem (repasse ou distribui\xE7\xE3o de lucros). Com pelo_banco=true vira conta a pagar ao parceiro, paga pelo banco, e entra no livro quando o pagamento confirmar. Participante que exige nota fica com nota pendente at\xE9 a NFS-e dele ser casada (casa sozinha quando o valor bate).",
4846
+ security: [{ ApiKeyAuth: ["parcerias:retirar"] }],
4847
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaRetiradaCreate" } } } },
4848
+ responses: { "201": { description: "Registrada", content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaLancamento" } } } }, "202": { description: "pelo_banco: conta a pagar criada; entra no livro quando o pagamento for confirmado", content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaRetiradaAPagar" } } } }, "422": errorResponse("Saldo insuficiente sem confirmar adiantamento, conta de outra empresa, m\xEAs fechado, data de pagamento no passado"), ...COMMON_ERRORS }
4849
+ }
4850
+ },
4851
+ "/parcerias/{id}/retiradas/{lancamento_id}/nota": {
4852
+ parameters: [
4853
+ { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
4854
+ { name: "lancamento_id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
4855
+ ],
4856
+ post: {
4857
+ tags: ["Parcerias"],
4858
+ summary: "Casar a nota da retirada (ou dispensar)",
4859
+ operationId: "resolveParceriaNota",
4860
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4861
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaNotaResolve" } } } },
4862
+ responses: { "200": { description: "Resolvida", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, nota_status: { type: "string" }, nfse_recebida_id: { type: "string" } } } } } }, "422": errorResponse("Nota de outro CNPJ, j\xE1 usada, ou retirada que n\xE3o est\xE1 pendente"), ...COMMON_ERRORS }
4863
+ }
4864
+ },
4865
+ "/parcerias/{id}/vinculos": {
4866
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
4867
+ get: {
4868
+ tags: ["Parcerias"],
4869
+ summary: "Contratos, faturas e despesas que alimentam a parceria",
4870
+ operationId: "listParceriaVinculos",
4871
+ security: [{ ApiKeyAuth: ["parcerias:list"] }],
4872
+ responses: { "200": { description: "V\xEDnculos", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/ParceriaVinculo" } } } } } } }, ...COMMON_ERRORS }
4873
+ },
4874
+ post: {
4875
+ tags: ["Parcerias"],
4876
+ summary: "Vincular contrato, fatura, despesa ou conta a pagar",
4877
+ operationId: "createParceriaVinculo",
4878
+ description: "O que j\xE1 foi pago desde 'desde' entra na hora; os pagamentos seguintes entram sozinhos. Um item pertence a uma parceria s\xF3.",
4879
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4880
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaVinculoCreate" } } } },
4881
+ responses: { "201": { description: "Vinculado", content: { "application/json": { schema: { type: "object", properties: { vinculo_id: { type: "string" }, lancados: { type: "integer" } } } } } }, "422": errorResponse("Item de empresa fora da parceria, j\xE1 em outra parceria ou com Split ativo"), ...COMMON_ERRORS }
4882
+ }
4883
+ },
4884
+ "/parcerias/{id}/vinculos/{vinculo_id}": {
4885
+ parameters: [
4886
+ { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
4887
+ { name: "vinculo_id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
4888
+ ],
4889
+ delete: {
4890
+ tags: ["Parcerias"],
4891
+ summary: "Desvincular (para de alimentar; o que j\xE1 entrou fica no livro)",
4892
+ operationId: "deleteParceriaVinculo",
4893
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4894
+ responses: { "200": { description: "Removido", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, removido: { type: "boolean" } } } } } }, ...COMMON_ERRORS }
4895
+ },
4896
+ patch: {
4897
+ tags: ["Parcerias"],
4898
+ summary: "Antecipar o in\xEDcio do v\xEDnculo (trazer pagamentos anteriores)",
4899
+ operationId: "updateParceriaVinculo",
4900
+ description: "Muda o 'a partir de' de um v\xEDnculo j\xE1 feito para MAIS CEDO e lan\xE7a na hora os pagamentos que faltaram. Data anterior ao corte exige admin e tem o mesmo significado de incluir_antes_do_corte (o dinheiro n\xE3o est\xE1 no saldo inicial). Data igual ou posterior \xE0 atual \xE9 recusada (422).",
4901
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4902
+ requestBody: { required: true, content: { "application/json": { schema: { type: "object", required: ["desde"], properties: { desde: { type: "string", format: "date", description: "Nova data de in\xEDcio, anterior \xE0 atual" } } } } } },
4903
+ responses: { "200": { description: "Antecipado", content: { "application/json": { schema: { type: "object", properties: { vinculo_id: { type: "string" }, desde: { type: "string", format: "date" }, lancados: { type: "integer", description: "Pagamentos lan\xE7ados agora" } } } } } }, "422": errorResponse("Data n\xE3o \xE9 anterior \xE0 atual, ou papel insuficiente para ir antes do corte"), ...COMMON_ERRORS }
4904
+ }
4905
+ },
4906
+ "/parcerias/{id}/vinculos/previa": {
4907
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
4908
+ get: {
4909
+ tags: ["Parcerias"],
4910
+ summary: "Pr\xE9via de um v\xEDnculo (o que entraria, antes de vincular)",
4911
+ operationId: "previewParceriaVinculo",
4912
+ description: "N\xE3o grava nada. Diz quantos pagamentos do item entrariam no livro e quanto (e quantos s\xE3o anteriores \xE0 data de corte), mais o que est\xE1 EM ABERTO \u2014 parcelas ainda n\xE3o pagas, que entram sozinhas quando forem pagas. Use antes de POST /parcerias/{id}/vinculos para decidir 'desde' e incluir_antes_do_corte.",
4913
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4914
+ parameters: [
4915
+ { name: "tipo", in: "query", required: true, schema: { type: "string", enum: ["contrato", "fatura", "despesa", "despesa_recorrente", "conta_a_pagar", "conta_a_pagar_recorrente", "das_mei"] } },
4916
+ { name: "ref_id", in: "query", required: true, schema: { type: "string", format: "uuid" }, description: "Id do item (das_mei: id da empresa MEI)" },
4917
+ { name: "desde", in: "query", schema: { type: "string", format: "date" }, description: "A partir de quando contar (padr\xE3o: a data de corte)" }
4918
+ ],
4919
+ responses: { "200": { description: "Pr\xE9via", content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaVinculoPrevia" } } } }, "422": errorResponse("Item n\xE3o encontrado"), ...COMMON_ERRORS }
4920
+ }
4921
+ },
4922
+ "/parcerias/{id}/participantes": {
4923
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
4924
+ patch: {
4925
+ tags: ["Parcerias"],
4926
+ summary: "Incluir, alterar ou tirar participantes",
4927
+ operationId: "updateParceriaParticipantes",
4928
+ description: "Edita os participantes de uma parceria j\xE1 criada: inclui (supplier_id), muda divis\xE3o, natureza da retirada e exig\xEAncia de nota (id), tira (excluir) ou reativa (ativo=true). S\xF3 admin. Devolve a parceria com o resumo atualizado.",
4929
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4930
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaParticipantesUpdate" } } } },
4931
+ responses: { "200": { description: "Salvo", content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaDetalhe" } } } }, "422": errorResponse("Ativos n\xE3o somam 100%, participante de outra parceria, ou com parte numa divis\xE3o pr\xF3pria de v\xEDnculo"), ...COMMON_ERRORS }
4932
+ }
4933
+ },
4934
+ "/parcerias/{id}/saldo-inicial": {
4935
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
4936
+ patch: {
4937
+ tags: ["Parcerias"],
4938
+ summary: "Editar contas e saldo inicial",
4939
+ operationId: "updateParceriaSaldoInicial",
4940
+ description: "Corrige onde est\xE1 e de quem \xE9 o saldo inicial depois de criada (por exemplo, ao incluir uma empresa cuja conta ficou de fora). S\xF3 admin.",
4941
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4942
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaSaldoInicialUpdate" } } } },
4943
+ responses: { "200": { description: "Salvo", content: { "application/json": { schema: { type: "object", properties: { mudancas: { type: "array", items: { type: "string" }, description: "O que mudou, em portugu\xEAs (vai tamb\xE9m no motivo do lan\xE7amento de ajuste)" } } } } } }, "422": errorResponse("Somas n\xE3o fecham, conta de empresa fora da parceria, ou m\xEAs da data de corte fechado"), ...COMMON_ERRORS }
4944
+ }
4945
+ },
4946
+ "/parcerias/{id}/empresas": {
4947
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
4948
+ post: {
4949
+ tags: ["Parcerias"],
4950
+ summary: "Incluir empresa (ou mudar o imposto dela)",
4951
+ operationId: "upsertParceriaEmpresa",
4952
+ description: "Inclui uma empresa que fatura para a parceria, ou, se ela j\xE1 est\xE1, troca a regra de imposto \u2014 e os impostos provis\xF3rios/pendentes dela s\xE3o recalculados. Membros da empresa inclu\xEDda passam a LER a parceria na tela; escrever continua exigindo o papel na gestora. Sem papel admin na empresa a incluir: 403.",
4953
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4954
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaEmpresaUpsert" } } } },
4955
+ responses: { "200": { description: "Inclu\xEDda/atualizada", content: { "application/json": { schema: { type: "object", properties: { empresa_id: { type: "string" }, impostos_recalculados: { type: "integer" } } } } } }, ...COMMON_ERRORS }
4956
+ }
4957
+ },
4958
+ "/parcerias/{id}/empresas/{empresa_id}": {
4959
+ parameters: [
4960
+ { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
4961
+ { name: "empresa_id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
4962
+ ],
4963
+ delete: {
4964
+ tags: ["Parcerias"],
4965
+ summary: "Tirar empresa da parceria",
4966
+ operationId: "deleteParceriaEmpresa",
4967
+ description: "S\xF3 se nada dela entrou no livro nem est\xE1 vinculado (o hist\xF3rico depende dela), e nunca a gestora.",
4968
+ security: [{ ApiKeyAuth: ["parcerias:update"] }],
4969
+ responses: { "200": { description: "Removida", content: { "application/json": { schema: { type: "object", properties: { empresa_id: { type: "string" }, removida: { type: "boolean" } } } } } }, "422": errorResponse("Empresa gestora, ou com lan\xE7amento/v\xEDnculo na parceria"), ...COMMON_ERRORS }
4970
+ }
4971
+ },
4972
+ "/parcerias/{id}/prestacao-de-contas": {
4973
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
4974
+ get: {
4975
+ tags: ["Parcerias"],
4976
+ summary: "Presta\xE7\xE3o de contas do m\xEAs",
4977
+ operationId: "getParceriaPrestacao",
4978
+ security: [{ ApiKeyAuth: ["parcerias:list"] }],
4979
+ parameters: [{ name: "competencia", in: "query", schema: { type: "string", pattern: "^\\d{4}-\\d{2}$" }, description: "AAAA-MM (padr\xE3o: m\xEAs atual)" }],
4980
+ responses: { "200": { description: "Presta\xE7\xE3o de contas", content: { "application/json": { schema: { $ref: "#/components/schemas/ParceriaPrestacao" } } } }, ...COMMON_ERRORS }
4981
+ }
4982
+ },
4983
+ // -----------------------------------------------------------------------
4317
4984
  // Formas de pagamento do fornecedor
4318
4985
  // -----------------------------------------------------------------------
4319
4986
  "/suppliers/{id}/payment-methods": {
@@ -4368,8 +5035,8 @@ var OPENAPI_SPEC = {
4368
5035
  parameters: [
4369
5036
  ...PAGINATION_PARAMS,
4370
5037
  { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } },
4371
- { name: "provider", in: "query", schema: { type: "string", enum: ["inter", "c6bank"] } },
4372
- { name: "channel", in: "query", schema: { type: "string", enum: ["pix", "boleto", "checkout", "credit_card"] } },
5038
+ { name: "provider", in: "query", schema: { type: "string", enum: ["inter", "c6bank", "cora", "pagarme", "mercadopago", "pix_offline"] } },
5039
+ { name: "channel", in: "query", schema: { type: "string", enum: ["pix", "boleto", "checkout", "credit_card", "pix_automatico"] } },
4373
5040
  { name: "all", in: "query", description: "true lista TODAS as formas cadastradas; por padr\xE3o s\xF3 as utiliz\xE1veis (manuais ou de provider com integra\xE7\xE3o ativa).", schema: { type: "string", enum: ["true", "false"] } }
4374
5041
  ],
4375
5042
  responses: { "200": paginatedResponse("#/components/schemas/PaymentMethod"), ...COMMON_ERRORS }
@@ -4380,12 +5047,12 @@ var OPENAPI_SPEC = {
4380
5047
  tags: ["M\xE9todos de pagamento"],
4381
5048
  summary: "Listar m\xE9todos de pagamento a fornecedor (AP)",
4382
5049
  operationId: "listPaymentMethodsAp",
4383
- description: "Formas de pagamento usadas em payouts (contas a pagar).",
5050
+ description: "Formas de pagamento usadas em payouts (contas a pagar) e no `payment_method_id` de POST /v1/purchase-invoices/{id}/pay.",
4384
5051
  security: [{ ApiKeyAuth: ["payouts:read"] }, { ApiKeyAuth: ["payouts:create"] }],
4385
5052
  parameters: [
4386
5053
  ...PAGINATION_PARAMS,
4387
5054
  { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } },
4388
- { name: "provider", in: "query", schema: { type: "string", enum: ["inter", "c6bank"] } }
5055
+ { name: "provider", in: "query", schema: { type: "string", enum: ["inter", "c6bank", "cora"] } }
4389
5056
  ],
4390
5057
  responses: { "200": paginatedResponse("#/components/schemas/PaymentMethod"), ...COMMON_ERRORS }
4391
5058
  }
@@ -4494,7 +5161,8 @@ var API_MODULES = [
4494
5161
  { key: "read", label: "Listar e visualizar", description: "Consultar contas a pagar" },
4495
5162
  { key: "create", label: "Criar", description: "Lan\xE7ar contas a pagar" },
4496
5163
  { key: "cancel", label: "Cancelar", description: "Cancelar contas a pagar" },
4497
- { key: "delete", label: "Excluir", description: "Excluir contas a pagar definitivamente" }
5164
+ { key: "delete", label: "Excluir", description: "Excluir contas a pagar definitivamente" },
5165
+ { key: "settle", label: "Registrar pagamento", description: "Dar baixa manual numa parcela (conta, forma, data, parcial, juros/multa/desconto) \u2014 n\xE3o move dinheiro no banco" }
4498
5166
  ]
4499
5167
  },
4500
5168
  {
@@ -4540,6 +5208,17 @@ var API_MODULES = [
4540
5208
  { key: "delete", label: "Excluir regra", description: "Remover regras de split" }
4541
5209
  ]
4542
5210
  },
5211
+ {
5212
+ key: "parcerias",
5213
+ label: "Parcerias",
5214
+ permissions: [
5215
+ { key: "list", label: "Listar e visualizar", description: "Consultar parcerias, saldos, livro de lan\xE7amentos, v\xEDnculos e presta\xE7\xE3o de contas" },
5216
+ { key: "create", label: "Criar e lan\xE7ar", description: "Criar parcerias e lan\xE7ar receita, despesa ou transfer\xEAncia na divis\xE3o padr\xE3o" },
5217
+ { key: "update", label: "Gerir", description: "Vincular itens, ajustar, estornar, al\xEDquota \xE0 m\xE3o, divis\xE3o pr\xF3pria e notas das retiradas" },
5218
+ { key: "retirar", label: "Registrar retirada", description: "Registrar retirada de participante (vira despesa paga na empresa)" },
5219
+ { key: "delete", label: "Encerrar", description: "Encerrar parcerias" }
5220
+ ]
5221
+ },
4543
5222
  {
4544
5223
  key: "inbox",
4545
5224
  label: "Caixa de Entrada",
@@ -5041,7 +5720,7 @@ function buildWhoamiTool(api) {
5041
5720
  // src/branding.ts
5042
5721
  var MCP_SERVER_NAME = "comando-one";
5043
5722
  var MCP_SERVER_TITLE = "Comando1";
5044
- var MCP_SERVER_VERSION = "0.14.0";
5723
+ var MCP_SERVER_VERSION = "0.16.0";
5045
5724
  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.";
5046
5725
  var MCP_SERVER_WEBSITE = "https://comando.one";
5047
5726
  var MCP_SERVER_ICONS = [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@comando.one/mcp-server",
3
- "version": "0.14.0",
3
+ "version": "0.16.0",
4
4
  "description": "Servidor MCP (Model Context Protocol) para a API pública do Comando1 — opere seu ERP por linguagem natural.",
5
5
  "author": "Orbital Tecnologia e Desenvolvimento LTDA <contato@comando.one> (https://orbitaldev.com.br)",
6
6
  "homepage": "https://comando.one",