@hed-hog/finance 0.0.238 → 0.0.240

package/src/finance.service.ts

@@ -1,13 +1,17 @@
 import { getLocaleText } from '@hed-hog/api-locale';
 import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
 import { PrismaService } from '@hed-hog/api-prisma';
-import { AiService } from '@hed-hog/core';
+import { AiService, FileService } from '@hed-hog/core';
 import {
-    BadRequestException,
-    Injectable,
-    Logger,
-    NotFoundException
+  BadRequestException,
+  forwardRef,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
 } from '@nestjs/common';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import { CreateBankAccountDto } from './dto/create-bank-account.dto';
 import { CreateCostCenterDto } from './dto/create-cost-center.dto';
 import { CreateFinanceCategoryDto } from './dto/create-finance-category.dto';
@@ -15,11 +19,27 @@ 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'
+  | 'open'
+  | 'partial'
+  | 'settled'
+  | 'canceled'
+  | 'overdue';
 
 @Injectable()
 export class FinanceService {
@@ -29,6 +49,8 @@ export class FinanceService {
     private readonly prisma: PrismaService,
     private readonly paginationService: PaginationService,
     private readonly ai: AiService,
+    @Inject(forwardRef(() => FileService))
+    private readonly fileService: FileService,
   ) {}
 
   async getAgentExtractInfoFromFile(
@@ -756,6 +778,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 +807,7 @@ export class FinanceService {
       pessoas: people,
       categorias: categories,
       centrosCusto: costCenters,
-      aprovacoesPendentes: [],
+      aprovacoesPendentes,
       agingInadimplencia: [],
       cenarios: [],
       transferencias: [],
@@ -819,6 +853,63 @@ export class FinanceService {
     return this.createTitle(data, 'payable', locale, userId);
   }
 
+  async updateAccountsPayableTitle(
+    id: number,
+    data: CreateFinancialTitleDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.updateDraftTitle(id, 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 cancelAccountsPayableTitle(
+    id: number,
+    data: RejectTitleDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.cancelTitle(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 +918,58 @@ export class FinanceService {
     return this.createTitle(data, 'receivable', locale, userId);
   }
 
+  async updateAccountsReceivableTitle(
+    id: number,
+    data: CreateFinancialTitleDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.updateDraftTitle(id, data, 'receivable', locale, userId);
+  }
+
+  async approveAccountsReceivableTitle(
+    id: number,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.approveTitle(id, 'receivable', locale, userId);
+  }
+
+  async cancelAccountsReceivableTitle(
+    id: number,
+    data: RejectTitleDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.cancelTitle(id, data, '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);
 
@@ -1146,6 +1289,497 @@ export class FinanceService {
     }));
   }
 
+  async exportBankStatementsCsv(bankAccountId: number) {
+    const statements = await this.listBankStatements(bankAccountId);
+
+    const headers = [
+      'id',
+      'data',
+      'descricao',
+      'valor',
+      'tipo',
+      'status_conciliacao',
+      'conta_bancaria_id',
+    ];
+
+    const lines = statements.map((statement) => {
+      const columns = [
+        statement.id,
+        statement.data,
+        statement.descricao,
+        String(statement.valor),
+        statement.tipo,
+        statement.statusConciliacao,
+        statement.contaBancariaId,
+      ];
+
+      return columns.map((column) => this.escapeCsvCell(column)).join(';');
+    });
+
+    const csv = ['\uFEFF' + headers.join(';'), ...lines].join('\n');
+    const fileName = `extrato-bancario-${bankAccountId}-${new Date()
+      .toISOString()
+      .slice(0, 10)}.csv`;
+
+    return {
+      csv,
+      fileName,
+    };
+  }
+
+  async importBankStatements(
+    bankAccountId: number,
+    file: MulterFile,
+    locale: string,
+    userId?: number,
+  ) {
+    if (!file) {
+      throw new BadRequestException('File is required');
+    }
+
+    const bankAccount = await this.prisma.bank_account.findUnique({
+      where: { id: bankAccountId },
+      select: { id: true },
+    });
+
+    if (!bankAccount) {
+      throw new NotFoundException(
+        getLocaleText('itemNotFound', locale, 'Bank account not found').replace(
+          '{{item}}',
+          'Bank account',
+        ),
+      );
+    }
+
+    const sourceType = this.detectStatementSourceType(file);
+    const uploadedFile = await this.fileService.upload('finance/statements', file);
+    const rawContent = await this.getUploadedFileText(file);
+    const parsedEntries =
+      sourceType === 'ofx'
+        ? this.parseOfxStatements(rawContent)
+        : this.parseCsvStatements(rawContent);
+
+    if (parsedEntries.length === 0) {
+      throw new BadRequestException(
+        'No valid statement rows were found in the uploaded file',
+      );
+    }
+
+    const normalizedEntries = parsedEntries
+      .filter((entry) => entry.postedDate && Number.isFinite(entry.amount))
+      .map((entry, index) => {
+        const postedDate = new Date(entry.postedDate);
+
+        if (Number.isNaN(postedDate.getTime())) {
+          return null;
+        }
+
+        const amountCents = this.toCents(entry.amount);
+
+        if (!Number.isFinite(amountCents) || amountCents === 0) {
+          return null;
+        }
+
+        const dedupeBase = [
+          bankAccountId,
+          postedDate.toISOString().slice(0, 10),
+          amountCents,
+          entry.externalId || '',
+          entry.description || '',
+          index,
+        ].join('|');
+
+        return {
+          postedDate,
+          amountCents,
+          externalId: entry.externalId || null,
+          description: (entry.description || 'Lançamento importado').slice(
+            0,
+            1000,
+          ),
+          dedupeKey: this.createShortHash(`statement-line:${dedupeBase}`, 64),
+        };
+      })
+      .filter(Boolean) as Array<{
+      postedDate: Date;
+      amountCents: number;
+      externalId: string | null;
+      description: string;
+      dedupeKey: string;
+    }>;
+
+    if (normalizedEntries.length === 0) {
+      throw new BadRequestException('No valid financial entries were parsed');
+    }
+
+    const statementFingerprint = this.createShortHash(
+      [
+        bankAccountId,
+        sourceType,
+        uploadedFile.id,
+        file.originalname,
+        file.size,
+        normalizedEntries.length,
+      ].join('|'),
+      24,
+    );
+
+    const statement = await this.prisma.bank_statement.create({
+      data: {
+        bank_account_id: bankAccountId,
+        source_type: sourceType,
+        idempotency_key: `import-${uploadedFile.id}-${statementFingerprint}`,
+        period_start: normalizedEntries
+          .map((entry) => entry.postedDate)
+          .sort((a, b) => a.getTime() - b.getTime())[0],
+        period_end: normalizedEntries
+          .map((entry) => entry.postedDate)
+          .sort((a, b) => b.getTime() - a.getTime())[0],
+        imported_at: new Date(),
+        imported_by_user_id: userId || null,
+      },
+      select: { id: true },
+    });
+
+    await this.prisma.bank_statement_line.createMany({
+      data: normalizedEntries.map((entry) => ({
+        bank_statement_id: statement.id,
+        bank_account_id: bankAccountId,
+        external_id: entry.externalId,
+        posted_date: entry.postedDate,
+        amount_cents: entry.amountCents,
+        description: entry.description,
+        status: 'imported',
+        dedupe_key: entry.dedupeKey,
+      })),
+      skipDuplicates: true,
+    });
+
+    return {
+      statementId: String(statement.id),
+      fileId: String(uploadedFile.id),
+      importedRows: normalizedEntries.length,
+      sourceType,
+    };
+  }
+
+  private detectStatementSourceType(file: MulterFile): 'csv' | 'ofx' {
+    const filename = (file.originalname || '').toLowerCase();
+    const mimetype = (file.mimetype || '').toLowerCase();
+
+    if (
+      filename.endsWith('.ofx') ||
+      mimetype.includes('ofx') ||
+      mimetype.includes('x-ofx')
+    ) {
+      return 'ofx';
+    }
+
+    if (
+      filename.endsWith('.csv') ||
+      mimetype.includes('csv') ||
+      mimetype.includes('comma-separated-values')
+    ) {
+      return 'csv';
+    }
+
+    throw new BadRequestException('Only CSV and OFX files are supported');
+  }
+
+  private async getUploadedFileText(file: MulterFile): Promise<string> {
+    let buffer = file.buffer;
+
+    if (!buffer && file.path) {
+      buffer = await readFile(file.path);
+    }
+
+    if (!buffer || buffer.length === 0) {
+      throw new BadRequestException('Uploaded file is empty');
+    }
+
+    const utf8 = buffer.toString('utf8');
+    if (utf8.includes('�')) {
+      return buffer.toString('latin1');
+    }
+
+    return utf8;
+  }
+
+  private parseCsvStatements(content: string) {
+    const normalizedContent = content.replace(/^\uFEFF/, '').trim();
+
+    if (!normalizedContent) {
+      return [];
+    }
+
+    const rows = normalizedContent
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => !!line);
+
+    if (rows.length === 0) {
+      return [];
+    }
+
+    const delimiter = this.detectCsvDelimiter(rows[0]);
+    const headerCells = this.parseCsvLine(rows[0], delimiter);
+    const normalizedHeaders = headerCells.map((cell) =>
+      this.normalizeCsvHeader(cell),
+    );
+
+    const headerIndexes = {
+      date: this.findFirstHeaderIndex(normalizedHeaders, [
+        'data',
+        'dt',
+        'posteddate',
+        'lancamento',
+        'movimento',
+      ]),
+      description: this.findFirstHeaderIndex(normalizedHeaders, [
+        'descricao',
+        'historico',
+        'memo',
+        'complemento',
+      ]),
+      amount: this.findFirstHeaderIndex(normalizedHeaders, [
+        'valor',
+        'amount',
+        'montante',
+      ]),
+      debit: this.findFirstHeaderIndex(normalizedHeaders, ['debito', 'debit']),
+      credit: this.findFirstHeaderIndex(normalizedHeaders, [
+        'credito',
+        'credit',
+      ]),
+      externalId: this.findFirstHeaderIndex(normalizedHeaders, [
+        'id',
+        'documento',
+        'numero',
+        'fitid',
+      ]),
+    };
+
+    const hasHeader =
+      headerIndexes.date >= 0 ||
+      headerIndexes.description >= 0 ||
+      headerIndexes.amount >= 0 ||
+      headerIndexes.debit >= 0 ||
+      headerIndexes.credit >= 0;
+
+    const dataRows = hasHeader ? rows.slice(1) : rows;
+
+    return dataRows
+      .map((line) => this.parseCsvLine(line, delimiter))
+      .map((columns) => {
+        const dateRaw =
+          (headerIndexes.date >= 0
+            ? columns[headerIndexes.date]
+            : columns[0]) || '';
+        const descriptionRaw =
+          (headerIndexes.description >= 0
+            ? columns[headerIndexes.description]
+            : columns[1]) || '';
+        const amountRaw =
+          headerIndexes.amount >= 0 ? columns[headerIndexes.amount] : '';
+        const debitRaw =
+          headerIndexes.debit >= 0 ? columns[headerIndexes.debit] : '';
+        const creditRaw =
+          headerIndexes.credit >= 0 ? columns[headerIndexes.credit] : '';
+        const fallbackAmountRaw = columns[2] || '';
+        const externalIdRaw =
+          headerIndexes.externalId >= 0 ? columns[headerIndexes.externalId] : '';
+
+        const postedDate = this.parseStatementDate(dateRaw);
+        if (!postedDate) {
+          return null;
+        }
+
+        const amount = this.resolveCsvAmount(
+          amountRaw || fallbackAmountRaw,
+          debitRaw,
+          creditRaw,
+        );
+
+        if (amount === null) {
+          return null;
+        }
+
+        return {
+          postedDate,
+          amount,
+          description: descriptionRaw?.trim() || 'Movimentação importada',
+          externalId: externalIdRaw?.trim() || null,
+        };
+      })
+      .filter(Boolean) as Array<{
+      postedDate: string;
+      amount: number;
+      description: string;
+      externalId: string | null;
+    }>;
+  }
+
+  private parseOfxStatements(content: string) {
+    const normalized = content.replace(/\r/g, '');
+    const segments = normalized
+      .split(/<STMTTRN>/i)
+      .slice(1)
+      .map((segment) => segment.split(/<\/STMTTRN>/i)[0]);
+
+    return segments
+      .map((segment) => {
+        const dateRaw = this.extractOfxTag(segment, 'DTPOSTED');
+        const amountRaw = this.extractOfxTag(segment, 'TRNAMT');
+        const fitId = this.extractOfxTag(segment, 'FITID');
+        const memo = this.extractOfxTag(segment, 'MEMO');
+        const name = this.extractOfxTag(segment, 'NAME');
+        const trnType = this.extractOfxTag(segment, 'TRNTYPE')?.toLowerCase();
+
+        const postedDate = this.parseStatementDate(dateRaw);
+        const amount = this.toNullableNumber(amountRaw);
+
+        if (!postedDate || amount === null) {
+          return null;
+        }
+
+        let normalizedAmount = amount;
+        if (
+          ['debit', 'payment', 'withdrawal'].includes(trnType || '') &&
+          normalizedAmount > 0
+        ) {
+          normalizedAmount *= -1;
+        }
+
+        const description = [memo, name].filter(Boolean).join(' - ').trim();
+
+        return {
+          postedDate,
+          amount: normalizedAmount,
+          description: description || 'Movimentação OFX',
+          externalId: fitId || null,
+        };
+      })
+      .filter(Boolean) as Array<{
+      postedDate: string;
+      amount: number;
+      description: string;
+      externalId: string | null;
+    }>;
+  }
+
+  private detectCsvDelimiter(line: string) {
+    const delimiters = [';', ',', '\t'];
+    const counts = delimiters.map((delimiter) => ({
+      delimiter,
+      count: (line.match(new RegExp(`\\${delimiter}`, 'g')) || []).length,
+    }));
+
+    return counts.sort((a, b) => b.count - a.count)[0]?.delimiter || ';';
+  }
+
+  private parseCsvLine(line: string, delimiter: string) {
+    const result: string[] = [];
+    let current = '';
+    let inQuotes = false;
+
+    for (let i = 0; i < line.length; i++) {
+      const char = line[i];
+      const next = line[i + 1];
+
+      if (char === '"') {
+        if (inQuotes && next === '"') {
+          current += '"';
+          i++;
+        } else {
+          inQuotes = !inQuotes;
+        }
+        continue;
+      }
+
+      if (char === delimiter && !inQuotes) {
+        result.push(current.trim());
+        current = '';
+        continue;
+      }
+
+      current += char;
+    }
+
+    result.push(current.trim());
+    return result;
+  }
+
+  private normalizeCsvHeader(value: string) {
+    return String(value || '')
+      .normalize('NFD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]/g, '');
+  }
+
+  private findFirstHeaderIndex(headers: string[], candidates: string[]) {
+    return headers.findIndex((header) =>
+      candidates.some((candidate) => header.includes(candidate)),
+    );
+  }
+
+  private parseStatementDate(value?: string) {
+    const raw = String(value || '').trim();
+    if (!raw) {
+      return '';
+    }
+
+    const onlyDateDigits = raw.match(/^(\d{8})/);
+    if (onlyDateDigits?.[1]) {
+      const v = onlyDateDigits[1];
+      return `${v.slice(0, 4)}-${v.slice(4, 6)}-${v.slice(6, 8)}`;
+    }
+
+    const normalized = this.normalizeDate(raw);
+    if (normalized) {
+      return normalized;
+    }
+
+    return '';
+  }
+
+  private resolveCsvAmount(
+    amountRaw?: string,
+    debitRaw?: string,
+    creditRaw?: string,
+  ): number | null {
+    const amount = this.toNullableNumber(amountRaw);
+    const debit = this.toNullableNumber(debitRaw);
+    const credit = this.toNullableNumber(creditRaw);
+
+    if (credit !== null || debit !== null) {
+      return (credit || 0) - (debit || 0);
+    }
+
+    if (amount === null) {
+      return null;
+    }
+
+    return amount;
+  }
+
+  private extractOfxTag(segment: string, tag: string) {
+    const regex = new RegExp(`<${tag}>([^\n\r<]*)`, 'i');
+    const match = segment.match(regex);
+    return match?.[1]?.trim() || '';
+  }
+
+  private createShortHash(input: string, length = 40) {
+    return createHash('sha256').update(input).digest('hex').slice(0, length);
+  }
+
+  private escapeCsvCell(value: string | number | null | undefined) {
+    const normalizedValue = String(value ?? '');
+    const escapedValue = normalizedValue.replace(/"/g, '""');
+
+    return `"${escapedValue}"`;
+  }
+
   async createBankAccount(data: CreateBankAccountDto, userId?: number) {
     const accountType = this.mapAccountTypeFromPt(data.type);
 
@@ -1529,137 +2163,1066 @@ 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'),
+          );
+        }
       }
-    }
 
-    const installments =
-      data.installments && data.installments.length > 0
-        ? data.installments
-        : [
-            {
-              installment_number: 1,
-              due_date: data.due_date,
-              amount: data.total_amount,
-            },
-          ];
+      if (data.cost_center_id) {
+        const costCenter = await tx.cost_center.findUnique({
+          where: { id: data.cost_center_id },
+          select: { id: true },
+        });
 
-    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,
-      },
-    });
+        if (!costCenter) {
+          throw new BadRequestException(
+            getLocaleText('costCenterNotFound', locale, 'Cost center not found'),
+          );
+        }
+      }
 
-    const attachmentFileIds = [
-      ...new Set((data.attachment_file_ids || []).filter((fileId) => fileId > 0)),
-    ];
+      const attachmentFileIds = [
+        ...new Set((data.attachment_file_ids || []).filter((fileId) => fileId > 0)),
+      ];
 
-    if (attachmentFileIds.length > 0) {
-      const existingFiles = await this.prisma.file.findMany({
-        where: {
-          id: { in: attachmentFileIds },
-        },
-        select: {
-          id: true,
-        },
-      });
+      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),
-      );
+        const existingFileIds = new Set(existingFiles.map((file) => file.id));
+        const invalidFileIds = attachmentFileIds.filter(
+          (fileId) => !existingFileIds.has(fileId),
+        );
 
