Ascend
Ascend
Docs
API

Transações

CRUD de transações financeiras.

Visao geral

Rotas para criar, listar, obter, atualizar e excluir (soft delete) transacoes financeiras.

  • Base: https://api.ascendteam.cloud/api/v1/transactions
  • Autenticacao: requer sessao/credenciais validas do Better Auth (ver /docs/api/auth).

Modelo (campos principais)

  • id (UUID)
  • userId (UUID)
  • categoryId (UUID, opcional)
  • familyMemberId (UUID, opcional)
  • amount (decimal)
  • type (INCOME | EXPENSE)
  • date (data/hora)
  • description (opcional)
  • serviceCategoryId (UUID, opcional; apenas para transacoes EM_ABERTO)
  • paymentMethod (DEBIT_CARD | CREDIT_CARD_ONE_TIME | CREDIT_CARD_INSTALLMENTS | EM_ABERTO, opcional)
  • originDebtId (UUID, opcional; referencia a divida criada quando em aberto)
  • isInstallmentParent (boolean, default false)
  • installmentsCount (number, opcional)
  • installmentBillingStart (CURRENT_MONTH | NEXT_MONTH, opcional)
  • firstInstallmentDueDate (date, opcional)
  • recurrenceRuleId (UUID, opcional; preenchido quando a transacao origina uma regra recorrente)
  • idempotencyKey (string, opcional; recomendado sempre e obrigatório para parcelado via header)
  • deletedAt (opcional)
  • createdAt
  • updatedAt

Endpoints

POST /

Cria uma nova transacao.

Body

  • amount (number, obrigatorio)
  • type (INCOME | EXPENSE, obrigatorio)
  • date (date, opcional)
  • description (string, opcional)
  • categoryId (UUID, opcional)
  • familyMemberId (UUID, opcional)
  • debtorId (UUID, opcional; usado quando paymentMethod=EM_ABERTO)
  • serviceCategoryId (UUID, opcional; permitido apenas quando paymentMethod=EM_ABERTO)
  • paymentMethod (DEBIT_CARD | CREDIT_CARD_ONE_TIME | CREDIT_CARD_INSTALLMENTS | EM_ABERTO, opcional)
  • installmentPlan (object, opcional; obrigatório quando paymentMethod=CREDIT_CARD_INSTALLMENTS)
    • count (number, obrigatório; ex.: 2–24)
    • billingStart (CURRENT_MONTH | NEXT_MONTH, obrigatório)
    • firstDueDate (date, opcional)
  • recurrencePlan (object, opcional; indisponível para parcelado)
    • periodicity (DAILY | MONTHLY | YEARLY, obrigatório)
    • interval (number, obrigatório; mínimo 1)
    • repeatCount (number, opcional; quando omitido, a recorrencia pode ser indefinida)
    • indefinite (boolean, obrigatório)
  • idempotencyKey (string, opcional no body; o header Idempotency-Key continua sendo o formato preferencial)

Respostas

  • 201: transacao criada
  • 400: dados invalidos

Parcelamento (crédito)

  • Quando paymentMethod=CREDIT_CARD_INSTALLMENTS, a API cria:
    • 1 transação-mãe (isInstallmentParent=true, amount=total)
    • N parcelas vinculadas (valores que somam exatamente o total)
  • Na contagem mensal (dashboard/relatórios), somamos apenas o valor das parcelas do mês (nunca o total da transação-mãe).
  • Idempotência: envie o header Idempotency-Key (obrigatório para parcelado) para evitar duplicidade em retries.

Em aberto

  • Quando paymentMethod=EM_ABERTO, a transacao representa uma intencao de recebimento.
  • Transacoes em aberto nao entram nos totais ate serem pagas.
  • Ao informar debtorId, a API cria automaticamente uma divida ABERTA vinculada em originDebtId.
  • serviceCategoryId so e aceito nesse modo e tambem e propagado para a divida criada.
  • Ao pagar, a mesma transacao deve ser atualizada para o metodo real e vinculada a uma alocacao.

GET /

Lista transacoes (paginado).

Query

  • type (INCOME | EXPENSE, opcional)
  • categoryId (UUID, opcional)
  • from (date ISO 8601, opcional)
  • to (date ISO 8601, opcional)
  • page (number, opcional, default 1)
  • pageSize (number, opcional, default 20, max 100)
  • includeDeleted (boolean, opcional, default false)

Resposta 200

  • total, page, pageSize, items (array de transacoes)

GET /export

Exporta transacoes em CSV ou PDF.

Query

  • type (INCOME | EXPENSE, opcional)
  • categoryId (UUID, opcional)
  • familyMemberId (UUID, opcional)
  • serviceCategoryId (UUID, opcional)
  • from (date ISO 8601, opcional)
  • to (date ISO 8601, opcional)
  • includeDeleted (boolean, opcional, default false)
  • format (csv | pdf, opcional, default csv)
  • fields (lista separada por virgula; ex.: date,amount,categoryName)

Resposta 200

  • Buffer do arquivo
  • Content-Type: text/csv ou application/pdf
  • Content-Disposition: attachment; filename="transacoes-..."

POST /import-csv

Faz upload de CSV de faturas pessoais para staging.

Query

  • source (string, opcional)
  • delimiter (string, opcional; 1 caractere)
  • negativeMode (IGNORE | AS_INCOME | AS_ADJUSTMENT, opcional)
  • installmentAmountMode (PER_INSTALLMENT | TOTAL, opcional; default PER_INSTALLMENT)
  • saveTemplate (boolean, opcional)

Body

  • multipart/form-data com campo file

