> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotizave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversión masiva USD/VES

> Convierte entre 1 y 50 montos con la misma tasa. Disponible en Escala.

`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.

<span id="request" />

## 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](/api/quickstart#paso-2); configura allí `COTIZAVE_API_KEY`.

<CodeGroup>
  ```bash curl theme={null}
  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"}'
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

<span id="response" />

## Respuesta

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

```json theme={null}
{
  "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.

<span id="casos-uso" />

## 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.

<span id="errores" />

## 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`.

```json theme={null}
{"code":"invalid_format","message":"Max 50 amounts per request.","field":"amounts","details":{"max":50,"got":73}}
```

```json theme={null}
{"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](/api/errors) de autenticación, cuota o disponibilidad. Las respuestas de error de la API son JSON; decide por `code`, no por el texto de `message`.

<span id="notas" />

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.