@hed-hog/finance 0.0.238 → 0.0.239

package/src/finance.service.ts

@@ -6,7 +6,7 @@ import {
     BadRequestException,
     Injectable,
     Logger,
-    NotFoundException
+    NotFoundException,
 } from '@nestjs/common';
 import { CreateBankAccountDto } from './dto/create-bank-account.dto';
 import { CreateCostCenterDto } from './dto/create-cost-center.dto';
@@ -15,11 +15,28 @@ import { CreateFinanceTagDto } from './dto/create-finance-tag.dto';
 import { CreateFinancialTitleDto } from './dto/create-financial-title.dto';
 import { CreatePeriodCloseDto } from './dto/create-period-close.dto';
 import { MoveFinanceCategoryDto } from './dto/move-finance-category.dto';
+import { RejectTitleDto } from './dto/reject-title.dto';
+import { ReverseSettlementDto } from './dto/reverse-settlement.dto';
+import { SettleInstallmentDto } from './dto/settle-installment.dto';
 import { UpdateBankAccountDto } from './dto/update-bank-account.dto';
 import { UpdateCostCenterDto } from './dto/update-cost-center.dto';
 import { UpdateFinanceCategoryDto } from './dto/update-finance-category.dto';
 
 type TitleType = 'payable' | 'receivable';