Resposta 201

  • Lote de importacao com contadores (totalRows, validRows, invalidRows).

POST /import-document

Faz upload de CSV, OFX, PDF ou XLSX para importacao de transacoes.

Query

  • sourceType (CSV | OFX | PDF | XLSX, opcional; inferido por extensao/magic quando omitido)
  • source (string, opcional)
  • delimiter (string, opcional; 1 caractere, apenas CSV)
  • negativeMode (IGNORE | AS_INCOME | AS_ADJUSTMENT, opcional; CSV/XLSX)
  • installmentAmountMode (PER_INSTALLMENT | TOTAL, opcional; CSV/XLSX)
  • saveTemplate (boolean, opcional)
  • bankCode (BB | CAIXA | BRADESCO | NUBANK | INTER | ITAU | SANTANDER, opcional; obrigatório para PDF)
  • pdfPassword (string, opcional; usado para PDF protegido)
  • sheetName (string, opcional; nome da aba para XLSX)

OFX

  • Formato preferencial para extratos bancários.
  • Quando presente, FITID participa da chave de idempotência ofx:{bank}:{acct}:{fitId}.
  • Reimportação da mesma chave resulta em SKIPPED, inclusive se a transação foi soft-deleted.

XLSX

  • Aceita .xlsx e .xlsm; arquivos .xls legados não são suportados.
  • Para Google Sheets, use Arquivo → Baixar → Microsoft Excel (.xlsx).
  • O importador detecta a aba mais provável, o cabeçalho e templates SIMPLE_STATEMENT/MONTHLY_SPEND.

Body

  • multipart/form-data com campo file

Resposta 201

  • Lote de importacao criado.
  • Para PDF, o lote pode retornar documentStatus=PENDING_PROCESSING ate o parser finalizar.

GET /imports/:id

Busca um lote de importacao.

Campos adicionais

  • documentStatus (PENDING_PROCESSING | PROCESSED | PROCESSING_FAILED | INVALID_PASSWORD, opcional)

GET /imports/:id/rows

Lista linhas do lote.

Query

  • status (PENDING | INVALID | COMMITTED | SKIPPED | FAILED, opcional)
  • page (number, opcional)
  • pageSize (number, opcional)

PATCH /imports/:id/configuration

Atualiza configuracao de mapeamento para o lote e reprocessa as linhas.

Body

  • columnMapping (objeto opcional com chaves date, description, amount, installmentIndex, installmentsCount)
  • negativeMode (IGNORE | AS_INCOME | AS_ADJUSTMENT, opcional)
  • installmentAmountMode (PER_INSTALLMENT | TOTAL, opcional)
  • saveTemplate (boolean, opcional)

Regra de parcelamento no import

  • Quando uma linha tiver parcela (ex.: Parcela 1/3), o sistema considera por padrão que o valor do CSV é valor da parcela.
  • Com installmentAmountMode=PER_INSTALLMENT (default), o total da compra vira valor * totalParcelas.
  • Com installmentAmountMode=TOTAL, o valor do CSV já é tratado como total da compra.

PATCH /imports/:id/rows/:rowId

Edita uma linha do staging e revalida status/erros.

Body

  • date (date, opcional)
  • amount (number, opcional)
  • description (string, opcional)

POST /imports/:id/commit

Confirma importacao do lote.

POST /imports/:id/reprocess

Reprocessa um lote PDF que falhou por senha invalida.

Body

  • pdfPassword (string, obrigatorio)

GET /:id

Busca uma transacao por ID.

Params

  • id (UUID)

Respostas

  • 200: transacao encontrada
  • 404: transacao nao encontrada

Detalhe de parcelado

  • Se isInstallmentParent=true, a resposta inclui installments: [] com as parcelas (ordenadas).

PATCH /:id

Atualiza campos da transacao.

Params

  • id (UUID)

Body

  • amount (number, opcional)
  • type (INCOME | EXPENSE, opcional)
  • date (date, opcional)
  • description (string, opcional)
  • categoryId (UUID, opcional)
  • familyMemberId (UUID, opcional)
  • serviceCategoryId (UUID, opcional; permitido apenas quando o metodo efetivo for EM_ABERTO)
  • paymentMethod (DEBIT_CARD | CREDIT_CARD_ONE_TIME | CREDIT_CARD_INSTALLMENTS | EM_ABERTO, opcional)

Respostas

  • 200: transacao atualizada
  • 404: transacao nao encontrada

Regras de atualizacao

  • paymentMethod=CREDIT_CARD_INSTALLMENTS nao pode ser definido via PATCH.
  • paymentMethod=EM_ABERTO so e permitido para transacoes do tipo INCOME.
  • Transacoes parceladas (isInstallmentParent=true) nao aceitam alteracao de valor, tipo, data ou metodo de pagamento; nesse caso, edite apenas descricao/categoria/membro.

DELETE /:id

Soft delete da transacao.

Params

  • id (UUID)

Respostas

  • 200: transacao deletada
  • 404: transacao nao encontrada

Observacoes

  • Soft delete preenche deletedAt.

Autenticação

Better Auth exposto sob /api/v1/auth.

Transações recorrentes

Recorrências diárias, mensais ou anuais.

On this page

Visao geralModelo (campos principais)EndpointsPOST /GET /GET /exportPOST /import-csvPOST /import-documentGET /imports/:idGET /imports/:id/rowsPATCH /imports/:id/configurationPATCH /imports/:id/rows/:rowIdPOST /imports/:id/commitPOST /imports/:id/reprocessGET /:idPATCH /:idDELETE /:idObservacoes