Event Processing Engine

O Event Processing Engine é o coração da plataforma. Ele é responsável por transformar dados brutos (seja via Webhook ou Polling) em eventos normalizados e úteis.

Estratégias de Ingestão

1. Webhooks (Push)

No fluxo passivo, recebemos o dado e enfileiramos para processamento. É o método preferido pela baixa latência.

2. Polling (Pull)

Quando o provedor não suporta webhooks, assumimos o controle. O processo de Polling funciona em um loop inteligente:

1. Poll: O Driver consulta a API do provedor periodicamente.
2. State Logic: Armazenamos um “estado” da última execução (ex: timestamp do último pedido, hash do último objeto).
3. Diff Check: Comparamos o resultado atual com o estado armazenado.
4. Event Creation: Se (e somente se) houver mudança, geramos um evento correspondente.

Isso garante que não geremos eventos duplicados mesmo consultando a API repetidamente.

Enrichment & State Machine

O processamento não é linear. Ele é uma Máquina de Estados complexa desenhada para resiliência.

O Processo de Enriquecimento

Muitas vezes, o payload inicial (do webhook ou polling) é pobre em dados. Exemplo: Recebemos apenas um order_id.

Para entregar um evento completo, o Engine entra em ação:

1. Analisa o Payload: Identifica dados faltantes.
2. Chamadas de API: O Driver faz chamadas extras ao provedor para buscar detalhes (ex: GET /orders/{id}).
3. Rate Limit Handling: Se o provedor responder com 429 Too Many Requests:
   • O Engine suspende o processamento desse evento específico.
   • Agenda uma nova tentativa respeitando o header Retry-After.
   • Não bloqueia outros eventos da fila.
4. Merge & Normalize: Combina o dado original com o enriquecido e aplica a normalização.

stateDiagram-v2
    [*] --> Received
    Received --> Analyzing
    Analyzing --> EnrichmentNeeded: Dados incompletos?
    Analyzing --> Normalizing: Dados completos

    EnrichmentNeeded --> CallingAPI
    CallingAPI --> RateLimited: 429 Detected
    RateLimited --> CallingAPI: Wait & Retry

    CallingAPI --> DataFetched: 200 OK
    DataFetched --> Normalizing


    Normalizing --> EventCreated

    state "Post-Processing" as PostProc {
        EventCreated --> Enriching: IP, Payment, Device
        Enriching --> WebhookDispatch
    }

    WebhookDispatch --> [*]

Custom Settings (Configurações Personalizadas)

O Engine permite ajustes finos para cada Instalação através do objeto settings no manifesto do Driver.

Parâmetro	Descrição	Padrão
poll_interval	Frequência de consulta ao provedor (em minutos). Ajuste para equilibrar frescor dos dados vs. cotas de API.	5
stability_window	Tempo de espera para confirmar que um dado “assentou” antes de processar. Útil para APIs com consistência eventual.	0 (imediato)
max_concurrency	Número máximo de processamentos simultâneos para evitar sobrecarga no destino.	1
enrichment_depth	Nível de profundidade na busca de dados relacionados (ex: buscar apenas Pedido ou Pedido + Cliente + Produtos).	shallow

Nota: Configurações agressivas (ex: poll_interval: 1) podem resultar em Rate Limiting severo por parte do provedor.

Camada de Pós-Processamento (Post-Processing Layer)

Após a criação bem-sucedida de um evento, ele entra em um estágio final de refinamento. Nesta camada, enriquecedores independentes adicionam metadados valiosos sem bloquear o fluxo principal.

Exemplos de Enriquecimento

• User IP: Geolocalização baseada no IP de origem (Cidade, País, ISP).
• Payment Data: Detalhes estendidos do método de pagamento (Bandeira do cartão, Banco emissor, Tipo de financiamento).
• Device Fingerprinting: Identificação do dispositivo utilizado na transação.