{"openapi":"3.1.0","info":{"title":"Moedux API","version":"1.0.0","description":"API JSON para agentes de IA. Autentique com `Authorization: Bearer moedux_live_\u003csegredo\u003e`. Cada operação declara em `x-permission` a permissão exigida na API Key. As regras de negócio e os gates de plano ficam apenas no servidor: uma API Key não libera recursos do Plano Pro.","license":{"name":"Proprietary","url":"https://www.moedux.com/terms-of-use"}},"servers":[{"url":"https://www.moedux.com","description":"Produção"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/diagnosis":{"get":{"summary":"Diagnóstico financeiro","operationId":"getDiagnosis","description":"Saldo, Gasto Diário observado, data do Mar Vermelho (somente Plano Pro) e projeção diária.","x-permission":"diagnosis:read","parameters":[{"name":"horizon_days","in":"query","description":"Horizonte da projeção em dias; limitado pelo plano. Padrão 60.","schema":{"type":"integer","default":60,"minimum":0}}],"responses":{"200":{"description":"Diagnóstico da conta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiagnosisResponse"}}}},"401":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/networth":{"get":{"summary":"Patrimônio líquido","operationId":"getNetworth","description":"Itens patrimoniais e total (bens menos dívidas). Recurso do Plano Pro: planos elegíveis recebem 200, os demais 403 com `plan_gate`.","x-permission":"networth:read","responses":{"200":{"description":"Patrimônio da conta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworthResponse"}}}},"401":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scenarios/apply":{"post":{"summary":"Aplicar cenário","operationId":"applyScenario","description":"Commita os itens do cenário como transações reais em um lote atômico. IDs repetidos não duplicam linhas. Recurso do Plano Pro.","x-permission":"scenarios:apply","requestBody":{"required":true,"description":"Itens do cenário a aplicar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioApplyRequest"}}}},"responses":{"200":{"description":"IDs das transações aplicadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioApplyResponse"}}}},"400":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scenarios/compare":{"post":{"summary":"Comparar cenário","operationId":"compareScenario","description":"Compara a projeção base com um cenário hipotético e devolve o delta. Nada é persistido (ADR 0014). Recurso do Plano Pro.","x-permission":"scenarios:compare","requestBody":{"required":true,"description":"Itens do cenário e horizonte em dias (padrão 365).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioCompareRequest"}}}},"responses":{"200":{"description":"Comparação base versus cenário.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioCompareResponse"}}}},"400":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/transactions":{"get":{"summary":"Listar transações","operationId":"listTransactions","description":"Transações filtradas por tipo e período (StartDate), ordenadas por data desc, paginadas.","x-permission":"transactions:read","parameters":[{"name":"type","in":"query","description":"Filtra por tipo de transação.","schema":{"type":"string","enum":["income","expense","savings","credit_card"]}},{"name":"from","in":"query","description":"StartDate mínima inclusiva (YYYY-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"StartDate máxima inclusiva (YYYY-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","description":"Tamanho da página; valores acima de 500 são cortados.","schema":{"type":"integer","default":100,"minimum":0,"maximum":500}},{"name":"offset","in":"query","description":"Deslocamento da página.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Página de transações.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsListResponse"}}}},"401":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Criar transação","operationId":"createTransaction","description":"Cria uma transação com `id` UUIDv4 fornecido pelo cliente. Um `id` repetido devolve a transação original sem duplicar (201 na criação, 200 na repetição).","x-permission":"transactions:write","requestBody":{"required":true,"description":"Transação a criar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTransactionRequest"}}}},"responses":{"200":{"description":"Transação já existente (idempotência).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"201":{"description":"Transação criada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/transactions/{id}":{"put":{"summary":"Editar transação","operationId":"editTransaction","description":"Edita uma transação preservando o Escopo de edição (`mode`). Transações recorrentes exigem `mode`; transações únicas não o aceitam.","x-permission":"transactions:write","parameters":[{"name":"id","in":"path","required":true,"description":"ID da transação.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"Novos valores da transação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditTransactionRequest"}}}},"responses":{"200":{"description":"Transação editada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Excluir transação","operationId":"deleteTransaction","description":"Exclui uma transação. Transações recorrentes exigem `mode` para indicar quais ocorrências remover.","x-permission":"transactions:write","parameters":[{"name":"id","in":"path","required":true,"description":"ID da transação.","schema":{"type":"string","format":"uuid"}},{"name":"mode","in":"query","description":"Escopo de edição: only, from ou all.","schema":{"type":"string","enum":["only","from","all"]}},{"name":"date","in":"query","description":"Ocorrência afetada (YYYY-MM-DD).","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Transação excluída.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResponse"}}}},"401":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro estruturado com código, mensagem e campos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"bearerFormat":"moedux_live_\u003csegredo\u003e","description":"API Key no formato `moedux_live_\u003csegredo\u003e`, enviada como `Authorization: Bearer \u003cchave\u003e`. Criação e revogação ocorrem apenas em /app/settings/apikeys.","scheme":"bearer","type":"http"}},"schemas":{"CreateTransactionRequest":{"type":"object","properties":{"amount":{"type":"number","description":"Positivo para Entrada, negativo para Saída."},"dayOfMonth":{"type":["integer","null"]},"description":{"type":"string"},"frequency":{"type":"string","enum":["once","daily","monthly"]},"id":{"type":"string","format":"uuid"},"isStartingBalance":{"type":"boolean"},"startDate":{"type":"string","format":"date","description":"YYYY-MM-DD"},"type":{"type":"string","enum":["income","expense","savings","credit_card"]}},"required":["id","amount","type","frequency"]},"DailyBalance":{"type":"object","properties":{"balance":{"type":"number"},"date":{"type":"string","format":"date","description":"YYYY-MM-DD"},"solvency":{"type":"string","enum":["dark-red","light-red","yellow","light-green","dark-green"]}}},"DailySpend":{"type":"object","properties":{"confidence":{"type":"string","enum":["Sem dados","Aprendendo","Confiável"]},"value":{"type":"number","description":"Gasto Diário observado."},"windowDays":{"type":"integer"}}},"DeletedResponse":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string","format":"uuid"}}},"DiagnosisResponse":{"type":"object","properties":{"balance":{"type":"number"},"dailyVariableSpend":{"$ref":"#/components/schemas/DailySpend"},"horizonDays":{"type":"integer"},"projection":{"type":"array","items":{"$ref":"#/components/schemas/DailyBalance"}},"redSeaDate":{"type":["string","null"],"format":"date","description":"YYYY-MM-DD ou null quando o recurso não está disponível ao plano."},"userTier":{"type":"string"}}},"EditTransactionRequest":{"type":"object","properties":{"amount":{"type":"number","description":"Positivo para Entrada, negativo para Saída."},"date":{"type":"string","format":"date","description":"YYYY-MM-DD"},"dayOfMonth":{"type":["integer","null"]},"description":{"type":"string"},"frequency":{"type":"string","enum":["once","daily","monthly"]},"mode":{"type":"string","description":"Escopo de edição; obrigatório para recorrentes e rejeitado para transações únicas.","enum":["only","from","all"]},"startDate":{"type":"string","format":"date","description":"YYYY-MM-DD"}},"required":["amount","frequency"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Código estável: unauthorized, invalid_request, validation_failed, plan_gate, not_found, internal_error."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldError"}},"message":{"type":"string"},"permission":{"type":"string"}}},"FieldError":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}},"MonthlyValue":{"type":"object","properties":{"month":{"type":"string"},"notes":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"value":{"type":"number"}}},"NetworthResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PatrimonioItem"}},"total":{"type":"number"}}},"PatrimonioItem":{"type":"object","properties":{"category":{"type":"string","enum":["reserva","investimentos","outros","devedor"]},"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"values":{"type":"array","items":{"$ref":"#/components/schemas/MonthlyValue"}}}},"ScenarioApplyRequest":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}},"ScenarioApplyResponse":{"type":"object","properties":{"results":{"type":"array","items":{"type":"string"}}}},"ScenarioCompareRequest":{"type":"object","properties":{"horizonDays":{"type":"integer","default":365},"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}},"ScenarioCompareResponse":{"type":"object","properties":{"baseline":{"$ref":"#/components/schemas/ScenarioSide"},"delta":{"$ref":"#/components/schemas/ScenarioDelta"},"scenario":{"$ref":"#/components/schemas/ScenarioSide"}}},"ScenarioDelta":{"type":"object","properties":{"endBalanceDelta":{"type":"number"},"redSeaDeltaDays":{"type":"integer"},"redSeaMoved":{"type":"string","enum":["later","earlier","unchanged","reached","averted","none"]}}},"ScenarioSide":{"type":"object","properties":{"projection":{"type":"array","items":{"$ref":"#/components/schemas/DailyBalance"}},"redSeaDate":{"type":["string","null"],"format":"date","description":"YYYY-MM-DD ou null quando o recurso não está disponível ao plano."}}},"Transaction":{"type":"object","properties":{"amount":{"type":"number","description":"Positivo para Entrada, negativo para Saída."},"createdAt":{"type":"string","format":"date-time"},"dayOfMonth":{"type":["integer","null"],"description":"Dia do mês (1-31), obrigatório para frequência monthly."},"description":{"type":"string"},"endDate":{"type":["string","null"],"format":"date"},"excludedDates":{"type":"array","items":{"type":"string","format":"date","description":"YYYY-MM-DD"}},"frequency":{"type":"string","enum":["once","daily","monthly"]},"id":{"type":"string","format":"uuid"},"isStartingBalance":{"type":"boolean","description":"Saldo inicial: só pode ser a primeira transação da conta."},"startDate":{"type":"string","format":"date","description":"YYYY-MM-DD"},"syncedAt":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["income","expense","savings","credit_card"]}},"required":["id","amount","type","frequency","startDate"]},"TransactionsListResponse":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}}}}}