API activa · v0.1.0

Cotipy API

API RESTful que sirve cotizaciones de monedas del Paraguay en tiempo real, obtenidas de tres fuentes oficiales: BCP, Maxicambios y Cambios Chaco. Caché inteligente, historial persistido y respuestas en JSON.

Swagger UI → ReDoc Empezar

Inicio rápido

No se requiere autenticación. Todas las respuestas son JSON con campos en español. El primer request scrapea las fuentes en paralelo; los subsiguientes se sirven desde caché (TTL configurable, por defecto 5 minutos).

🔗

Base URL

https://tu-dominio.com

🔓

Autenticación

No requerida

📦

Formato

JSON · UTF-8

⚡

Caché TTL

5 minutos

Tu primera solicitud

BASH

curl https://tu-dominio.com/api/v1/cotizaciones

ℹ️ Si el scraper de alguna fuente falla, la API retorna la última caché disponible con el campo desactualizado: true en lugar de un error 503. Solo se retorna 503 cuando todas las fuentes fallan simultáneamente.

Fuentes de datos

Cotipy obtiene cotizaciones de tres fuentes paraguayas en paralelo. Cada fuente se identifica con el valor del parámetro fuente.

Banco Central del Paraguay

bcp

Tasas referenciales oficiales. 26 monedas. Sin sucursales. Solo campo referencial.

referencial

Maxicambios

maxicambios

Compra/venta y arbitraje. 4 sucursales: Asunción, CDE, Cheques y Arbitraje.

efectivoarbitraje

Cambios Chaco

cambios_chaco

Compra/venta y arbitraje. 27 monedas disponibles.

efectivoarbitraje

Tipos y modelos

SourceName — Fuente

Valor	Descripción
"bcp"	Banco Central del Paraguay
"maxicambios"	Maxicambios (4 sucursales)
"cambios_chaco"	Cambios Chaco

RateType — Tipo de cotización

Valor	Descripción
"referencial"	Tasa referencial del BCP. Sin compra/venta; solo campo `referencial`.
"efectivo"	Compra y venta en efectivo de casas de cambio.
"arbitraje"	Tasas cruzadas de arbitraje.

Modelo CurrencyRate — cotización individual

JSON

{
  "moneda":      "USD",                  // Código ISO 4217
  "nombre":      "Dólar Estadounidense",
  "compra":      6300.0,                 // null para BCP
  "venta":       6400.0,                 // null para BCP
  "referencial": null,                   // solo BCP
  "tipo":        "efectivo",             // referencial | efectivo | arbitraje
  "fuente":      "maxicambios",          // bcp | maxicambios | cambios_chaco
  "sucursal":    "asuncion"              // null si no aplica
}

Sucursales de Maxicambios

Valor	Descripción
"asuncion"	Casa central, Asunción
"cde"	Ciudad del Este
"cheques"	Tasas para cheques
"arbitraje"	Tasas de arbitraje

Cotizaciones en vivo

GET /api/v1/cotizaciones

Retorna las cotizaciones actuales de todas las fuentes activas (o de una fuente específica si se pasa el parámetro fuente). Las fuentes se scrapen en paralelo. Cada respuesta exitosa guarda los datos en la base de historial de forma asíncrona.

Parámetros de consulta (todos opcionales)

Parámetro	Tipo	Descripción
fuenteopcional	SourceName	Limitar a una fuente: `bcp`, `maxicambios`, `cambios_chaco`
tipoopcional	RateType	Filtrar por tipo: `referencial`, `efectivo`, `arbitraje`
sucursalopcional	string	Filtrar por sucursal: `asuncion`, `cde`, `cheques`, `arbitraje`

Ejemplos

BASH

# Todas las fuentes
curl https://tu-dominio.com/api/v1/cotizaciones

# Solo BCP
curl https://tu-dominio.com/api/v1/cotizaciones?fuente=bcp

# Compra/venta en Asunción (Maxicambios)
curl https://tu-dominio.com/api/v1/cotizaciones?tipo=efectivo&sucursal=asuncion

Respuesta

JSON · 200 OK

{
  "fuentes": [
    {
      "fuente":         "bcp",
      "cotizaciones":  [
        {
          "moneda":      "USD",
          "nombre":      "Dólar Estadounidense",
          "compra":      null,
          "venta":       null,
          "referencial": 6416.86,
          "tipo":        "referencial",
          "fuente":      "bcp",
          "sucursal":    null
        }
        // ... 25 monedas más
      ],
      "actualizado_en": "2026-04-14T03:00:00Z",
      "desactualizado": false,
      "error":          null
    },
    // ... maxicambios, cambios_chaco
  ],
  "actualizado_en": "2026-04-14T03:00:00Z"
}

GET /api/v1/cotizaciones/{moneda}

Retorna las cotizaciones de una moneda específica en todas las fuentes activas. Usar el código ISO 4217 en cualquier capitalización (USD, eur, BRL).

Parámetro de ruta

Parámetro	Tipo	Descripción
monedarequerido	string	Código ISO 4217: `USD`, `EUR`, `BRL`, `ARS`, `JPY`…

Ejemplos

BASH

curl https://tu-dominio.com/api/v1/cotizaciones/USD

curl https://tu-dominio.com/api/v1/cotizaciones/EUR

curl https://tu-dominio.com/api/v1/cotizaciones/BRL

Respuesta

JSON · 200 OK

