openapi: 3.1.0
info:
  title: Tipodecambio.cr API
  version: 2.0.0
  summary: Tipo de cambio oficial USD/CRC e indicadores económicos de Costa Rica
  description: |
    API pública, sin autenticación para consultas. Fuente primaria: Banco Central de
    Costa Rica (BCCR) vía su API SDDE. Rate-limit: 120 req/min por IP.
  contact:
    url: https://tipodecambio.cr
  license:
    name: Datos del BCCR (uso público)
servers:
  - url: https://tipodecambio.cr
    description: Producción
tags:
  - name: tipo-cambio
  - name: indicadores
  - name: noticias
paths:
  /api/v1/tipo-cambio/hoy:
    get:
      tags: [tipo-cambio]
      summary: Tipo de cambio oficial del día (USD/CRC)
      operationId: tipoCambioHoy
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RateEnvelope' }
  /api/v1/tipo-cambio/historico:
    get:
      tags: [tipo-cambio]
      summary: Serie histórica USD/CRC
      operationId: tipoCambioHistorico
      parameters:
        - in: query
          name: desde
          schema: { type: string, format: date }
        - in: query
          name: hasta
          schema: { type: string, format: date }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SeriesEnvelope' }
  /api/v1/convertir:
    get:
      tags: [tipo-cambio]
      summary: Convertir USD ↔ CRC al tipo de cambio actual
      operationId: convertir
      parameters:
        - in: query
          name: monto
          required: true
          schema: { type: number, minimum: 0 }
        - in: query
          name: desde
          required: true
          schema: { type: string, enum: [USD, CRC] }
        - in: query
          name: hacia
          required: true
          schema: { type: string, enum: [USD, CRC] }
      responses:
        '200':
          description: OK
  /api/v1/indicadores:
    get:
      tags: [indicadores]
      summary: Listado de indicadores disponibles
      operationId: listIndicadores
      responses:
        '200': { description: OK }
  /api/v1/indicadores/{slug}:
    get:
      tags: [indicadores]
      operationId: getIndicador
      parameters:
        - in: path
          name: slug
          required: true
          schema: { type: string }
        - in: query
          name: desde
          schema: { type: string, format: date }
        - in: query
          name: hasta
          schema: { type: string, format: date }
      responses:
        '200': { description: OK }
        '404': { description: Indicador desconocido }
  /api/v1/noticias:
    get:
      tags: [noticias]
      operationId: noticias
      parameters:
        - in: query
          name: q
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 30, default: 10 }
      responses:
        '200': { description: OK }
  /api/v1/health:
    get:
      operationId: health
      responses:
        '200': { description: OK }
components:
  schemas:
    RateEnvelope:
      type: object
      properties:
        ok: { type: boolean }
        data:
          type: object
          properties:
            fecha: { type: string, format: date }
            compra: { type: number, nullable: true }
            venta:  { type: number, nullable: true }
            moneda: { type: string, example: USD }
            referencia: { type: string, example: CRC }
        source: { type: string }
        retrievedAt: { type: string, format: date-time }
    SeriesEnvelope:
      type: object
      properties:
        ok: { type: boolean }
        data:
          type: array
          items:
            type: object
            properties:
              date: { type: string, format: date }
              compra: { type: number, nullable: true }
              venta:  { type: number, nullable: true }