-      if (invalidFileIds.length > 0) {
+        if (invalidFileIds.length > 0) {
+          throw new BadRequestException(
+            `Invalid attachment file IDs: ${invalidFileIds.join(', ')}`,
+          );
+        }
+      }
+
+      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 async updateDraftTitle(
+    titleId: number,
+    data: CreateFinancialTitleDto,
+    titleType: TitleType,
+    locale: string,
+    userId?: number,
+  ) {
+    const installments = this.normalizeAndValidateInstallments(data, locale);
+
+    const updatedTitle = await this.prisma.$transaction(async (tx) => {
+      const title = await tx.financial_title.findFirst({
+        where: {
+          id: titleId,
+          title_type: titleType,
+        },
+        include: {
+          financial_installment: {
+            select: {
+              id: true,
+            },
+          },
+        },
+      });
+
+      if (!title) {
+        throw new NotFoundException(
+          getLocaleText(
+            'itemNotFound',
+            locale,
+            `Financial title with ID ${titleId} not found`,
+          ).replace('{{item}}', 'Financial title'),
+        );
+      }
+
+      if (title.status !== 'draft') {
+        throw new BadRequestException('Only draft titles can be edited');
+      }
+
+      const person = await tx.person.findUnique({
+        where: { id: data.person_id },
+        select: { id: true },
+      });
+
+      if (!person) {
+        throw new BadRequestException(
+          getLocaleText('personNotFound', locale, 'Person not found'),
+        );
+      }
+
+      if (data.finance_category_id) {
+        const category = await tx.finance_category.findUnique({
+          where: { id: data.finance_category_id },
+          select: { id: true },
+        });
+
+        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(', ')}`,
+          );
+        }
+      }
+
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        data.competence_date
+          ? new Date(data.competence_date)
+          : new Date(installments[0].due_date),
+        'update title',
+      );
+
+      const installmentIds = title.financial_installment.map((item) => item.id);
+
+      if (installmentIds.length > 0) {
+        const hasSettlements = await tx.settlement_allocation.findFirst({
+          where: {
+            installment_id: {
+              in: installmentIds,
+            },
+          },
+          select: {
+            id: true,
+          },
+        });
+
+        if (hasSettlements) {
+          throw new BadRequestException(
+            'Cannot edit title with settled installments',
+          );
+        }
+      }
+
+      await tx.financial_title.update({
+        where: { id: title.id },
+        data: {
+          person_id: data.person_id,
+          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,
+        },
+      });
+
+      if (installmentIds.length > 0) {
+        await tx.installment_allocation.deleteMany({
+          where: {
+            installment_id: {
+              in: installmentIds,
+            },
+          },
+        });
+
+        await tx.financial_installment_tag.deleteMany({
+          where: {
+            installment_id: {
+              in: installmentIds,
+            },
+          },
+        });
+
+        await tx.financial_installment.deleteMany({
+          where: {
+            title_id: title.id,
+          },
+        });
+      }
+
+      for (const installment of installments) {
+        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,
+            },
+          });
+        }
+      }
+
+      if (data.attachment_file_ids) {
+        await tx.financial_title_attachment.deleteMany({
+          where: {
+            title_id: title.id,
+          },
+        });
+
+        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,
+            })),
+          });
+        }
+      }
+
+      await this.createAuditLog(tx, {
+        action: 'UPDATE_TITLE',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Updated draft ${titleType} title ${title.id}`,
+        beforeData: JSON.stringify({ status: title.status }),
+        afterData: JSON.stringify({
+          status: title.status,
+          total_amount_cents: this.toCents(data.total_amount),
+        }),
+      });
+
+      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, 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: fallbackDueDate,
+              amount: data.total_amount,
+            },
+          ];
+
+    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: 'open',
+        },
+      });
+
+      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: 'open' }),
+      });
+
+      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 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: 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,
+        'reject title',
+      );
+
+      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 cancelTitle(
+    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: 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'),
+        );
+      }
+
+      if (title.status === 'settled' || title.status === 'canceled') {
+        throw new BadRequestException('Title cannot be canceled in current status');
+      }
+
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        title.competence_date,
+        'cancel title',
+      );
+
+      await tx.financial_title.update({
+        where: { id: title.id },
+        data: {
+          status: 'canceled',
+        },
+      });
+
+      await this.createAuditLog(tx, {
+        action: 'CANCEL_TITLE',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Canceled ${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 (!['open', 'partial'].includes(title.status)) {
         throw new BadRequestException(
-          `Invalid attachment file IDs: ${invalidFileIds.join(', ')}`,
+          'Only 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 +3416,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 +3623,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 +3649,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,
@@ -1962,7 +3720,6 @@ export class FinanceService {
   private mapStatusToPt(status?: string | null) {
     const statusMap = {
       draft: 'rascunho',
-      approved: 'aprovado',
       open: 'aberto',
       partial: 'parcial',
       settled: 'liquidado',
@@ -1994,7 +3751,7 @@ export class FinanceService {
 
     const statusMap = {
       rascunho: 'draft',
-      aprovado: 'approved',
+      aprovado: 'open',
       aberto: 'open',
       parcial: 'partial',
       liquidado: 'settled',
@@ -2006,7 +3763,7 @@ export class FinanceService {
   }
 
   private mapPaymentMethodToPt(paymentMethodType?: string | null) {
-    const paymentMethodMap = {
+    const paymentMethodMap: Record<string, string> = {
       boleto: 'boleto',
       pix: 'pix',
       ted: 'transferencia',
@@ -2019,6 +3776,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',