Conversión masiva USD/VES

POST /v1/fx/bulk/convert · Escala · Una consulta de cuota por lote. Límite adicional: 300 llamadas por hora por cuenta, compartido entre sus claves.

Consulta

Campo JSON	Regla
`from`, `to`	`USD` → `VES` o `VES` → `USD`. No admite EUR.
`amounts`	Array de 1 a 50 números finitos, mayores que 0 y como máximo `1e12`.
`market`	Opcional; por defecto `reference`. Debe cotizar en USD y estar incluido en tu plan.

Envía amounts y market. items y via no son campos de este endpoint. Los campos desconocidos del body pueden ignorarse: un via no selecciona mercado. Los mercados de remesa solo admiten USD → VES; eur_reference no es válido aquí. Los ejemplos se ejecutan en el servidor. JavaScript y Python usan los clientes del inicio rápido; configura allí COTIZAVE_API_KEY.

curl --fail-with-body --max-time 10 "https://api.cotizave.com/v1/fx/bulk/convert" \
  -H "X-API-Key: $COTIZAVE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"from":"USD","to":"VES","amounts":[100,250,500,1000],"market":"parallel"}'

import { cotizave } from './cotizave.mjs';

const data = await cotizave('/v1/fx/bulk/convert', {
  method: 'POST',
  body: {"from": "USD", "to": "VES", "amounts": [100, 250, 500, 1000], "market": "parallel"}
});
console.log(data);

from cotizave import cotizave

data = cotizave('/v1/fx/bulk/convert', method='POST', body={'from': 'USD', 'to': 'VES', 'amounts': [100, 250, 500, 1000], 'market': 'parallel'})
print(data)

Respuesta

Respuesta ilustrativa: las cifras y fechas no son cotizaciones actuales.

{
  "rate": 638.87,
  "market": "parallel",
  "type": "parallel",
  "updated_at": "2026-10-19T17:25:00Z",
  "results": [
    {
      "amount": 100,
      "result": 63887.0
    },
    {
      "amount": 250,
      "result": 159717.5
    },
    {
      "amount": 500,
      "result": 319435.0
    },
    {
      "amount": 1000,
      "result": 638870.0
    }
  ],
  "total_in": 1850,
  "total_out": 1181909.5
}

rate, market, type y updated_at describen la tasa común. results conserva el orden de amounts; cada elemento contiene la entrada amount y su result, redondeado a dos decimales. total_in suma entradas y total_out suma resultados. Este endpoint no devuelve effective_date ni stale. Cabeceras: X-RateLimit-Cost: 1, X-Bulk-Operations con el número de montos, y X-Bulk-RateLimit-Limit / X-Bulk-RateLimit-Remaining para el límite horario.

Listas de precios y reportes

Agrupa hasta 50 importes con la misma moneda, mercado y fecha de valoración. Asocia cada resultado con su entrada por posición. No recalcules facturas pasadas con la tasa actual; conserva la tasa utilizada al emitirlas. Para un catálogo grande también puedes obtener un snapshot y calcular localmente con una política explícita de redondeo.

Errores

Un body inválido, una moneda incompatible o más de 50 montos devuelve 400. Un array vacío devuelve missing_field. El plan insuficiente devuelve 402 feature_not_in_plan. El límite horario devuelve 429 rate_limit_exceeded con Retry-After; no presupongas que todo 429 tiene X-RateLimit-Scope.

{"code":"invalid_format","message":"Max 50 amounts per request.","field":"amounts","details":{"max":50,"got":73}}

{"code":"feature_not_in_plan","message":"This feature ('bulk_convert') requires a plan upgrade.","details":{"feature":"bulk_convert","current_plan":"indie"}}

Además pueden producirse los errores comunes de autenticación, cuota o disponibilidad. Las respuestas de error de la API son JSON; decide por code, no por el texto de message.

Consideraciones

Cada lote usa una sola tasa; no mezcla mercados. Una conversión es un cálculo informativo: Cotizave no ejecuta pagos ni cambios de divisas.

Documentación

Empezar

API

Venezuela: endpoints

Índices

Guías

Conversión masiva USD/VES

Consulta

Respuesta

Listas de precios y reportes

Errores

Consideraciones

​Consulta

​Respuesta

​Listas de precios y reportes

​Errores

​Consideraciones

Consulta

Respuesta

Listas de precios y reportes

Errores

Consideraciones