openapi: 3.1.0
info:
  title: Fideliza API - Integracao de Eventos
  version: 1.0.0
  summary: API B2B para envio seguro de eventos do programa de CRM Fideliza.
  description: |
    ## Sobre esta documentacao

    Esta referencia foi preparada para clientes e parceiros que integram seus sistemas ao ecossistema **Fideliza**.
    O objetivo e padronizar o envio de eventos (compras, resgates, visitas, etc.) com seguranca, rastreabilidade e previsibilidade operacional.

    ## Escopo desta versao

    - Endpoint publico para **registro de eventos** de KPI.
    - Autenticacao por cabecalhos de credencial (API Key + Secret).
    - Processamento **assincrono** dos indicadores.

    > Importante: o status `201 Created` confirma o **registro** do evento.  
    > O **processamento** dos indicadores ocorre por demanda, normalmente em ate **5 minutos**.

    ## Exemplos de uso para clientes

    Esta API usa um unico endpoint de evento (`POST /v1/event`).
    Casos como **deposito** e **saque** sao enviados como eventos diferentes no campo `event`.
    Nesta documentacao voce encontra exemplos prontos de autenticacao e payload para ambos os fluxos.

    ## Fluxo sugerido para um usuario

    Abaixo, um fluxo completo recomendado para operacoes de iGaming/fintech.
    Todos os passos usam o mesmo endpoint `POST /v1/event`, mudando apenas o payload.
    Os valores de `event` precisam estar previamente cadastrados e habilitados para sua empresa.

    1. **Criar conta**
    ```json
    {
      "event": "ACCOUNT_CREATED",
      "user_id": "usr_001",
      "occurred_at": "2026-03-31T14:00:00.000Z",
      "metadata": {
        "origin": "landing_page",
        "campaign": "welcome_bonus"
      }
    }
    ```

    2. **Fazer deposito**
    ```json
    {
      "event": "DEPOSIT_CONFIRMED",
      "user_id": "usr_001",
      "amount": 250.00,
      "occurred_at": "2026-03-31T14:30:00.000Z",
      "metadata": {
        "transaction_id": "dep_78910",
        "wallet_id": "wl_01"
      }
    }
    ```

    3. **Apostar**
    ```json
    {
      "event": "BET_PLACED",
      "user_id": "usr_001",
      "amount": 50.00,
      "occurred_at": "2026-03-31T14:45:00.000Z",
      "metadata": {
        "bet_id": "bet_4471",
        "game": "slots"
      }
    }
    ```

    4. **Ganhar**
    ```json
    {
      "event": "BET_WON",
      "user_id": "usr_001",
      "amount": 120.50,
      "occurred_at": "2026-03-31T15:00:00.000Z",
      "metadata": {
        "bet_id": "bet_4471",
        "round_id": "rnd_778"
      }
    }
    ```

    5. **Sacar**
    ```json
    {
      "event": "WITHDRAWAL_CONFIRMED",
      "user_id": "usr_001",
      "amount": 120.50,
      "occurred_at": "2026-03-31T15:10:00.000Z",
      "metadata": {
        "transaction_id": "wd_77889",
        "wallet_id": "wl_01"
      }
    }
    ```

servers:
  - url: https://api.fideliza-crm.com
    description: Ambiente de producao oficial
  - url: https://homolog.api.fideliza-crm.com
    description: Ambiente de homologacao
  - url: http://localhost:9002
    description: Ambiente local

tags:
  - name: Eventos (KPI)
    description: Recepcao de eventos para alimentacao do motor de indicadores da Fideliza.
  - name: Autenticacao
    description: Contrato de seguranca para chamadas server-to-server.

