Fase 03 — Product Delivery

O ECP Pay usa o Provider Pattern para abstrair gateways de pagamento. Apps do ecossistema chamam uma única API — a factory seleciona o adapter ativo (Internal ou Asaas) via feature flag, sem que os apps saibam qual está ativo.

graph TD
    A["ecp-bank :3333"] -->|X-API-Key| B["ECP Pay API :3335"]
    C["ecp-emps :3334"] -->|X-API-Key| B
    D["ecp-food :3000"] -->|X-API-Key| B
    B --> E["Payment Service"]
    E --> F["Provider Factory"]
    F -->|"feature flag"| G["Internal Adapter"]
    F -->|"feature flag"| H["Asaas Adapter"]
    G --> I[("SQLite")]
    H --> J["Asaas API"]
    B --> K["Admin Panel :5176"]
      

Bounded Contexts

Pagamento Pix — Fluxo Completo (Internal Provider)

sequenceDiagram
    participant App as App (ecp-food)
    participant Pay as ECP Pay API :3335
    participant Svc as Payment Service
    participant Prov as Internal Adapter
    participant DB as SQLite

    App->>Pay: POST /pay/pix
    Note over Pay: Headers: X-API-Key, X-Idempotency-Key

    Pay->>Pay: Validar API Key (app_registrations)
    Pay->>DB: SELECT WHERE idempotency_key = ?
    DB-->>Pay: null (novo)

    Pay->>Svc: createPixPayment(data)
    Svc->>Prov: ProviderFactory.get("internal")
    Prov->>Prov: Gerar QR Code + copia-e-cola

    Note over Svc,DB: Transação atômica
    Svc->>DB: INSERT transactions (status: pending)
    Svc->>DB: INSERT splits (se definido)
    DB-->>Svc: transactionId

    Prov->>Prov: Delay configurável (3-5s)
    Prov->>DB: UPDATE transactions SET status = paid

    Svc->>App: POST callback_url (status: paid)
    Note over App: Webhook delivery com retry

    Pay-->>App: { id, status: pending, qrCode, copyPaste }
      

Pagamento Cartão — Provider Asaas (External)

sequenceDiagram
    participant App as App (ecp-bank)
    participant Pay as ECP Pay API
    participant Svc as Payment Service
    participant Prov as Asaas Adapter
    participant Asaas as Asaas API
    participant DB as SQLite

    App->>Pay: POST /pay/card
    Note over Pay: { amount, card: {number, cvv, ...}, customer }

    Pay->>Pay: Validar API Key + Idempotency
    Pay->>Svc: createCardPayment(data)
    Svc->>Prov: ProviderFactory.get("external")

    Prov->>DB: SELECT card_tokens WHERE customer_document
    alt Cartão novo
        Prov->>Asaas: POST /payments (card data)
        Asaas-->>Prov: { id, status, token }
        Prov->>DB: INSERT card_tokens (token, last4, brand)
    else Cartão tokenizado
        Prov->>Asaas: POST /payments (token)
        Asaas-->>Prov: { id, status }
    end

    Svc->>DB: INSERT transactions (status: pending)

    Note over Asaas,Pay: Webhook assíncrono
    Asaas->>Pay: POST /pay/webhooks/asaas
    Pay->>DB: INSERT webhook_events (dedup event_id)
    Pay->>DB: UPDATE transactions SET status = paid
    Pay->>App: POST callback_url (status: paid)
      

Switch de Provider — Internal ↔ External

sequenceDiagram
    participant Admin as Admin (Browser)
    participant Panel as Admin Panel :5176
    participant API as Admin API
    participant DB as SQLite

    Admin->>Panel: Abre página Providers
    Panel->>API: GET /admin/providers
    API->>DB: SELECT feature_flags WHERE key = PAYMENT_PROVIDER
    DB-->>API: { value: "internal" }
    API-->>Panel: { active: "internal", available: ["internal", "external"] }
    Panel-->>Admin: Two-card com toggle (Internal ativo)

    Admin->>Panel: Clica "Ativar External"
    Panel-->>Admin: Modal de confirmação
    Admin->>Panel: Confirma switch

    Panel->>API: POST /admin/providers/switch
    Note over API: Middleware: requireRole("admin")
    API->>DB: UPDATE feature_flags SET value = "external"
    API->>DB: INSERT audit_logs (action: provider_switch)
    API-->>Panel: { active: "external", switchedAt }

    Panel-->>Admin: Banner atualizado + toast de confirmação
    Note over Admin: Todas as novas transações usam Asaas
      

Webhook Delivery — Retry com Backoff Exponencial

sequenceDiagram
    participant Pay as ECP Pay
    participant DB as SQLite
    participant App as App callback_url

    Note over Pay,App: Status de transação mudou

    Pay->>DB: SELECT callback_url FROM transactions
    Pay->>App: POST callback_url (attempt 1)

    alt Sucesso (2xx)
        App-->>Pay: 200 OK
        Pay->>DB: UPDATE: delivery_status = delivered
    else Falha (timeout/5xx)
        App-->>Pay: 500 / timeout

        Note over Pay: Retry 1: aguarda 30s
        Pay->>App: POST callback_url (attempt 2)
        App-->>Pay: 500 / timeout

        Note over Pay: Retry 2: aguarda 2min
        Pay->>App: POST callback_url (attempt 3)
        App-->>Pay: 500 / timeout

        Note over Pay: Retry 3: aguarda 10min
        Pay->>App: POST callback_url (attempt 4)

        alt Sucesso
            App-->>Pay: 200 OK
            Pay->>DB: UPDATE: delivery_status = delivered
        else Falha final
            Pay->>DB: UPDATE: delivery_status = failed
            Note over Pay: Admin pode fazer retry manual
        end
    end
      

Payment API (app-facing) — /pay

Autenticação via X-API-Key header. 9 endpoints.

Admin API (web panel) — /admin

Autenticação via JWT Bearer token. 20 endpoints.

10 tabelas + 16 índices. SQLite com WAL mode via better-sqlite3. Migration: 001-initial.sql.