Payment Method Service

Gerencia operações relacionadas às formas de pagamento, permitindo buscar métodos de pagamento disponíveis para vendas.

Visão Geral

O PaymentMethodService é responsável por:

• Buscar formas de pagamento da API remota
• Fornecer informações sobre condições de pagamento
• Listar opções de pagamento com juros, prazos e restrições
• Filtrar métodos disponíveis para consumidores

As formas de pagamento definem como os clientes podem pagar por produtos/serviços, incluindo cartões, boleto, PIX, parcelamento, entre outros, cada um com suas regras específicas.

Localização: services/payment-method/payment-method.service.ts

Endpoints Utilizados

Base URL

Todos os endpoints são relativos à base URL configurada em services/api.service.ts

Métodos

fetchRemote(params)

Busca formas de pagamento remotamente com paginação.

Endpoint: GET /formaPagamento

Parâmetros:

type FetchPaymentMethodParams = {
  page?: number; // Número da página (padrão: 0)
  size?: number; // Quantidade de itens por página (padrão: 999)
  dataHora?: string;
};

Query Params enviados:

• page: número da página
• size: tamanho da página
• dataHora: timestamp (opcional)

Retorno:

Promise<PaymentMethod[]>;

Exemplo de uso:

import { paymentMethodService } from "@/services/payment-method/payment-method.service.instance";

// Buscar todas as formas de pagamento
const allMethods = await paymentMethodService.fetchRemote();

// Buscar com paginação
const methodsPage = await paymentMethodService.fetchRemote({
  page: 0,
  size: 50,
});

// Buscar para sincronização
const methods = await paymentMethodService.fetchRemote({
  page: 0,
  size: 999,
  dataHora: "2026-02-25T10:00:00Z",
});

Tratamento de erros:

• Lança Error se o status da resposta não for 2xx
• Mensagem: PaymentMethodService.fetchRemote failed: {status}

---

Estruturas de Dados

Interface PaymentMethod

interface PaymentMethod {
  id: string;
  idorganizacao: string;
  organizacao: string; 
  idExterno: string; 
  nome: string; 
  dhAlter: string; 
  value: string; 
  grupoAutor: string; 
  dhTipVenda: string; 
  vlrVendaMin: number; 
  codTab: string; 
  fixaVenc: string;
  subtipoVenda: string;
  taxaJuro: number; 
  tipJuro: string; 
  descPromo: string; 
  dtMax: number; 
  tipTaxa: string;
  podeConsumidor: string;
}

---

Componentes Relacionados

buildQueryParams Helper

Função utilitária que converte objeto de parâmetros em URLSearchParams.

Localização: helpers/buildQueryParams.ts

PageResponse Interface

Interface compartilhada para respostas paginadas.

Localização: services/client/client.service.ts

interface PageResponse<T> {
  content: T[]; // Array de itens da página
  page?: number; // Número da página atual
  size?: number; // Tamanho da página
  totalPages?: number; // Total de páginas
  totalElements?: number; // Total de elementos
}

---

Fluxo de Integração

Fluxo de Listagem de Formas de Pagamento

1. App precisa exibir opções de pagamento no checkout
2. App chama paymentMethodService.fetchRemote()
3. GET /formaPagamento é enviado com query params
4. API retorna formas de pagamento disponíveis
5. App filtra por podeConsumidor === "S"
6. App aplica regras de valor mínimo (vlrVendaMin)
7. App renderiza opções de pagamento

Fluxo de Cálculo de Juros

1. Obter forma de pagamento selecionada
2. Verificar se tipJuro !== "NONE"
3. Se tem juros:
   a. Obter taxaJuro (percentual ou valor fixo)
   b. Obter dtMax (número de parcelas/dias)
   c. Calcular valor final com juros
4. Exibir valor total ao cliente

---

Casos de Uso

Listar Formas de Pagamento Disponíveis

// Buscar todas as formas de pagamento
const methods = await paymentMethodService.fetchRemote();

// Filtrar apenas disponíveis para consumidor
const consumerMethods = methods.filter((m) => m.podeConsumidor === "S");

console.log(`Formas de pagamento disponíveis: ${consumerMethods.length}`);

consumerMethods.forEach((method) => {
  console.log(`- ${method.nome}`);
  if (method.vlrVendaMin > 0) {
    console.log(`  Valor mínimo: R$ ${method.vlrVendaMin.toFixed(2)}`);
  }
  if (method.taxaJuro > 0) {
    console.log(`  Taxa de juros: ${method.taxaJuro}%`);
  }
});

// Buscar formas de pagamento
const methods = await paymentMethodService.fetchRemote();

// Valor da compra
const purchaseValue = 150.0;

// Filtrar formas válidas para este valor
const validMethods = methods.filter(
  (m) => m.podeConsumidor === "S" && m.vlrVendaMin <= purchaseValue,
);

console.log(`Formas de pagamento válidas para R$ ${purchaseValue}:`);
validMethods.forEach((m) => console.log(`- ${m.nome}`));

Renderizar Select de Pagamento

// Buscar formas de pagamento
const methods = await paymentMethodService.fetchRemote();
const purchaseValue = 200.0;

// Filtrar válidas para este valor
const validMethods = methods.filter(
  (m) => m.podeConsumidor === "S" && m.vlrVendaMin <= purchaseValue,
);

// Gerar opções para select
const options = validMethods.map((method) => {
  let label = method.nome;

  if (method.taxaJuro > 0) {
    label += ` (${method.taxaJuro}% juros)`;
  }

  if (method.dtMax > 1) {
    label += ` - até ${method.dtMax}x`;
  }

  return {
    value: method.id,
    label: label,
    method: method,
  };
});

// Renderizar
console.log("Opções de pagamento:");
options.forEach((opt) => {
  console.log(`<option value="${opt.value}">${opt.label}</option>`);
});

---

Testes

Localização

services/payment-method/payment-method.service.test.ts

Executar Testes

# Teste específico do serviço
npx jest services/payment-method/payment-method.service.test.ts

# Modo watch
npx jest services/payment-method/payment-method.service.test.ts --watch

# Com coverage
npx jest services/payment-method/payment-method.service.test.ts --coverage

Casos de Teste

• ✅ fetchRemote: busca de formas de pagamento com paginação
• ✅ fetchRemote: retorna content em status 2xx
• ✅ Tratamento de erros para status não-2xx

---

Mocks

Localização

__mocks__/payment-method.mock.ts

Dados Disponíveis

Mock completo com diversos tipos de pagamento:

• Credit Card (pm-001): Cartão de crédito com juros mensal
• Debit Card (pm-002): Cartão de débito sem juros
• PIX (pm-003): Pagamento instantâneo
• Bank Transfer (pm-004): Transferência bancária
• Cash (pm-005): Dinheiro
• Installment 3x (pm-006): Parcelamento em 3x
• Voucher (pm-007): Vale/benefício
• Store Credit (pm-008): Crédito da loja
• Buy Now Pay Later (pm-009): Compre agora, pague depois
• Gift Card (pm-010): Cartão presente

Exemplo de uso em testes:

import { paymentMethodResponseMock } from "@/__mocks__/payment-method.mock";

// Mock da API
const apiMock = {
  get: jest.fn(async () => ({
    status: 200,
    data: paymentMethodResponseMock,
  })),
};

const service = new PaymentMethodService({ apiWithoutAccessToken: apiMock });
const result = await service.fetchRemote();

expect(result).toEqual(paymentMethodResponseMock.content);
expect(result[0]).toHaveProperty("taxaJuro");

---