paths:
  /v1/event:
    post:
      tags:
        - Eventos (KPI)
      summary: Registrar evento de KPI
      description: |
        Registra um evento associado a um usuario (`user_id`),
        dentro do escopo da empresa e do pais enviados nos cabecalhos de autenticacao.

        ### Modelo de processamento
        1. A API valida autenticacao, empresa/pais, schema e permissao do evento.
        2. O evento e persistido e retorna `201`.
        3. O processamento das agregacoes e dos indicadores ocorre de forma assincrona.

        **SLA operacional:** o processamento e executado por demanda, em ate aproximadamente **5 minutos**.
      operationId: registerKpiEvent
      security:
        - CompanyHmac: []
      parameters:
        - $ref: '#/components/parameters/XCompanyCode'
        - $ref: '#/components/parameters/XCountryCode'
        - $ref: '#/components/parameters/XCompanySecret'
      x-codeSamples:
        - lang: Shell
          label: Autenticacao (template)
          source: |
            curl --request POST 'https://api.fideliza-crm.com/v1/event' \
              --header 'Content-Type: application/json' \
              --header 'x-company-key: pk_live_cliente_123' \
              --header 'x-company-secret: sk_live_cliente_456' \
              --header 'x-company-code: ACME' \
              --header 'x-country-code: BR' \
              --data '{
                "event": "DEPOSIT_CONFIRMED",
                "user_id": "usr_001",
                "amount": 250.00,
                "occurred_at": "2026-03-31T14:30:00.000Z",
                "metadata": {
                  "transaction_id": "tx_10001",
                  "channel": "pix"
                }
              }'
        - lang: Shell
          label: Deposito
          source: |
            curl --request POST 'https://api.fideliza-crm.com/v1/event' \
              --header 'Content-Type: application/json' \
              --header 'x-company-key: pk_live_cliente_123' \
              --header 'x-company-secret: sk_live_cliente_456' \
              --header 'x-company-code: ACME' \
              --header 'x-country-code: BR' \
              --data '{
                "event": "DEPOSIT_CONFIRMED",
                "user_id": "usr_001",
                "amount": 250.00,
                "occurred_at": "2026-03-31T14:30:00.000Z",
                "metadata": {
                  "transaction_id": "dep_78910",
                  "wallet_id": "wl_01"
                }
              }'
        - lang: Shell
          label: Saque
          source: |
            curl --request POST 'https://api.fideliza-crm.com/v1/event' \
              --header 'Content-Type: application/json' \
              --header 'x-company-key: pk_live_cliente_123' \
              --header 'x-company-secret: sk_live_cliente_456' \
              --header 'x-company-code: ACME' \
              --header 'x-country-code: BR' \
              --data '{
                "event": "WITHDRAWAL_CONFIRMED",
                "user_id": "usr_001",
                "amount": 120.50,
                "occurred_at": "2026-03-31T15:10:00.000Z",
                "metadata": {
                  "transaction_id": "wd_77889",
                  "wallet_id": "wl_01"
                }
              }'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKpiEvent'
            examples:
              conta_criada:
                summary: Criar conta (enviar evento)
                value:
                  event: ACCOUNT_CREATED
                  user_id: usr_001
                  occurred_at: '2026-03-31T14:00:00.000Z'
                  metadata:
                    origin: landing_page
                    campaign: welcome_bonus
              deposito_confirmado:
                summary: Deposito confirmado (exemplo real)
                value:
                  event: DEPOSIT_CONFIRMED
                  user_id: usr_001
                  amount: 250.00
                  metadata:
                    transaction_id: dep_78910
                    wallet_id: wl_01
                  occurred_at: '2026-03-31T14:30:00.000Z'
              aposta_realizada:
                summary: Aposta realizada
                value:
                  event: BET_PLACED
                  user_id: usr_001
                  amount: 50.00
                  metadata:
                    bet_id: bet_4471
                    game: slots
                  occurred_at: '2026-03-31T14:45:00.000Z'
              aposta_ganha:
                summary: Aposta ganha
                value:
                  event: BET_WON
                  user_id: usr_001
                  amount: 120.50
                  metadata:
                    bet_id: bet_4471
                    round_id: rnd_778
                  occurred_at: '2026-03-31T15:00:00.000Z'
              saque_confirmado:
                summary: Saque confirmado (exemplo real)
                value:
                  event: WITHDRAWAL_CONFIRMED
                  user_id: usr_001
                  amount: 120.50
                  metadata:
                    transaction_id: wd_77889
                    wallet_id: wl_01
                  occurred_at: '2026-03-31T15:10:00.000Z'
      responses:
        '201':
          description: |
            Evento aceito e persistido com sucesso.
            O processamento dos indicadores e assincrono (ate cerca de 5 minutos).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterKpiEventResponse'
              examples:
                sucesso:
                  value:
                    message: Evento registrado com sucesso.
                    event_id: evt_01HABC123
        '400':
          description: Requisicao invalida (cabecalhos obrigatorios ausentes ou payload invalido)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                cabecalho_ausente:
                  value:
                    status_code: 400
                    message: Headers x-company-secret, x-company-code sao obrigatorios.
        '403':
          description: |
            Acesso negado por violacao de seguranca ou politica operacional
            (credenciais invalidas, rate limit, evento nao habilitado para a empresa).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                credencial_invalida:
                  value:
                    status_code: 403
                    message: Credenciais invalidas.
        '404':
          description: Evento/acao de KPI nao encontrado no catalogo da empresa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                evento_desconhecido:
                  value:
                    status_code: 404
                    message: Evento nao encontrado.