+type InstallmentStatus =
+  | 'open'
+  | 'partial'
+  | 'settled'
+  | 'canceled'
+  | 'overdue';
+type TitleStatus =
+  | 'draft'
+  | 'approved'
+  | 'open'
+  | 'partial'
+  | 'settled'
+  | 'canceled'
+  | 'overdue';
 
 @Injectable()
 export class FinanceService {
@@ -756,6 +773,18 @@ export class FinanceService {
       this.logger.error('Failed to load finance audit logs', auditLogsResult.reason);
     }
 
+    const aprovacoesPendentes = payables
+      .filter((title: any) => title.status === 'rascunho')
+      .map((title: any) => ({
+        id: String(title.id),
+        tituloId: String(title.id),
+        solicitante: '-',
+        valor: Number(title.valorTotal || 0),
+        politica: 'Aprovação financeira',
+        urgencia: 'media',
+        dataSolicitacao: title.criadoEm,
+      }));
+
     return {
       kpis: {
         saldoCaixa: 0,
@@ -773,7 +802,7 @@ export class FinanceService {
       pessoas: people,
       categorias: categories,
       centrosCusto: costCenters,
-      aprovacoesPendentes: [],
+      aprovacoesPendentes,
       agingInadimplencia: [],
       cenarios: [],
       transferencias: [],
@@ -819,6 +848,45 @@ export class FinanceService {
     return this.createTitle(data, 'payable', locale, userId);
   }
 
+  async approveAccountsPayableTitle(id: number, locale: string, userId?: number) {
+    return this.approveTitle(id, 'payable', locale, userId);
+  }
+
+  async rejectAccountsPayableTitle(
+    id: number,
+    data: RejectTitleDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.rejectTitle(id, data, 'payable', locale, userId);
+  }
+
+  async settleAccountsPayableInstallment(
+    id: number,
+    data: SettleInstallmentDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.settleTitleInstallment(id, data, 'payable', locale, userId);
+  }
+
+  async reverseAccountsPayableSettlement(
+    id: number,
+    settlementId: number,
+    data: ReverseSettlementDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.reverseTitleSettlement(
+      id,
+      settlementId,
+      data,
+      'payable',
+      locale,
+      userId,
+    );
+  }
+
   async createAccountsReceivableTitle(
     data: CreateFinancialTitleDto,
     locale: string,
@@ -827,6 +895,40 @@ export class FinanceService {
     return this.createTitle(data, 'receivable', locale, userId);
   }
 
+  async approveAccountsReceivableTitle(
+    id: number,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.approveTitle(id, 'receivable', locale, userId);
+  }
+
+  async settleAccountsReceivableInstallment(
+    id: number,
+    data: SettleInstallmentDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.settleTitleInstallment(id, data, 'receivable', locale, userId);
+  }
+
+  async reverseAccountsReceivableSettlement(
+    id: number,
+    settlementId: number,
+    data: ReverseSettlementDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.reverseTitleSettlement(
+      id,
+      settlementId,
+      data,
+      'receivable',
+      locale,
+      userId,
+    );
+  }
+
   async createTag(data: CreateFinanceTagDto) {
     const slug = this.normalizeTagSlug(data.name);
 
@@ -1529,137 +1631,741 @@ export class FinanceService {
     locale: string,
     userId?: number,
   ) {
-    const person = await this.prisma.person.findUnique({
-      where: { id: data.person_id },
-      select: { id: true },
-    });
+    const installments = this.normalizeAndValidateInstallments(data, locale);
 
-    if (!person) {
-      throw new BadRequestException(
-        getLocaleText('personNotFound', locale, 'Person not found'),
-      );
-    }
-
-    if (data.finance_category_id) {
-      const category = await this.prisma.finance_category.findUnique({
-        where: { id: data.finance_category_id },
+    const createdTitleId = await this.prisma.$transaction(async (tx) => {
+      const person = await tx.person.findUnique({
+        where: { id: data.person_id },
         select: { id: true },
       });
 
-      if (!category) {
+      if (!person) {
         throw new BadRequestException(
-          getLocaleText('categoryNotFound', locale, 'Category not found'),
+          getLocaleText('personNotFound', locale, 'Person not found'),
         );
       }
-    }
 
-    if (data.cost_center_id) {
-      const costCenter = await this.prisma.cost_center.findUnique({
-        where: { id: data.cost_center_id },
-        select: { id: true },
-      });
+      if (data.finance_category_id) {
+        const category = await tx.finance_category.findUnique({
+          where: { id: data.finance_category_id },
+          select: { id: true },
+        });
 
-      if (!costCenter) {
-        throw new BadRequestException(
-          getLocaleText('costCenterNotFound', locale, 'Cost center not found'),
+        if (!category) {
+          throw new BadRequestException(
+            getLocaleText('categoryNotFound', locale, 'Category not found'),
+          );
+        }
+      }
+
+      if (data.cost_center_id) {
+        const costCenter = await tx.cost_center.findUnique({
+          where: { id: data.cost_center_id },
+          select: { id: true },
+        });
+
+        if (!costCenter) {
+          throw new BadRequestException(
+            getLocaleText('costCenterNotFound', locale, 'Cost center not found'),
+          );
+        }
+      }
+
+      const attachmentFileIds = [
+        ...new Set((data.attachment_file_ids || []).filter((fileId) => fileId > 0)),
+      ];
+
+      if (attachmentFileIds.length > 0) {
+        const existingFiles = await tx.file.findMany({
+          where: {
+            id: { in: attachmentFileIds },
+          },
+          select: {
+            id: true,
+          },
+        });
+
+        const existingFileIds = new Set(existingFiles.map((file) => file.id));
+        const invalidFileIds = attachmentFileIds.filter(
+          (fileId) => !existingFileIds.has(fileId),
         );
+
+        if (invalidFileIds.length > 0) {
+          throw new BadRequestException(
+            `Invalid attachment file IDs: ${invalidFileIds.join(', ')}`,
+          );
+        }
       }
-    }
 
-    const installments =
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        data.competence_date
+          ? new Date(data.competence_date)
+          : new Date(installments[0].due_date),
+        'create title',
+      );
+
+      const title = await tx.financial_title.create({
+        data: {
+          person_id: data.person_id,
+          title_type: titleType,
+          status: 'draft',
+          document_number: data.document_number,
+          description: data.description,
+          competence_date: data.competence_date
+            ? new Date(data.competence_date)
+            : null,
+          issue_date: data.issue_date ? new Date(data.issue_date) : null,
+          total_amount_cents: this.toCents(data.total_amount),
+          finance_category_id: data.finance_category_id,
+          created_by_user_id: userId,
+        },
+      });
+
+      if (attachmentFileIds.length > 0) {
+        await tx.financial_title_attachment.createMany({
+          data: attachmentFileIds.map((fileId) => ({
+            title_id: title.id,
+            file_id: fileId,
+            uploaded_by_user_id: userId,
+          })),
+        });
+      }
+
+      for (let index = 0; index < installments.length; index++) {
+        const installment = installments[index];
+        const amountCents = installment.amount_cents;
+
+        const createdInstallment = await tx.financial_installment.create({
+          data: {
+            title_id: title.id,
+            installment_number: installment.installment_number,
+            competence_date: data.competence_date
+              ? new Date(data.competence_date)
+              : new Date(installment.due_date),
+            due_date: new Date(installment.due_date),
+            amount_cents: amountCents,
+            open_amount_cents: amountCents,
+            status: this.resolveInstallmentStatus(
+              amountCents,
+              amountCents,
+              new Date(installment.due_date),
+            ),
+            notes: data.description,
+          },
+        });
+
+        if (data.cost_center_id) {
+          await tx.installment_allocation.create({
+            data: {
+              installment_id: createdInstallment.id,
+              cost_center_id: data.cost_center_id,
+              allocated_amount_cents: amountCents,
+            },
+          });
+        }
+      }
+
+      await this.createAuditLog(tx, {
+        action: 'CREATE_TITLE',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Created ${titleType} title ${title.id} in draft`,
+        afterData: JSON.stringify({
+          status: 'draft',
+          total_amount_cents: this.toCents(data.total_amount),
+        }),
+      });
+
+      return title.id;
+    });
+
+    const createdTitle = await this.getTitleById(createdTitleId, titleType, locale);
+    return this.mapTitleToFront(createdTitle, data.payment_channel);
+  }
+
+  private normalizeAndValidateInstallments(
+    data: CreateFinancialTitleDto,
+    locale: string,
+  ) {
+    const fallbackDueDate = data.due_date;
+    const totalAmountCents = this.toCents(data.total_amount);
+    const sourceInstallments =
       data.installments && data.installments.length > 0
         ? data.installments
         : [
             {
               installment_number: 1,
-              due_date: data.due_date,
+              due_date: fallbackDueDate,
               amount: data.total_amount,
             },
           ];
 
-    const title = await this.prisma.financial_title.create({
-      data: {
-        person_id: data.person_id,
-        title_type: titleType,
-        status: 'open',
-        document_number: data.document_number,
-        description: data.description,
-        competence_date: data.competence_date
-          ? new Date(data.competence_date)
-          : null,
-        issue_date: data.issue_date ? new Date(data.issue_date) : null,
-        total_amount_cents: this.toCents(data.total_amount),
-        finance_category_id: data.finance_category_id,
-        created_by_user_id: userId,
+    const normalizedInstallments = sourceInstallments.map(
+      (installment, index) => {
+        const installmentDueDate = installment.due_date || fallbackDueDate;
+
+        if (!installmentDueDate) {
+          throw new BadRequestException(
+            getLocaleText(
+              'installmentDueDateRequired',
+              locale,
+              'Installment due date is required',
+            ),
+          );
+        }
+
+        const amountCents = this.toCents(installment.amount);
+
+        if (amountCents <= 0) {
+          throw new BadRequestException(
+            getLocaleText(
+              'installmentAmountInvalid',
+              locale,
+              'Installment amount must be greater than zero',
+            ),
+          );
+        }
+
+        return {
+          installment_number: installment.installment_number || index + 1,
+          due_date: installmentDueDate,
+          amount_cents: amountCents,
+        };
       },
+    );
+
+    const installmentsTotalCents = normalizedInstallments.reduce(
+      (acc, installment) => acc + installment.amount_cents,
+      0,
+    );
+
+    if (installmentsTotalCents !== totalAmountCents) {
+      throw new BadRequestException(
+        getLocaleText(
+          'installmentsTotalMismatch',
+          locale,
+          'Installments total must be equal to title total amount',
+        ),
+      );
+    }
+
+    return normalizedInstallments;
+  }
+
+  private async approveTitle(
+    titleId: number,
+    titleType: TitleType,
+    locale: string,
+    userId?: number,
+  ) {
+    const updatedTitle = await this.prisma.$transaction(async (tx) => {
+      const title = await tx.financial_title.findFirst({
+        where: {
+          id: titleId,
+          title_type: titleType,
+        },
+        select: {
+          id: true,
+          status: true,
+          competence_date: true,
+        },
+      });
+
+      if (!title) {
+        throw new NotFoundException(
+          getLocaleText(
+            'itemNotFound',
+            locale,
+            `Financial title with ID ${titleId} not found`,
+          ).replace('{{item}}', 'Financial title'),
+        );
+      }
+
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        title.competence_date,
+        'approve title',
+      );
+
+      if (title.status !== 'draft') {
+        throw new BadRequestException('Only draft titles can be approved');
+      }
+
+      await tx.financial_title.update({
+        where: { id: title.id },
+        data: {
+          status: 'approved',
+        },
+      });
+
+      await this.createAuditLog(tx, {
+        action: 'APPROVE_TITLE',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Approved ${titleType} title ${title.id}`,
+        beforeData: JSON.stringify({ status: title.status }),
+        afterData: JSON.stringify({ status: 'approved' }),
+      });
+
+      return tx.financial_title.findFirst({
+        where: {
+          id: title.id,
+          title_type: titleType,
+        },
+        include: this.defaultTitleInclude(),
+      });
     });
 
-    const attachmentFileIds = [
-      ...new Set((data.attachment_file_ids || []).filter((fileId) => fileId > 0)),
-    ];
+    if (!updatedTitle) {
+      throw new NotFoundException('Financial title not found');
+    }
+
+    return this.mapTitleToFront(updatedTitle);
+  }
 
-    if (attachmentFileIds.length > 0) {
-      const existingFiles = await this.prisma.file.findMany({
+  private async rejectTitle(
+    titleId: number,
+    data: RejectTitleDto,
+    titleType: TitleType,
+    locale: string,
+    userId?: number,
+  ) {
+    const updatedTitle = await this.prisma.$transaction(async (tx) => {
+      const title = await tx.financial_title.findFirst({
         where: {
-          id: { in: attachmentFileIds },
+          id: titleId,
+          title_type: titleType,
         },
         select: {
           id: true,
+          status: true,
+          competence_date: true,
         },
       });
 
-      const existingFileIds = new Set(existingFiles.map((file) => file.id));
-      const invalidFileIds = attachmentFileIds.filter(
-        (fileId) => !existingFileIds.has(fileId),
+      if (!title) {
+        throw new NotFoundException(
+          getLocaleText(
+            'itemNotFound',
+            locale,
+            `Financial title with ID ${titleId} not found`,
+          ).replace('{{item}}', 'Financial title'),
+        );
+      }
+
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        title.competence_date,
+        'reject title',
       );
 
-      if (invalidFileIds.length > 0) {
+      if (title.status !== 'draft') {
+        throw new BadRequestException('Only draft titles can be rejected');
+      }
+
+      await tx.financial_title.update({
+        where: { id: title.id },
+        data: {
+          status: 'canceled',
+        },
+      });
+
+      await this.createAuditLog(tx, {
+        action: 'REJECT_TITLE',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Rejected ${titleType} title ${title.id}`,
+        beforeData: JSON.stringify({ status: title.status }),
+        afterData: JSON.stringify({
+          status: 'canceled',
+          reason: data?.reason || null,
+        }),
+      });
+
+      return tx.financial_title.findFirst({
+        where: {
+          id: title.id,
+          title_type: titleType,
+        },
+        include: this.defaultTitleInclude(),
+      });
+    });
+
+    if (!updatedTitle) {
+      throw new NotFoundException('Financial title not found');
+    }
+
+    return this.mapTitleToFront(updatedTitle);
+  }
+
+  private async settleTitleInstallment(
+    titleId: number,
+    data: SettleInstallmentDto,
+    titleType: TitleType,
+    locale: string,
+    userId?: number,
+  ) {
+    const amountCents = this.toCents(data.amount);
+
+    if (amountCents <= 0) {
+      throw new BadRequestException('Settlement amount must be greater than zero');
+    }
+
+    const settledAt = data.settled_at ? new Date(data.settled_at) : new Date();
+    if (Number.isNaN(settledAt.getTime())) {
+      throw new BadRequestException('Invalid settlement date');
+    }
+
+    const result = await this.prisma.$transaction(async (tx) => {
+      const title = await tx.financial_title.findFirst({
+        where: {
+          id: titleId,
+          title_type: titleType,
+        },
+        select: {
+          id: true,
+          person_id: true,
+          status: true,
+          competence_date: true,
+        },
+      });
+
+      if (!title) {
+        throw new NotFoundException(
+          getLocaleText(
+            'itemNotFound',
+            locale,
+            `Financial title with ID ${titleId} not found`,
+          ).replace('{{item}}', 'Financial title'),
+        );
+      }
+
+      if (!['approved', 'open', 'partial'].includes(title.status)) {
         throw new BadRequestException(
-          `Invalid attachment file IDs: ${invalidFileIds.join(', ')}`,
+          'Only approved/open/partial titles can be settled',
         );
       }
 
-      await this.prisma.financial_title_attachment.createMany({
-        data: attachmentFileIds.map((fileId) => ({
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        title.competence_date,
+        'settle installment',
+      );
+
+      const installment = await tx.financial_installment.findFirst({
+        where: {
+          id: data.installment_id,
           title_id: title.id,
-          file_id: fileId,
-          uploaded_by_user_id: userId,
-        })),
+        },
+        select: {
+          id: true,
+          title_id: true,
+          amount_cents: true,
+          open_amount_cents: true,
+          due_date: true,
+          status: true,
+        },
       });
-    }
 
-    for (let index = 0; index < installments.length; index++) {
-      const installment = installments[index];
-      const amountCents = this.toCents(installment.amount);
+      if (!installment) {
+        throw new BadRequestException('Installment not found for this title');
+      }
+
+      if (installment.status === 'settled' || installment.status === 'canceled') {
+        throw new BadRequestException('This installment cannot be settled');
+      }
+
+      if (amountCents > installment.open_amount_cents) {
+        throw new BadRequestException('Settlement amount exceeds open amount');
+      }
+
+      const paymentMethodId = await this.resolvePaymentMethodId(
+        tx,
+        data.payment_channel,
+      );
 
-      const createdInstallment = await this.prisma.financial_installment.create({
+      const settlement = await tx.settlement.create({
         data: {
-          title_id: title.id,
-          installment_number: installment.installment_number || index + 1,
-          competence_date: data.competence_date
-            ? new Date(data.competence_date)
-            : new Date(installment.due_date),
-          due_date: new Date(installment.due_date),
+          person_id: title.person_id,
+          bank_account_id: data.bank_account_id || null,
+          payment_method_id: paymentMethodId,
+          settlement_type: titleType,
+          status: 'confirmed',
+          settled_at: settledAt,
           amount_cents: amountCents,
-          open_amount_cents: amountCents,
-          status: 'open',
-          notes: data.description,
+          description: data.description?.trim() || null,
+          created_by_user_id: userId,
         },
       });
 
-      if (data.cost_center_id) {
-        await this.prisma.installment_allocation.create({
+      await tx.settlement_allocation.create({
+        data: {
+          settlement_id: settlement.id,
+          installment_id: installment.id,
+          allocated_amount_cents: amountCents,
+          discount_cents: this.toCents(data.discount || 0),
+          interest_cents: this.toCents(data.interest || 0),
+          penalty_cents: this.toCents(data.penalty || 0),
+        },
+      });
+
+      const decrementResult = await tx.financial_installment.updateMany({
+        where: {
+          id: installment.id,
+          open_amount_cents: {
+            gte: amountCents,
+          },
+        },
+        data: {
+          open_amount_cents: {
+            decrement: amountCents,
+          },
+        },
+      });
+
+      if (decrementResult.count !== 1) {
+        throw new BadRequestException(
+          'Installment was updated concurrently, please try again',
+        );
+      }
+
+      const updatedInstallment = await tx.financial_installment.findUnique({
+        where: {
+          id: installment.id,
+        },
+        select: {
+          id: true,
+          amount_cents: true,
+          open_amount_cents: true,
+          due_date: true,
+          status: true,
+        },
+      });
+
+      if (!updatedInstallment) {
+        throw new NotFoundException('Installment not found');
+      }
+
+      const nextInstallmentStatus = this.resolveInstallmentStatus(
+        updatedInstallment.amount_cents,
+        updatedInstallment.open_amount_cents,
+        updatedInstallment.due_date,
+      );
+
+      if (updatedInstallment.status !== nextInstallmentStatus) {
+        await tx.financial_installment.update({
+          where: {
+            id: updatedInstallment.id,
+          },
+          data: {
+            status: nextInstallmentStatus,
+          },
+        });
+      }
+
+      const previousTitleStatus = title.status;
+      const nextTitleStatus = await this.recalculateTitleStatus(tx, title.id);
+
+      await this.createAuditLog(tx, {
+        action: 'SETTLE_INSTALLMENT',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Settled installment ${installment.id} of title ${title.id}`,
+        beforeData: JSON.stringify({
+          title_status: previousTitleStatus,
+          installment_open_amount_cents: installment.open_amount_cents,
+        }),
+        afterData: JSON.stringify({
+          title_status: nextTitleStatus,
+          installment_open_amount_cents: updatedInstallment.open_amount_cents,
+          settlement_id: settlement.id,
+        }),
+      });
+
+      const updatedTitle = await tx.financial_title.findFirst({
+        where: {
+          id: title.id,
+          title_type: titleType,
+        },
+        include: this.defaultTitleInclude(),
+      });
+
+      if (!updatedTitle) {
+        throw new NotFoundException('Financial title not found');
+      }
+
+      return {
+        title: updatedTitle,
+        settlementId: settlement.id,
+      };
+    });
+
+    return {
+      ...this.mapTitleToFront(result.title),
+      settlementId: String(result.settlementId),
+    };
+  }
+
+  private async reverseTitleSettlement(
+    titleId: number,
+    settlementId: number,
+    data: ReverseSettlementDto,
+    titleType: TitleType,
+    locale: string,
+    userId?: number,
+  ) {
+    const updatedTitle = await this.prisma.$transaction(async (tx) => {
+      const title = await tx.financial_title.findFirst({
+        where: {
+          id: titleId,
+          title_type: titleType,
+        },
+        select: {
+          id: true,
+          status: true,
+          competence_date: true,
+        },
+      });
+
+      if (!title) {
+        throw new NotFoundException(
+          getLocaleText(
+            'itemNotFound',
+            locale,
+            `Financial title with ID ${titleId} not found`,
+          ).replace('{{item}}', 'Financial title'),
+        );
+      }
+
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        title.competence_date,
+        'reverse settlement',
+      );
+
+      const settlement = await tx.settlement.findFirst({
+        where: {
+          id: settlementId,
+          settlement_type: titleType,
+          settlement_allocation: {
+            some: {
+              financial_installment: {
+                title_id: title.id,
+              },
+            },
+          },
+        },
+        include: {
+          settlement_allocation: {
+            include: {
+              financial_installment: {
+                select: {
+                  id: true,
+                  amount_cents: true,
+                  open_amount_cents: true,
+                  due_date: true,
+                  status: true,
+                },
+              },
+            },
+          },
+        },
+      });
+
+      if (!settlement) {
+        throw new NotFoundException('Settlement not found for this title');
+      }
+
+      if (settlement.status === 'reversed') {
+        throw new BadRequestException('This settlement is already reversed');
+      }
+
+      for (const allocation of settlement.settlement_allocation) {
+        const installment = allocation.financial_installment;
+
+        if (!installment) {
+          continue;
+        }
+
+        const nextOpenAmountCents =
+          installment.open_amount_cents + allocation.allocated_amount_cents;
+
+        if (nextOpenAmountCents > installment.amount_cents) {
+          throw new BadRequestException(
+            `Reverse would exceed installment amount for installment ${installment.id}`,
+          );
+        }
+
+        const nextInstallmentStatus = this.resolveInstallmentStatus(
+          installment.amount_cents,
+          nextOpenAmountCents,
+          installment.due_date,
+        );
+
+        await tx.financial_installment.update({
+          where: {
+            id: installment.id,
+          },
           data: {
-            installment_id: createdInstallment.id,
-            cost_center_id: data.cost_center_id,
-            allocated_amount_cents: amountCents,
+            open_amount_cents: nextOpenAmountCents,
+            status: nextInstallmentStatus,
           },
         });
       }
+
+      await tx.settlement.update({
+        where: {
+          id: settlement.id,
+        },
+        data: {
+          status: 'reversed',
+          description: [
+            settlement.description,
+            data.reason ? `Reversed: ${data.reason.trim()}` : 'Reversed',
+          ]
+            .filter(Boolean)
+            .join(' | '),
+        },
+      });
+
+      const previousTitleStatus = title.status;
+      const nextTitleStatus = await this.recalculateTitleStatus(tx, title.id);
+
+      await this.createAuditLog(tx, {
+        action: 'REVERSE_SETTLEMENT',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Reversed settlement ${settlement.id} from title ${title.id}`,
+        beforeData: JSON.stringify({
+          title_status: previousTitleStatus,
+          settlement_status: settlement.status,
+        }),
+        afterData: JSON.stringify({
+          title_status: nextTitleStatus,
+          settlement_status: 'reversed',
+        }),
+      });
+
+      return tx.financial_title.findFirst({
+        where: {
+          id: title.id,
+          title_type: titleType,
+        },
+        include: this.defaultTitleInclude(),
+      });
+    });
+
+    if (!updatedTitle) {
+      throw new NotFoundException('Financial title not found');
     }
 
-    const createdTitle = await this.getTitleById(title.id, titleType, locale);
-    return this.mapTitleToFront(createdTitle, data.payment_channel);
+    return this.mapTitleToFront(updatedTitle);
   }
 
   private async updateTitleTags(
@@ -1853,6 +2559,189 @@ export class FinanceService {
     }));
   }
 
+  private async resolvePaymentMethodId(tx: any, paymentChannel?: string) {
+    const paymentType = this.mapPaymentMethodFromPt(paymentChannel);
+
+    if (!paymentType) {
+      return null;
+    }
+
+    const paymentMethod = await tx.payment_method.findFirst({
+      where: {
+        type: paymentType,
+        status: 'active',
+      },
+      select: {
+        id: true,
+      },
+    });
+
+    return paymentMethod?.id || null;
+  }
+
+  private async assertDateNotInClosedPeriod(
+    tx: any,
+    competenceDate: Date | null | undefined,
+    operation: string,
+  ) {
+    if (!competenceDate) {
+      return;
+    }
+
+    const closedPeriod = await tx.period_close.findFirst({
+      where: {
+        status: 'closed',
+        period_start: {
+          lte: competenceDate,
+        },
+        period_end: {
+          gte: competenceDate,
+        },
+      },
+      select: {
+        id: true,
+      },
+    });
+
+    if (closedPeriod) {
+      throw new BadRequestException(
+        `Cannot ${operation}: competence is in a closed period`,
+      );
+    }
+  }
+
+  private resolveInstallmentStatus(
+    amountCents: number,
+    openAmountCents: number,
+    dueDate: Date,
+    currentStatus?: string,
+  ): InstallmentStatus {
+    if (currentStatus === 'canceled') {
+      return 'canceled';
+    }
+
+    if (openAmountCents <= 0) {
+      return 'settled';
+    }
+
+    if (openAmountCents < amountCents) {
+      return 'partial';
+    }
+
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    const dueDateOnly = new Date(dueDate);
+    dueDateOnly.setHours(0, 0, 0, 0);
+
+    if (dueDateOnly < today) {
+      return 'overdue';
+    }
+
+    return 'open';
+  }
+
+  private deriveTitleStatusFromInstallments(
+    installments: Array<{
+      amount_cents: number;
+      open_amount_cents: number;
+      due_date: Date;
+      status?: string;
+    }>,
+  ): TitleStatus {
+    if (installments.length === 0) {
+      return 'open';
+    }
+
+    const effectiveStatuses = installments.map((installment) =>
+      this.resolveInstallmentStatus(
+        installment.amount_cents,
+        installment.open_amount_cents,
+        installment.due_date,
+        installment.status,
+      ),
+    );
+
+    if (effectiveStatuses.every((status) => status === 'settled')) {
+      return 'settled';
+    }
+
+    const hasPayment = installments.some(
+      (installment) => installment.open_amount_cents < installment.amount_cents,
+    );
+
+    if (hasPayment) {
+      return 'partial';
+    }
+
+    return 'open';
+  }
+
+  private async recalculateTitleStatus(tx: any, titleId: number): Promise<TitleStatus> {
+    const title = await tx.financial_title.findUnique({
+      where: {
+        id: titleId,
+      },
+      select: {
+        id: true,
+        status: true,
+        financial_installment: {
+          select: {
+            amount_cents: true,
+            open_amount_cents: true,
+            due_date: true,
+            status: true,
+          },
+        },
+      },
+    });
+
+    if (!title) {
+      throw new NotFoundException('Financial title not found');
+    }
+
+    const nextStatus = this.deriveTitleStatusFromInstallments(
+      title.financial_installment,
+    );
+
+    if (title.status !== nextStatus) {
+      await tx.financial_title.update({
+        where: {
+          id: title.id,
+        },
+        data: {
+          status: nextStatus,
+        },
+      });
+    }
+
+    return nextStatus;
+  }
+
+  private async createAuditLog(
+    tx: any,
+    data: {
+      actorUserId?: number;
+      action: string;
+      entityTable: string;
+      entityId: string;
+      summary?: string;
+      beforeData?: string;
+      afterData?: string;
+    },
+  ) {
+    await tx.audit_log.create({
+      data: {
+        actor_user_id: data.actorUserId || null,
+        action: data.action,
+        entity_table: data.entityTable,
+        entity_id: data.entityId,
+        summary: data.summary || null,
+        before_data: data.beforeData || null,
+        after_data: data.afterData || null,
+      },
+    });
+  }
+
   private mapTitleToFront(title: any, paymentChannelOverride?: string) {
     const allocations = title.financial_installment.flatMap(
       (installment) => installment.installment_allocation,
@@ -1877,13 +2766,24 @@ export class FinanceService {
       numero: installment.installment_number,
       vencimento: installment.due_date.toISOString(),
       valor: this.fromCents(installment.amount_cents),
-      status: this.mapStatusToPt(installment.status),
+      valorAberto: this.fromCents(installment.open_amount_cents),
+      status: this.mapStatusToPt(
+        this.resolveInstallmentStatus(
+          installment.amount_cents,
+          installment.open_amount_cents,
+          installment.due_date,
+          installment.status,
+        ),
+      ),
       metodoPagamento:
         this.mapPaymentMethodToPt(
           installment.settlement_allocation[0]?.settlement?.payment_method?.type,
         ) || paymentChannelOverride || 'transferencia',
       liquidacoes: installment.settlement_allocation.map((allocation) => ({
         id: String(allocation.id),
+        settlementId: allocation.settlement?.id
+          ? String(allocation.settlement.id)
+          : null,
         data: allocation.settlement?.settled_at?.toISOString(),
         valor: this.fromCents(allocation.allocated_amount_cents),
         juros: this.fromCents(allocation.interest_cents || 0),
@@ -1892,6 +2792,7 @@ export class FinanceService {
         contaBancariaId: allocation.settlement?.bank_account_id
           ? String(allocation.settlement.bank_account_id)
           : null,
+        status: allocation.settlement?.status || null,
         metodo:
           this.mapPaymentMethodToPt(
             allocation.settlement?.payment_method?.type,
@@ -2006,7 +2907,7 @@ export class FinanceService {
   }
 
   private mapPaymentMethodToPt(paymentMethodType?: string | null) {
-    const paymentMethodMap = {
+    const paymentMethodMap: Record<string, string> = {
       boleto: 'boleto',
       pix: 'pix',
       ted: 'transferencia',
@@ -2019,6 +2920,30 @@ export class FinanceService {
     return paymentMethodMap[paymentMethodType] || undefined;
   }
 
+  private mapPaymentMethodFromPt(paymentMethodType?: string | null) {
+    if (!paymentMethodType) {
+      return undefined;
+    }
+
+    const paymentMethodMap = {
+      boleto: 'boleto',
+      pix: 'pix',
+      transferencia: 'ted',
+      transferência: 'ted',
+      ted: 'ted',
+      doc: 'doc',
+      cartao: 'card',
+      cartão: 'card',
+      dinheiro: 'cash',
+      cheque: 'other',
+      cash: 'cash',
+      card: 'card',
+      other: 'other',
+    };
+
+    return paymentMethodMap[(paymentMethodType || '').toLowerCase()];
+  }
+
   private mapAccountTypeToPt(accountType?: string | null) {
     const accountTypeMap = {
       checking: 'corrente',