Changelog

Notas de
actualización.

Cambios, mejoras y correcciones de la API de Cotizave, en orden cronológico inverso.

  1. Fixv1.9.1

    Cambios de acceso por plan que no se anunciaron en su momento

    Entre mayo y septiembre cambió qué planes acceden a varias funciones, y ninguno de esos cambios llegó al changelog. Se publican ahora, con su fecha real, en vez de dejarlos sin registro.

    • 10 de mayo de 2026 — GET /v1/fx/route pasó a estar disponible solo desde el plan Escala. Antes alcanzaba con Profesional. Es el único de esta lista que redujo el acceso de alguien, y debió anunciarse cuando ocurrió.
    • 16 de mayo de 2026 — el snapshot del BCV (/v1/fx/bcv/banks y /v1/fx/bcv/currencies) pasó a estar disponible en todos los planes, incluido Gratis. Ese mismo día se amplió el acceso al catálogo de bancos venezolanos y a la validación de RIF y cuenta bancaria, pero esos endpoints todavía no están expuestos: responden 403 hasta que terminemos de validarlos. Se anunciarán cuando se habiliten, no antes.
    • 15 de junio de 2026 — la validación de RIF y cuenta bancaria y el calendario de feriados venezolanos salieron de la oferta comercial. No estaban expuestos, así que ninguna integración se vio afectada; el código y las rutas quedan intactos por compatibilidad.
    • 8 de agosto de 2026 — GET /v1/fx/spread quedó disponible en todos los planes. Se calcula sobre el snapshot que ya está en caché y es replicable con la respuesta de /v1/fx/rates, así que gatearlo era fricción sin contrapartida.
    • 15 de agosto de 2026 — el histórico por fecha quedó disponible en todos los planes; lo que escala con el plan es la profundidad. En la misma fecha, las reglas de markup volvieron a ser exclusivas de planes de pago: en el plan Gratis solo se podían crear, nunca aplicar, porque el uso de ?markup= siempre exigió plan de pago. Se corrigió una inconsistencia, no se retiró una función que funcionara.
    • 5 de septiembre de 2026 — CoinEx y KuCoin salieron del catálogo de mercados. Se anunciaban en la documentación, en los legales y en el marketing sin que la API los sirviera.
  2. APIv1.9.0

    Respuestas en CSV y XML

    Cualquier endpoint con API key puede devolver CSV o XML además de JSON, con ?format= o el header Accept. Disponible desde el plan Esencial.

    • Nuevo parámetro ?format=csv|xml|json y negociación por Accept. Si mandas los dos, gana el parámetro de la URL.
    • El CSV convierte la colección de la respuesta en filas y repite los campos del sobre en cada una, prefijados con su nombre (rates.mid). Se descarga como archivo si abres la URL en el navegador.
    • El XML no lleva atributos ni namespaces: cada campo es un elemento con el mismo nombre que su clave JSON, y los elementos de un arreglo se llaman <item>.
    • Los errores siguen llegando en JSON aunque pidas otro formato, para que el código de estado y la estructura code/message no cambien nunca.
    • GET /v1/fx/route no admite CSV: devuelve dos colecciones y no hay una sola tabla que las represente. Responde 406 nombrando cuáles; en XML y JSON funciona igual que siempre.
    • JSON sigue siendo el formato por defecto en todos los planes: nada cambia si no pides nada.
  3. APIv1.8.0

    La tasa del BCV ahora dice desde qué día rige

    Las cotizaciones de referencia incluyen effective_date, la fecha valor publicada por el BCV. Resuelve la confusión de ver un número distinto al de bcv.org.ve.

    • Nuevo campo effective_date (YYYY-MM-DD) en reference y eur_reference, disponible en /v1/fx/rates, /v1/fx/rates/:market, /v1/fx/convert y el endpoint público de tasas.
    • El BCV publica los días hábiles con vigencia para el siguiente día hábil: la tasa del viernes rige también sábado y domingo. Por eso su web puede mostrar un número mientras la API sirve otro — el que rige hoy.
    • Si emites facturas, effective_date es el campo que conviene archivar junto al monto: identifica con qué publicación oficial se calculó.
    • Corregido el umbral de frescura del BCV. Una tasa de fin de semana ya no se marca como vencida: el hueco legítimo entre publicaciones llega a cinco días con feriados largos.
    • El resto de los mercados no lleva effective_date: el paralelo y los P2P no tienen publicación oficial, su updated_at ya es un instante real.
  4. APIv1.7.0

    Profesional sube a 6 meses de histórico

    El plan Profesional pasa de 3 a 6 meses de retención en el endpoint de histórico. Gratis, Esencial y Escala no cambian.

    • Retención de histórico en Profesional: 90 → 180 días.
    • Gratis se mantiene en 14 días, Esencial en 90 y Escala en 1 año.
    • Sin cambios de contrato: mismos parámetros y formato de respuesta de GET /v1/fx/rates/:market/history.
  5. Fixv1.6.0

    Respuestas 429 con información accionable

    Un 429 ahora te dice contra qué límite chocaste y cuánto esperar con precisión. Antes X-RateLimit-Remaining reportaba 0 en cualquier rechazo, incluso cuando te quedaba casi toda la cuota del mes.

    • X-RateLimit-Remaining refleja tu cuota real. Si el rechazo fue por velocidad, tu saldo mensual aparece intacto — antes decía 0 y podía leerse como "agotaste el plan".
    • X-RateLimit-Scope distingue burst (pediste demasiado rápido) de monthly (agotaste la cuota). Se resuelven distinto: el primero espaciando pedidos, el segundo con más volumen.
    • X-RateLimit-Limit-Second y X-RateLimit-Burst publican tus límites de velocidad; antes había que descubrirlos chocando.
    • X-RateLimit-Retry-After-Ms trae la espera exacta en milisegundos. Retry-After solo admite segundos enteros, así que en planes altos redondear a 1 segundo puede ser 30 veces más de lo necesario.
    • El cuerpo del error incluye details con kind, retry_after y retry_after_ms.
    • Todos los headers están expuestos vía CORS, así que se leen desde el navegador.
  6. APIv1.5.0

    Histórico por rango y serie completa

    El endpoint de histórico ahora devuelve series completas, no solo un punto. Sin parámetros trae toda tu retención; con ?from=&to= un rango. El modo ?date= sigue devolviendo un único valor, igual que antes.

    • GET /v1/fx/rates/:market/history sin parámetros devuelve la serie completa dentro de la retención de tu plan.
    • Parámetros ?from=&to= (YYYY-MM-DD) acotan un rango de fechas; un solo día = from igual a to.
    • granularity=daily (default) da un punto de cierre por día; granularity=raw da cada captura, hasta 5.000 puntos.
    • La respuesta de colección incluye from, to, granularity, count y points[]. El modo ?date= no cambia su contrato.
    • Retención de histórico en ese momento: 90 días en Profesional y 1 año en Escala. Profesional pasó a 180 días en v1.7.0.
    • Disponible desde el plan Profesional.
  7. Newv1.4.0

    BingX y CoinEx — dos exchanges P2P nuevos (CoinEx retirado)

    Ampliamos la cobertura P2P con BingX y CoinEx. CoinEx se retiró del catálogo en septiembre de 2026: la cobertura P2P vigente es Binance, Bybit, OKX, Bitget, MEXC, BingX y Saldo.

    • BingX P2P añadido al agregador de tasas paralelas.
    • CoinEx P2P se anunció aquí y se retiró del catálogo en septiembre de 2026 por no servirse en la API. Esta entrada mencionaba además pares BTC/VES, que la API nunca expuso: los mercados P2P cotizan USDT/VES.
    • El campo `source` incorporó el identificador `bingx`. El de `coinex` dejó de estar disponible con su retiro.
    • La incorporación no degradó el tiempo de respuesta del snapshot: las fuentes se consultan en el ciclo de refresco, no dentro de la petición del cliente.
  8. APIv1.3.0

    Nuevo endpoint: GET /convert

    Se publica el endpoint de conversión directa. Convierte cualquier monto entre VES, USD, EUR o cualquier moneda soportada, usando la tasa del mercado que elijas.

    • GET /v1/fx/convert?from=USD&to=VES&amount=100&via=binance devuelve el monto convertido y la tasa usada.
    • El parámetro opcional se llama `via` —no `market`— y acepta cualquier mercado del catálogo.
    • La respuesta incluye `from` y `to` con el monto de cada lado, más `rate`, `market`, `type` y `updated_at`. Esta entrada anunciaba `converted_amount` y `fetched_at`, que nunca existieron.
    • Si `via` se omite, la conversión usa la tasa de referencia (BCV). Esta entrada decía que usaba una media ponderada de los P2P activos: es incorrecto y se corrige el 7 de septiembre de 2026, porque quien omitiera el parámetro creyendo recibir un promedio P2P estaba recibiendo la tasa oficial.
    • Disponible en todos los planes, incluyendo Gratis.
  9. APIv1.2.0

    Nuevo endpoint GET /spread

    El nuevo endpoint GET /spread compara dos mercados entre sí y devuelve la diferencia entre sus tasas: absoluta, porcentual y su dirección.

    • GET /spread acepta `against` y `base`, y devuelve `reference` y `compared` —cada uno con su market, su valor y su updated_at—, un bloque `spread` con `absolute`, `percentage` y `direction`, y el `fetched_at` de la consulta.
    • Corrección del 7 de septiembre de 2026: esta entrada describía campos `bid`, `ask`, `spread_pct`, `depth_bid` y `depth_ask`, y una "profundidad de primer nivel" por exchange. Nada de eso existió nunca. Cotizave no lee libros de órdenes ni expone profundidad en ningún endpoint, y /spread no es un diferencial bid/ask sino la diferencia entre dos mercados. La referencia del endpoint en la documentación siempre reflejó el contrato real; esta entrada no.
    • El endpoint quedó liberado a todos los planes el 8 de agosto de 2026.
    • Se agrega documentación interactiva del endpoint en /docs/api/endpoints/spread.
  10. Fixv1.1.0

    Headers de rate-limit y mejoras de errores

    Correcciones y mejoras de calidad de vida: headers de límite de tasa más precisos y códigos de error estandarizados según RFC 9457.

    • X-RateLimit-Remaining ahora se actualiza correctamente en cada respuesta, no solo al agotar el límite.
    • X-RateLimit-Reset devuelve un timestamp Unix en lugar de segundos relativos.
    • Los errores llevan un cuerpo estable con `code` y `message`. Esta entrada anunciaba el formato Problem Details (RFC 9457) con los campos `type`, `title`, `status` y `detail`: nunca se implementó y se corrige el 7 de septiembre de 2026.
    • El error 429 informa cuánto esperar. El detalle definitivo del cuerpo y de los headers quedó en v1.6.0.
    • Se corrige un bug donde llamadas concurrentes podían consumir doble cuota en condiciones de alta carga.
  11. Newv1.0.0

    Lanzamiento público de Cotizave API

    Primera versión estable de la API. Seis fuentes P2P, tasa BCV oficial y paralela, todo en un solo contrato.

    • GET /v1/fx/rates — snapshot de todos los mercados activos.
    • GET /v1/fx/rates/:market — tasa de un mercado específico (binance, bybit, okx, bitget, mexc, saldo, bcv, paralela).
    • Autenticación por API key en header X-API-Key.
    • Plan Gratis disponible con su propio rate limit.
    • Plan de pago con mayor volumen y más profundidad de histórico. Ningún plan incluyó nunca un SLA contractual: esta entrada lo mencionaba por error y se corrige el 7 de septiembre de 2026.
    • Documentación completa en /docs con ejemplos en cURL, Python y Node.js.

¿Tienes preguntas sobre un cambio?

Revisa la documentación o escríbenos. Respondemos en 2-3 días hábiles en los planes de pago.

Ver documentación →Contactar soporte