openapi: "3.0.3"
info:
  title: Oracle Centralizado API
  description: |
    API de datos financieros en tiempo real para el ecosistema cripto venezolano.
    USD/VES multi-fuente + BCV vía GoldT, 24 commodities globales, 143 divisas,
    histórico 1-minuto. Respuestas firmadas con ecdsa-secp256k1 para verificación
    off-chain y on-chain en BSC.
  version: 2.0.0
  contact:
    name: GoldT Ecosystem
    url: https://goldt.criptoinversiones.net
servers:
  - url: https://oraculo.criptoinversiones.net/api
    description: Producción
  - url: https://oraculo1.criptoinversiones.net/api
    description: Réplica 1
  - url: https://oraculo2.criptoinversiones.net/api
    description: Réplica 2
  - url: https://oraculo3.criptoinversiones.net/api
    description: Réplica 3
  - url: https://oraculo4.criptoinversiones.net/api
    description: Réplica 4
paths:
  /health.php:
    get:
      summary: Estado del sistema
      description: Health check con conectividad de fuentes, última sincronización y conteo de activos.
      tags: [Sistema]
      responses:
        "200":
          description: Sistema operativo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          description: Sistema degradado
  /rates.php:
    get:
      summary: Tasas de cambio
      description: 143 tasas incluyendo FIAT, Spot crypto y USD/VES.
      tags: [Datos]
      parameters:
        - name: iso
          in: query
          schema: { type: string, example: BNB }
          description: Filtrar por código ISO del activo
      responses:
        "200":
          description: Lista de tasas
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RatesResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
  /rates_ves.php:
    get:
      summary: USD/VES multi-fuente
      description: Detalle completo de todas las fuentes de USD/VES con latencia y estado.
      tags: [Datos]
      responses:
        "200":
          description: Detalle USD/VES
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VesResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
  /commodities.php:
    get:
      summary: Commodities globales
      description: 24 activos globales con OHLC y variación 24h vía Yahoo Finance.
      tags: [Datos]
      responses:
        "200":
          description: Lista de commodities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommoditiesResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
  /history.php:
    get:
      summary: Histórico 1-minuto
      description: Consulta de datos históricos por tipo, fecha y activo.
      tags: [Datos]
      parameters:
        - name: type
          in: query
          schema: { type: string, enum: [rates, commodities], default: rates }
          description: Tipo de histórico
        - name: date
          in: query
          schema: { type: string, pattern: "^\\d{8}$", example: "20260626" }
          description: Fecha en formato YYYYMMDD
        - name: ticker
          in: query
          schema: { type: string, example: "GC=F" }
          description: Filtrar por ticker de commodity
        - name: limit
          in: query
          schema: { type: integer, maximum: 1000, default: 100 }
          description: Máximo de registros a retornar
      responses:
        "200":
          description: Datos históricos
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HistoryResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
  /public-key.php:
    get:
      summary: Clave pública del Oracle
      description: Clave pública ECDSA secp256k1 para verificar firmas de respuestas.
      tags: [Sistema]
      responses:
        "200":
          description: Clave pública
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicKeyResponse"
components:
  schemas:
    Signature:
      type: object
      properties:
        value:
          type: string
          description: Firma ECDSA secp256k1 en hex DER
        algorithm:
          type: string
          enum: [ecdsa-secp256k1]
        public_key:
          type: string
          description: Clave pública en hex DER SubjectPublicKeyInfo
        timestamp:
          type: integer
          description: Timestamp UNIX en milisegundos
        nonce:
          type: string
          description: Nonce aleatorio de 16 bytes en hex
    HealthResponse:
      type: object
      properties:
        success: { type: boolean }
        app: { type: string }
        timestamp: { type: string, format: date-time }
        uptime: { type: string, nullable: true }
        checks:
          type: object
          properties:
            rates:
              type: object
              properties:
                status: { type: string, enum: [ok, error] }
                last_update: { type: string, nullable: true }
                usd_ves: { type: number, nullable: true }
                source: { type: string, nullable: true }
            commodities:
              type: object
              properties:
                status: { type: string, enum: [ok, error] }
                count: { type: integer }
                last_updated: { type: string, nullable: true }
        _signature: { $ref: "#/components/schemas/Signature" }
    RatesResponse:
      type: object
      properties:
        status: { type: string, enum: [success, error] }
        author: { type: string }
        count: { type: integer }
        data:
          type: array
          items:
            type: object
            properties:
              iso: { type: string }
              rate: { type: number }
              fuente: { type: string }
              tendencia: { type: string, enum: [SUBE, BAJA, NEUTRAL] }
              ultima_actualizacion: { type: string }
        _signature: { $ref: "#/components/schemas/Signature" }
    VesResponse:
      type: object
      properties:
        success: { type: boolean }
        app: { type: string }
        timestamp: { type: object }
        usd_ves:
          type: object
          properties:
            rate: { type: number }
            source_id: { type: string }
            all_sources:
              type: object
              additionalProperties:
                type: object
                properties:
                  success: { type: boolean }
                  rate: { type: number, nullable: true }
                  fetch_time_ms: { type: number }
                  error: { type: string, nullable: true }
        note: { type: string }
        _signature: { $ref: "#/components/schemas/Signature" }
    CommoditiesResponse:
      type: object
      properties:
        success: { type: boolean }
        count: { type: integer }
        last_updated: { type: string }
        source: { type: string }
        data:
          type: array
          items:
            type: object
            properties:
              nombre: { type: string }
              ticker: { type: string }
              categoria: { type: string }
              unidad: { type: string }
              precio: { type: number }
              apertura: { type: number }
              maximo: { type: number }
              minimo: { type: number }
              volumen: { type: integer }
              variacion_24h_pct: { type: number }
              timestamp: { type: string }
        _signature: { $ref: "#/components/schemas/Signature" }
    HistoryResponse:
      type: object
      properties:
        success: { type: boolean }
        type: { type: string, enum: [rates, commodities] }
        date: { type: string }
        count: { type: integer }
        data: { type: array }
        _signature: { $ref: "#/components/schemas/Signature" }
    PublicKeyResponse:
      type: object
      properties:
        algorithm: { type: string }
        curve: { type: string }
        public_key: { type: string }
        format: { type: string }
        created: { type: string, format: date-time }
        usage: { type: string }
        _signature: { $ref: "#/components/schemas/Signature" }
  responses:
    RateLimited:
      description: Demasiadas solicitudes
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, enum: [false] }
              error: { type: string }
              code: { type: integer, enum: [429] }