{"openapi":"3.1.0","info":{"title":"Agenda Financeira API","version":"1.0.0","description":"API REST da Agenda Financeira. Documentação completa em https://agendafinanceira.online/developers."},"servers":[{"url":"https://agendafinanceira.online/api/v1"}],"externalDocs":{"url":"https://agendafinanceira.online/developers","description":"Guia completo (autenticação, webhooks, limites)"},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Titular"},{"name":"Contas"},{"name":"Categorias"},{"name":"Contatos"},{"name":"Lançamentos"},{"name":"Conciliação"},{"name":"Tarefas"},{"name":"Webhooks"}],"paths":{"/me":{"get":{"tags":["Titular"],"summary":"Confirma a chave e mostra o titular","responses":{"200":{"description":"OK"},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profiles":{"get":{"tags":["Titular"],"summary":"Agendas do titular","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Profile"}}}}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/accounts":{"get":{"tags":["Contas"],"summary":"Contas do titular","parameters":[{"name":"profile_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Account"}}}}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"profile_id inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Contas"],"summary":"Cria uma conta simples (sem cartão de crédito)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCreate"}}}},"responses":{"201":{"description":"Criada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Account"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"tags":["Categorias"],"summary":"Categorias do titular","parameters":[{"name":"entry_type","in":"query","schema":{"type":"string","enum":["income","expense"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"get":{"tags":["Contatos"],"summary":"Contatos ativos","parameters":[{"name":"profile_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Trecho do nome"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions":{"get":{"tags":["Lançamentos"],"summary":"Lista lançamentos (só linhas reais; ocorrências futuras não materializadas não aparecem)","parameters":[{"name":"profile_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"account_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"category_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"contact_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"entry_type","in":"query","schema":{"type":"string","enum":["income","expense"]}},{"name":"is_paid","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date","example":"2026-09-19"}},{"name":"to","in":"query","schema":{"type":"string","format":"date","example":"2026-09-19"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Trecho da descrição"},{"name":"external_id","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Filtro inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Lançamentos"],"summary":"Cria um lançamento avulso (idempotente por external_id)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionCreate"}}}},"responses":{"200":{"description":"Já existia com o mesmo external_id (devolve o existente)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionEnvelope"}}}},"201":{"description":"Criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionEnvelope"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bank-transactions":{"post":{"tags":["Conciliação"],"summary":"Sugere uma movimentação para a fila de Conciliação (idempotente por account_id + external_id)","description":"Não cria lançamento: a movimentação fica pendente até alguém confirmar na tela de Conciliação, como o extrato bancário. Aceita a legenda de quem mandou e a imagem/PDF do comprovante (base64, até 5 MB).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankTransactionCreate"}}}},"responses":{"200":{"description":"Já existia com o mesmo external_id nesta conta (devolve a existente)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankTransactionCreated"}}}},"201":{"description":"Registrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankTransactionCreated"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Lançamentos"],"summary":"Um lançamento","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionEnvelope"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Lançamentos"],"summary":"Altera campos simples","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionEnvelope"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Só pelo app (transferência, fatura, saldo inicial, cartão)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Lançamentos"],"summary":"Exclui um lançamento avulso","responses":{"200":{"description":"Excluído"},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Só pelo app (transferência, fatura, recorrência, parcela)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks":{"get":{"tags":["Tarefas"],"summary":"Lista tarefas (itens de agenda sem valor financeiro)","parameters":[{"name":"profile_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"contact_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"is_done","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date","example":"2026-09-19"}},{"name":"to","in":"query","schema":{"type":"string","format":"date","example":"2026-09-19"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Trecho da descrição"},{"name":"external_id","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Filtro inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Tarefas"],"summary":"Cria uma tarefa avulsa (idempotente por external_id)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"200":{"description":"Já existia com o mesmo external_id (devolve a existente)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskEnvelope"}}}},"201":{"description":"Criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskEnvelope"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Tarefas"],"summary":"Uma tarefa","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskEnvelope"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Tarefas"],"summary":"Altera campos simples","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskEnvelope"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Ocorrência de tarefa recorrente — só pelo app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Tarefas"],"summary":"Exclui uma tarefa avulsa","responses":{"200":{"description":"Excluída"},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Ocorrência de tarefa recorrente — só pelo app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"Lista endpoints","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Webhooks"],"summary":"Cadastra um endpoint (o secret só vem nesta resposta)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"responses":{"201":{"description":"Criado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string"}}}]}}}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","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":"Endpoint + últimas 20 entregas","responses":{"200":{"description":"OK"},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Webhooks"],"summary":"Altera url, events, description ou is_active","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPatch"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Exclui o endpoint","responses":{"200":{"description":"Excluído"},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","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":"Enfileira um evento ping","responses":{"202":{"description":"Enfileirado"},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Chave sem escopo write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições (120/min, 10000/dia)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer af_live_…"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_error","conflict","rate_limited","internal_error"]},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}},"Profile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"Account":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profile_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["checking","savings","investment","cash","credit_card"]},"currency":{"type":"string"},"initial_balance":{"type":"number"},"is_default":{"type":"boolean"},"is_profile_default_account":{"type":"boolean","description":"Conta padrão desta Agenda — usada quando account_id não é informado em POST /transactions"},"closing_day":{"type":["integer","null"]},"due_day":{"type":["integer","null"]},"credit_limit":{"type":["number","null"]},"created_at":{"type":"string","format":"date-time"}}},"AccountCreate":{"type":"object","required":["name"],"properties":{"profile_id":{"type":"string","format":"uuid","description":"Opcional se o titular só tem uma Agenda"},"name":{"type":"string","maxLength":120},"type":{"type":"string","enum":["checking","savings","investment","cash"],"default":"checking"},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"BRL"},"initial_balance":{"type":"number","default":0}}},"Category":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profile_id":{"type":["string","null"],"format":"uuid"},"parent_id":{"type":["string","null"],"format":"uuid"},"name":{"type":"string"},"entry_type":{"type":"string","enum":["income","expense"]},"expense_nature":{"type":["string","null"],"enum":["lifestyle","debt","investment",null]},"income_nature":{"type":["string","null"],"enum":["operating","investment",null]},"color":{"type":["string","null"]},"icon":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profile_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["individual","company"]},"role":{"type":"string","enum":["cliente","fornecedor","ambos","nao_classificado"]},"document":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Transaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profile_id":{"type":"string","format":"uuid"},"account_id":{"type":"string","format":"uuid"},"account_name":{"type":["string","null"]},"category_id":{"type":["string","null"],"format":"uuid"},"category_name":{"type":["string","null"]},"contact_id":{"type":["string","null"],"format":"uuid"},"description":{"type":"string"},"amount":{"type":"number","description":"Sempre positivo; o sentido vem de entry_type"},"entry_type":{"type":"string","enum":["income","expense"]},"date":{"type":"string","format":"date","example":"2026-09-19"},"is_paid":{"type":"boolean"},"is_scheduled":{"type":"boolean"},"auto_settle":{"type":"boolean"},"is_transfer":{"type":"boolean"},"transfer_account_id":{"type":["string","null"],"format":"uuid"},"is_initial_balance":{"type":"boolean"},"is_invoice_payment":{"type":"boolean"},"credit_card_invoice_id":{"type":["string","null"],"format":"uuid"},"recurrence_group_id":{"type":["string","null"],"format":"uuid"},"installment_group_id":{"type":["string","null"],"format":"uuid"},"installment_number":{"type":["integer","null"]},"installment_total":{"type":["integer","null"]},"split_from_id":{"type":["string","null"],"format":"uuid"},"external_id":{"type":["string","null"]},"notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"TransactionEnvelope":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Transaction"}}},"TransactionCreate":{"type":"object","required":["category_id","description","amount","entry_type","date"],"properties":{"profile_id":{"type":"string","format":"uuid","description":"Opcional se o titular só tem uma Agenda"},"account_id":{"type":"string","format":"uuid","description":"Opcional — sem isso, usa a conta padrão da Agenda (is_profile_default_account)"},"category_id":{"type":"string","format":"uuid"},"description":{"type":"string","maxLength":200},"amount":{"type":"number","exclusiveMinimum":0},"entry_type":{"type":"string","enum":["income","expense"]},"date":{"type":"string","format":"date","example":"2026-09-19"},"is_paid":{"type":"boolean","default":false},"is_scheduled":{"type":"boolean","default":false},"auto_settle":{"type":"boolean","default":false},"notes":{"type":["string","null"],"maxLength":2000},"contact_id":{"type":["string","null"],"format":"uuid"},"external_id":{"type":"string","maxLength":200,"description":"Id no seu sistema — reenvio com o mesmo id não duplica"}}},"BankTransactionCreate":{"type":"object","required":["account_id","external_id","posted_at","description","amount","direction"],"properties":{"account_id":{"type":"string","format":"uuid"},"external_id":{"type":"string","maxLength":200,"description":"Id na origem (ex.: id da mensagem do WhatsApp) — reenvio não duplica"},"posted_at":{"type":"string","format":"date","example":"2026-09-19"},"description":{"type":"string","maxLength":300},"amount":{"type":"number","exclusiveMinimum":0},"direction":{"type":"string","enum":["debit","credit"],"description":"debit = saiu dinheiro, credit = entrou"},"source":{"type":"string","enum":["whatsapp","api"],"default":"api"},"caption":{"type":["string","null"],"maxLength":1000,"description":"Legenda de quem mandou o comprovante (o motivo)"},"merchant_name":{"type":["string","null"],"maxLength":200},"raw":{"type":["object","null"],"description":"Dados extraídos na origem, guardados como vieram"},"receipt":{"type":["object","null"],"required":["media_type","data"],"properties":{"media_type":{"type":"string","enum":["image/jpeg","image/png","image/webp","application/pdf"]},"data":{"type":"string","description":"Base64 puro, sem prefixo data:"}}}}},"BankTransactionCreated":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","reconciled","ignored"]},"source":{"type":"string"},"created":{"type":"boolean"},"receipt_uploaded":{"type":"boolean"}}}}},"TransactionPatch":{"type":"object","minProperties":1,"properties":{"description":{"type":"string","maxLength":200},"amount":{"type":"number","exclusiveMinimum":0},"date":{"type":"string","format":"date","example":"2026-09-19"},"is_paid":{"type":"boolean"},"notes":{"type":["string","null"],"maxLength":2000},"category_id":{"type":"string","format":"uuid"},"contact_id":{"type":["string","null"],"format":"uuid"},"external_id":{"type":["string","null"],"maxLength":200}}},"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profile_id":{"type":"string","format":"uuid"},"description":{"type":"string"},"date":{"type":"string","format":"date","example":"2026-09-19"},"time":{"type":["string","null"],"description":"HH:MM opcional"},"color":{"type":"string"},"is_done":{"type":"boolean"},"contact_id":{"type":["string","null"],"format":"uuid"},"recurrence_group_id":{"type":["string","null"],"format":"uuid"},"external_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"TaskEnvelope":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}}},"TaskCreate":{"type":"object","required":["description","date"],"properties":{"profile_id":{"type":"string","format":"uuid","description":"Opcional se o titular só tem uma Agenda"},"description":{"type":"string","maxLength":200},"date":{"type":"string","format":"date","example":"2026-09-19"},"time":{"type":["string","null"],"description":"HH:MM opcional"},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","default":"#6b7280"},"is_done":{"type":"boolean","default":false},"contact_id":{"type":["string","null"],"format":"uuid"},"external_id":{"type":"string","maxLength":200,"description":"Id no seu sistema — reenvio com o mesmo id não duplica"}}},"TaskPatch":{"type":"object","minProperties":1,"properties":{"description":{"type":"string","maxLength":200},"date":{"type":"string","format":"date","example":"2026-09-19"},"time":{"type":["string","null"]},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"is_done":{"type":"boolean"},"contact_id":{"type":["string","null"],"format":"uuid"},"external_id":{"type":["string","null"],"maxLength":200}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string","enum":["transaction.created","transaction.updated","transaction.paid","transaction.deleted","*"]}},"is_active":{"type":"boolean"},"consecutive_failures":{"type":"integer"},"last_delivery_at":{"type":["string","null"],"format":"date-time"},"last_delivery_status":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"WebhookCreate":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"https obrigatório"},"events":{"type":"array","items":{"type":"string","enum":["transaction.created","transaction.updated","transaction.paid","transaction.deleted","*"]},"default":["*"]},"description":{"type":["string","null"],"maxLength":120}}},"WebhookPatch":{"type":"object","minProperties":1,"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["transaction.created","transaction.updated","transaction.paid","transaction.deleted","*"]}},"description":{"type":["string","null"],"maxLength":120},"is_active":{"type":"boolean"}}},"WebhookDelivery":{"type":"object","description":"Corpo do POST que a Agenda envia pra sua URL","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string","enum":["transaction.created","transaction.updated","transaction.paid","transaction.deleted","ping"]},"created_at":{"type":"string","format":"date-time"},"data":{"oneOf":[{"$ref":"#/components/schemas/Transaction"},{"type":"object"}]}}}}}}