RFC - Pix automático

rfc-pix-automatico.md

RFC - Implementação de PIX Programado e Recorrente

Objetivo

Este documento propõe a implementação de uma funcionalidade para a execução programada e/ou recorrente de transações via PIX. O recurso permitirá que clientes da plataforma agendem transferências PIX para datas futuras, com a possibilidade de definir uma recorrência, visando facilitar pagamentos regulares, como mensalidades, assinaturas e transferências periódicas.

Escopo

Definição de Requisitos

A implementação cobrirá os seguintes requisitos fundamentais para a realização de PIX programado e recorrente:

• Conta de Origem: Identificação da conta bancária que realizará o pagamento.
• Conta de Destino: Identificação da conta bancária do destinatário da transferência.
• Valor da Transferência: Montante a ser transferido via PIX.
• Data da Próxima Execução: Data na qual a transação programada será realizada.
• Regra de Recorrência: Frequência com a qual a transferência será repetida (ex.: diária, semanal, mensal).

Persistência dos Dados

Todos os dados relacionados às transações programadas e recorrentes devem ser armazenados de forma segura e confiável, para garantir a consistência das operações e o histórico de transações. Esses dados incluem:

• Detalhes da conta de origem e destino.
• Informações de valor, data e recorrência.
• Status das transações (ex.: agendada, concluída, falha).
• Histórico de tentativas em caso de falhas e data das próximas execuções.

Validações

Para assegurar a integridade e segurança das operações, a plataforma realizará as seguintes validações antes de efetuar qualquer transação programada ou recorrente:

1. Validação das Chaves das Contas de Origem e Destino:

   • Verificar a validade das chaves PIX fornecidas para a conta de origem e destino.
   • Confirmar que ambas as chaves estão ativas e são elegíveis para transferências.

2. Verificação de Saldo da Conta de Origem:

   • Antes da execução da transferência, o sistema deverá confirmar se a conta de origem possui saldo suficiente.
   • Notificar o cliente caso o saldo seja insuficiente para a transferência programada.

---

Fluxograma

---

Modelo de dados

{
  "_id": "507f191e810c19729de860ea",
  "sender_pix_key": "1234567890abcdef1234567890abcdef",
  "receiver_pix_key": "9876543210fedcba9876543210fedcba",
  "amount": 150.00,
  "scheduled_date": "2024-11-15T10:00:00Z",
  "rrule": "FREQ=MONTHLY;BYDAY=FR",
  "status": "SCHEDULED" | "COMPLETED" | "FAILED" | "CANCELLED",
  "attempts": 0,
  "max_attempts": 3,
  "execution_history": [
    {
      "execution_date": "2024-11-15T10:05:00Z",
      "execution_status": "COMPLETED" | "FAILED",
      "error_message": ""
    }
  ],
  "next_execution": "2024-12-15T10:00:00Z",
  "created_at": "2024-11-10T12:00:00Z",
  "updated_at": "2024-11-10T12:00:00Z",
  "last_attempt_date": null
}

---

API

Endpoints

Criar Agendamento PIX

• Método: POST em /api/scheduled-pix
• Descrição: Permite que um cliente agende uma transferência PIX para uma data futura ou recorrente. O agendamento inclui o valor, data inicial, chave PIX do remetente e destinatário, e uma regra de recorrência.
• Exemplo de Parâmetros:

  {
    "sender_pix_key": "1234567890abcdef",
    "receiver_pix_key": "fedcba0987654321",
    "amount": 150.00,
    "scheduled_date": "2024-11-15T10:00:00Z",
    "rrule": "FREQ=MONTHLY;BYDAY=FR",
    "max_attempts": 3
  }

Consultar Agendamento

• Método: GET em /api/scheduled-pix/{scheduled_pix_id}
• Descrição: Retorna detalhes de um agendamento específico, incluindo status atual, histórico de execuções e próximas datas.

Listar Agendamentos

• Método: GET em /api/scheduled-pix
• Descrição: Lista agendamentos existentes, permitindo filtragem por status (SCHEDULED, COMPLETED, FAILED) para facilitar o acompanhamento de todas as transações programadas.

Atualizar Agendamento

• Método: PATCH em /api/scheduled-pix/{scheduled_pix_id}
• Descrição: Permite ao cliente atualizar os detalhes de um agendamento, como a data da próxima execução, regra de recorrência, ou o status para CANCELLED, caso queira desativá-lo.
• Exemplo de Parâmetros:

  {
    "scheduled_date": "2024-12-15T10:00:00Z",
    "rrule": "FREQ=WEEKLY;BYDAY=MO",
    "status": "CANCELLED"
  }

Executar Agendamentos

• Método: POST em /api/scheduled-pix/execute
• Descrição: Este endpoint verifica e executa agendamentos elegíveis, normalmente acionado por um job em segundo plano. Realiza tentativas automáticas caso a execução falhe.

---

Webhook de Notificação

Registro de Webhook

• Método: POST em /api/webhooks
• Descrição: Permite que clientes registrem uma URL para receber notificações automáticas sobre eventos de agendamentos. Ao registrar o webhook, o cliente escolhe quais eventos deseja acompanhar, como a conclusão de um PIX ou o cancelamento de um agendamento.
• Exemplo de Registro:

  {
    "url": "https://example.com/webhook",
    "events": ["PIX_COMPLETED", "PIX_FAILED", "PIX_SCHEDULED", "PIX_CANCELLED"]
  }

Estrutura de Notificação

• Formato da Notificação:

  {
    "event": "PIX_COMPLETED",
    "scheduled_pix": {
      "sender_pix_key": "1234567890abcdef",
      "receiver_pix_key": "fedcba0987654321",
      "amount": 150.00,
      "scheduled_date": "2024-11-15T10:00:00Z",
      "execution_date": "2024-11-15T10:05:00Z",
      "status": "COMPLETED",
      "attempts": 1,
      "error_message": ""
    }
  }

Eventos Suportados

• PIX_COMPLETED: Transferência concluída com sucesso.
• PIX_FAILED: Falha na execução do PIX.
• PIX_SCHEDULED: Novo agendamento de PIX criado.
• PIX_CANCELLED: Agendamento de PIX cancelado.