Alocações

Visao geral

Rotas para alocar pagamentos entre transacoes e dividas.

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

Modelo (campos principais)

• id (UUID)
• debtId (UUID)
• transactionId (UUID)
• amount (decimal)
• deletedAt (opcional)
• createdAt

Endpoints

POST /

Cria uma alocacao manual entre uma transacao e uma divida.

Body

• debtId (UUID, obrigatorio)
• transactionId (UUID, obrigatorio)
• amount (number, obrigatorio, > 0)

Respostas

• 201: alocacao criada
• 400: dados invalidos

POST /cascade

Alocacao em cascata baseada no valor da transacao.

Body

• transactionId (UUID, obrigatorio)
• debtIds (UUID[], opcional) - se nao informado, usa todas as dividas elegiveis

Regras principais

• Usa o valor total da transacao como limite de alocacao.
• Se debtIds for informado, aloca somente nessas dividas (ordenadas por dueDate).
• Se debtIds nao for informado, aloca em dividas com status ABERTA, PARCIAL ou EM_NEGOCIACAO, ordenando por dueDate e createdAt.
• Dividas CANCELADA ou com currentBalance <= 0 sao ignoradas.
• Atualiza currentBalance e status das dividas conforme o saldo restante.

Resposta 200

• allocations: lista com { debtId, allocationId, amount }
• updatedDebts: lista de dividas atualizadas
• remaining: saldo da transacao nao alocado

Erros comuns

• 400: transacao sem valor para alocacao
• 400: nenhuma divida disponivel para alocacao

GET /

Lista alocacoes (paginado).

Query

• debtId (UUID, opcional)
• transactionId (UUID, 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 alocacoes)

DELETE /:id

Soft delete da alocacao.

Params

• id (UUID)

Respostas

• 200: alocacao deletada
• 404: alocacao nao encontrada

Observacoes

• Soft delete preenche deletedAt.