Dívidas

Visao geral

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

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

Modelo (campos principais)

• id (UUID)
• debtorId (UUID)
• serviceCategoryId (UUID, opcional)
• originalAmount (decimal)
• currentBalance (decimal)
• dueDate (data, opcional)
• status (ABERTA | PARCIAL | QUITADA | CANCELADA | EM_NEGOCIACAO)
• description (opcional)
• issueDate (data)
• deletedAt (opcional)
• createdAt
• updatedAt

Endpoints

POST /

Cria uma nova divida.

Body

• debtorId (UUID, obrigatorio)
• serviceCategoryId (UUID, opcional)
• originalAmount (number, obrigatorio)
• currentBalance (number, opcional; default = originalAmount)
• dueDate (date, opcional)
• status (opcional; default = ABERTA)
• description (string, opcional)
• issueDate (date, opcional)

Respostas

• 201: divida criada
• 400: dados invalidos

GET /

Lista dividas (paginado).

Query

• debtorId (UUID, opcional)
• status (ABERTA | PARCIAL | QUITADA | CANCELADA | EM_NEGOCIACAO, 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 dividas)

GET /:id

Busca uma divida por ID.

Params

• id (UUID)

Respostas

• 200: divida encontrada
• 404: divida nao encontrada

PATCH /:id

Atualiza campos da divida.

Params

• id (UUID)

Body

• originalAmount (number, opcional)
• currentBalance (number, opcional)
• dueDate (date, opcional)
• status (opcional)
• description (string, opcional)
• issueDate (date, opcional)
• serviceCategoryId (UUID, opcional)

Respostas

• 200: divida atualizada
• 404: divida nao encontrada

DELETE /:id

Soft delete da divida.

Params

• id (UUID)

Respostas

• 200: divida deletada
• 404: divida nao encontrada

Observacoes

• Soft delete preenche deletedAt.
• debtorId pertence ao vinculo original da cobranca e nao e alterado via PATCH.
• serviceCategoryId precisa pertencer ao mesmo usuario e nao pode estar arquivada.
• Para importacao de faturas via CSV, consulte Importação de débitos.