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

# Integrar BCV en facturación

> Obtén una referencia BCV y conserva tasa, fecha valor y resultado para trazabilidad.

<span id="por-que" />

## Alcance de la integración

Esta guía cubre la obtención y el registro de una tasa. La API no determina impuestos, retenciones ni requisitos fiscales de una factura. Configura esas reglas por separado según la operación y la jurisdicción; no reutilices reglas venezolanas para Australia o Argentina.

<span id="obtener-tasa" />

## Consultar BCV

Usa `reference` para USD y `eur_reference` para EUR. La conversión devuelve la tasa aplicada y, para BCV, `effective_date`. `updated_at` describe actualización; la fecha valor describe desde cuándo aplica la publicación.

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/convert?from=USD&to=VES&amount=120&via=reference" \
    -H "X-API-Key: $COTIZAVE_API_KEY"
  ```

  ```javascript Node.js theme={null}
  import { cotizave } from './cotizave.mjs';

  const data = await cotizave('/v1/fx/convert?from=USD&to=VES&amount=120&via=reference');
  console.log(data);
  ```

  ```python Python theme={null}
  from cotizave import cotizave

  data = cotizave('/v1/fx/convert?from=USD&to=VES&amount=120&via=reference')
  print(data)
  ```
</CodeGroup>

<span id="ejemplo" />

## Preparar un registro trazable

Ejemplo del servidor con el cliente del [inicio rápido](/api/quickstart#paso-2). Produce un registro candidato: antes de emitir una factura debes validar la fecha valor para la fecha y operación correspondientes, y persistirlo de forma transaccional con el documento.

```javascript theme={null}
import { cotizave } from './cotizave.mjs';
const conversion = await cotizave(
  '/v1/fx/convert?from=USD&to=VES&amount=120&via=reference'
);
if (conversion.market !== 'reference' || !conversion.effective_date || conversion.stale) {
  throw new Error('BCV reference requires review before invoicing');
}
const candidate = {
  source_amount: conversion.from,
  converted_amount: conversion.to,
  rate: conversion.rate,
  market: conversion.market,
  effective_date: conversion.effective_date,
  source_updated_at: conversion.updated_at,
  retrieved_at: new Date().toISOString()
};
console.log(candidate);
```

`stale: false` es una comprobación técnica, no la aprobación de una factura. Una fecha valor anterior puede seguir vigente durante días no hábiles; no exijas que coincida siempre con el día de consulta. Los importes de impuestos y su redondeo pertenecen a tu motor de facturación.

<span id="recomendaciones" />

## Errores y conservación

Conserva la referencia usada y no recalcules documentos emitidos con tasas nuevas. Si falla la API, un respaldo solo es admisible si tu aplicación puede validar su vigencia. Si no puede, detén la emisión e informa indisponibilidad. No sustituyas BCV por paralelo ni por el índice. El histórico por captura no sustituye la fecha valor archivada.


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