components:
  securitySchemes:
    CompanyHmac:
      type: apiKey
      in: header
      name: x-company-key
      description: |
        Chave publica da empresa fornecida pela Fideliza.
        Deve ser enviada junto com os demais cabecalhos de autenticacao.

        ### Cabecalhos obrigatorios
        - `x-company-key`
        - `x-company-secret`
        - `x-company-code`
        - `x-country-code`

        ### Regra de validacao
        - `x-company-key` identifica a empresa
        - `x-company-secret` deve corresponder ao segredo cadastrado para a `x-company-key`
        - `x-company-code` deve bater com a empresa da chave
        - `x-country-code` deve estar dentro dos paises habilitados para a empresa

        ### Exemplo de autenticacao valida
        - `x-company-key: pk_live_cliente_123`
        - `x-company-secret: sk_live_cliente_456`
        - `x-company-code: ACME`
        - `x-country-code: BR`

  parameters:
    XCompanyCode:
      name: x-company-code
      in: header
      required: true
      schema:
        type: string
      description: "Codigo da empresa em caixa alta (ex.: ACME)"
      example: ACME
    XCountryCode:
      name: x-country-code
      in: header
      required: true
      schema:
        type: string
      description: "Codigo do pais no escopo da empresa (ex.: BR)"
      example: BR
    XCompanySecret:
      name: x-company-secret
      in: header
      required: true
      schema:
        type: string
      description: Segredo da empresa associado a `x-company-key`
      example: sk_live_9a8b7c6d5e4f3a2b1c

  schemas:
    CreateKpiEvent:
      type: object
      required:
        - event
        - user_id
        - occurred_at
      properties:
        event:
          type: string
          description: Acao de KPI cadastrada e habilitada para a empresa (normalizada em caixa alta)
          example: PURCHASE_COMPLETED
        user_id:
          type: string
          description: Identificador unico do usuario no sistema do cliente
          example: usr_01HXYZ
        amount:
          type: number
          description: Valor numerico opcional associado ao evento
          example: 129.9
        metadata:
          type: object
          additionalProperties: true
          description: Objeto de metadados livres (limite operacional de ate 10 chaves)
          example:
            channel: ecommerce
            order_id: '554433'
        occurred_at:
          type: string
          format: date-time
          description: Data/hora de ocorrencia do fato de negocio (ISO 8601)
          example: '2026-03-31T14:30:00.000Z'

    RegisterKpiEventResponse:
      type: object
      required:
        - message
        - event_id
      properties:
        message:
          type: string
          description: Confirmacao de persistencia do evento (nao representa processamento concluido)
          example: Evento registrado com sucesso.
        event_id:
          type: string
          description: Identificador unico do evento para rastreio e suporte
          example: evt_01HABC123

    ErrorResponse:
      type: object
      properties:
        status_code:
          type: integer
          example: 403
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Credenciais invalidas.
      description: Modelo padrao de erro retornado pela API.

x-tagGroups:
  - name: Integracao
    tags:
      - Eventos (KPI)
      - Autenticacao
