openapi: 3.1.0
info:
  title: ENYGMAGAMES Platform API
  version: 0.3.0
  description: Multi-tenant catalog, sessions, rounds, reports and controlled game-math assignments.
servers:
  - url: https://enygmagames.sollutionsbr.com.br/api/v1
security:
  - ApiKey: []
  - OIDC: []
paths:
  /commercial/leads:
    post:
      security: []
      summary: Register an operator, aggregator, affiliate or studio contact request
      responses:
        '201': {description: Lead stored for Studio qualification}
  /auth/config:
    get:
      security: []
      summary: Return the ENYGMAGAMES local identity configuration
      responses:
        '200': {description: Local password plus TOTP authentication capabilities}
  /auth/login:
    post:
      security: []
      summary: Validate ENYGMAGAMES credentials and start first-access or MFA flow
      responses:
        '200': {description: Short-lived challenge and next required step}
        '401': {description: Invalid credentials}
  /auth/password/change:
    post:
      security: []
      summary: Replace the temporary password during first access
      responses:
        '200': {description: Password changed and MFA challenge returned}
  /auth/mfa/enroll:
    post:
      security: []
      summary: Create a QR compatible with Microsoft Authenticator after password change
      responses:
        '201': {description: QR, manual key and pending factor returned}
  /auth/mfa/verify:
    post:
      security: []
      summary: Verify TOTP and issue an eight-hour local Studio session
      responses:
        '200': {description: Bearer session issued; recovery codes included on enrollment}
  /admin/users:
    post:
      summary: Provision a local ENYGMAGAMES user with a one-time temporary password
      description: Requires platform administrator scope. The local login forces password change and Microsoft Authenticator enrollment.
      responses:
        '201': {description: User created; temporary password returned once}
  /support/tickets:
    get:
      summary: List support tickets for the authenticated operator
      responses:
        '200': {description: Ticket queue returned}
    post:
      summary: Open a contextual technical or commercial support ticket
      responses:
        '201': {description: Ticket and target SLA returned}
  /affiliates/dashboard:
    get:
      summary: Return affiliate attribution, revenue and commission totals
      responses:
        '200': {description: Affiliate dashboard returned}
  /affiliates:
    post:
      summary: Invite an affiliate and generate a unique tracking code
      responses:
        '201': {description: Affiliate invitation created}
  /economy/config:
    get:
      summary: Return the tenant wallet, gateway and virtual-credit configuration
      responses:
        '200': {description: Economy configuration and credit packages returned}
    put:
      summary: Save a tenant-specific economy configuration for controlled publication
      description: Gateway and wallet settings never modify game math, RTP or per-player odds.
      responses:
        '200': {description: Configuration stored and awaiting publication approval}
  /economy/packages:
    post:
      summary: Create a tenant-specific fiat or virtual-credit package draft
      responses:
        '201': {description: Credit package draft created}
  /catalog:
    get:
      summary: List active games and assigned math versions for the authenticated tenant
      responses:
        '200': {description: Catalog returned}
  /integrations/manifest:
    post:
      summary: Generate and persist the operator's catalog integration manifest
      responses:
        '201': {description: Integration draft created}
  /sessions:
    post:
      summary: Create a short-lived game session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [gameSlug, operatorPlayerId]
              properties:
                gameSlug: {type: string}
                operatorPlayerId: {type: string}
                walletAccountId: {type: string, format: uuid}
                currency: {type: string, minLength: 3, maxLength: 3}
                locale: {type: string}
                environment: {type: string, enum: [sandbox, production], default: sandbox}
      responses:
        '201': {description: Session created}
        '451': {description: Production denied because one or more jurisdiction, legal, laboratory, wallet, responsible-gaming, math or certificate gates are missing}
  /rounds/{roundId}/play:
    post:
      summary: Execute one idempotent round against the session's pinned math version
      parameters:
        - in: path
          name: roundId
          required: true
          schema: {type: string, format: uuid}
        - in: header
          name: Idempotency-Key
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sessionId, betMinor]
              properties:
                sessionId: {type: string, format: uuid}
                betMinor: {type: integer, minimum: 1}
      responses:
        '200': {description: Settled round with verifiable proof}
        '409': {description: Wallet mismatch or idempotency key reused with a different request}
  /reports/financial:
    get:
      summary: Get daily wager, payout and GGR aggregates
      parameters:
        - {in: query, name: from, required: true, schema: {type: string, format: date}}
        - {in: query, name: to, required: true, schema: {type: string, format: date}}
        - {in: query, name: currency, required: false, schema: {type: string, default: BRL}}
        - {in: query, name: environment, required: false, schema: {type: string, enum: [sandbox, production], default: production}}
      responses:
        '200': {description: Daily financial report}
  /rounds/{roundId}/proof:
    get:
      summary: Verify commitment, reveal and HMAC for a settled round
      parameters:
        - in: path
          name: roundId
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200': {description: Round proof and verification status}
        '404': {description: Round not found for this tenant}
  /certification/status:
    get:
      summary: List internal validation evidence and external-lab status per game version
      responses:
        '200': {description: Certification-readiness registry; internal gates are not regulatory certificates}
  /reports/profitability:
    get:
      summary: Profitability by client and game; global scope requires platform administrator
      responses:
        '200': {description: Contribution margin report}
  /commercial/terms:
    get:
      summary: Return the tenant fixed, GGR-share or hybrid commercial terms
      responses:
        '200': {description: Current commercial terms and GGR formula}
    put:
      summary: Create a draft GGR-first commercial term set for approval
      responses:
        '201': {description: Draft terms created; approval required}
  /commercial/ggr-settlements:
    get:
      summary: Return reconciled wager, payout, GGR and revenue-share settlements
      responses:
        '200': {description: Last 24 GGR settlement periods}
    post:
      summary: Calculate and approve a GGR settlement from a matched reconciliation and active commercial terms
      responses:
        '201': {description: GGR settlement approved}
        '409': {description: Reconciliation or commercial terms do not satisfy settlement gates}
  /finance/reconciliations:
    post:
      summary: Reconcile settled engine rounds against posted double-entry ledger transactions
      description: Scope is explicit by environment, currency and half-open timestamp interval; only round ledger transactions are compared.
      responses:
        '201': {description: Reconciliation completed with matched or divergent status}
  /finance/operator-statements:
    post:
      summary: Import an immutable operator statement for five-source reconciliation
      responses:
        '201': {description: Statement persisted with SHA-256 source hash}
  /reports/financial-breakdown:
    get:
      summary: Break down reconciled wagering by game, math version, country, currency or day
      responses:
        '200': {description: Server-side financial dimensions returned}
  /finance/adjustments:
    post:
      summary: Request a refund, bonus, chargeback, fee, tax, credit or manual adjustment
      responses:
        '201': {description: Pending adjustment requiring two independent approvals}
  /finance/adjustments/{id}/approve:
    post:
      summary: Register an independent human approval for a financial adjustment
      parameters:
        - {in: path, name: id, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Approval state returned}
  /finance/fx-rates:
    post:
      summary: Record an immutable exchange-rate observation with source and timestamp
      responses:
        '201': {description: FX evidence recorded}
  /finance/costs:
    post:
      summary: Record bonus, chargeback, gateway, infrastructure, royalty, support or tax costs
      responses:
        '201': {description: Cost entry created}
  /finance/margin:
    get:
      summary: Return GGR, NGR, cost components and contribution margin
      responses:
        '200': {description: Auditable margin bridge}
  /finance/aging:
    get:
      summary: Return open receivables and 1-30, 31-60 and 60+ overdue buckets
      responses:
        '200': {description: Invoice aging by currency}
  /finance/alerts:
    get:
      summary: Return financial reconciliation and margin alerts
      responses:
        '200': {description: Financial alerts returned}
  /finance/investigations/{roundId}:
    get:
      summary: Investigate one round across RGS, ledger, adjustments, outbox and alerts
      parameters:
        - {in: path, name: roundId, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Correlated round evidence returned}
  /finance/closures:
    get:
      summary: List cryptographically sealed billing closures
      responses:
        '200': {description: Closure registry returned}
    post:
      summary: Close a reconciled settlement and invoice and materialize dimensional facts
      responses:
        '201': {description: Period closed with SHA-256 evidence}
  /finance/erp-connectors:
    post:
      summary: Create an ERP connector that stores only a credential secret reference
      responses:
        '201': {description: Draft ERP connector created}
  /finance/erp-connectors/{id}/sync/{invoiceId}:
    post:
      summary: Queue a signed invoice payload through the transactional outbox
      parameters:
        - {in: path, name: id, required: true, schema: {type: string, format: uuid}}
        - {in: path, name: invoiceId, required: true, schema: {type: string, format: uuid}}
      responses:
        '202': {description: ERP sync queued idempotently}
  /invoices/{id}/export:
    get:
      summary: Export an invoice as JSON or CSV with content SHA-256
      parameters:
        - {in: path, name: id, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Accounting payload returned with x-content-sha256}
  /invoices/from-ggr/{settlementId}:
    post:
      summary: Generate a draft invoice from an approved GGR settlement
      parameters:
        - {in: path, name: settlementId, required: true, schema: {type: string, format: uuid}}
      responses:
        '201': {description: Draft invoice created and linked to the settlement}
  /compliance/policy:
    get:
      summary: Return the default-deny production policy and tenant market gates
      responses:
        '200': {description: Versioned policy and jurisdiction matrix}
  /flagships:
    get:
      summary: Return the three phase-one flagship games and their external gates
      responses:
        '200': {description: Flagship program returned}
  /audit/verify:
    get:
      summary: Verify the tenant audit hash chain and report legacy link-only coverage
      responses:
        '200': {description: Chain validity, coverage and current root hash}
  /finance/dashboard:
    get:
      summary: MRR, receivables, overdue invoices and active clients
      responses:
        '200': {description: Financial control-tower metrics}
  /math/assignments:
    post:
      summary: Request a future assignment of an approved math version
      responses:
        '201': {description: Request awaiting two approvals}
  /math/assignments/{id}/approve:
    post:
      summary: Register one independent approval
      parameters:
        - {in: path, name: id, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Current approval state}
  /wallet/reserve:
    post:
      summary: Move funds from player available balance into a short-lived hold
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema: {type: string}
      responses:
        '201': {description: Funds reserved in the double-entry ledger}
  /wallet/commit:
    post:
      summary: Settle a hold and credit the payout atomically
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema: {type: string}
      responses:
        '200': {description: Hold committed and payout credited}
  /wallet/rollback:
    post:
      summary: Return reserved funds to the player account
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema: {type: string}
      responses:
        '200': {description: Hold rolled back}
  /rounds/{roundId}/replay:
    get:
      summary: Deterministically replay a settled round without changing state
      parameters:
        - {in: path, name: roundId, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Stored outcome, recomputed outcome and proof gates}
  /certification/factory:
    get:
      summary: Return 36-game engineering packages, waves and mobile QA evidence
      responses:
        '200': {description: Factory status; external certificates are separate}
  /certification/cases/{gameSlug}/submission:
    post:
      summary: Record an externally evidenced laboratory status transition
      parameters:
        - {in: path, name: gameSlug, required: true, schema: {type: string}}
      responses:
        '200': {description: External status recorded; production gates remain enforced}
  /certification/cases/{gameSlug}/nonconformities:
    post:
      summary: Record a laboratory observation and force the case back to questions
      parameters:
        - {in: path, name: gameSlug, required: true, schema: {type: string}}
      responses:
        '201': {description: Nonconformity opened and real-money activation denied}
  /sandbox/fault-profiles:
    post:
      summary: Create a sandbox-only latency, error, webhook or wallet-timeout profile
      responses:
        '201': {description: Fault profile created}
  /operations/readiness:
    get:
      summary: Return alerts, SLA snapshots, DR drills, security findings and pilots
      responses:
        '200': {description: Operational readiness control tower}
  /pilots:
    post:
      summary: Open a licensed-operator pilot checklist
      responses:
        '201': {description: Pilot qualification workflow created}
  /distribution:
    get:
      summary: List aggregator connectors and jurisdiction-gated distribution features
      responses:
        '200': {description: Connector and feature registry}
  /public/verify/releases/{fingerprint}:
    get:
      security: []
      summary: Publicly verify hashes, software attestation and external-certificate status
      parameters:
        - {in: path, name: fingerprint, required: true, schema: {type: string, pattern: '^[a-f0-9]{64}$'}}
      responses:
        '200': {description: Release verification result with explicit regulatory disclaimer}
        '404': {description: Release not found}
  /responsible-gaming/players/{playerId}:
    get:
      summary: Read player protection controls
      parameters:
        - {in: path, name: playerId, required: true, schema: {type: string}}
      responses:
        '200': {description: Limits, cooling-off and exclusion status}
    put:
      summary: Configure player limits and reality checks
      responses:
        '200': {description: Controls updated}
  /responsible-gaming/players/{playerId}/self-exclude:
    post:
      summary: Self-exclude a player and block active sessions
      responses:
        '200': {description: Exclusion applied}
  /security/api-keys/{id}/rotate:
    post:
      summary: Atomically rotate an API key and display the replacement once
      responses:
        '200': {description: New secret returned once}
  /risk/evaluate:
    post:
      summary: Evaluate velocity, duplicate-account, bonus and wallet signals
      responses:
        '200': {description: Allow, review or block decision}
  /promotions:
    post:
      summary: Create a sandbox promotion isolated from certified game math
      responses:
        '201': {description: Promotion created behind jurisdiction and contract gates}
  /studio/bootstrap:
    get:
      summary: Return the authenticated tenant operational control-plane snapshot
      responses:
        '200': {description: Tenant, finance, catalog, environments, onboarding, changes, support, deployments and audit data}
  /onboarding/projects:
    post:
      summary: Start or resume an operator onboarding project
      responses:
        '201': {description: Seven-step onboarding workflow created}
  /onboarding/projects/{id}/steps/{step}/complete:
    post:
      summary: Attach evidence and complete an onboarding step
      parameters:
        - {in: path, name: id, required: true, schema: {type: string, format: uuid}}
        - {in: path, name: step, required: true, schema: {type: string}}
      responses:
        '200': {description: Step evidence stored and audited}
  /sandbox/provision:
    post:
      summary: Provision an isolated tenant sandbox and return a one-time API key
      responses:
        '201': {description: Sandbox, fault simulator and one-time credential created}
  /configuration/changes:
    post:
      summary: Request a tenant configuration or catalog change
      responses:
        '201': {description: Pending change requiring two independent approvals}
  /configuration/changes/{id}/approve:
    post:
      summary: Independently approve or reject a sensitive change
      parameters:
        - {in: path, name: id, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Approval count and resulting state}
        '409': {description: Separation-of-duties violation}
  /configuration/changes/{id}/publish:
    post:
      summary: Publish an approved change as a 10 percent canary
      responses:
        '200': {description: Versioned canary deployment created}
        '409': {description: Approval or external production gate missing}
  /deployments/{id}/promote:
    post:
      summary: Promote a healthy canary to 25, 50 or 100 percent
      responses:
        '200': {description: Monotonic traffic promotion recorded}
  /deployments/{id}/rollback:
    post:
      summary: Restore the previous immutable configuration
      responses:
        '200': {description: Rollback deployment created and audited}
  /integrations/{id}/contract-test:
    post:
      summary: Execute the sandbox callback, idempotency and fault-injection preflight
      responses:
        '200': {description: Contract suite passed with correlation evidence}
        '422': {description: One or more contract checks failed}
  /audit/search:
    get:
      summary: Search the tenant hash-chained audit trail
      responses:
        '200': {description: Cursor-paginated audit events}
  /audit/export:
    get:
      summary: Export and Ed25519-sign the complete tenant audit chain
      responses:
        '200': {description: Payload, hash, public key and signature}
  /status:
    get:
      summary: Return tenant environments, active incidents and latest SLA evidence
      responses:
        '200': {description: Operational, attention or degraded status}
  /security/posture:
    get:
      summary: Return scans, findings, key metadata and production release gates
      responses:
        '200': {description: Tenant-safe security posture returned without secret material}
  /security/scans:
    post:
      summary: Record a platform security scan and immutable evidence hash
      responses:
        '201': {description: Scan evidence registered}
  /security/release-gates:
    post:
      summary: Evaluate internal scans plus independent pentest and external certificate gates
      responses:
        '201': {description: Release gate snapshot persisted}
  /operations/control-tower:
    get:
      summary: Return incidents, alerts, SLOs, error budgets, queues, regions, FinOps and capacity
      responses:
        '200': {description: Operational control tower returned}
  /operations/incidents:
    post:
      summary: Declare an incident and open its immutable timeline
      responses:
        '201': {description: Incident declared}
  /operations/dlq/{eventId}/replay:
    post:
      summary: Idempotently replay one tenant dead-letter event
      responses:
        '202': {description: Replay queued}
  /operations/traces/{traceId}:
    get:
      summary: Retrieve tenant-scoped distributed trace spans
      responses:
        '200': {description: Trace returned}
  /promotions/{id}/activate:
    post:
      summary: Activate a campaign only after a jurisdiction feature gate is approved
      responses:
        '200': {description: Campaign activated without changing game math}
  /tournaments/{campaignId}/leaderboard:
    get:
      summary: Return server-calculated tournament scores from settled rounds
      responses:
        '200': {description: Leaderboard returned}
  /jackpots/{id}/activate:
    post:
      summary: Activate a local or network jackpot after jurisdiction approval
      responses:
        '200': {description: Jackpot activated}
  /risk/devices/evaluate:
    post:
      summary: Evaluate a salted device hash without storing the raw fingerprint
      responses:
        '200': {description: Risk score and decision returned}
  /portfolio/intelligence:
    get:
      summary: Return portfolio retention, GGR, RTP and volatility facts without personalized odds
      responses:
        '200': {description: Portfolio intelligence returned}
  /ecosystem:
    get:
      summary: Return the tenant-safe Phase 13 studio, certification, marketplace, distribution and universe control plane
      responses:
        '200': {description: Ecosystem overview returned}
  /ecosystem/studios:
    post:
      summary: Onboard a third-party studio for due diligence
      responses:
        '201': {description: Studio registration created}
  /ecosystem/submissions:
    post:
      summary: Create an immutable third-party game submission with code, asset, math and SBOM hashes
      responses:
        '201': {description: Submission draft created}
  /ecosystem/submissions/{id}/review:
    post:
      summary: Approve or reject an internally reviewed submission and queue its certification package
      responses:
        '200': {description: Submission review recorded}
  /ecosystem/certification-jobs/{id}/external-result:
    post:
      summary: Record the real external laboratory result and certificate reference
      responses:
        '200': {description: External result recorded without self-certification}
  /ecosystem/marketplace/{listingId}/install:
    post:
      summary: Install an externally approved marketplace listing as a tenant catalog draft
      responses:
        '201': {description: Tenant entitlement and catalog draft created}
  /ecosystem/distribution-routes/{id}/activate:
    post:
      summary: Activate a jurisdiction-approved aggregator or third-party RGS distribution route
      responses:
        '200': {description: Distribution route activated}
  /ecosystem/seasons/{id}/progress:
    post:
      summary: Record pseudonymous universe progress from a settled round without affecting math
      responses:
        '201': {description: Progress event recorded}
  /rounds/{roundId}/public-receipt:
    post:
      summary: Issue an expiring public verification token for a tenant-owned settled round
      responses:
        '201': {description: Privacy-preserving receipt token issued}
  /public/verify/rounds/{token}:
    get:
      security: []
      summary: Verify a public round receipt, cryptographic proof and immutable payload hash
      responses:
        '200': {description: Public proof returned without player or tenant identity}
  /ecosystem/network-jackpots/{id}/activate:
    post:
      summary: Activate a continental jackpot only after approval in at least two jurisdictions
      responses:
        '200': {description: Multi-market jackpot activated}
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
    OIDC:
      type: openIdConnect
      openIdConnectUrl: https://identity.example.com/.well-known/openid-configuration