{
  "openapi": "3.1.0",
  "info": {
    "title": "Rava Bursatil API",
    "version": "5.0.0",
    "description": "API REST de Rava Bursatil para consultar cotizaciones en tiempo real y series historicas de acciones, bonos, indices, CEDEARs, ETFs, ADRs y criptomonedas del mercado argentino e internacional.\n\n## Autenticacion\n\nTodas las solicitudes requieren un token Bearer. Incluir el header `Authorization: Bearer <API_KEY>` en cada request.\n\n## Limites\n\n- Usar siempre HTTPS.\n- No exponer la API Key en codigo del lado del cliente.\n- Contactar a soporte si la clave fue comprometida.",
    "contact": {
      "name": "Rava Bursatil",
      "url": "https://www.rava.com"
    }
  },
  "servers": [
    {
      "url": "https://api5.rava.com",
      "description": "Produccion"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/cotizaciones": {
      "get": {
        "operationId": "getCotizaciones",
        "summary": "Cotizaciones en tiempo real",
        "description": "Devuelve la ultima cotizacion disponible para las especies solicitadas. Se puede consultar por especie individual, varias separadas por coma, o por panel predefinido. Debe enviarse al menos `especie` o `panel`.",
        "tags": ["Cotizaciones"],
        "parameters": [
          {
            "name": "especie",
            "in": "query",
            "description": "Ticker o tickers separados por coma. Ejemplos: `GGAL`, `GGAL,YPFD,MERVAL`, `AAPL_US,MSFT_US`, `DOLAR MEP`.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "una_accion": { "value": "GGAL" },
              "varias": { "value": "GGAL,YPFD,MERVAL" },
              "eeuu": { "value": "AAPL_US,MSFT_US" },
              "indices": { "value": "MERVAL,DOLAR MEP,RIESGO PAIS" }
            }
          },
          {
            "name": "panel",
            "in": "query",
            "description": "Codigo de panel predefinido. Devuelve todas las especies del grupo.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["LID", "GEN", "LIDGEN", "BONOS", "BON", "ETF", "ADR", "ADRARG", "VARIAS", "CED", "IND"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array de cotizaciones. Puede ser vacio si no hay coincidencias.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Cotizacion" }
                },
                "example": [
                  {
                    "especie": "GGAL",
                    "fecha": "2026-03-28",
                    "ultimo": 5280.0,
                    "variacion": 2.15,
                    "varMTD": 8.3,
                    "varYTD": 22.5,
                    "volumen": 12500000
                  },
                  {
                    "especie": "MERVAL",
                    "fecha": "2026-03-28",
                    "ultimo": 2150000.0,
                    "variacion": 1.8,
                    "varMTD": 6.2,
                    "varYTD": 18.9,
                    "volumen": null
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Falta `especie` o `panel`, o el panel no existe.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": { "error": "Panel 'XYZ' no valido. Paneles: LID, GEN, LIDGEN, BONOS, BON, ETF, ADR, ADRARG, VARIAS, CED, IND" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/historicos": {
      "get": {
        "operationId": "getHistoricos",
        "summary": "Cotizaciones historicas",
        "description": "Devuelve la serie historica de precios de cierre para una especie en un rango de fechas. Los datos se devuelven ordenados por fecha ascendente.",
        "tags": ["Historicos"],
        "parameters": [
          {
            "name": "especie",
            "in": "query",
            "description": "Ticker de la especie. Ejemplos: `GGAL`, `AAPL_US`, `MERVAL`, `DOLAR MEP`.",
            "required": true,
            "schema": { "type": "string" },
            "example": "GGAL"
          },
          {
            "name": "desde",
            "in": "query",
            "description": "Fecha de inicio (inclusive).",
            "required": true,
            "schema": { "type": "string", "format": "date" },
            "example": "2025-01-01"
          },
          {
            "name": "hasta",
            "in": "query",
            "description": "Fecha de fin (inclusive).",
            "required": true,
            "schema": { "type": "string", "format": "date" },
            "example": "2026-03-28"
          }
        ],
        "responses": {
          "200": {
            "description": "Array de precios historicos ordenados por fecha ASC.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Historico" }
                },
                "example": [
                  { "especie": "GGAL", "fecha": "2025-01-02", "ultimo": 3850.0, "volumen": 8200000 },
                  { "especie": "GGAL", "fecha": "2025-01-03", "ultimo": 3920.0, "volumen": 9100000 }
                ]
              }
            }
          },
          "400": {
            "description": "Faltan parametros o formato de fecha invalido.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": { "error": "Parametros requeridos: especie, desde, hasta" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API Key proporcionada por Rava Bursatil. Enviar en el header `Authorization: Bearer <API_KEY>`."
      }
    },
    "schemas": {
      "Cotizacion": {
        "type": "object",
        "properties": {
          "especie":   { "type": "string",  "description": "Ticker de la especie", "example": "GGAL" },
          "fecha":     { "type": "string",  "format": "date", "description": "Fecha de la cotizacion (YYYY-MM-DD)" },
          "ultimo":    { "type": "number",  "description": "Ultimo precio disponible", "example": 5280.0 },
          "variacion": { "type": ["number", "null"], "description": "Variacion diaria (%)", "example": 2.15 },
          "varMTD":    { "type": ["number", "null"], "description": "Variacion acumulada del mes (%)", "example": 8.3 },
          "varYTD":    { "type": ["number", "null"], "description": "Variacion acumulada del ano (%)", "example": 22.5 },
          "volumen":   { "type": ["number", "null"], "description": "Volumen nominal operado (null para indices)", "example": 12500000 }
        },
        "required": ["especie", "fecha", "ultimo"]
      },
      "Historico": {
        "type": "object",
        "properties": {
          "especie": { "type": "string",  "description": "Ticker de la especie", "example": "GGAL" },
          "fecha":   { "type": "string",  "format": "date", "description": "Fecha (YYYY-MM-DD)" },
          "ultimo":  { "type": "number",  "description": "Precio de cierre", "example": 3850.0 },
          "volumen": { "type": ["number", "null"], "description": "Volumen operado (null para indices)", "example": 8200000 }
        },
        "required": ["especie", "fecha", "ultimo"]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Mensaje de error" }
        },
        "required": ["error"]
      },
      "Panel": {
        "type": "string",
        "description": "Paneles disponibles para agrupar especies en `/cotizaciones`.",
        "enum": ["LID", "GEN", "LIDGEN", "BONOS", "BON", "ETF", "ADR", "ADRARG", "VARIAS", "CED", "IND"],
        "x-panel-descriptions": {
          "LID":    "Panel Lider (acciones Merval) — ~23 especies",
          "GEN":    "Panel General (acciones) — ~59 especies",
          "LIDGEN": "Panel Lider + General combinado",
          "BONOS":  "Bonos argentinos (soberanos, provinciales, ON) — ~78 especies",
          "BON":    "Alias de BONOS (backward-compatible)",
          "ETF":    "ETFs internacionales — ~74 especies",
          "ADR":    "ADRs internacionales — ~14 especies",
          "ADRARG": "ADRs de empresas argentinas en NYSE/Nasdaq — 18 especies",
          "VARIAS": "Acciones internacionales (NYSE/Nasdaq) — ~32 especies",
          "CED":    "CEDEARs completo — ~186 especies",
          "IND":    "Indices, dolares, commodities y tasas — 26 especies"
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Falta el header Authorization o la API Key es invalida.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "error": "API key invalida" }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Cotizaciones",
      "description": "Precios en tiempo real de acciones, bonos, indices, CEDEARs, ETFs, ADRs y criptomonedas."
    },
    {
      "name": "Historicos",
      "description": "Series historicas de precios de cierre diarios."
    }
  ]
}