Visão Geral¶

O que é esta integração?¶

A integração Nayax → Saipos é um sistema que conecta terminais de pagamento Nayax com o sistema POS Saipos, permitindo que transações realizadas em máquinas de vending ou self-service sejam automaticamente registradas no sistema de gestão do restaurante.

Como Funciona?¶

sequenceDiagram
    participant N as Nayax
    participant W as Webhook
    participant DB as Database
    participant J as JobsProcessor
    participant S as Saipos

    N->>W: POST /webhooks/nayax
    W->>W: Autenticação
    W->>DB: Salva evento
    W->>DB: Cria job (PENDING)
    W-->>N: 200 OK (imediato)

    loop A cada 20s
        J->>DB: Busca jobs PENDING
        J->>DB: Marca como PROCESSING
        J->>J: Transforma dados
        J->>S: POST /order
        alt Sucesso
            S-->>J: 200 OK
            J->>DB: Marca como SENT
        else Erro
            S-->>J: 4xx/5xx
            J->>DB: Marca como FAILED/DLQ
        end
    end

Características Principais¶

1. Recepção de Webhooks¶

O sistema recebe webhooks do Nayax contendo informações sobre transações realizadas.

Endpoint: POST /webhooks/nayax

Autenticação suportada:

• Bearer Token (JWT ou Nayax)
• Basic Auth

2. Processamento Assíncrono¶

Utiliza o Outbox Pattern para garantir que nenhuma transação seja perdida:

1. Recepção imediata: Webhook retorna 200 OK instantaneamente
2. Salvamento: Evento é salvo no banco de dados
3. Enfileiramento: Job é criado com status PENDING
4. Processamento: Worker processa jobs a cada 20 segundos
5. Retry: Jobs com falha são retentados com backoff exponencial

3. Transformação de Dados¶

O Mapper converte o formato Nayax para o formato Saipos:

• Mapeamento de formas de pagamento (tenderType)
• Cálculo de totais, descontos e acréscimos
• Ajuste de somas para evitar diferenças de centavos
• Geração de IDs únicos (com timestamp para testes)

4. Sistema Multi-tenant¶

Suporta múltiplos restaurantes com:

• Credenciais Saipos isoladas por restaurante
• Sistema de permissões (OWNER, ADMIN, MANAGER, EMPLOYEE, VIEWER)
• Vínculo N:N entre usuários e restaurantes

5. Resiliência¶

• Retry com backoff: 30s → 2min → 5min → 15min → 30min → 60min
• DLQ (Dead Letter Queue): Erros permanentes (400, 422)
• Reaper: Limpa jobs travados automaticamente
• Lock otimista: Evita processamento duplicado

Casos de Uso¶

Restaurante Self-Service¶

graph LR
    A[Cliente] --> B[Terminal Nayax]
    B --> C[Pagamento]
    C --> D[Webhook]
    D --> E[Sistema]
    E --> F[Saipos]
    F --> G[Pedido na Cozinha]

1. Cliente seleciona produtos no terminal
2. Realiza pagamento (Pix, cartão, etc)
3. Nayax envia webhook com transação
4. Sistema processa e envia para Saipos
5. Pedido aparece no sistema do restaurante

Máquina de Vending¶

graph LR
    A[Cliente] --> B[Máquina Nayax]
    B --> C[Compra + Pagamento]
    C --> D[Webhook]
    D --> E[Sistema]
    E --> F[Saipos]
    F --> G[Registro de Venda]

1. Cliente compra produto na máquina
2. Pagamento processado pelo Nayax
3. Transação enviada via webhook
4. Sistema registra venda no Saipos

Benefícios¶

Para o Negócio¶

• Automação completa: Sem intervenção manual
• Rastreabilidade: Todas as transações registradas
• Centralização: Todos os dados no Saipos
• Relatórios unificados: Visão consolidada de vendas

Para o Desenvolvedor¶

• Alta confiabilidade: Outbox pattern + retry
• Observabilidade: Logs detalhados em cada etapa
• Manutenibilidade: Código bem estruturado e documentado
• Testabilidade: Modo de teste built-in

Para a Operação¶

• Monitoramento: Dashboard de métricas
• Alertas: Notificação de problemas
• Troubleshooting: Queries prontas para debug
• Reprocessamento: Jobs podem ser retentados manualmente

Fluxo de Dados¶

Entrada (Nayax)¶

{
  "transactionKey": "550e8400-e29b-41d4-a716-446655440000",
  "storeCode": "LOJA001",
  "totalAmount": 50.00,
  "items": [...],
  "payments": [...]
}

Saída (Saipos)¶

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "cod_store": "LOJA_SAIPOS_001",
  "total_amount": 50.00,
  "items": [...],
  "payment_types": [...]
}

Próximos Passos¶

Agora que você entende como funciona, vamos para a arquitetura detalhada:

Ver Arquitetura