{"openapi":"3.1.0","info":{"title":"Comando1 API","version":"1.1.0","description":"API REST pública do Comando1 — ERP SaaS para empresas de serviço brasileiras.\n\nAutentique com uma API key no header `x-api-key` ou `Authorization: Bearer <key>`.\n\n**Idempotência:** envie o header `Idempotency-Key` (string única) em requisições POST. Repetições com a mesma chave retornam a resposta original (header `Idempotent-Replayed: true`), evitando cobranças/pagamentos duplicados em caso de retry.\n\n**Rate limit:** 60 requisições/minuto por chave (429 ao exceder).\n\n**Erros:** toda falha devolve JSON com `error` (texto acionável, em português). `424 Failed Dependency` = a requisição estava correta, mas um terceiro falhou — 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ágina HTML dela e o motivo se perderia.\n\n**Não existe ambiente de homologação.** Só há chaves `cmd_live_`, e toda emissão de NFS-e é documento fiscal real. Para ensaiar a integração 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árias empresas. Use `GET /v1/companies` para listá-las e o header `X-Company-Id` para escolher o tenant de cada request (omitido = empresa padrão da chave).\n\nGere sua chave em **Configurações → API Keys** dentro da plataforma.","contact":{"email":"contato@comando.one","url":"https://comando.one"},"license":{"name":"Proprietário"}},"servers":[{"url":"https://api.comando.one/v1","description":"Produção"},{"url":"https://sb.comando.one/functions/v1/public-api/v1","description":"Supabase direto"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Auth","description":"Verificação de conectividade e identidade"},{"name":"Clientes","description":"Gerenciamento de clientes e contatos"},{"name":"Propostas","description":"Propostas comerciais"},{"name":"Contratos","description":"Contratos recorrentes"},{"name":"Faturas","description":"Faturas e cobranças"},{"name":"Financeiro","description":"Razão financeiro — entradas e saídas"},{"name":"NFS-e","description":"Notas Fiscais de Serviço Eletrônicas"},{"name":"Fornecedores","description":"Cadastro de fornecedores"},{"name":"Serviços","description":"Catálogo de serviços"},{"name":"Despesas","description":"Despesas operacionais"},{"name":"Contas a Pagar","description":"Notas fiscais de entrada / contas a pagar"},{"name":"Cobranças","description":"Gateway de pagamentos — Pix, boleto e checkout"},{"name":"Webhooks","description":"Notificações de eventos (cobrança/pagamento) com retry e log"},{"name":"Catálogos","description":"Listagens de referência (naturezas, centros de custo, condições, unidades)"},{"name":"Contas bancárias","description":"Contas bancárias (somente leitura)"},{"name":"Pagamentos a Fornecedor","description":"Payouts — pagar/agendar Pix e boleto a fornecedores"},{"name":"Métodos de pagamento","description":"Formas de recebimento disponíveis"},{"name":"Formas de pagamento do fornecedor","description":"Cadastro de destinos de pagamento por fornecedor"},{"name":"Lembretes","description":"Lembretes e resumos agendados (recorrentes ou avulsos)"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API no formato `cmd_live_...`. Pode também ser enviada como `Authorization: Bearer cmd_live_...`"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Descrição do erro"}}},"PaginatedMeta":{"type":"object","required":["page","per_page","total"],"properties":{"page":{"type":"integer","description":"Página atual"},"per_page":{"type":"integer","description":"Itens por página"},"total":{"type":"integer","description":"Total de itens"}}},"Customer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"document":{"type":["string","null"],"description":"CPF ou CNPJ"},"type":{"type":"string","enum":["fisica","juridica","estrangeira"],"description":"Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum."},"company_name":{"type":["string","null"]},"trade_name":{"type":["string","null"]},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CustomerCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"document":{"type":"string"},"type":{"type":"string","enum":["fisica","juridica","estrangeira"],"default":"fisica","description":"Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum."},"company_name":{"type":"string"},"trade_name":{"type":"string"},"status":{"type":"string","default":"ativo"}}},"CustomerUpdate":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"document":{"type":["string","null"]},"type":{"type":"string","enum":["fisica","juridica","estrangeira"],"description":"Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum."},"company_name":{"type":["string","null"]},"trade_name":{"type":["string","null"]},"status":{"type":"string"}}},"ProposalItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"unit":{"type":["string","null"]},"quantity":{"type":"number"},"unit_price":{"type":"number"},"subtotal":{"type":"number"}}},"Proposal":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"customers":{"type":"object","properties":{"name":{"type":"string"}}},"status":{"type":"string","enum":["rascunho","enviada","aceita","recusada","cancelada","faturada"]},"total_amount":{"type":"number"},"valid_until":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProposalDetail":{"allOf":[{"$ref":"#/components/schemas/Proposal"},{"type":"object","properties":{"proposal_items":{"type":"array","items":{"$ref":"#/components/schemas/ProposalItem"}}}}]},"ContractItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"unit":{"type":["string","null"]},"quantity":{"type":"number"},"unit_price":{"type":"number"},"subtotal":{"type":"number"}}},"ContractSection":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"}}},"Contract":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"customers":{"type":"object","properties":{"name":{"type":"string"}}},"title":{"type":["string","null"]},"status":{"type":"string","enum":["ativo","suspenso","cancelado","finalizado"]},"frequency":{"type":"string","enum":["semanal","quinzenal","mensal","bimestral","trimestral","semestral","anual"]},"start_date":{"type":"string","format":"date"},"end_date":{"type":["string","null"],"format":"date"},"amount":{"type":"number"},"due_days":{"type":"integer"},"next_generation_date":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ContractDetail":{"allOf":[{"$ref":"#/components/schemas/Contract"},{"type":"object","properties":{"contract_items":{"type":"array","items":{"$ref":"#/components/schemas/ContractItem"}},"contract_sections":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ContractSection"}}}}]},"ProposalCreate":{"type":"object","required":["customer_id"],"properties":{"customer_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["rascunho","enviada","aceita","recusada","cancelada"],"default":"rascunho"},"total_amount":{"type":"number"},"valid_until":{"type":"string","format":"date"},"notes":{"type":"string"}}},"ContractCreate":{"type":"object","required":["customer_id"],"properties":{"customer_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"status":{"type":"string","enum":["ativo","suspenso","cancelado","finalizado"],"default":"ativo"},"frequency":{"type":"string","enum":["semanal","quinzenal","mensal","bimestral","trimestral","semestral","anual"],"default":"mensal"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"due_days":{"type":"integer","default":10},"amount":{"type":"number"},"payment_method_id":{"type":"string","format":"uuid"},"next_generation_date":{"type":"string","format":"date","description":"Data da próxima geração de fatura. Omitido, usa 'start_date'."},"notes":{"type":"string"}}},"ContractReadjustment":{"type":"object","description":"Reajuste aplicado a um contrato (specs/reajustes/).","properties":{"id":{"type":"string","format":"uuid"},"contract_id":{"type":"string","format":"uuid"},"applied_at":{"type":"string","format":"date-time"},"applied_by":{"type":["string","null"],"format":"uuid"},"period_start":{"type":["string","null"],"format":"date","description":"Início do período coberto (último reajuste anterior)"},"period_end":{"type":["string","null"],"format":"date"},"previous_amount":{"type":"number"},"new_amount":{"type":"number"},"applied_percent":{"type":"number","description":"Percentual efetivamente aplicado"},"suggested_percent":{"type":["number","null"],"description":"Sugestão do índice preferido no momento da aplicação"},"suggested_index":{"type":["string","null"],"enum":["ipca","igpm","inpc","usd","eur",null]},"notes":{"type":["string","null"]}}},"ContractReadjustmentCreate":{"type":"object","description":"Informe 'new_amount' OU 'percent' — o outro é derivado do valor atual do contrato.","properties":{"new_amount":{"type":"number","description":"Novo valor do contrato (R$)"},"percent":{"type":"number","description":"Percentual de reajuste (ex.: 4.62)"},"suggested_percent":{"type":"number","description":"Sugestão exibida no momento (para o histórico sugerido × aplicado)"},"suggested_index":{"type":"string","enum":["ipca","igpm","inpc","usd","eur"]},"notes":{"type":"string"}}},"ContractReadjustmentQueueItem":{"type":"object","description":"Contrato na fila de reajuste (vencido ou na janela).","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"customers":{"type":"object","properties":{"name":{"type":"string"}}},"title":{"type":["string","null"]},"status":{"type":"string"},"frequency":{"type":"string"},"amount":{"type":"number"},"readjustment_index":{"type":"string","enum":["ipca","igpm","inpc","usd","eur","manual"]},"readjustment_period_months":{"type":"integer"},"last_readjustment_date":{"type":["string","null"],"format":"date"},"next_readjustment_date":{"type":["string","null"],"format":"date"},"next_generation_date":{"type":["string","null"],"format":"date","description":"Quando a próxima fatura será gerada — se antes do reajuste, ela sai no valor antigo"},"overdue":{"type":"boolean"}}},"MarketIndexSuggestion":{"type":"object","description":"Acumulado de um índice oficial no período (fonte: BCB, cache local).","properties":{"index_code":{"type":"string","enum":["ipca","igpm","inpc","usd","eur"]},"accumulated_pct":{"type":["number","null"],"description":"Acumulado em pontos percentuais (4.62 = 4,62%); null = sem cobertura de dados"},"coverage_start":{"type":["string","null"],"format":"date"},"coverage_end":{"type":["string","null"],"format":"date"},"last_ref_date":{"type":["string","null"],"format":"date","description":"Até onde o índice cobre (IPCA sai com ~15 dias de atraso)"}}},"InvoiceItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"service_id":{"type":["string","null"],"format":"uuid","description":"Serviço vinculado (null se item avulso)."},"name":{"type":"string"},"description":{"type":["string","null"]},"unit":{"type":["string","null"]},"quantity":{"type":"number"},"unit_price":{"type":"number"},"subtotal":{"type":"number"},"is_manual":{"type":"boolean","description":"true = item avulso; false = vindo de um serviço cadastrado."}}},"InvoiceCharge":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"due_date":{"type":"string","format":"date"},"amount":{"type":"number"},"payment_status":{"type":"string"}}},"Invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"customers":{"type":"object","properties":{"name":{"type":"string"},"legal_name":{"type":["string","null"]}}},"invoice_number":{"type":["string","null"]},"title":{"type":["string","null"]},"amount":{"type":"number"},"status":{"type":"string","enum":["rascunho","enviada","aceita","cancelada"]},"payment_status":{"type":"string","enum":["pendente","parcial","pago","vencido"]},"due_date":{"type":["string","null"],"format":"date"},"proposal_id":{"type":["string","null"],"format":"uuid"},"contract_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"InvoiceDetail":{"allOf":[{"$ref":"#/components/schemas/Invoice"},{"type":"object","properties":{"invoice_items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"invoice_charges":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceCharge"}}}}]},"FinanceLedgerEntry":{"type":"object","properties":{"origin_id":{"type":"string","format":"uuid"},"origin":{"type":"string","enum":["payment","supplier_payment","expense","financial_movement"]},"direction":{"type":"string","enum":["entrada","saida"]},"entry_date":{"type":"string","format":"date"},"amount":{"type":"number"},"signed_amount":{"type":"number"},"counterparty_name":{"type":["string","null"]},"description":{"type":["string","null"]},"document_numbers":{"type":["string","null"]},"bank_account_name":{"type":["string","null"]},"payment_method_name":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"NfseHistory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invoice_id":{"type":"string","format":"uuid"},"invoice_number":{"type":["string","null"]},"numero_nfse":{"type":["string","null"]},"status":{"type":"string","enum":["rascunho","transmitindo","autorizada","rejeitada","cancelada"]},"protocolo":{"type":["string","null"]},"chave_acesso":{"type":["string","null"]},"danfse_url":{"type":["string","null"]},"artifact_source":{"type":["string","null"]},"cancelada_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"NfseHistoryDetail":{"allOf":[{"$ref":"#/components/schemas/NfseHistory"},{"type":"object","properties":{"cancel_motivo":{"type":["integer","null"]},"cancel_justificativa":{"type":["string","null"]},"cancel_protocolo":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}}}]},"Supplier":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Título / rótulo de exibição do fornecedor"},"legal_name":{"type":["string","null"],"description":"Razão social (PJ) ou nome completo (PF/estrangeira)"},"surname":{"type":["string","null"],"description":"Sobrenome (pessoa física)"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"document":{"type":["string","null"],"description":"CPF ou CNPJ"},"type":{"type":"string","enum":["fisica","juridica","estrangeira"],"description":"Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum."},"company_name":{"type":["string","null"]},"trade_name":{"type":["string","null"]},"state_registration":{"type":["string","null"]},"municipal_registration":{"type":["string","null"]},"payment_terms_label":{"type":["string","null"]},"payment_terms_days":{"type":["integer","null"]},"status":{"type":"string","enum":["ativo","inativo"]},"notes":{"type":["string","null"]},"pagarme_recipient_id":{"type":["string","null"],"description":"ID do recebedor Pagar.me (re_…) para split nativo. Criado pela aplicação."},"pagarme_kyc_status":{"type":["string","null"],"enum":["pending","registration","approved","refused","suspended","blocked",null],"description":"Status de KYC do recebedor Pagar.me."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SupplierCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Título / rótulo de exibição. Se omitido, derivado de legal_name."},"legal_name":{"type":"string","description":"Razão social (PJ) ou nome completo (PF/estrangeira)"},"surname":{"type":"string","description":"Sobrenome (pessoa física)"},"email":{"type":"string"},"phone":{"type":"string"},"document":{"type":"string"},"type":{"type":"string","enum":["fisica","juridica","estrangeira"],"default":"juridica","description":"Natureza JURÍDICA do cadastro, não a categoria de atividade: fisica = pessoa física (CPF); juridica = pessoa jurídica (CNPJ), o que inclui empresas, órgãos públicos, prefeituras e a Receita Federal; estrangeira = sem CNPJ/CPF. Na dúvida, OMITA o campo — o padrão já cobre o caso comum."},"company_name":{"type":"string"},"trade_name":{"type":"string"},"state_registration":{"type":"string"},"municipal_registration":{"type":"string"},"payment_terms_label":{"type":"string"},"payment_terms_days":{"type":"integer"},"status":{"type":"string","enum":["ativo","inativo"],"default":"ativo"},"notes":{"type":"string"}}},"Service":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"price":{"type":"number"},"unit":{"type":"string","description":"Unidade (texto livre, ex: hora, unidade, mensal)"},"item_type":{"type":"string","enum":["venda","compra","ambos"]},"categories":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ServiceCreate":{"type":"object","required":["name","price"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"number"},"unit":{"type":"string","default":"hora"},"item_type":{"type":"string","enum":["venda","compra","ambos"],"default":"venda"},"categories":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean","default":true}}},"Expense":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplier_id":{"type":"string","format":"uuid"},"description":{"type":"string"},"amount":{"type":"number"},"expense_date":{"type":"string","format":"date"},"payment_date":{"type":["string","null"],"format":"date"},"category_id":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["pendente","pago","cancelado"]},"bank_account_id":{"type":["string","null"],"format":"uuid"},"payment_method_id":{"type":["string","null"],"format":"uuid"},"notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ExpenseCreate":{"type":"object","required":["supplier_id","description","amount","expense_date"],"properties":{"supplier_id":{"type":"string","format":"uuid"},"description":{"type":"string"},"amount":{"type":"number"},"expense_date":{"type":"string","format":"date"},"payment_date":{"type":"string","format":"date"},"category_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pendente","pago","cancelado"],"default":"pendente"},"bank_account_id":{"type":"string","format":"uuid"},"payment_method_id":{"type":"string","format":"uuid"},"notes":{"type":"string"},"attachment_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ids de anexos já enviados que devem ser vinculados à despesa criada. É o fluxo 'lance esse imposto e anexe o PDF' numa chamada só."}}},"PurchaseInvoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplier_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["rascunho","recebida","aprovada","cancelada"]},"payment_status":{"type":"string","enum":["pendente","parcial","pago","vencido"]},"invoice_number":{"type":["string","null"]},"amount":{"type":"number"},"issue_date":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"purchase_invoice_charges":{"type":"array","description":"Parcelas a pagar (o vencimento mora aqui, não na fatura).","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"description":{"type":"string"},"amount":{"type":"number"},"due_date":{"type":"string","format":"date"},"payment_status":{"type":"string","enum":["pendente","parcial","pago","vencido"]}}}}}},"PurchaseInvoiceCreate":{"type":"object","required":["supplier_id"],"properties":{"supplier_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["rascunho","recebida","aprovada","cancelada"],"default":"recebida"},"payment_status":{"type":"string","enum":["pendente","parcial","pago","vencido"],"default":"pendente"},"invoice_number":{"type":"string"},"amount":{"type":"number"},"issue_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date","description":"Atalho: cria uma única parcela com este vencimento e o valor de 'amount'. Ignorado se 'charges' for informado."},"charges":{"type":"array","description":"Parcelas a pagar. Cada uma exige 'due_date'.","items":{"type":"object","required":["due_date"],"properties":{"sequence":{"type":"integer"},"description":{"type":"string"},"amount":{"type":"number"},"due_date":{"type":"string","format":"date"},"payment_status":{"type":"string","enum":["pendente","parcial","pago","vencido"],"default":"pendente"},"boleto_barcode":{"type":"string","description":"Linha digitável / código de barras do boleto (só dígitos)."},"pix_key":{"type":"string"},"pix_copia_e_cola":{"type":"string"}}}},"items":{"type":"array","description":"Itens da fatura. Se omitido, o valor de 'amount' vira um item único — a fatura não pode ficar sem item (o formulário do app não salva assim).","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"unit":{"type":"string","default":"un"},"quantity":{"type":"number","default":1},"unit_price":{"type":"number"},"subtotal":{"type":"number","description":"Calculado de quantity × unit_price quando omitido."}}}},"title":{"type":"string","description":"Descrição da fatura; vira o nome do item quando 'items' não é informado."},"description":{"type":"string","description":"Apelido de 'title' na hora de nomear o item único. Precedência: title > description > notes > invoice_number."},"digitable_line":{"type":"string","description":"Atalho: grava o boleto na parcela única criada por 'due_date'."},"boleto_barcode":{"type":"string","description":"Apelido de 'digitable_line' no nível raiz. Vale para as parcelas que não trouxerem o seu próprio."},"barcode":{"type":"string","description":"Apelido de 'digitable_line'. Precedência: o da parcela > boleto_barcode > digitable_line > barcode."},"pix_key":{"type":"string","description":"Atalho: grava a chave Pix na parcela única."},"pix_copia_e_cola":{"type":"string","description":"Pix copia-e-cola no nível raiz. Vale para as parcelas que não trouxerem o seu próprio."},"pix_payload":{"type":"string","description":"Apelido de 'pix_copia_e_cola'. Precedência: o da parcela > pix_copia_e_cola > pix_payload."},"notes":{"type":"string"},"attachment_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ids de anexos já enviados que devem ser vinculados à fatura criada. É o fluxo 'lance esse imposto e anexe o PDF' numa chamada só."}}},"Charge":{"type":"object","description":"Cobrança normalizada (independente do provider).","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","paid","cancelled","expired","failed"]},"status_raw":{"type":"string","description":"Status bruto do provider"},"method":{"type":"string","enum":["pix","boleto","checkout","credit_card"]},"provider":{"type":"string","enum":["inter","c6bank","pix_offline","pagarme","cora"],"description":"Provedor resolvido. 'pix_offline' = Pix estático (BR Code local). 'pagarme' = Pix server-side ou cartão (method=credit_card retorna 'checkout.url' = link da página de pagamento). 'cora' = boleto ou Pix emitidos de forma síncrona (o boleto já volta com 'pdf_url')."},"invoice_id":{"type":["string","null"],"format":"uuid"},"customer_id":{"type":["string","null"],"format":"uuid"},"amount":{"type":["number","null"]},"due_date":{"type":["string","null"],"format":"date"},"pix":{"type":["object","null"],"properties":{"qr_code":{"type":["string","null"]},"qr_url":{"type":["string","null"]},"txid":{"type":["string","null"]}}},"boleto":{"type":["object","null"],"properties":{"digitable_line":{"type":["string","null"]},"pdf_url":{"type":["string","null"]}}},"checkout":{"type":["object","null"],"properties":{"url":{"type":["string","null"]}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ChargeCreate":{"type":"object","required":["method"],"properties":{"method":{"type":"string","enum":["pix","boleto","checkout","credit_card"],"description":"Canal de pagamento"},"provider":{"type":"string","enum":["inter","c6bank","pix_offline","pagarme","cora"],"description":"Opcional. Desambigua quando a empresa tem mais de um provedor no mesmo canal (ex.: Pix Inter x Pix Pagar.me x Pix Cora). Se omitido, usa o provedor ativo do canal."},"invoice_id":{"type":"string","format":"uuid","description":"Fatura existente (opcional)"},"charge_id":{"type":"string","format":"uuid","description":"PARCELA da fatura a cobrar (invoice_charges.id — veja GET /v1/invoices/{id}/charges). Só vale com invoice_id. Quando informado, a cobrança sai com o VALOR e o VENCIMENTO da parcela e fica amarrada a ela, que é o que dá baixa certa quando o dinheiro entra. Omitido, a cobrança é no nível da fatura (valor cheio) — numa fatura parcelada isso normalmente não é o que se quer."},"customer_id":{"type":"string","format":"uuid","description":"Obrigatório se invoice_id omitido"},"amount":{"type":"number","description":"Obrigatório se invoice_id omitido"},"due_date":{"type":"string","format":"date","description":"Obrigatório se invoice_id omitido"},"description":{"type":"string"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"],"description":"Rótulo opcional do webhook"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["charge.paid","charge.cancelled","charge.expired","charge.failed","charge.refunded","payout.completed","payout.failed","payout.scheduled","payout.cancelled","invoice.created","invoice.paid","invoice.cancelled","proposal.created","proposal.sent","proposal.accepted","proposal.rejected","contract.created","contract.cancelled","contract.finished","nfse.issued","nfse.rejected","nfse.cancelled","purchase_invoice.created","purchase_invoice.paid","expense.paid","customer.created","customer.updated","customer.deleted","supplier.created","supplier.updated","supplier.deleted","split.calculated","repasse.released","repasse.paid","repasse.failed","repasse.reversed","supplier_payout_request.created","supplier_payout_request.approved"]}},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WebhookCreate":{"type":"object","required":["url"],"properties":{"name":{"type":"string","description":"Rótulo opcional"},"url":{"type":"string","format":"uri","description":"Deve começar com https://"},"events":{"type":"array","items":{"type":"string","enum":["charge.paid","charge.cancelled","charge.expired","charge.failed","charge.refunded","payout.completed","payout.failed","payout.scheduled","payout.cancelled","invoice.created","invoice.paid","invoice.cancelled","proposal.created","proposal.sent","proposal.accepted","proposal.rejected","contract.created","contract.cancelled","contract.finished","nfse.issued","nfse.rejected","nfse.cancelled","purchase_invoice.created","purchase_invoice.paid","expense.paid","customer.created","customer.updated","customer.deleted","supplier.created","supplier.updated","supplier.deleted","split.calculated","repasse.released","repasse.paid","repasse.failed","repasse.reversed","supplier_payout_request.created","supplier_payout_request.approved"]},"description":"Eventos assinados (default: charge.paid, charge.cancelled, charge.expired)"},"active":{"type":"boolean","default":true}}},"InboxMessage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"from_email":{"type":"string"},"from_name":{"type":"string"},"subject":{"type":"string"},"status":{"type":"string"},"error_reason":{"type":"string"},"attempts":{"type":"number"},"received_at":{"type":"string","format":"date-time"},"processed_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"body_text":{"type":"string"},"spf_verdict":{"type":"string"},"dkim_verdict":{"type":"string"},"dmarc_verdict":{"type":"string"},"spam_verdict":{"type":"string"},"virus_verdict":{"type":"string"},"raw_size_bytes":{"type":"number"},"thread_root_id":{"type":"string","format":"uuid"}}},"InboxDocument":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"message_id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"number"},"kind":{"type":"string"},"direction":{"type":"string"},"amount":{"type":"number"},"due_date":{"type":"string","format":"date"},"issue_date":{"type":"string","format":"date"},"document_number":{"type":"string"},"counterparty_name":{"type":"string"},"counterparty_document":{"type":"string"},"barcode":{"type":"string"},"pix_key":{"type":"string"},"outcome":{"type":"string"},"outcome_reason":{"type":"string"},"match_method":{"type":"string"},"match_confidence":{"type":"number"},"supplier_id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"purchase_invoice_id":{"type":"string","format":"uuid"},"invoice_id":{"type":"string","format":"uuid"},"duplicate_of_document_id":{"type":"string","format":"uuid"},"dda_boleto_id":{"type":"string","format":"uuid"},"card_statement_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"StatementEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"bank_account_id":{"type":"string","format":"uuid"},"entry_date":{"type":"string","format":"date"},"amount":{"type":"number"},"entry_type":{"type":"string"},"operation_type":{"type":"string"},"transaction_type":{"type":"string"},"description":{"type":"string"},"balance":{"type":"number"},"external_id":{"type":"string","format":"uuid"},"is_ignored":{"type":"boolean"},"reconciliation_period_id":{"type":"string","format":"uuid"},"card_statement_id":{"type":"string","format":"uuid"},"end_to_end_id":{"type":"string","format":"uuid"},"counterparty_name":{"type":"string"},"counterparty_document":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ReconciliationMatch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"company_id":{"type":"string","format":"uuid"},"reconciliation_period_id":{"type":"string","format":"uuid"},"bank_statement_entry_id":{"type":"string","format":"uuid"},"ledger_origin":{"type":"string"},"ledger_origin_id":{"type":"string","format":"uuid"},"match_type":{"type":"string"},"created_ledger_origin":{"type":"string"},"created_ledger_origin_id":{"type":"string","format":"uuid"},"matched_at":{"type":"string","format":"date-time"}}},"ReconciliationPeriod":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"bank_account_id":{"type":"string","format":"uuid"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"status":{"type":"string"},"opening_balance":{"type":"number"},"closing_balance":{"type":"number"},"notes":{"type":"string"},"closed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CardStatement":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"bank_account_id":{"type":"string","format":"uuid"},"reference_month":{"type":"string","format":"date"},"closing_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"status":{"type":"string"},"total_expenses":{"type":"number"},"total_entries":{"type":"number"},"paid_amount":{"type":"number"},"paid_at":{"type":"string","format":"date-time"},"paid_bank_account_id":{"type":"string","format":"uuid"},"boleto_barcode":{"type":"string"},"boleto_amount":{"type":"number"},"boleto_due_date":{"type":"string","format":"date"},"purchase_invoice_id":{"type":"string","format":"uuid"},"reconciliation_period_id":{"type":"string","format":"uuid"},"notes":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"DdaBoleto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplier_id":{"type":"string","format":"uuid"},"purchase_invoice_id":{"type":"string","format":"uuid"},"barcode":{"type":"string"},"beneficiary_name":{"type":"string"},"beneficiary_document":{"type":"string"},"payer_name":{"type":"string"},"payer_document":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"amount":{"type":"number"},"due_date":{"type":"string","format":"date"},"overdue":{"type":"boolean"},"match_status":{"type":"string"},"match_method":{"type":"string"},"match_confidence":{"type":"number"},"error_message":{"type":"string"},"triaged_at":{"type":"string","format":"date-time"},"triage_note":{"type":"string"},"card_statement_id":{"type":"string","format":"uuid"},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"RecurringExpense":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplier_id":{"type":"string","format":"uuid"},"description":{"type":"string"},"amount":{"type":"number"},"category_id":{"type":"string","format":"uuid"},"bank_account_id":{"type":"string","format":"uuid"},"payment_method_id":{"type":"string","format":"uuid"},"frequency":{"type":"string"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"next_generation_date":{"type":"string","format":"date"},"status":{"type":"string"},"notes":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"RecurringPurchaseInvoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplier_id":{"type":"string","format":"uuid"},"payment_condition_id":{"type":"string","format":"uuid"},"payment_method_id":{"type":"string","format":"uuid"},"supplier_payment_method_id":{"type":"string","format":"uuid"},"frequency":{"type":"string"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"next_generation_date":{"type":"string","format":"date"},"status":{"type":"string"},"notes":{"type":"string"},"adjust_due_to_business_day":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"InsumoWrite":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"unit":{"type":"string","default":"un"},"unit_price":{"type":"number"},"active":{"type":"boolean","default":true}}},"Insumo":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"unit":{"type":"string"},"unit_price":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Notification":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"entity_type":{"type":"string"},"entity_id":{"type":"string","format":"uuid"},"read_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"BankAccount":{"type":"object","description":"Conta bancária (campos sensíveis como agência, conta, chave Pix e documento do titular são omitidos da API pública).","properties":{"id":{"type":"string","format":"uuid"},"bank_name":{"type":"string"},"bank_code":{"type":["string","null"]},"account_type":{"type":["string","null"]},"is_primary":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Payout":{"type":"object","description":"Pagamento a fornecedor normalizado (independente do banco).","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"provider":{"type":"string","enum":["inter","c6bank"]},"method":{"type":"string","enum":["pix","boleto"]},"amount":{"type":"number"},"scheduled_for":{"type":["string","null"],"format":"date"},"bank_account_id":{"type":"string","format":"uuid"},"purchase_invoice_charge_id":{"type":["string","null"],"format":"uuid"},"supplier_payment_method_id":{"type":["string","null"],"format":"uuid"},"provider_reference":{"type":["string","null"],"description":"codigoSolicitacao (Inter) ou group_id (C6)"},"error_message":{"type":["string","null"]},"executed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PayoutCreate":{"type":"object","required":["bank_account_id","method"],"properties":{"bank_account_id":{"type":"string","format":"uuid","description":"Conta bancária de origem"},"method":{"type":"string","enum":["pix","boleto"]},"provider":{"type":"string","enum":["inter","c6bank"],"description":"Opcional — detectado se houver uma única integração ativa"},"amount":{"type":"number","description":"Obrigatório se não vier de purchase_invoice_charge_id"},"purchase_invoice_charge_id":{"type":"string","format":"uuid","description":"Parcela a quitar (settlement automático)"},"supplier_payment_method_id":{"type":"string","format":"uuid","description":"Forma de pagamento do fornecedor (Pix)"},"pix_key":{"type":"string"},"pix_key_type":{"type":"string","enum":["cpf","cnpj","email","phone","random"]},"pix_copia_e_cola":{"type":"string","description":"QR Pix copia e cola (EMV)"},"boleto_barcode":{"type":"string"},"scheduled_for":{"type":"string","format":"date","description":"Data de agendamento (YYYY-MM-DD); omitir paga à vista"},"description":{"type":"string"}}},"SplitRuleRecipient":{"type":"object","description":"Linha de uma regra de split: um beneficiário e sua base de cálculo.","properties":{"id":{"type":"string","format":"uuid"},"recipient_type":{"type":"string","enum":["supplier","platform","company_master"]},"supplier_id":{"type":["string","null"],"format":"uuid"},"supplier_payment_method_id":{"type":["string","null"],"format":"uuid"},"basis":{"type":"string","enum":["percentual","fixo","combinado"]},"percent":{"type":"number","description":"0–100 (percentual)"},"fixed_cents":{"type":"integer","description":"Valor fixo em centavos"},"is_platform_fee":{"type":"boolean"},"apply_per_installment":{"type":"boolean"},"installments":{"type":["object","null"],"description":"Divisão por parcela (jsonb)"},"sort_order":{"type":"integer"}}},"SplitRule":{"type":"object","description":"Regra de divisão (template) de um recebimento entre beneficiários.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"scope":{"type":"string","enum":["company_default","contract","invoice","charge"]},"contract_id":{"type":["string","null"],"format":"uuid"},"fiscal_mode":{"type":"string","enum":["intermediacao","revenda"]},"fee_payer":{"type":"string","enum":["platform","recipients","proportional"]},"release_trigger":{"type":"string","enum":["on_settlement","on_nota","manual","scheduled"]},"rounding_strategy":{"type":"string","enum":["remainder_to_master","largest_remainder"]},"is_active":{"type":"boolean"},"gateway_split_enabled":{"type":"boolean","description":"Quando true, usa o split nativo da Pagar.me (divisão no ato do pagamento) se a cobrança for Pagar.me e os fornecedores tiverem recebedor aprovado; senão, repasse interno."},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/SplitRuleRecipient"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SplitRuleCreate":{"type":"object","required":["name","recipients"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"scope":{"type":"string","enum":["company_default","contract","invoice","charge"],"default":"company_default"},"contract_id":{"type":"string","format":"uuid","description":"Obrigatório quando scope=contract"},"fiscal_mode":{"type":"string","enum":["intermediacao","revenda"],"default":"intermediacao"},"fee_payer":{"type":"string","enum":["platform","recipients","proportional"],"default":"platform"},"release_trigger":{"type":"string","enum":["on_settlement","on_nota","manual","scheduled"],"default":"on_settlement"},"rounding_strategy":{"type":"string","enum":["remainder_to_master","largest_remainder"],"default":"remainder_to_master"},"is_active":{"type":"boolean","default":true},"gateway_split_enabled":{"type":"boolean","default":true,"description":"Usar o split nativo da Pagar.me quando aplicável (senão repasse interno)."},"recipients":{"type":"array","description":"Beneficiários. Percentual primeiro, depois fixo. Soma de percentuais ≤ 100.","items":{"type":"object","required":["recipient_type","basis"],"properties":{"recipient_type":{"type":"string","enum":["supplier","platform","company_master"]},"supplier_id":{"type":"string","format":"uuid","description":"Obrigatório se recipient_type=supplier"},"supplier_payment_method_id":{"type":"string","format":"uuid"},"basis":{"type":"string","enum":["percentual","fixo","combinado"]},"percent":{"type":"number"},"fixed_cents":{"type":"integer"},"is_platform_fee":{"type":"boolean"},"sort_order":{"type":"integer"},"apply_per_installment":{"type":"boolean","description":"Split por parcela: percent/fixo vêm de 'installments'"},"installments":{"type":"object","description":"Por nº de parcela, ex.: { \"1\": { \"percent\": 50 }, \"default\": { \"percent\": 100 } }"}}}}}},"SplitExecutionItem":{"type":"object","description":"Fatia de uma execução de split, por beneficiário.","properties":{"id":{"type":"string","format":"uuid"},"recipient_type":{"type":"string","enum":["supplier","platform","company_master"]},"supplier_id":{"type":["string","null"],"format":"uuid"},"supplier_name":{"type":["string","null"]},"is_platform_fee":{"type":"boolean"},"gross_share_cents":{"type":"integer"},"fee_share_cents":{"type":"integer"},"net_share_cents":{"type":"integer"},"status":{"type":"string","enum":["pending","awaiting_nota","released","paying","paid","reversed","failed"]},"payment_order_id":{"type":["string","null"],"format":"uuid"},"nota_status":{"type":"string"},"error_message":{"type":["string","null"],"description":"Motivo da falha do repasse (quando status=failed)"},"released_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"reversed_at":{"type":["string","null"],"format":"date-time"}}},"SplitExecution":{"type":"object","description":"Execução de split: instância concreta de uma divisão por cobrança recebida.","properties":{"id":{"type":"string","format":"uuid"},"invoice_id":{"type":["string","null"],"format":"uuid"},"charge_id":{"type":["string","null"],"format":"uuid"},"split_rule_id":{"type":["string","null"],"format":"uuid"},"gateway_provider":{"type":["string","null"]},"gross_cents":{"type":"integer"},"gateway_fee_cents":{"type":"integer"},"net_cents":{"type":"integer"},"fiscal_mode":{"type":"string","enum":["intermediacao","revenda"]},"release_trigger":{"type":"string","enum":["on_settlement","on_nota","manual","scheduled"]},"status":{"type":"string","enum":["pending","calculated","releasing","completed","partial","reversed","failed"]},"settled_at":{"type":["string","null"],"format":"date-time"},"error_message":{"type":["string","null"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/SplitExecutionItem"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SupplierPaymentMethod":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"supplier_id":{"type":"string","format":"uuid"},"label":{"type":"string"},"type":{"type":"string","enum":["pix","transfer","boleto","other"]},"is_default":{"type":"boolean"},"notes":{"type":["string","null"]},"pix_key_type":{"type":["string","null"],"enum":["cpf","cnpj","email","phone","random",null]},"pix_key":{"type":["string","null"]},"bank_code":{"type":["string","null"]},"bank_name":{"type":["string","null"]},"agency":{"type":["string","null"]},"account_number":{"type":["string","null"]},"account_type":{"type":["string","null"],"enum":["corrente","poupanca",null]},"holder_name":{"type":["string","null"]},"holder_document":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SupplierPaymentMethodCreate":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["pix","transfer","boleto","other"],"default":"pix"},"label":{"type":"string"},"is_default":{"type":"boolean"},"notes":{"type":"string"},"pix_key_type":{"type":"string","enum":["cpf","cnpj","email","phone","random"]},"pix_key":{"type":"string","description":"Obrigatório para type=pix"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"agency":{"type":"string"},"account_number":{"type":"string"},"account_type":{"type":"string","enum":["corrente","poupanca"]},"holder_name":{"type":"string"},"holder_document":{"type":"string"}}},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"system_key":{"type":["string","null"],"description":"Ex: inter_pix, c6bank_boleto"},"channel_key":{"type":["string","null"],"enum":["pix","boleto","checkout",null]},"provider_name":{"type":["string","null"],"enum":["inter","c6bank",null]},"active":{"type":"boolean"}}},"InvoiceCreate":{"type":"object","required":["customer_id","due_date"],"properties":{"customer_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"amount":{"type":"number","description":"Ignorado se 'items' for enviado (calculado dos itens)"},"status":{"type":"string","enum":["rascunho","enviada","aceita","ativa"],"default":"rascunho"},"due_date":{"type":"string","format":"date","description":"Obrigatório. A fatura nasce com uma parcela 1/1 neste vencimento — sem parcela ninguém cobra (o dispatch seleciona por parcela). O envio automático nasce desligado; para ligar use PATCH /v1/invoices/{id}/auto-send."},"items":{"type":"array","items":{"type":"object","properties":{"service_id":{"type":"string","format":"uuid","description":"Vincula um serviço cadastrado (GET /v1/services). Se omitido, o item é avulso (is_manual)."},"name":{"type":"string"},"description":{"type":"string"},"unit":{"type":"string","default":"un"},"quantity":{"type":"number","default":1},"unit_price":{"type":"number"},"subtotal":{"type":"number","description":"Opcional — calculado como quantity*unit_price se omitido"}}}}}},"FinancialMovement":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nature_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["entrada","saida"]},"amount":{"type":"number"},"movement_date":{"type":"string","format":"date"},"description":{"type":"string"},"counterparty_name":{"type":["string","null"]},"bank_account_id":{"type":["string","null"],"format":"uuid"},"payment_method_id":{"type":["string","null"],"format":"uuid"},"notes":{"type":["string","null"]},"status":{"type":"string","enum":["realizado","previsto","cancelado"]},"source_type":{"type":"string","enum":["manual","reconciliation","rule"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"FinancialMovementCreate":{"type":"object","required":["nature_id","direction","amount","movement_date","description"],"properties":{"nature_id":{"type":"string","format":"uuid","description":"Natureza financeira (financial_movement_natures)"},"direction":{"type":"string","enum":["entrada","saida"]},"amount":{"type":"number"},"movement_date":{"type":"string","format":"date"},"description":{"type":"string"},"counterparty_name":{"type":"string"},"bank_account_id":{"type":"string","format":"uuid"},"payment_method_id":{"type":"string","format":"uuid"},"notes":{"type":"string"},"status":{"type":"string","enum":["realizado","previsto","cancelado"],"default":"realizado"}}},"NfseEmit":{"type":"object","required":["invoice_id"],"properties":{"invoice_id":{"type":"string","format":"uuid","description":"Fatura a partir da qual emitir a NFS-e"}}},"NfseCancel":{"type":"object","required":["motivo","justificativa"],"properties":{"motivo":{"type":"integer","enum":[1,2,3,4,9],"description":"1=erro na emissão, 2=serviço não prestado, 3=duplicidade de emissão, 4=decisão judicial, 9=outros. Use o código pelo RÓTULO, não pela ordem."},"justificativa":{"type":"string","minLength":15,"maxLength":255}}},"CustomerAddress":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"label":{"type":["string","null"]},"street":{"type":["string","null"]},"number":{"type":["string","null"]},"complement":{"type":["string","null"]},"neighborhood":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"],"description":"UF (2 letras)"},"zip":{"type":["string","null"]},"country":{"type":["string","null"]},"ibge_code":{"type":["string","null"]},"is_default":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CustomerAddressCreate":{"type":"object","description":"Para emitir boleto, street, number, city, state e zip são necessários.","properties":{"label":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"},"ibge_code":{"type":"string"},"is_default":{"type":"boolean"}}},"CustomerContact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"role":{"type":["string","null"]},"department":{"type":["string","null"]},"notes":{"type":["string","null"]},"is_primary":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CustomerContactCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"role":{"type":"string"},"department":{"type":"string"},"notes":{"type":"string"},"is_primary":{"type":"boolean"}}},"FinancialNature":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"allowed_direction":{"type":"string","enum":["credit","debit","both"]},"is_active":{"type":"boolean"},"sort_order":{"type":"integer"}}},"CostCenter":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"active":{"type":"boolean"},"color":{"type":["string","null"]},"icon":{"type":["string","null"]},"dre_group":{"type":["string","null"]},"sort_order":{"type":"integer"}}},"Reminder":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["personal","company"]},"audience":{"type":"array","items":{"type":"string","enum":["admin","operador","visualizador"]},"description":"Papéis que recebem (vazio = todos os membros)."},"kind":{"type":"string","enum":["manual","digest"]},"template_key":{"type":["string","null"],"description":"Para digest: revenue.summary, receivables.overdue, payables.due, cards.upcoming, nfse.monthly, cashflow.position, mrr.snapshot."},"params":{"type":"object","description":"Parâmetros do digest (ex: { period: 'week' } ou { days_ahead: 7 })."},"title":{"type":["string","null"]},"body":{"type":["string","null"]},"entity_type":{"type":["string","null"]},"entity_id":{"type":["string","null"],"format":"uuid"},"channels":{"type":"object","properties":{"in_app":{"type":"boolean"},"email":{"type":"boolean"},"push":{"type":"boolean"}}},"recurrence_type":{"type":"string","enum":["once","daily","weekly","monthly"]},"run_time":{"type":"string","description":"HH:MM[:SS], hora local do fuso."},"weekday":{"type":["integer","null"],"description":"0=domingo … 6=sábado (semanal)."},"day_of_month":{"type":["integer","null"],"description":"1–31 (mensal; meses curtos usam o último dia)."},"timezone":{"type":"string"},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"},"next_run_at":{"type":["string","null"],"format":"date-time"},"last_run_at":{"type":["string","null"],"format":"date-time"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PaymentCondition":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"active":{"type":"boolean"},"installments":{"type":"array","items":{"type":"object"},"description":"[{sequence, label, days, percentage}]"}}},"ServiceUnit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ServiceCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"color":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"webhook_id":{"type":"string","format":"uuid"},"event":{"type":"string"},"status":{"type":"string","enum":["pending","delivering","delivered","failed"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"http_status":{"type":["integer","null"]},"last_error":{"type":["string","null"]},"next_retry_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Company":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"trade_name":{"type":["string","null"]},"document":{"type":["string","null"],"description":"CNPJ/CPF"},"active":{"type":"boolean"},"is_default":{"type":"boolean","description":"Empresa padrão da chave (usada quando X-Company-Id é omitido)"}}}}},"paths":{"/me":{"get":{"tags":["Auth"],"summary":"Verificar conectividade","operationId":"getMe","description":"Retorna os dados da empresa e da chave autenticada. Não exige scope específico — qualquer chave válida funciona.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Empresa e chave autenticada","content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"trade_name":{"type":["string","null"]},"document":{"type":"string"}}},"api_key":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"last_used_at":{"type":["string","null"],"format":"date-time"}}}}},"example":{"company":{"id":"18fc359b-...","name":"Acme Serviços","trade_name":"Acme","document":"12345678000195"},"api_key":{"name":"Integração ERP","scopes":["customers:read","invoices:read"],"last_used_at":"2026-06-04T18:17:47+00:00"}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies":{"get":{"tags":["Auth"],"summary":"Listar empresas acessíveis pela chave","operationId":"listCompanies","description":"Lista as empresas que a chave pode acessar. Keys single-company retornam apenas a sua; keys multi-empresa retornam todas as permitidas. Use o id em **X-Company-Id** para escolher o tenant de cada request.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Empresas acessíveis","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Auth"],"summary":"Obter empresa acessível","operationId":"getCompany","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Empresa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Empresa não encontrada ou não acessível pela chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers":{"get":{"tags":["Clientes"],"summary":"Listar clientes","operationId":"listCustomers","security":[{"ApiKeyAuth":["customers:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Busca por nome, e-mail ou documento"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Filtrar por status"}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Clientes"],"summary":"Criar cliente","operationId":"createCustomer","security":[{"ApiKeyAuth":["customers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCreate"},"example":{"name":"Acme Serviços Ltda","email":"contato@acme.com.br","type":"juridica","document":"12345678000195"}}}},"responses":{"201":{"description":"Cliente criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Clientes"],"summary":"Obter cliente","operationId":"getCustomer","security":[{"ApiKeyAuth":["customers:read"]}],"responses":{"200":{"description":"Cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Clientes"],"summary":"Atualizar cliente","operationId":"updateCustomer","security":[{"ApiKeyAuth":["customers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdate"}}}},"responses":{"200":{"description":"Cliente atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Clientes"],"summary":"Excluir cliente","operationId":"deleteCustomer","security":[{"ApiKeyAuth":["customers:delete"]}],"responses":{"204":{"description":"Cliente excluído (sem corpo)"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados (faturas, contratos, etc.) que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/invoices":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Clientes"],"summary":"Faturas do cliente","operationId":"listCustomerInvoices","security":[{"ApiKeyAuth":["customers:read","invoices:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"}],"responses":{"200":{"description":"Faturas do cliente","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/contracts":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Clientes"],"summary":"Contratos do cliente","operationId":"listCustomerContracts","security":[{"ApiKeyAuth":["customers:read","contracts:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contract"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/proposals":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Clientes"],"summary":"Propostas do cliente","operationId":"listCustomerProposals","security":[{"ApiKeyAuth":["customers:read","proposals:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Proposal"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/addresses":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Clientes"],"summary":"Listar endereços do cliente","operationId":"listCustomerAddresses","security":[{"ApiKeyAuth":["customers:read"]}],"responses":{"200":{"description":"Endereços","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerAddress"}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Clientes"],"summary":"Adicionar endereço","operationId":"createCustomerAddress","security":[{"ApiKeyAuth":["customers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerAddressCreate"}}}},"responses":{"201":{"description":"Criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerAddress"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/addresses/{addressId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"addressId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Clientes"],"summary":"Atualizar endereço","operationId":"updateCustomerAddress","security":[{"ApiKeyAuth":["customers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerAddressCreate"}}}},"responses":{"200":{"description":"Atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerAddress"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Clientes"],"summary":"Excluir endereço","operationId":"deleteCustomerAddress","security":[{"ApiKeyAuth":["customers:delete"]}],"responses":{"204":{"description":"Excluído"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/contacts":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Clientes"],"summary":"Listar contatos do cliente","operationId":"listCustomerContacts","security":[{"ApiKeyAuth":["customers:read"]}],"responses":{"200":{"description":"Contatos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerContact"}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Clientes"],"summary":"Adicionar contato","operationId":"createCustomerContact","security":[{"ApiKeyAuth":["customers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerContactCreate"}}}},"responses":{"201":{"description":"Criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerContact"}}}},"400":{"description":"name obrigatório","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/contacts/{contactId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"contactId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Clientes"],"summary":"Atualizar contato","operationId":"updateCustomerContact","security":[{"ApiKeyAuth":["customers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerContactCreate"}}}},"responses":{"200":{"description":"Atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerContact"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Clientes"],"summary":"Excluir contato","operationId":"deleteCustomerContact","security":[{"ApiKeyAuth":["customers:delete"]}],"responses":{"204":{"description":"Excluído"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/proposals":{"get":{"tags":["Propostas"],"summary":"Listar propostas","operationId":"listProposals","security":[{"ApiKeyAuth":["proposals:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","schema":{"type":"string","enum":["rascunho","enviada","aceita","recusada","cancelada","faturada"]},"description":"Filtrar por status"},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtrar por cliente"}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Proposal"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Propostas"],"summary":"Criar proposta","operationId":"createProposal","security":[{"ApiKeyAuth":["proposals:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalCreate"}}}},"responses":{"201":{"description":"Proposta criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/proposals/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Propostas"],"summary":"Obter proposta","operationId":"getProposal","security":[{"ApiKeyAuth":["proposals:read"]}],"responses":{"200":{"description":"Proposta com itens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalDetail"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Proposta não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Propostas"],"summary":"Atualizar proposta","operationId":"updateProposal","security":[{"ApiKeyAuth":["proposals:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalCreate"}}}},"responses":{"200":{"description":"Proposta atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Proposta não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Propostas"],"summary":"Excluir proposta","operationId":"deleteProposal","security":[{"ApiKeyAuth":["proposals:delete"]}],"responses":{"204":{"description":"Excluída"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Proposta não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/proposals/{id}/send":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Propostas"],"summary":"Enviar proposta","operationId":"sendProposal","description":"Apenas MUDA O STATUS da proposta para 'enviada'. NÃO dispara e-mail — não existe envio de proposta por e-mail no sistema (conferido: email_schedules só tem invoice e charge). Depois de chamar, não afirme ao usuário que a proposta foi enviada ao cliente.","security":[{"ApiKeyAuth":["proposals:send"]}],"responses":{"200":{"description":"Proposta enviada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Proposta não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Proposta cancelada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contracts":{"get":{"tags":["Contratos"],"summary":"Listar contratos","operationId":"listContracts","security":[{"ApiKeyAuth":["contracts:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Busca por título ou notas"},{"name":"status","in":"query","schema":{"type":"string","enum":["ativo","suspenso","cancelado","finalizado"]}},{"name":"frequency","in":"query","schema":{"type":"string","enum":["semanal","quinzenal","mensal","bimestral","trimestral","semestral","anual"]}},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contract"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Contratos"],"summary":"Criar contrato","operationId":"createContract","security":[{"ApiKeyAuth":["contracts:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractCreate"}}}},"responses":{"201":{"description":"Contrato criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contracts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Contratos"],"summary":"Obter contrato","operationId":"getContract","security":[{"ApiKeyAuth":["contracts:read"]}],"responses":{"200":{"description":"Contrato com itens e seções","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractDetail"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Contratos"],"summary":"Atualizar contrato","operationId":"updateContract","security":[{"ApiKeyAuth":["contracts:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractCreate"}}}},"responses":{"200":{"description":"Contrato atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Contratos"],"summary":"Excluir contrato","operationId":"deleteContract","security":[{"ApiKeyAuth":["contracts:delete"]}],"responses":{"204":{"description":"Excluído"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contracts/{id}/pause":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Contratos"],"summary":"Pausar contrato (status → suspenso)","operationId":"pauseContract","security":[{"ApiKeyAuth":["contracts:write"]}],"responses":{"200":{"description":"Contrato pausado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contracts/{id}/resume":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Contratos"],"summary":"Retomar contrato (status → ativo)","operationId":"resumeContract","security":[{"ApiKeyAuth":["contracts:write"]}],"responses":{"200":{"description":"Contrato retomado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Status não permite retomada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contracts/readjustments/due":{"get":{"tags":["Contratos"],"summary":"Fila de reajuste (contratos atrasados + janela)","description":"Contratos ativos, não isentos, com reajuste vencido ou vencendo na janela informada. Campo 'overdue' indica atraso.","operationId":"listDueReadjustments","security":[{"ApiKeyAuth":["contracts:read"]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"minimum":0,"maximum":365},"description":"Janela em dias além dos atrasados"}],"responses":{"200":{"description":"Fila de reajuste","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContractReadjustmentQueueItem"}},"window_days":{"type":"integer"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contracts/{id}/readjustments":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Contratos"],"summary":"Histórico de reajustes do contrato","operationId":"listContractReadjustments","security":[{"ApiKeyAuth":["contracts:read"]}],"responses":{"200":{"description":"Reajustes aplicados (mais recente primeiro)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContractReadjustment"}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Contratos"],"summary":"Aplicar reajuste no contrato","description":"Atualiza o valor do contrato (e escala os itens proporcionalmente), grava o histórico e avança a data do próximo reajuste. Informe 'new_amount' OU 'percent'. Faturas já geradas não são alteradas.","operationId":"applyContractReadjustment","security":[{"ApiKeyAuth":["contracts:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractReadjustmentCreate"}}}},"responses":{"201":{"description":"Reajuste aplicado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractReadjustment"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Contrato não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Contrato com valor zero — informe new_amount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contracts/{id}/readjustments/{readjustmentId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"readjustmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"tags":["Contratos"],"summary":"Desfazer um reajuste aplicado","description":"Devolve o contrato ao valor anterior, restaura os itens ao estado gravado no momento da aplicação e recalcula a data do próximo reajuste. Só o reajuste mais recente ainda vigente pode ser desfeito, e apenas se o valor do contrato não tiver sido alterado depois. A linha permanece no histórico marcada como desfeita; faturas já geradas não são alteradas.","operationId":"revertContractReadjustment","security":[{"ApiKeyAuth":["contracts:write"]}],"responses":{"200":{"description":"Reajuste desfeito","content":{"application/json":{"schema":{"type":"object","properties":{"reverted":{"type":"boolean"},"contract_id":{"type":"string","format":"uuid"},"restored_amount":{"type":"number"},"items_exact":{"type":"boolean","description":"false quando os itens voltaram por escala inversa (aproximada), por ausência do registro anterior"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Reajuste ou contrato não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Não é o reajuste mais recente, já foi desfeito, ou o valor mudou depois","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market-indices":{"get":{"tags":["Contratos"],"summary":"Índices de mercado acumulados no período (BCB)","description":"Acumulado de IPCA/IGP-M/INPC (composto mensal) e variação da PTAX de dólar/euro entre 'from' e 'to'. Fonte: Banco Central (SGS e PTAX), sincronizada diariamente.","operationId":"getMarketIndices","security":[{"ApiKeyAuth":["contracts:read"]}],"parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Início do período (ex.: data do último reajuste)"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Fim do período (padrão: hoje)"}],"responses":{"200":{"description":"Acumulados por índice","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketIndexSuggestion"}}}}}}},"400":{"description":"Parâmetro 'from' obrigatório","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices":{"get":{"tags":["Faturas"],"summary":"Listar faturas","operationId":"listInvoices","security":[{"ApiKeyAuth":["invoices:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Busca por número ou título"},{"name":"status","in":"query","schema":{"type":"string","enum":["rascunho","enviada","aceita","cancelada"]}},{"name":"payment_status","in":"query","schema":{"type":"string","enum":["pendente","parcial","pago","vencido"]}},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"due_date_from","in":"query","schema":{"type":"string","format":"date"},"description":"Vencimento a partir de (YYYY-MM-DD)"},{"name":"overdue","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"true = vencidas de VERDADE (vencimento passado e não pagas). Não confunda com payment_status=vencido: esse campo é agregado e 'parcial' ganha de 'vencido', então uma fatura com parcela paga e parcela vencida NÃO aparece lá. Para cobrança, use este filtro."},{"name":"sort_by","in":"query","description":"Coluna de ordenação. Use com sort_order para responder 'as maiores' ou 'as mais recentes'.","schema":{"type":"string","enum":["amount","due_date","created_at","updated_at","invoice_number"]}},{"name":"sort_order","in":"query","description":"Direção da ordenação. Padrão: desc quando sort_by é informado.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"due_date_to","in":"query","schema":{"type":"string","format":"date"},"description":"Vencimento até (YYYY-MM-DD)"}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Faturas"],"summary":"Criar fatura","operationId":"createInvoice","description":"Cria uma fatura. Se 'items' for enviado, o valor é calculado a partir deles.","security":[{"ApiKeyAuth":["invoices:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"}}}},"responses":{"201":{"description":"Fatura criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cliente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Faturas"],"summary":"Obter fatura","operationId":"getInvoice","security":[{"ApiKeyAuth":["invoices:read"]}],"responses":{"200":{"description":"Fatura com itens e cobranças","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetail"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Faturas"],"summary":"Corrigir fatura","operationId":"patchInvoice","description":"Corrige o cabeçalho de uma fatura já criada. Existe para não ser preciso APAGAR a fatura (e estornar a baixa antes) só para trocar um status.\n\nEscopo estreito de propósito: para cancelar use `PATCH /v1/invoices/{id}/cancel` — o cancelamento tem efeitos que uma troca de status não dispara. O vencimento não muda aqui: quem cobra é a parcela (`invoice_charges`), e mexer só no cabeçalho daria a impressão de ter mudado a cobrança sem mudar nada do que é cobrado.","security":[{"ApiKeyAuth":["invoices:create"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["rascunho","enviada","aceita","ativa"]},"title":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Fatura atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Nenhum campo aceito foi enviado, ou status inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"status \"cancelada\" (use /cancel), ou a fatura já está cancelada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Faturas"],"summary":"Excluir fatura","operationId":"deleteInvoice","description":"Exclusão física da fatura (itens e cobranças vinculadas via cascade). Use cancel para apenas cancelar.","security":[{"ApiKeyAuth":["invoices:delete"]}],"responses":{"204":{"description":"Excluída"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contracts/{id}/generate-invoices":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Contratos"],"summary":"Gerar as faturas devidas do contrato","operationId":"generateContractInvoices","description":"Gera fatura do contrato. Por padrão (mode=extra) cria uma fatura AVULSA fora do ciclo: não avança o agendamento, então chamar duas vezes gera DUAS faturas. Use mode=cycle para antecipar a fatura do ciclo corrente — é esse modo que avança next_generation_date e evita duplicar a competência. mode=skip pula o ciclo sem gerar nada. Contrato cancelado ou suspenso é recusado.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["extra","cycle","skip"],"default":"extra","description":"extra = avulsa (repetível) · cycle = fatura do ciclo, avança o agendamento · skip = só avança"}}}}}},"security":[{"ApiKeyAuth":["invoices:create"]}],"responses":{"200":{"description":"Geração executada","content":{"application/json":{"schema":{"type":"object","properties":{"contract_id":{"type":"string","format":"uuid"},"created":{"type":"integer","description":"Quantas faturas nasceram nesta chamada."}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/auto-send":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Faturas"],"summary":"Programar a cobrança automática","operationId":"setInvoiceAutoSend","description":"Liga ou desliga o envio AUTOMÁTICO da cobrança nas parcelas em aberto da fatura. Sem isso a cobrança nunca sai sozinha: o disparo diário só envia com `auto_send_enabled` ligado na parcela, e a fatura criada por API nasce desligada. `days_before` = quantos dias ANTES do vencimento disparar (0 = no dia). Desligar devolve o canal para `manual`.","security":[{"ApiKeyAuth":["invoices:send"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","default":true,"description":"false desliga e volta o canal para manual"},"channel":{"type":"string","enum":["manual","email","whatsapp","ambos"],"default":"email","description":"\"ambos\" = e-mail E WhatsApp"},"days_before":{"type":"integer","minimum":0,"maximum":90,"default":0,"description":"dias ANTES do vencimento"}}}}}},"responses":{"200":{"description":"Programação aplicada","content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"},"auto_send_enabled":{"type":"boolean"},"send_channel":{"type":"string"},"send_days_before":{"type":"integer"},"parcelas_afetadas":{"type":"integer"}}}}}},"400":{"description":"channel ou days_before inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Fatura sem parcela em aberto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/charges":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Faturas"],"summary":"Listar as parcelas da fatura","operationId":"listInvoiceCharges","description":"As PARCELAS (invoice_charges) da fatura, com quanto já foi pago e quanto falta em cada uma. Não confunda com `/v1/charges`, que é a cobrança do GATEWAY (Pix/boleto emitido no banco): a parcela é o que manda no vencimento e no status de pagamento da fatura. Use esta rota para descobrir o `charge_id` antes de dar baixa.","security":[{"ApiKeyAuth":["invoices:read"]}],"responses":{"200":{"description":"Parcelas da fatura","content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"},"invoice_number":{"type":"string"},"invoice_status":{"type":"string"},"invoice_payment_status":{"type":"string"},"total":{"type":"integer"},"charges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sequence":{"type":"integer"},"description":{"type":"string"},"amount":{"type":"number"},"due_date":{"type":"string","format":"date"},"payment_status":{"type":"string","enum":["pendente","parcial","pago","vencido"]},"paid_amount":{"type":"number","description":"soma já baixada nesta parcela"},"remaining_amount":{"type":"number","description":"saldo a receber"},"auto_send_enabled":{"type":"boolean"},"send_channel":{"type":"string"}}}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/charges/{charge_id}/pay":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"charge_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"id da PARCELA (veja GET /v1/invoices/{id}/charges)"}],"post":{"tags":["Faturas"],"summary":"Dar baixa em uma parcela","operationId":"settleInvoiceCharge","description":"Registra o recebimento de uma parcela: cria o pagamento e o aloca à parcela. A parcela e a fatura passam a `pago` (ou `parcial`) pelo próprio banco. Sem `amount`, quita o saldo restante; sem `payment_date`, usa hoje (America/Sao_Paulo). Baixa PARCIAL é permitida; acima do saldo, não. Campo de corpo que a rota não conhece devolve 400 em vez de ser ignorado.","security":[{"ApiKeyAuth":["invoices:settle"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Valor recebido. Omitido, quita o saldo restante da parcela."},"payment_date":{"type":"string","format":"date","description":"Data do recebimento (YYYY-MM-DD). Padrão: hoje."},"receipt_method_id":{"type":"string","format":"uuid","description":"Forma de RECEBIMENTO (GET /v1/payment-methods). Aceita também o nome `payment_method_id`."},"payment_method_id":{"type":"string","format":"uuid","description":"Apelido de 'receipt_method_id'. Este só tem efeito quando o canônico não vem."},"bank_account_id":{"type":"string","format":"uuid","description":"Conta que recebeu (GET /v1/bank-accounts)."},"notes":{"type":"string","description":"Observação livre do pagamento."}}}}}},"responses":{"201":{"description":"Baixa registrada","content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string"},"invoice_id":{"type":"string"},"invoice_number":{"type":"string"},"invoice_payment_status":{"type":"string"},"amount":{"type":"number"},"payment_date":{"type":"string","format":"date"},"charge":{"type":"object","properties":{"id":{"type":"string"},"sequence":{"type":"integer"},"amount":{"type":"number"},"paid_amount":{"type":"number"},"remaining_amount":{"type":"number"},"payment_status":{"type":"string"}}}}}}}},"400":{"description":"amount, payment_date ou campo de corpo inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura ou parcela não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Fatura cancelada, parcela já quitada ou valor acima do saldo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/charges/{charge_id}/payments":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"charge_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Faturas"],"summary":"Listar as baixas de uma parcela","operationId":"listChargePayments","description":"Os recebimentos já registrados na parcela. `reconciled: true` avisa que aquele pagamento está conciliado com o extrato — o estorno dele será recusado até a conciliação ser desfeita.","security":[{"ApiKeyAuth":["invoices:read"]}],"responses":{"200":{"description":"Baixas da parcela","content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"},"charge_id":{"type":"string"},"charge_amount":{"type":"number"},"charge_payment_status":{"type":"string"},"paid_amount":{"type":"number"},"remaining_amount":{"type":"number"},"total":{"type":"integer"},"payments":{"type":"array","items":{"type":"object","properties":{"payment_id":{"type":"string"},"allocation_id":{"type":"string"},"amount":{"type":"number"},"payment_date":{"type":"string","format":"date"},"payment_total":{"type":"number"},"notes":{"type":"string"},"reconciled":{"type":"boolean","description":"conciliado com o extrato — não pode ser estornado por aqui"}}}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura ou parcela não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/charges/{charge_id}/payments/{payment_id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"charge_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"payment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"tags":["Faturas"],"summary":"Estornar uma baixa","operationId":"reverseChargePayment","description":"Desfaz um recebimento registrado na parcela. A parcela e a fatura voltam a `pendente`/`vencido`/`parcial` pelo próprio banco. O pagamento é apagado quando existia só para esta baixa; cobrindo outras faturas, perde apenas esta alocação e tem o valor reduzido. RECUSA (409) se o pagamento estiver conciliado com o extrato ou se a parcela tiver gerado repasse (split) já liberado ou pago — nos dois casos a resposta diz o que desfazer antes.","security":[{"ApiKeyAuth":["invoices:settle"]}],"responses":{"200":{"description":"Baixa estornada","content":{"application/json":{"schema":{"type":"object","properties":{"reversed_payment_id":{"type":"string"},"reversed_amount":{"type":"number"},"payment_deleted":{"type":"boolean","description":"false = o pagamento cobria outras faturas e foi só reduzido"},"invoice_id":{"type":"string"},"invoice_number":{"type":"string"},"invoice_payment_status":{"type":"string"},"charge":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"paid_amount":{"type":"number"},"remaining_amount":{"type":"number"},"payment_status":{"type":"string"}}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura, parcela ou baixa não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Pagamento conciliado com o extrato, ou repasse (split) liberado/pago","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/send":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Faturas"],"summary":"Enviar segunda via da fatura ao cliente","operationId":"sendInvoiceSecondCopy","description":"Envia a segunda via por e-mail. Sem 'to', usa o e-mail cadastrado do cliente. Os anexos da fatura vão junto por padrão. Registra a tentativa na fila de e-mails antes de enviar, então um envio que falha deixa rastro.","security":[{"ApiKeyAuth":["invoices:send"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"description":"Destinatário(s). Aceita string separada por vírgula ou lista. Omitido, usa o e-mail do cliente.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string","format":"email"}}]},"recipient_emails":{"description":"Apelido de 'to'. Mesmo formato; 'to' tem precedência.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string","format":"email"}}]},"subject":{"type":"string","description":"Assunto. Padrão: 'Segunda via da fatura <numero>'."},"body_html":{"type":"string","description":"Corpo em HTML. Padrão: mensagem curta com valor e vencimento."},"include_attachments":{"type":"boolean","default":true,"description":"Anexa os arquivos da fatura."}}}}}},"responses":{"200":{"description":"Segunda via enviada","content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","format":"uuid"},"schedule_id":{"type":"string","format":"uuid"},"recipients":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"attachments":{"type":"integer"},"sent_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Faturas"],"summary":"Cancelar fatura","operationId":"cancelInvoice","security":[{"ApiKeyAuth":["invoices:cancel"]}],"responses":{"200":{"description":"Fatura cancelada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invoice_number":{"type":["string","null"]},"title":{"type":["string","null"]},"status":{"type":"string","enum":["cancelada"]},"payment_status":{"type":"string"},"amount":{"type":"number"},"updated_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Fatura já está cancelada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/finance/ledger":{"get":{"tags":["Financeiro"],"summary":"Razão financeiro","operationId":"getFinanceLedger","description":"Retorna entradas e saídas consolidadas: recebimentos de clientes, pagamentos a fornecedores e despesas.","security":[{"ApiKeyAuth":["finance:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"},"description":"Data inicial (YYYY-MM-DD)"},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"},"description":"Data final (YYYY-MM-DD)"},{"name":"direction","in":"query","schema":{"type":"string","enum":["all","entrada","saida"],"default":"all"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FinanceLedgerEntry"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/finance/movements":{"post":{"tags":["Financeiro"],"summary":"Lançar movimentação manual","operationId":"createFinancialMovement","security":[{"ApiKeyAuth":["finance:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialMovementCreate"}}}},"responses":{"201":{"description":"Movimentação criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialMovement"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Natureza financeira não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/finance/movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"tags":["Financeiro"],"summary":"Excluir movimentação manual","operationId":"deleteFinancialMovement","security":[{"ApiKeyAuth":["finance:delete"]}],"responses":{"204":{"description":"Excluída"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Movimentação não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Apenas movimentações manuais podem ser excluídas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/finance/natures":{"get":{"tags":["Catálogos"],"summary":"Listar naturezas financeiras","operationId":"listFinancialNatures","description":"IDs usados em POST /v1/finance/movements (nature_id).","security":[{"ApiKeyAuth":["finance:read","finance:write"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"is_active","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"direction","in":"query","schema":{"type":"string","enum":["credit","debit","both"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FinancialNature"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cost-centers":{"get":{"tags":["Catálogos"],"summary":"Listar centros de custo","operationId":"listCostCenters","description":"IDs usados em despesas (category_id).","security":[{"ApiKeyAuth":["expenses:read","expenses:write","finance:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CostCenter"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Catálogos"],"summary":"Criar centro de custo","operationId":"createCostCenter","security":[{"ApiKeyAuth":["finance:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"dre_group":{"type":"string"},"sort_order":{"type":"integer"},"active":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Centro de custo criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostCenter"}}}},"400":{"description":"Nome ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Nome duplicado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cost-centers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Catálogos"],"summary":"Atualizar centro de custo","operationId":"updateCostCenter","security":[{"ApiKeyAuth":["finance:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"dre_group":{"type":"string"},"sort_order":{"type":"integer"},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostCenter"}}}},"400":{"description":"Nada para atualizar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Nome duplicado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Catálogos"],"summary":"Excluir centro de custo","operationId":"deleteCostCenter","security":[{"ApiKeyAuth":["finance:delete"]}],"responses":{"204":{"description":"Excluído"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reminders":{"get":{"tags":["Lembretes"],"summary":"Listar lembretes","operationId":"listReminders","description":"Lembretes e resumos agendados da empresa.","security":[{"ApiKeyAuth":["reminders:list"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"scope","in":"query","schema":{"type":"string","enum":["personal","company"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reminder"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Lembretes"],"summary":"Criar lembrete","operationId":"createReminder","description":"Cria um lembrete. ESCOPO: scope='personal' cria um lembrete só do usuário (aparece em 'Meus lembretes'); scope='company' cria para a empresa (todos os membros veem). No chat, scope='personal' usa o usuário autenticado; via chave cmd_live (sem usuário) informe owner_user_id para pessoal. RELATIVO ('daqui 30 min'): { title, remind_in_minutes } — o servidor calcula o horário. ABSOLUTO: { title, remind_at } (ISO, use 'Z' p/ UTC). Em ambos, kind=manual, recurrence_type=once, start_date e run_time são inferidos.","security":[{"ApiKeyAuth":["reminders:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"scope":{"type":"string","enum":["personal","company"],"description":"personal = só do usuário; company = todos da empresa. Default: personal no chat (com usuário), company via chave de API."},"owner_user_id":{"type":"string","format":"uuid","description":"Dono do lembrete pessoal (membro da empresa). No chat é inferido do usuário; só necessário via chave cmd_live para scope=personal."},"kind":{"type":"string","enum":["manual","digest"],"description":"Default: manual (ou digest se houver template_key)."},"title":{"type":"string","description":"Título do lembrete (obrigatório para kind=manual)."},"body":{"type":"string"},"template_key":{"type":"string","description":"Obrigatório para kind=digest."},"remind_in_minutes":{"type":"integer","description":"Atalho RELATIVO: minutos a partir de agora (servidor calcula). Ex.: 'daqui 30min' → 30. Preferir para lembretes relativos."},"remind_at":{"type":"string","description":"Atalho ABSOLUTO: instante ISO (use 'Z' para UTC). Vira recurrence once + start_date + run_time no fuso."},"params":{"type":"object"},"audience":{"type":"array","items":{"type":"string","enum":["admin","operador","visualizador"]}},"channels":{"type":"object","properties":{"in_app":{"type":"boolean"},"email":{"type":"boolean"},"push":{"type":"boolean"}}},"recurrence_type":{"type":"string","enum":["once","daily","weekly","monthly"],"description":"Default once quando se usa remind_in_minutes/remind_at."},"run_time":{"type":"string","description":"HH:MM (hora local) — para recorrências."},"weekday":{"type":"integer","description":"0–6 (semanal)."},"day_of_month":{"type":"integer","description":"1–31 (mensal)."},"timezone":{"type":"string"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"}}}}}},"responses":{"201":{"description":"Lembrete criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reminder"}}}},"400":{"description":"Campos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reminders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Lembretes"],"summary":"Atualizar / pausar lembrete","operationId":"updateReminder","security":[{"ApiKeyAuth":["reminders:update"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"params":{"type":"object"},"audience":{"type":"array","items":{"type":"string"}},"channels":{"type":"object"},"recurrence_type":{"type":"string","enum":["once","daily","weekly","monthly"]},"run_time":{"type":"string"},"weekday":{"type":"integer"},"day_of_month":{"type":"integer"},"timezone":{"type":"string"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reminder"}}}},"400":{"description":"Nada para atualizar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Lembretes"],"summary":"Excluir lembrete","operationId":"deleteReminder","security":[{"ApiKeyAuth":["reminders:delete"]}],"responses":{"204":{"description":"Excluído"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-conditions":{"get":{"tags":["Catálogos"],"summary":"Listar condições de pagamento","operationId":"listPaymentConditions","security":[{"ApiKeyAuth":["invoices:read","contracts:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentCondition"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/service-units":{"get":{"tags":["Catálogos"],"summary":"Listar unidades de serviço","operationId":"listServiceUnits","security":[{"ApiKeyAuth":["services:read","services:write"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ServiceUnit"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents":{"get":{"tags":["Documentos"],"summary":"Procurar anexos já enviados","operationId":"listDocuments","description":"Busca anexos da empresa por nome do arquivo e/ou entidade a que estão ligados. Ordenado do mais recente para o mais antigo — é o que 'aquele boleto que mandei' quer dizer na prática.","security":[{"ApiKeyAuth":["documents:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Trecho do nome do arquivo."},{"name":"entity_type","in":"query","schema":{"type":"string","enum":["invoice","purchase_invoice","expense","proposal","contract","customer","supplier","payment","supplier_payment","agent_message"]}},{"name":"entity_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Anexos de um registro específico."}],"responses":{"200":{"description":"Anexos encontrados","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"entity_id":{"type":"string","format":"uuid","nullable":true},"file_name":{"type":"string"},"file_path":{"type":"string"},"file_size":{"type":"integer"},"mime_type":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/analyze":{"post":{"tags":["Documentos"],"summary":"Analisar documento anexado","operationId":"analyzeDocument","description":"Lê um anexo da empresa (PDF, imagem ou texto) e extrai os campos financeiros: tipo do documento, valor, vencimento, número, emitente, linha digitável do boleto e chave Pix. Usa o texto do arquivo e, quando ele não basta (PDF escaneado), a leitura visual do modelo.","security":[{"ApiKeyAuth":["documents:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"attachment_id":{"type":"string","format":"uuid","description":"UUID do anexo em entity_attachments."},"file_name":{"type":"string","description":"Alternativa ao id: parte do nome do arquivo."}}}}}},"responses":{"200":{"description":"Campos extraídos do documento","content":{"application/json":{"schema":{"type":"object","properties":{"attachment_id":{"type":"string","format":"uuid"},"file_name":{"type":"string"},"kind":{"type":"string","description":"boleto | arrecadacao | nfe | nfse | fatura | recibo | desconhecido"},"direction":{"type":"string","description":"pagar | receber | indefinido"},"amount":{"type":"number","nullable":true},"due_date":{"type":"string","format":"date","nullable":true},"document_number":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"digitable_line":{"type":"string","nullable":true},"pix_key":{"type":"string","nullable":true},"counterparty_name":{"type":"string","nullable":true},"counterparty_document":{"type":"string","nullable":true},"is_own_company_document":{"type":"boolean","description":"O documento encontrado é o da própria empresa (contribuinte/pagador)."},"missing":{"type":"array","items":{"type":"string"},"description":"Campos essenciais que não foi possível extrair."},"extracted":{"type":"boolean"}}}}}},"404":{"description":"Documento não encontrado"}}}},"/audit/timeline":{"get":{"tags":["Auditoria"],"summary":"Timeline de auditoria de uma entidade","operationId":"getAuditTimeline","description":"Retorna o histórico de alterações (audit_logs) de uma entidade da empresa, mais recente primeiro.","security":[{"ApiKeyAuth":["audit:read"]}],"parameters":[{"name":"entity_type","in":"query","required":true,"schema":{"type":"string"},"description":"Tipo da entidade (ex.: invoice, customer, contract)"},{"name":"entity_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID da entidade"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":12},"description":"Máximo de eventos (1–30)"}],"responses":{"200":{"description":"Timeline da entidade","content":{"application/json":{"schema":{"type":"object","properties":{"entity_type":{"type":"string"},"entity_id":{"type":"string","format":"uuid"},"entries":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"action":{"type":"string"},"description":{"type":"string"},"user_email":{"type":"string"}}}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/service-categories":{"get":{"tags":["Serviços"],"summary":"Listar categorias de serviço","operationId":"listServiceCategories","security":[{"ApiKeyAuth":["services:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Filtro por nome (ilike)"},{"name":"query","in":"query","schema":{"type":"string"},"description":"Apelido de 'search' — o código já aceitava os dois nomes; agora está documentado."}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCategory"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Serviços"],"summary":"Criar categoria(s) de serviço","operationId":"createServiceCategory","security":[{"ApiKeyAuth":["services:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome de uma categoria"},"names":{"type":"array","items":{"type":"string"},"description":"Lista de nomes (cria várias de uma vez)"},"color":{"type":"string","description":"Cor hex (default #6366f1)"}}}}}},"responses":{"201":{"description":"Categoria(s) criada(s)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCategory"}}}},"400":{"description":"Nome ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Categoria já existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/service-categories/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Serviços"],"summary":"Atualizar categoria de serviço","operationId":"updateServiceCategory","security":[{"ApiKeyAuth":["services:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"}}}}}},"responses":{"200":{"description":"Atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCategory"}}}},"400":{"description":"Nada para atualizar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Nome duplicado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Serviços"],"summary":"Excluir categoria de serviço","operationId":"deleteServiceCategory","security":[{"ApiKeyAuth":["services:delete"]}],"responses":{"204":{"description":"Excluída"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/aging-actions":{"get":{"tags":["Relatórios"],"summary":"Aging de inadimplência com ações sugeridas","operationId":"reportAgingActions","security":[{"ApiKeyAuth":["invoices:read","finance:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":40,"default":12}},{"name":"min_overdue_days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":1}},{"name":"include_shared","in":"query","schema":{"type":"boolean","default":true},"description":"Incluir clientes compartilhados"},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"company_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Restringe a UMA empresa: a sua, ou a dona de um cliente compartilhado. Aplicado SOBRE o escopo permitido — nunca amplia acesso."},{"name":"query","in":"query","schema":{"type":"string"},"description":"Apelido de 'search' — o código já aceitava os dois nomes; agora está documentado."}],"responses":{"200":{"description":"Faturas em atraso + ações recomendadas","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"limit":{"type":"integer"},"min_overdue_days":{"type":"integer"},"total_overdue_amount":{"type":"number","description":"Soma do SALDO em aberto (valor da fatura menos o que já foi pago) — o que ainda dá para cobrar."},"total_invoiced_amount":{"type":"number","description":"Soma do valor cheio das mesmas faturas, ignorando pagamentos parciais."},"actions":{"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string","format":"uuid"},"company_id":{"type":"string","format":"uuid","description":"Empresa DONA da fatura. Com clientes compartilhados a lista mistura empresas; sem este campo não dá para saber de quem é cada linha."},"company_name":{"type":"string","nullable":true},"invoice_number":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"customer_id":{"type":"string","format":"uuid"},"customer_name":{"type":"string","nullable":true},"amount":{"type":"number","description":"Valor cheio da fatura."},"paid_amount":{"type":"number","description":"Quanto já foi pago nesta fatura."},"outstanding_amount":{"type":"number","description":"Saldo devedor — é este o valor a cobrar."},"due_date":{"type":"string","format":"date","nullable":true},"payment_status":{"type":"string"},"status":{"type":"string"},"days_overdue":{"type":"integer"},"recommended_action":{"type":"string"}}}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/cashflow-forecast":{"get":{"tags":["Relatórios"],"summary":"Previsão de fluxo de caixa","operationId":"reportCashflowForecast","description":"Projeta o caixa dia a dia pelas parcelas em aberto. `total_inflow`/`total_outflow` e a `timeline` usam o **saldo devedor** de cada parcela (valor menos o que já foi baixado) — é o que de fato entra e sai; `total_inflow_full`/`total_outflow_full` trazem o valor cheio. Parcela de fatura/compra **cancelada ou em rascunho** não entra: o título foi desfeito ou ainda não foi emitido.","security":[{"ApiKeyAuth":["finance:read"]}],"parameters":[{"name":"horizon_days","in":"query","schema":{"type":"integer","minimum":1,"maximum":120,"default":30}},{"name":"opening_balance","in":"query","schema":{"type":"number","default":0}},{"name":"include_receivables","in":"query","schema":{"type":"boolean","default":true}},{"name":"include_payables","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Projeção diária de caixa (timeline). Cada linha de `receivables_preview`/`payables_preview` traz `amount` (cheio), `paid_amount` e `outstanding_amount` (o que falta).","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/nfse":{"get":{"tags":["NFS-e"],"summary":"Listar NFS-e","operationId":"listNfse","security":[{"ApiKeyAuth":["nfse:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","schema":{"type":"string","enum":["rascunho","transmitindo","autorizada","rejeitada","cancelada"]}},{"name":"invoice_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtrar por fatura"}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NfseHistory"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["NFS-e"],"summary":"Emitir NFS-e","operationId":"emitNfse","description":"Emite uma NFS-e a partir de uma fatura. O método (certificado/portal) vem da configuração da empresa. Pode levar alguns segundos.\n\n**Os itens da fatura NÃO precisam de `service_id`** — item avulso emite normalmente; a classificação fiscal (cTribNac, cNBS, alíquotas) vem da configuração fiscal da empresa e do CNAE padrão, não do item.\n\nCódigos: **201** = autorizada ou em transmissão — o `id` devolvido é o mesmo `{id}` de `/v1/nfse/{id}`, `/files`, `/sync` e `/cancel`. **422 com `status: 'rejeitada'`** = o fisco REJEITOU (motivo em `message`) — não existe nota, não afirme ao usuário que foi emitida. **422 sem `status`** = a EMPRESA não está configurada para emitir. **409** = esta fatura já tem nota (o `error` traz o id da existente). **424** = o provedor fiscal falhou; o motivo dele vem em `error`.\n\nRetentativa é 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.","security":[{"ApiKeyAuth":["nfse:emitir"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseEmit"}}}},"responses":{"201":{"description":"Emissão solicitada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Id da NFS-e — 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":{"description":"invoice_id ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A fatura já tem NFS-e autorizada ou em transmissão — o `error` traz o id da existente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Rejeitada pelo fisco (corpo traz `status: \"rejeitada\"` e `message`) OU empresa sem NFS-e configurada (corpo traz só `error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"O provedor de NFS-e falhou — o motivo dele vem em `error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/nfse/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["NFS-e"],"summary":"Cancelar NFS-e","operationId":"cancelNfse","security":[{"ApiKeyAuth":["nfse:cancelar"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseCancel"}}}},"responses":{"200":{"description":"Cancelamento solicitado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"cancel_protocolo":{"type":["string","null"]}}}}}},"400":{"description":"motivo/justificativa inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NFS-e não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"NFS-e não está autorizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"Erro do provedor de NFS-e","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/nfse/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["NFS-e"],"summary":"Obter NFS-e","operationId":"getNfse","security":[{"ApiKeyAuth":["nfse:read"]}],"responses":{"200":{"description":"NFS-e com detalhes de cancelamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseHistoryDetail"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NFS-e não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/nfse/{id}/sync":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["NFS-e"],"summary":"Sincronizar status da NFS-e com o provedor","operationId":"syncNfse","security":[{"ApiKeyAuth":["nfse:read"]}],"responses":{"200":{"description":"Resultado da sincronização","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"invoice_id":{"type":"string"},"processed":{"type":"integer"},"updated":{"type":"integer"},"attached":{"type":"integer"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NFS-e não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"Erro do provedor de NFS-e","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/nfse/{id}/files":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["NFS-e"],"summary":"URLs assinadas do XML e DANFSE","operationId":"getNfseFiles","description":"Retorna URLs temporárias (30 min). `xml_signed_url` = XML autorizado. `danfse_signed_url` = DANFSe em PDF (gerada sob demanda a partir do XML se ainda não existir). `danfse_html_signed_url` = HTML OFICIAL publicado pelo ADN, quando disponível — é outro documento, não uma versão pior do PDF. `danfse_formato` diz o que veio em `danfse_signed_url` (pdf|html).","security":[{"ApiKeyAuth":["nfse:read"]}],"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. É outro documento, não uma versão pior do PDF — nulo aqui não 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"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NFS-e não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suppliers":{"get":{"tags":["Fornecedores"],"summary":"Listar fornecedores","operationId":"listSuppliers","security":[{"ApiKeyAuth":["suppliers:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Busca por nome, e-mail ou documento"},{"name":"status","in":"query","schema":{"type":"string","enum":["ativo","inativo"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["fisica","juridica","estrangeira"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Fornecedores"],"summary":"Criar fornecedor","operationId":"createSupplier","security":[{"ApiKeyAuth":["suppliers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierCreate"}}}},"responses":{"201":{"description":"Fornecedor criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suppliers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Fornecedores"],"summary":"Obter fornecedor","operationId":"getSupplier","security":[{"ApiKeyAuth":["suppliers:read"]}],"responses":{"200":{"description":"Fornecedor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fornecedor não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Fornecedores"],"summary":"Atualizar fornecedor","operationId":"updateSupplier","security":[{"ApiKeyAuth":["suppliers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierCreate"}}}},"responses":{"200":{"description":"Fornecedor atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fornecedor não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Fornecedores"],"summary":"Excluir fornecedor","operationId":"deleteSupplier","security":[{"ApiKeyAuth":["suppliers:delete"]}],"responses":{"204":{"description":"Excluído"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fornecedor não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados (contas a pagar, despesas, etc.) que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/services":{"get":{"tags":["Serviços"],"summary":"Listar serviços","operationId":"listServices","security":[{"ApiKeyAuth":["services:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Busca por nome ou descrição"},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Serviços"],"summary":"Criar serviço","operationId":"createService","security":[{"ApiKeyAuth":["services:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCreate"}}}},"responses":{"201":{"description":"Serviço criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/services/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Serviços"],"summary":"Obter serviço","operationId":"getService","security":[{"ApiKeyAuth":["services:read"]}],"responses":{"200":{"description":"Serviço","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Serviço não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Serviços"],"summary":"Atualizar serviço","operationId":"updateService","security":[{"ApiKeyAuth":["services:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCreate"}}}},"responses":{"200":{"description":"Serviço atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Serviço não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Serviços"],"summary":"Excluir serviço","operationId":"deleteService","security":[{"ApiKeyAuth":["services:delete"]}],"responses":{"204":{"description":"Excluído"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Serviço não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses":{"get":{"tags":["Despesas"],"summary":"Listar despesas","operationId":"listExpenses","security":[{"ApiKeyAuth":["expenses:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","schema":{"type":"string","enum":["pendente","pago","cancelado"]}},{"name":"supplier_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"category_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"expense_date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"expense_date_to","in":"query","schema":{"type":"string","format":"date"}},{"name":"sort_by","in":"query","description":"Coluna de ordenação. Use com sort_order para responder 'as maiores' ou 'as mais recentes'.","schema":{"type":"string","enum":["amount","expense_date","due_date","created_at","updated_at"]}},{"name":"sort_order","in":"query","description":"Direção da ordenação. Padrão: desc quando sort_by é informado.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Expense"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Despesas"],"summary":"Criar despesa","operationId":"createExpense","security":[{"ApiKeyAuth":["expenses:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseCreate"}}}},"responses":{"201":{"description":"Despesa criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fornecedor não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Despesas"],"summary":"Obter despesa","operationId":"getExpense","security":[{"ApiKeyAuth":["expenses:read"]}],"responses":{"200":{"description":"Despesa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Despesa não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Despesas"],"summary":"Atualizar despesa","operationId":"updateExpense","security":[{"ApiKeyAuth":["expenses:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseCreate"}}}},"responses":{"200":{"description":"Despesa atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Despesa não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Despesas"],"summary":"Excluir despesa","operationId":"deleteExpense","security":[{"ApiKeyAuth":["expenses:delete"]}],"responses":{"204":{"description":"Excluída"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Despesa não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/purchase-invoices":{"get":{"tags":["Contas a Pagar"],"summary":"Listar contas a pagar","operationId":"listPurchaseInvoices","security":[{"ApiKeyAuth":["purchase_invoices:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","schema":{"type":"string","enum":["rascunho","recebida","aprovada","cancelada"]}},{"name":"payment_status","in":"query","schema":{"type":"string","enum":["pendente","parcial","pago","vencido"]}},{"name":"supplier_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"invoice_number","in":"query","schema":{"type":"string"}},{"name":"due_date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"due_date_to","in":"query","schema":{"type":"string","format":"date"}},{"name":"overdue","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"true = contas a pagar com parcela vencida e não paga. O vencimento mora nas parcelas, então o status agregado da fatura não responde isso."},{"name":"sort_by","in":"query","description":"Coluna de ordenação. Use com sort_order para responder 'as maiores' ou 'as mais recentes'.","schema":{"type":"string","enum":["amount","issue_date","created_at","updated_at","invoice_number"]}},{"name":"sort_order","in":"query","description":"Direção da ordenação. Padrão: desc quando sort_by é informado.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseInvoice"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Contas a Pagar"],"summary":"Criar conta a pagar","operationId":"createPurchaseInvoice","security":[{"ApiKeyAuth":["purchase_invoices:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseInvoiceCreate"}}}},"responses":{"201":{"description":"Conta a pagar criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseInvoice"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fornecedor não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/purchase-invoices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Contas a Pagar"],"summary":"Obter conta a pagar (com itens e parcelas)","operationId":"getPurchaseInvoice","security":[{"ApiKeyAuth":["purchase_invoices:read"]}],"responses":{"200":{"description":"Conta a pagar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseInvoice"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conta a pagar não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Contas a Pagar"],"summary":"Excluir conta a pagar","operationId":"deletePurchaseInvoice","description":"Exclusão definitiva. Recusa (409) contas com pagamento registrado ou parcela paga — nesses casos use o cancelamento, que preserva o histórico.","security":[{"ApiKeyAuth":["purchase_invoices:delete"]}],"responses":{"204":{"description":"Excluída"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conta a pagar não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há pagamento registrado ou registros vinculados que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/purchase-invoices/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Contas a Pagar"],"summary":"Cancelar conta a pagar","operationId":"cancelPurchaseInvoice","security":[{"ApiKeyAuth":["purchase_invoices:cancel"]}],"responses":{"200":{"description":"Cancelada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseInvoice"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conta a pagar não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Já cancelada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/charges":{"get":{"tags":["Cobranças"],"summary":"Listar cobranças","operationId":"listCharges","security":[{"ApiKeyAuth":["charges:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","paid","cancelled","expired","failed"]}},{"name":"method","in":"query","schema":{"type":"string","enum":["pix","boleto","checkout","credit_card"]}},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"invoice_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"sort_by","in":"query","description":"Coluna de ordenação. Use com sort_order para responder 'as maiores' ou 'as mais recentes'.","schema":{"type":"string","enum":["amount","due_date","created_at","paid_at"]}},{"name":"sort_order","in":"query","description":"Direção da ordenação. Padrão: desc quando sort_by é informado.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Charge"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cobranças"],"summary":"Criar cobrança (Pix, boleto, checkout ou cartão)","operationId":"createCharge","description":"Gera uma cobrança no provider ativo da empresa (Inter, C6 Bank, Pix Offline, Cora ou Pagar.me). Forneça invoice_id ou customer_id+amount+due_date. Com Pagar.me, method=pix retorna o copia-e-cola e method=credit_card retorna 'checkout.url' (link da página de pagamento própria).\n\nNuma fatura PARCELADA, informe `charge_id`: sem ele a cobrança sai no valor cheio da fatura e não fica amarrada a nenhuma parcela — então a baixa não fecha a parcela certa. Use GET /v1/invoices/{id}/charges para descobrir o charge_id.","security":[{"ApiKeyAuth":["charges:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargeCreate"}}}},"responses":{"201":{"description":"Cobrança criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Fatura já paga","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Integração bancária não configurada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/charges/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Cobranças"],"summary":"Obter cobrança","operationId":"getCharge","security":[{"ApiKeyAuth":["charges:read"]}],"responses":{"200":{"description":"Cobrança","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cobrança não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Cobranças"],"summary":"Cancelar cobrança","operationId":"cancelCharge","security":[{"ApiKeyAuth":["charges:cancel"]}],"responses":{"200":{"description":"Cancelamento solicitado"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cobrança não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cobrança não pode ser cancelada no estado atual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/charges/{id}/refund":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Cobranças"],"summary":"Estornar cobrança (devolução Pix)","operationId":"refundCharge","description":"Estorna (devolve) uma cobrança Pix paga. Disponível apenas para Pix — boleto e checkout retornam 422. Requer que o endToEndId do pagamento tenha sido capturado.","security":[{"ApiKeyAuth":["charges:refund"]}],"responses":{"200":{"description":"Devolução solicitada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"provider":{"type":"string"},"amount":{"type":"number"},"message":{"type":"string"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cobrança não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cobrança não está paga ou já estornada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Método não suportado (apenas Pix) ou endToEndId indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/charges/{id}/confirm":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Cobranças"],"summary":"Confirmar pagamento (Pix estático/offline)","operationId":"confirmCharge","description":"Marca manualmente uma cobrança Pix estático (provider 'pix_offline') como paga e dispara o webhook charge.paid. Para Inter/C6 a baixa vem do banco (não use este endpoint).","security":[{"ApiKeyAuth":["charges:create"]}],"responses":{"200":{"description":"Cobrança confirmada (paga)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cobrança não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cobrança já paga ou em estado terminal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Confirmação manual só vale para Pix estático/offline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"Listar webhooks da empresa","operationId":"listWebhooks","description":"Lista todos os webhooks da empresa. Webhooks são por empresa (não por API key) e você pode ter vários, cada um com seus eventos.","security":[{"ApiKeyAuth":["webhooks:manage"]}],"responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Webhooks"],"summary":"Criar webhook","operationId":"createWebhook","description":"Cria um webhook.\n\nO `secret` vem no corpo do 201 e **só nessa vez** — guarde-o. É com ele que você confere a assinatura de cada entrega.\n\nHeaders de toda entrega:\n- `x-signature` — HMAC-SHA256 do **corpo cru** (os bytes recebidos, antes de qualquer parse/reserialização), em hexadecimal minúsculo. Compare em tempo constante e rejeite o que não bater: é o que distingue uma entrega nossa de qualquer POST na sua URL.\n- `x-event` — o evento (ex.: `invoice.paid`).\n- `x-delivery-id` — id da entrega; serve para você deduplicar retentativas (há até 3 tentativas, com backoff de 30s e 2min).","security":[{"ApiKeyAuth":["webhooks:manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"responses":{"201":{"description":"Webhook criado (inclui secret único)","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string","description":"Segredo HMAC-SHA256. Devolvido SÓ nesta resposta; assina o header x-signature de cada entrega."},"secret_note":{"type":"string"}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Webhooks"],"summary":"Obter webhook","operationId":"getWebhookById","security":[{"ApiKeyAuth":["webhooks:manage"]}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Webhooks"],"summary":"Atualizar webhook","operationId":"updateWebhook","security":[{"ApiKeyAuth":["webhooks:manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"responses":{"200":{"description":"Atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Excluir webhook","operationId":"deleteWebhook","security":[{"ApiKeyAuth":["webhooks:manage"]}],"responses":{"204":{"description":"Excluído"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/events":{"get":{"tags":["Webhooks"],"summary":"Catálogo de eventos disponíveis","operationId":"listWebhookEvents","description":"Lista todos os eventos que um webhook pode assinar (key, label, group).","security":[{"ApiKeyAuth":["webhooks:manage"]}],"responses":{"200":{"description":"Catálogo","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"group":{"type":"string"}}}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Webhooks"],"summary":"Enviar evento de teste","operationId":"testWebhook","description":"Enfileira um evento `webhook.test` direcionado apenas a este webhook (para validar a URL e a verificação de assinatura).","security":[{"ApiKeyAuth":["webhooks:manage"]}],"responses":{"202":{"description":"Teste enfileirado","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"delivery":{"type":"object"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/payments":{"get":{"tags":["Webhooks"],"summary":"Obter configuração de webhook","operationId":"getWebhook","security":[{"ApiKeyAuth":["webhooks:manage"]}],"responses":{"200":{"description":"Configuração atual","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"oneOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"null"}]}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Webhooks"],"summary":"Registrar/atualizar webhook","operationId":"upsertWebhook","description":"Cria ou atualiza a URL de callback. O `secret` é retornado apenas na criação — guarde-o. Cada entrega vai assinada no header `x-signature` = HMAC-SHA256 do corpo cru, em hexadecimal minúsculo, junto de `x-event` e `x-delivery-id`.","security":[{"ApiKeyAuth":["webhooks:manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"responses":{"200":{"description":"Webhook atualizado","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"201":{"description":"Webhook criado (inclui secret único)","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string","description":"Segredo HMAC-SHA256. Devolvido SÓ nesta resposta; assina o header x-signature de cada entrega."},"secret_note":{"type":"string"}}}}}},"400":{"description":"URL inválida ou eventos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Remover a configuração de webhook de pagamentos","operationId":"deletePaymentsWebhookConfig","security":[{"ApiKeyAuth":["webhooks:manage"]}],"responses":{"200":{"description":"Removido"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nenhum webhook configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/deliveries":{"get":{"tags":["Webhooks"],"summary":"Listar entregas de webhook (log)","operationId":"listWebhookDeliveries","description":"Histórico de entregas com status, tentativas e erro. Entregas são reprocessadas automaticamente com backoff.","security":[{"ApiKeyAuth":["webhooks:manage"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","delivering","delivered","failed"]}},{"name":"event","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/deliveries/{id}/redeliver":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Webhooks"],"summary":"Reenviar entrega","operationId":"redeliverWebhook","security":[{"ApiKeyAuth":["webhooks:manage"]}],"responses":{"200":{"description":"Re-enfileirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Entrega não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbox/messages/{id}/status":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Caixa de Entrada"],"summary":"Reprocessar ou arquivar mensagem","operationId":"updateInboxMessageStatus","description":"`recebido` devolve a mensagem ao processamento (limpando o erro anterior); `ignorado` a arquiva. Os demais estados são escritos pelo processamento, não pelo cliente.","security":[{"ApiKeyAuth":["inbox:update"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["recebido","ignorado"]}}}}}},"responses":{"200":{"description":"Mensagem atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxMessage"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Mensagem não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reconciliation/entries/{id}/resolve":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Conciliação"],"summary":"Conciliar um lançamento do extrato","operationId":"resolveStatementEntry","description":"Concilia pela mesma rotina que a tela usa. As recusas vêm de lá e são específicas: período fechado, lançamento ignorado, lançamento já conciliado, e a direção do dinheiro por ação (recebimento só resolve entrada; despesa e pagamento a fornecedor, só saída). Omitindo `period_id`, usa o período do lançamento ou o período ABERTO da conta. Criar REGRA de automação junto não é exposto: é outra decisão e fica no aplicativo.","security":[{"ApiKeyAuth":["reconciliation:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["match_existing","create_payment_from_customer_charge","create_supplier_payment_from_purchase_charge","create_expense","create_financial_movement"]},"period_id":{"type":"string","format":"uuid","description":"Opcional: o período. Omitido, resolve sozinho."},"target_kind":{"type":"string","enum":["existing_payment","existing_supplier_payment","existing_expense","existing_split_payout"],"description":"Só em `match_existing`. O destino precisa existir nesta empresa."},"target_id":{"type":"string","format":"uuid","description":"Só em `match_existing`."},"payload":{"type":"object","description":"Campos da ação (ex.: `supplier_id` e `category_id` em `create_expense`; `charge_id` nas que partem de uma parcela).","additionalProperties":true}}}}}},"responses":{"201":{"description":"Conciliado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconciliationMatch"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Lançamento, período ou destino não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Não foi possível conciliar (já conciliado, período fechado, direção incompatível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reconciliation/matches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"tags":["Conciliação"],"summary":"Desfazer uma conciliação","operationId":"deleteReconciliationMatch","description":"Desconcilia o lançamento, pela mesma rotina que o botão da tela usa. CONCILIAR não é exposto na API: depende de ação/alvo/payload e merece desenho próprio.","security":[{"ApiKeyAuth":["reconciliation:write"]}],"responses":{"200":{"description":"Desconciliado","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"match_id":{"type":"string","format":"uuid"},"desconciliado":{"type":"boolean"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conciliação não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dda-boletos/{id}/triage":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["DDA"],"summary":"Arquivar ou reabrir boleto do DDA","operationId":"triageDdaBoleto","description":"`ignore` arquiva; `reopen` devolve à fila. As ações que criam ou vinculam documento (conta a pagar, fatura de cartão) e o bloqueio de beneficiário ficam no aplicativo — registram quem fez, e uma chave de API não tem usuário.","security":[{"ApiKeyAuth":["dda:triage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["ignore","reopen"]},"note":{"type":"string","description":"Observação da triagem (só em `ignore`)."}}}}}},"responses":{"200":{"description":"Boleto triado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DdaBoleto"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Boleto não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-expenses/{id}/status":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Recorrentes"],"summary":"Pausar ou retomar despesa recorrente","operationId":"updateRecurringExpenseStatus","description":"Só `ativo` ↔ `pausado`. Regra `finalizado` é terminal: não volta a gerar documentos, e reativar seria ressuscitar um ciclo encerrado — crie uma regra nova.","security":[{"ApiKeyAuth":["recurring:update"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ativo","pausado"]}}}}}},"responses":{"200":{"description":"Regra atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringExpense"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Regra não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Regra finalizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-purchase-invoices/{id}/status":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Recorrentes"],"summary":"Pausar ou retomar conta a pagar recorrente","operationId":"updateRecurringPurchaseInvoiceStatus","description":"Só `ativo` ↔ `pausado`; `finalizado` é terminal.","security":[{"ApiKeyAuth":["recurring:update"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ativo","pausado"]}}}}}},"responses":{"200":{"description":"Regra atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchaseInvoice"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Regra não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Regra finalizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notifications/{id}/read":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Notificações"],"summary":"Marcar notificação como lida","operationId":"updateNotificationRead","security":[{"ApiKeyAuth":["notifications:update"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"read":{"type":"boolean","default":true,"description":"`false` marca como NÃO lida."}}}}}},"responses":{"200":{"description":"Notificação atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Notification"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Notificação não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbox/messages":{"get":{"tags":["Caixa de Entrada"],"summary":"Listar mensagens da caixa de entrada","operationId":"listInboxMessages","security":[{"ApiKeyAuth":["inbox:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","description":"Estado do processamento da mensagem.","schema":{"type":"string"}},{"name":"from_email","in":"query","description":"Remetente (busca parcial).","schema":{"type":"string"}},{"name":"subject","in":"query","description":"Assunto (busca parcial).","schema":{"type":"string"}},{"name":"received_from","in":"query","description":"Recebidas a partir desta data.","schema":{"type":"string","format":"date"}},{"name":"received_to","in":"query","description":"Recebidas até esta data.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InboxMessage"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbox/messages/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Caixa de Entrada"],"summary":"Obter mensagem da caixa de entrada","operationId":"getInboxMessage","security":[{"ApiKeyAuth":["inbox:read"]}],"responses":{"200":{"description":"Mensagem da caixa de entrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxMessage"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Mensagem da caixa de entrada não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbox/documents":{"get":{"tags":["Caixa de Entrada"],"summary":"Listar documentos da caixa de entrada","operationId":"listInboxDocuments","security":[{"ApiKeyAuth":["inbox:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"kind","in":"query","description":"Tipo do documento extraído (boleto, nfe, guia…).","schema":{"type":"string"}},{"name":"outcome","in":"query","description":"Desfecho do processamento.","schema":{"type":"string"}},{"name":"message_id","in":"query","description":"Mensagem de origem.","schema":{"type":"string","format":"uuid"}},{"name":"supplier_id","in":"query","description":"Fornecedor casado.","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice_id","in":"query","description":"Conta a pagar lançada a partir dele.","schema":{"type":"string","format":"uuid"}},{"name":"due_from","in":"query","description":"Vencimento a partir de.","schema":{"type":"string","format":"date"}},{"name":"due_to","in":"query","description":"Vencimento até.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InboxDocument"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inbox/documents/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Caixa de Entrada"],"summary":"Obter documento da caixa de entrada","operationId":"getInboxDocument","security":[{"ApiKeyAuth":["inbox:read"]}],"responses":{"200":{"description":"Documento da caixa de entrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxDocument"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Documento da caixa de entrada não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reconciliation/entries":{"get":{"tags":["Conciliação"],"summary":"Listar lançamentos do extrato","operationId":"listStatementEntries","security":[{"ApiKeyAuth":["reconciliation:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"bank_account_id","in":"query","description":"Conta bancária.","schema":{"type":"string","format":"uuid"}},{"name":"entry_type","in":"query","description":"Entrada ou saída.","schema":{"type":"string"}},{"name":"reconciliation_period_id","in":"query","description":"Período de conciliação.","schema":{"type":"string","format":"uuid"}},{"name":"is_ignored","in":"query","description":"Somente ignorados (true) ou não ignorados (false).","schema":{"type":"string","enum":["true","false"]}},{"name":"description","in":"query","description":"Descrição (busca parcial).","schema":{"type":"string"}},{"name":"date_from","in":"query","description":"Data do lançamento a partir de.","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","description":"Data do lançamento até.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StatementEntry"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reconciliation/entries/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Conciliação"],"summary":"Obter lançamento de extrato","operationId":"getStatementEntry","security":[{"ApiKeyAuth":["reconciliation:read"]}],"responses":{"200":{"description":"Lançamento de extrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementEntry"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Lançamento de extrato não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reconciliation/periods":{"get":{"tags":["Conciliação"],"summary":"Listar períodos de conciliação","operationId":"listReconciliationPeriods","security":[{"ApiKeyAuth":["reconciliation:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"bank_account_id","in":"query","description":"Conta bancária.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Estado do período (open, closed…).","schema":{"type":"string"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReconciliationPeriod"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reconciliation/periods/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Conciliação"],"summary":"Obter período de conciliação","operationId":"getReconciliationPeriod","security":[{"ApiKeyAuth":["reconciliation:read"]}],"responses":{"200":{"description":"Período de conciliação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconciliationPeriod"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Período de conciliação não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/card-statements":{"get":{"tags":["Cartão de Crédito"],"summary":"Listar faturas de cartão","operationId":"listCardStatements","security":[{"ApiKeyAuth":["cards:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"bank_account_id","in":"query","description":"Cartão (conta bancária do tipo cartão).","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"aberta, fechada ou paga.","schema":{"type":"string"}},{"name":"reference_month","in":"query","description":"Mês de competência (AAAA-MM-DD do 1º dia).","schema":{"type":"string"}},{"name":"due_from","in":"query","description":"Vencimento a partir de.","schema":{"type":"string","format":"date"}},{"name":"due_to","in":"query","description":"Vencimento até.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CardStatement"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/card-statements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Cartão de Crédito"],"summary":"Obter fatura de cartão","operationId":"getCardStatement","security":[{"ApiKeyAuth":["cards:read"]}],"responses":{"200":{"description":"Fatura de cartão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardStatement"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatura de cartão não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dda-boletos":{"get":{"tags":["DDA"],"summary":"Listar boletos do DDA","operationId":"listDdaBoletos","security":[{"ApiKeyAuth":["dda:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"match_status","in":"query","description":"Situação do casamento com uma conta a pagar.","schema":{"type":"string"}},{"name":"supplier_id","in":"query","description":"Fornecedor casado.","schema":{"type":"string","format":"uuid"}},{"name":"overdue","in":"query","description":"Somente vencidos (true).","schema":{"type":"string","enum":["true","false"]}},{"name":"beneficiary_name","in":"query","description":"Beneficiário (busca parcial).","schema":{"type":"string"}},{"name":"due_from","in":"query","description":"Vencimento a partir de.","schema":{"type":"string","format":"date"}},{"name":"due_to","in":"query","description":"Vencimento até.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DdaBoleto"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dda-boletos/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["DDA"],"summary":"Obter boleto de dda","operationId":"getDdaBoleto","security":[{"ApiKeyAuth":["dda:read"]}],"responses":{"200":{"description":"Boleto de DDA","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DdaBoleto"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Boleto de DDA não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-expenses":{"get":{"tags":["Recorrentes"],"summary":"Listar despesas recorrentes","operationId":"listRecurringExpenses","security":[{"ApiKeyAuth":["recurring:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","description":"Estado da regra (ativa, pausada…).","schema":{"type":"string"}},{"name":"supplier_id","in":"query","description":"Fornecedor.","schema":{"type":"string","format":"uuid"}},{"name":"frequency","in":"query","description":"Periodicidade.","schema":{"type":"string"}},{"name":"next_from","in":"query","description":"Próxima geração a partir de.","schema":{"type":"string","format":"date"}},{"name":"next_to","in":"query","description":"Próxima geração até.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecurringExpense"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-expenses/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Recorrentes"],"summary":"Obter despesa recorrente","operationId":"getRecurringExpense","security":[{"ApiKeyAuth":["recurring:read"]}],"responses":{"200":{"description":"Despesa recorrente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringExpense"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Despesa recorrente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-purchase-invoices":{"get":{"tags":["Recorrentes"],"summary":"Listar contas a pagar recorrentes","operationId":"listRecurringPurchaseInvoices","security":[{"ApiKeyAuth":["recurring:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","description":"Estado da regra.","schema":{"type":"string"}},{"name":"supplier_id","in":"query","description":"Fornecedor.","schema":{"type":"string","format":"uuid"}},{"name":"frequency","in":"query","description":"Periodicidade.","schema":{"type":"string"}},{"name":"next_from","in":"query","description":"Próxima geração a partir de.","schema":{"type":"string","format":"date"}},{"name":"next_to","in":"query","description":"Próxima geração até.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecurringPurchaseInvoice"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-purchase-invoices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Recorrentes"],"summary":"Obter conta a pagar recorrente","operationId":"getRecurringPurchaseInvoice","security":[{"ApiKeyAuth":["recurring:read"]}],"responses":{"200":{"description":"Conta a pagar recorrente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchaseInvoice"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conta a pagar recorrente não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/insumos":{"get":{"tags":["Insumos"],"summary":"Listar insumos","operationId":"listInsumos","security":[{"ApiKeyAuth":["insumos:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"name","in":"query","description":"Nome (busca parcial).","schema":{"type":"string"}},{"name":"active","in":"query","description":"Somente ativos (true) ou inativos (false).","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Insumo"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Insumos"],"summary":"Criar insumo","operationId":"createInsumo","security":[{"ApiKeyAuth":["insumos:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsumoWrite"}}}},"responses":{"201":{"description":"Insumo criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Insumo"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/insumos/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Insumos"],"summary":"Obter insumo","operationId":"getInsumo","security":[{"ApiKeyAuth":["insumos:read"]}],"responses":{"200":{"description":"Insumo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Insumo"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Insumo não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Insumos"],"summary":"Editar insumo","operationId":"updateInsumo","security":[{"ApiKeyAuth":["insumos:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsumoWrite"}}}},"responses":{"200":{"description":"Insumo atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Insumo"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Insumo não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Insumos"],"summary":"Excluir insumo","operationId":"deleteInsumo","security":[{"ApiKeyAuth":["insumos:delete"]}],"responses":{"204":{"description":"Excluído"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Insumo não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notifications":{"get":{"tags":["Notificações"],"summary":"Listar notificações","operationId":"listNotifications","security":[{"ApiKeyAuth":["notifications:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"type","in":"query","description":"Tipo da notificação.","schema":{"type":"string"}},{"name":"entity_type","in":"query","description":"Entidade relacionada.","schema":{"type":"string"}},{"name":"entity_id","in":"query","description":"Id da entidade relacionada.","schema":{"type":"string","format":"uuid"}},{"name":"user_id","in":"query","description":"Destinatário.","schema":{"type":"string","format":"uuid"}},{"name":"created_from","in":"query","description":"Criadas a partir de.","schema":{"type":"string","format":"date"}},{"name":"created_to","in":"query","description":"Criadas até.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notifications/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Notificações"],"summary":"Obter notificação","operationId":"getNotification","security":[{"ApiKeyAuth":["notifications:read"]}],"responses":{"200":{"description":"Notificação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Notification"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Notificação não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bank-accounts":{"get":{"tags":["Contas bancárias"],"summary":"Listar contas bancárias","operationId":"listBankAccounts","security":[{"ApiKeyAuth":["bank_accounts:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"account_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BankAccount"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bank-accounts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Contas bancárias"],"summary":"Obter conta bancária","operationId":"getBankAccount","security":[{"ApiKeyAuth":["bank_accounts:read"]}],"responses":{"200":{"description":"Conta bancária","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccount"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conta bancária não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts":{"get":{"tags":["Pagamentos a Fornecedor"],"summary":"Listar pagamentos a fornecedor","operationId":"listPayouts","security":[{"ApiKeyAuth":["payouts:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]}},{"name":"provider","in":"query","schema":{"type":"string","enum":["inter","c6bank"]}},{"name":"method","in":"query","schema":{"type":"string","enum":["pix","boleto"]}},{"name":"bank_account_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"scheduled_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"scheduled_to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payout"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Pagamentos a Fornecedor"],"summary":"Pagar ou agendar pagamento (Pix/boleto)","operationId":"createPayout","description":"Executa ou agenda um pagamento a fornecedor no provider ativo (Inter/C6). Informe o alvo via purchase_invoice_charge_id, supplier_payment_method_id, pix_key/pix_copia_e_cola ou boleto_barcode.","security":[{"ApiKeyAuth":["payouts:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutCreate"}}}},"responses":{"201":{"description":"Pagamento criado/executado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"400":{"description":"Dados inválidos / alvo ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conta bancária, parcela ou fornecedor não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Integração não configurada ou provider ambíguo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"Erro retornado pelo banco","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Pagamentos a Fornecedor"],"summary":"Obter pagamento","operationId":"getPayout","security":[{"ApiKeyAuth":["payouts:read"]}],"responses":{"200":{"description":"Pagamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Pagamento não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Pagamentos a Fornecedor"],"summary":"Cancelar pagamento agendado","operationId":"cancelPayout","description":"Cancela um pagamento agendado. Pix agendado no Inter não é cancelável pela API (retorna 422 — cancele no Internet Banking).","security":[{"ApiKeyAuth":["payouts:cancel"]}],"responses":{"200":{"description":"Cancelado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Pagamento não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Não pode ser cancelado no estado atual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Pix Inter — cancele no Internet Banking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/{id}/sync":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Pagamentos a Fornecedor"],"summary":"Sincronizar status com o banco","operationId":"syncPayout","security":[{"ApiKeyAuth":["payouts:read"]}],"responses":{"200":{"description":"Status sincronizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Pagamento não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/split-rules":{"get":{"tags":["Split de Pagamentos"],"summary":"Listar regras de split","operationId":"listSplitRules","security":[{"ApiKeyAuth":["split:list"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["company_default","contract","invoice","charge"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SplitRule"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Split de Pagamentos"],"summary":"Criar regra de split","operationId":"createSplitRule","description":"Cria uma regra de divisão com seus beneficiários (recipients). Percentual primeiro, depois fixo; soma de percentuais ≤ 100.","security":[{"ApiKeyAuth":["split:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRuleCreate"}}}},"responses":{"201":{"description":"Regra criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRule"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/split-rules/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Split de Pagamentos"],"summary":"Obter regra de split","operationId":"getSplitRule","security":[{"ApiKeyAuth":["split:list"]}],"responses":{"200":{"description":"Regra","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRule"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Regra não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Split de Pagamentos"],"summary":"Atualizar regra de split","operationId":"updateSplitRule","description":"Atualiza campos da regra. Se 'recipients' for enviado, substitui todos os beneficiários.","security":[{"ApiKeyAuth":["split:update"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRuleCreate"}}}},"responses":{"200":{"description":"Regra atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRule"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Regra não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Split de Pagamentos"],"summary":"Excluir regra de split","operationId":"deleteSplitRule","security":[{"ApiKeyAuth":["split:delete"]}],"responses":{"200":{"description":"Removida","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Regra não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/split-executions":{"get":{"tags":["Split de Pagamentos"],"summary":"Listar execuções de split","operationId":"listSplitExecutions","security":[{"ApiKeyAuth":["split:list"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","calculated","releasing","completed","partial","reversed","failed"]}},{"name":"invoice_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"supplier_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtra execuções que contenham fatia deste fornecedor"}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SplitExecution"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/split-executions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Split de Pagamentos"],"summary":"Obter execução de split (com fatias)","operationId":"getSplitExecution","security":[{"ApiKeyAuth":["split:list"]}],"responses":{"200":{"description":"Execução","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitExecution"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Execução não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/split-executions/{id}/reverse":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Split de Pagamentos"],"summary":"Estornar execução de split","operationId":"reverseSplitExecution","description":"Marca a execução e suas fatias como 'reversed'. Para cada fatia de fornecedor já paga, registra um ajuste de recuperação (o fornecedor deve devolver o valor).","security":[{"ApiKeyAuth":["split:update"]}],"responses":{"200":{"description":"Estornada","content":{"application/json":{"schema":{"type":"object","properties":{"execution_id":{"type":"string"},"status":{"type":"string"},"adjustments_created":{"type":"integer"},"recover_amount_cents":{"type":"integer"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Execução não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Já estornada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/split-items/{id}/release":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["Split de Pagamentos"],"summary":"Liberar fatia manualmente","operationId":"releaseSplitItem","description":"Libera uma fatia (pending/awaiting_nota/failed → released), apta a virar payout.","security":[{"ApiKeyAuth":["split:update"]}],"responses":{"200":{"description":"Liberada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fatia não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suppliers/{id}/payment-methods":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Formas de pagamento do fornecedor"],"summary":"Listar formas de pagamento do fornecedor","operationId":"listSupplierPaymentMethods","security":[{"ApiKeyAuth":["suppliers:read"]}],"responses":{"200":{"description":"Formas de pagamento","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SupplierPaymentMethod"}}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fornecedor não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Formas de pagamento do fornecedor"],"summary":"Cadastrar forma de pagamento","operationId":"createSupplierPaymentMethod","security":[{"ApiKeyAuth":["suppliers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPaymentMethodCreate"}}}},"responses":{"201":{"description":"Criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPaymentMethod"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Fornecedor não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suppliers/{id}/payment-methods/{methodId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"methodId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"tags":["Formas de pagamento do fornecedor"],"summary":"Atualizar forma de pagamento","operationId":"updateSupplierPaymentMethod","security":[{"ApiKeyAuth":["suppliers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPaymentMethodCreate"}}}},"responses":{"200":{"description":"Atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierPaymentMethod"}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Formas de pagamento do fornecedor"],"summary":"Excluir forma de pagamento","operationId":"deleteSupplierPaymentMethod","security":[{"ApiKeyAuth":["suppliers:delete"]}],"responses":{"204":{"description":"Excluída"},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Há registros vinculados que impedem a exclusão","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-methods":{"get":{"tags":["Métodos de pagamento"],"summary":"Listar métodos de pagamento disponíveis","operationId":"listPaymentMethods","description":"Lista as formas de recebimento configuradas (Pix, boleto, checkout) por provider. Útil antes de criar uma cobrança.","security":[{"ApiKeyAuth":["charges:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"provider","in":"query","schema":{"type":"string","enum":["inter","c6bank"]}},{"name":"channel","in":"query","schema":{"type":"string","enum":["pix","boleto","checkout","credit_card"]}},{"name":"all","in":"query","description":"true lista TODAS as formas cadastradas; por padrão só as utilizáveis (manuais ou de provider com integração ativa).","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-methods/ap":{"get":{"tags":["Métodos de pagamento"],"summary":"Listar métodos de pagamento a fornecedor (AP)","operationId":"listPaymentMethodsAp","description":"Formas de pagamento usadas em payouts (contas a pagar).","security":[{"ApiKeyAuth":["payouts:read"]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Número da página (default: 1)"},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Itens por página (default: 20, máx: 100)"},{"name":"active","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"provider","in":"query","schema":{"type":"string","enum":["inter","c6bank"]}}],"responses":{"200":{"description":"Listagem paginada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}}}}},"401":{"description":"API key não fornecida, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido (60 req/min por padrão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}