Módulo de Pagamentos

Objetivo

Emitir cobranças de aluguel, disponibilizar Cobrança PIX ao locatário, registrar o pagamento (automático ou manual), atualizar o status da fatura e disparar eventos para os demais domínios (financeiro, contratos, relatórios).

Escopo funcional

1. Geração de faturas;
2. Integração com provedor PIX (“Gateway”);
3. Atualização automática via webhook/pull API;
4. Baixa manual & estorno;
5. Lembretes de cobrança;
6. Logs e auditoria.

Domínios vizinhos

• Contratos: (origem dos valores + vencimentos);
• Notificações: (e-mail/push);
• Relatórios: (dashboards financeiros).

Tecnologias de referência

• Provedor PIX: API PSP (banco) ou gateway terceirizado (e.g. Gerencianet, Asaas, Iugu).
• Assinador de webhook: HMAC-SHA256 ou similar.
• Filas/eventos: RabbitMQ ou Kafka para desacoplar confirmação.

Atores & Papéis

Ator	Papel no fluxo
Locatário	Visualiza fatura, copia/escaneia QR Code, paga via app bancário.
Administrador de Imobiliária	Emite faturas, visualiza status, executa baixa manual, consulta relatórios.
Gateway PIX	Gera QR Code, recebe pagamento, notifica Rentake.
Serviço Pagamentos (Rentake)	Orquestra geração → disponibilização → conciliação.

User Stories

Épico EP-PAG-01 – Pagamento de Aluguel via PIX

US-PAG-01 – Emissão de fatura

Como administrador da imobiliária
Quero gerar a fatura mensal de um contrato
Para que o locatário possa pagá-la via PIX.

Critérios de aceite

1. Ao clicar em “Gerar faturas do mês”, o sistema consulta todos os contratos ativos cuja próxima mensalidade ≥ data atual.
2. Para cada contrato, cria registro uma cobrança em transactions.
3. Chama endpointpara geração da cobrança → resposta contém qrCodeData, qrCodeImageURL.
4. Persiste qrCodeData & txid na transação; retorna sucesso agregado e lista de cobranças geradas.

---

US-PAG-02 – Geração automática de faturas via Cronjob configurável

Como administrador da imobiliária
Quero configurar o dia e horário para que o sistema gere automaticamente as faturas mensais dos contratos ativos
Para que as cobranças sejam emitidas no momento mais adequado à operação da minha imobiliária.

Critérios de aceite

1. O sistema deverá permitir que o administrador configure, via interface administrativa, o dia do mês (1 a 28) e o horário (hora:minuto) para a execução da rotina de geração automática de faturas.
2. O sistema deverá executar a rotina agendada, conforme essa configuração personalizada, que:
   • Consulta todos os contratos ativos cuja próxima mensalidade seja referente ao mês corrente.
   • Gera as faturas com status=PENDING e chama o Gateway PIX para criação dos QR Codes.
3. Caso a configuração não seja definida, o sistema utilizará o valor padrão: dia 1º do mês às 00:00.
4. A rotina deve continuar a registrar logs detalhados da execução, incluindo quantidade de faturas geradas e erros.
5. A opção de disparo manual da rotina pela interface administrativa permanece disponível, independente da configuração agendada.
6. O sistema deve validar a configuração para garantir que valores inválidos (ex.: dia 31 em meses com menos dias) não sejam salvos, ou ajustar automaticamente para o último dia válido do mês.
7. Tratamento de falhas com tentativas automáticas e alertas para equipe.
8. Disparo de eventos internos para atualização dos sistemas dependentes (notificações, financeiro).

---

US-PAG-03 – Visualização & pagamento pelo locatário

Como locatário
Quero acessar minhas faturas pendentes
Para copiar o código PIX e efetuar o pagamento.

Critérios de aceite

1. Endpoint GET /me/faturas?status=pendente devolve lista paginada.
2. Cada item inclui qrCodeData (texto copia-e-cola) e link da imagem (exibido inline).
3. UX mobile: botão “Copiar código” + “Abrir app do banco (intent)”.
4. Se vencimento < hoje, mostrar badge “Vencida” em vermelho.

---

US-PAG-04 – Recebimento da confirmação automática

Como sistema de pagamentos
Quero receber notificação do gateway
Para atualizar a fatura como paga sem intervenção humana.

Critérios de aceite

1. Endpoint POST /webhooks/pix-paid recebe JSON {txid, valor, pagador, timestamp}.
2. Cabeçalho X-Signature contém HMAC; backend valida assinatura -> 401 se inválida.
3. Busca fatura por txid & status=PENDENTE.
4. Em transação ACID: 4.1. Atualiza status=PAGA, dataPagamento=timestamp, pagadorInfo.
   4.2. Emite evento InvoicePaid {contratoId, faturaId, valor}.
5. Retorna 200 em ≤ 500 ms; loga resultado em tabela WebhookLog.

---