{
  "fuentes": [
    {
      "fuente": "maxicambios",
      "cotizaciones": [
        {
          "moneda":   "USD",
          "nombre":   "Dólar",
          "compra":   6300.0,
          "venta":    6400.0,
          "tipo":     "efectivo",
          "fuente":   "maxicambios",
          "sucursal": "asuncion"
        },
        {
          "moneda":   "USD",
          "nombre":   "Dólar",
          "compra":   6280.0,
          "venta":    6400.0,
          "tipo":     "efectivo",
          "fuente":   "maxicambios",
          "sucursal": "cde"
        }
      ],
      "desactualizado": false,
      "error": null
    }
  ],
  "actualizado_en": "2026-04-14T03:00:00Z"
}

GET /api/v1/cotizaciones/sources/{fuente}

Retorna todas las cotizaciones de una fuente específica. Equivale a /api/v1/cotizaciones?fuente=… pero en formato SourceResult plano (sin el envoltorio de lista de fuentes).

Parámetro de ruta

Parámetro	Tipo	Descripción
fuenterequerido	SourceName	`bcp` · `maxicambios` · `cambios_chaco`

Ejemplos

BASH

curl https://tu-dominio.com/api/v1/cotizaciones/sources/bcp

curl https://tu-dominio.com/api/v1/cotizaciones/sources/maxicambios

curl https://tu-dominio.com/api/v1/cotizaciones/sources/cambios_chaco

Respuesta

JSON · 200 OK

{
  "fuente":        "cambios_chaco",
  "cotizaciones":  [ /* lista de CurrencyRate */ ],
  "actualizado_en": "2026-04-14T03:00:00Z",
  "desactualizado": false,
  "error":          null
}

Historial

GET /api/v1/historial/{moneda}

Retorna el historial de cotizaciones almacenadas en base de datos para una moneda. Cada registro corresponde a una cotización guardada durante un scrape o refresco automático. Los resultados vienen ordenados del más reciente al más antiguo.

Parámetro de ruta

Parámetro	Tipo	Descripción
monedarequerido	string	Código ISO 4217 (`USD`, `EUR`, `BRL`…)

Parámetros de consulta (todos opcionales)

Parámetro	Tipo	Default	Descripción
fuente	SourceName	—	Filtrar por fuente
fecha_desde	date	—	Inicio del rango. Formato `YYYY-MM-DD`
fecha_hasta	date	—	Fin del rango. Formato `YYYY-MM-DD`
sucursal	string	—	Filtrar por sucursal
limite	integer	`100`	Máximo de registros. Rango: 1 – 500

Ejemplos

BASH

# Últimos 100 registros de USD
curl https://tu-dominio.com/api/v1/historial/USD

# USD desde el 1 de abril, máximo 50
curl https://tu-dominio.com/api/v1/historial/USD?fecha_desde=2026-04-01&limite=50

# USD de Maxicambios Asunción
curl https://tu-dominio.com/api/v1/historial/USD?fuente=maxicambios&sucursal=asuncion

Respuesta

JSON · 200 OK

{
  "moneda":   "USD",
  "total":    248,          // total en DB (sin aplicar limite)
  "registros": [
    {
      "id":            53,
      "moneda":        "USD",
      "nombre":        "Dólar Estadounidense",
      "fuente":        "bcp",
      "compra":        null,
      "venta":         null,
      "referencial":   6416.86,
      "tipo":          "referencial",
      "sucursal":      null,
      "registrado_en": "2026-04-14T03:00:00Z"
    }
    // ... hasta `limite` registros
  ]
}

GET /api/v1/historial/{moneda}/diario

Retorna los promedios diarios de compra, venta y referencial para una moneda, agrupados por día, fuente y sucursal. Útil para construir gráficos de tendencia histórica.

Parámetro de ruta

Parámetro	Tipo	Descripción
monedarequerido	string	Código ISO 4217

Parámetros de consulta (todos opcionales)

Parámetro	Tipo	Descripción
fuente	SourceName	Filtrar por fuente
fecha_desde	date	Inicio del rango `YYYY-MM-DD`
fecha_hasta	date	Fin del rango `YYYY-MM-DD`

Ejemplo

BASH

curl https://tu-dominio.com/api/v1/historial/USD/diario?fecha_desde=2026-04-01

Respuesta

JSON · 200 OK

{
  "moneda": "USD",
  "promedios": [
    {
      "fecha":                "2026-04-14",
      "fuente":               "bcp",
      "moneda":               "USD",
      "compra_promedio":      null,
      "venta_promedio":       null,
      "referencial_promedio": 6416.86,
      "sucursal":             null
    },
    {
      "fecha":                "2026-04-14",
      "fuente":               "maxicambios",
      "moneda":               "USD",
      "compra_promedio":      6300.0,
      "venta_promedio":       6400.0,
      "referencial_promedio": null,
      "sucursal":             "asuncion"
    }
  ]
}

Health Check

GET /health

Retorna el estado de salud de la aplicación: disponibilidad del caché de cada fuente y estado de la base de datos. Sin parámetros. Ideal para liveness probes en Docker o Coolify.

Ejemplo

BASH

curl https://tu-dominio.com/health

Respuesta

JSON · 200 OK

{
  "estado":        "ok",
  "version":       "0.1.0",
  "fuentes": {
    "bcp":           "ok",
    "maxicambios":   "ok",
    "cambios_chaco": "ok"
  },
  "base_de_datos": "ok"
}

Estados posibles por fuente

Valor	Significado
"ok"	Caché vigente disponible (TTL no vencido)
"desactualizado"	Solo caché vencida disponible (el último scrape falló)
"error"	Sin datos disponibles en caché
"deshabilitado"	Fuente desactivada por configuración de entorno

Desarrollado por IPYAHU

Cotipy es un proyecto open source desarrollado por el equipo de IPYAHU, enfocado en soluciones tecnológicas para el ecosistema paraguayo.

ipyahu.com →