US-PAG-05 – Listagem de inadimplentes

Como administrador da imobiliária
Quero visualizar quem está atrasado
Para acionar lembretes ou medidas de cobrança.

Critérios de aceite

1. Endpoint GET /imobiliarias/:id/inadimplentes?mes=YYYY-MM retorna locatários com faturas onde vencimento < hoje && status!=PAGA.
2. Resposta paginada inclui total de dias em atraso e valor total devido.
3. Exportação CSV disponível (botão “Exportar”).

---

US-PAG-06 – Envio de lembretes automáticos

Como sistema
Quero disparar lembretes para faturas vencidas há X dias
Para diminuir inadimplência sem ação manual.

Critérios de aceite

1. Cron diário às 08:00 local busca faturas status=PENDENTE cujo vencimento = hoje-3.
2. Publica evento SendReminder {locatarioId, faturaId}.
3. Serviço de Notificações envia e-mail/push com template:
   “Sua fatura de R${valor} venceu em {dias} dias. Pague usando este QR Code.”
4. Loga tentativa; evita duplicar envio (marca reminderSent=TRUE).

---

US-PAG-07 – Baixa manual de fatura

Como administrador da imobiliária
Quero registrar pagamento recebido em dinheiro
Para manter os registros financeiros corretos.

Critérios de aceite

1. Tela “Detalhes da fatura” tem botão “Baixar manualmente” (visível apenas a papéis c/ permissão).

2. Modal exige: dataPagamento, valor, método (Dinheiro, TED, etc.), campo opcional observação.

3. Ao confirmar, backend:

   • Verifica status=PENDENTE; se já PAGA, retorna erro 409.
   • Altera status=PAGA_MANUAL, grava auditoria (userId, timestamp, observação).
   • Emite InvoicePaid com flag manual=true.

---

US-PAG-08 – Estorno / cancelamento (edge case)

Como administrador da imobiliária
Quero cancelar uma fatura emitida erroneamente
Para corrigir falhas operacionais sem afetar relatórios.

Critérios de aceite

1. Cancelamento permitido apenas se status=PENDENTE.
2. Endpoint POST /faturas/:id/cancel registra status=CANCELADA, cancelReason, userId, timestamp.
3. Se QR Code gerado, faz chamada DELETE /charges/{txid} no gateway.
4. Evento InvoiceCancelled publicado.
5. Faturas canceladas não entram nos relatórios de receita.

Sequência de Integração (Simplificada)

API Design (REST) – Endpoints-chave

Verbo	Rota	Descrição	Auth & RBAC
POST	/contracts/:id/invoices	Gera fatura(s) futuras conforme contrato	Papel: corretor, administrador
GET	/imobiliarias/:id/invoices	Lista faturas com filtros status, residencial, data	corretor, administrador
GET	/me/invoices	Locatário obtém suas faturas	locatário
POST	/invoices/:id/reminder	Dispara lembrete individual	corretor, administrador
POST	/invoices/:id/pay-manual	Baixa manual	corretor, administrador
POST	/invoices/:id/cancel	Cancela fatura pendente	administrador
GET	/imobiliarias/:id/reports/revenue	Exportação CSV mensal	administrador
POST	/webhooks/pix-paid	Recebe notificação do PSP	sem auth; valida assinatura

Modelo de Estados da Fatura

Detalhes de Integração com o Gateway PIX

Etapa	Chamada	Campos principais	Observações
Criar cobrança	POST /charges	txid, calendar.expiration, amount.original, payer.name opcional, payer.cpf opcional	Retorna location, qrCodeData, emv, txid.
Consultar status	GET /pix/:txid	–	Usado como fallback caso webhook falhe.
Remover cobrança	DELETE /charges/:txid	–	Necessário em US-PAG-07.
Webhook	Envio PSP → Rentake	txid, endToEndId, valor, horario, payer (JSON), chave	Assinado via HMAC SHA-256 + secret.

Segurança: armazenar pixSecret e webhookSecret em vault (env/secret-manager); logs de webhook devem mascarar dados sensíveis.

Considerações de Implementação Independente

1. Serviço isolado: Pagamentos pode ser micro-serviço (REST) com DB próprio (transactions, webhook_logs) e publicar eventos em broker → restante do monolito escuta.
2. Idempotência: Use txid (chave PIX única) como chave natural; garantir update idempotente em caso de webhook duplicado.
3. Circuit-breaker / retry: Ao chamar gateway, implementar retry exponencial (máx 3) e fallback para job assíncrono de reconciliação.
4. Compliance: Registrar todos os endToEndId retornados pelo PSP para fins de auditoria e contestação.
5. Testes: Mock de API PIX em ambiente de QA; fixture de QR Code; simular webhook com POST local.
6. KPIs: percentual de inadimplência, tempo médio de pagamento, falhas de webhook.
7. Failover manual: UI para re-consultar status no PSP em caso de discrepância (botão “Reconciliar”).