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

# Integrate BCV into invoicing

> Fetch a BCV reference and retain the rate, value date and result for traceability.

<span id="por-que" />

## Integration scope

This guide covers retrieving and recording a rate. The API does not determine an invoice’s taxes, withholdings or fiscal requirements. Configure those rules separately for the transaction and jurisdiction; do not reuse Venezuelan rules for Australia or Argentina.

A point-of-sale system may display the applied rate and conversions to its merchants, including on Gratis and when charging for the software. The key stays on the server, and requests count against that account’s quota. See [applications for other businesses](/en/data-use#aplicaciones-para-clientes) to distinguish this use from redistribution that requires a special licence.

<span id="obtener-tasa" />

## Query BCV

Use `reference` for USD and `eur_reference` for EUR. Conversion returns the applied rate and, for BCV, `effective_date`. `updated_at` describes the update; the value date describes when the publication applies.

If you only need the rate for multiple sales, query `/v1/fx/rates` and select `market: reference`, or use `/v1/fx/rates/reference`, then calculate conversions within your application. A daily query may fit within the quota, but it does not guarantee the rate is applicable when used. Plan refreshes, retain the value date and validate the reference before fixing amounts.

Run these examples on your server. JavaScript and Python use the clients in the [quickstart](/en/api/quickstart#paso-2); configure `COTIZAVE_API_KEY` there.

<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" />

## Prepare a traceable record

Server example using the [quickstart client](/en/api/quickstart#paso-2). Produces a candidate record: before issuing an invoice, validate the value date for the relevant date and transaction, then persist it transactionally with the document.

```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` is a technical check, not invoice approval. An earlier value date may remain applicable over non-business days; do not require it to always equal the query date. Tax amounts and their rounding belong to your invoicing engine.

<span id="recomendaciones" />

## Errors and retention

Retain the reference used and do not recalculate issued records with newer rates. If the API fails, a fallback is acceptable only if your application can validate its applicability. Otherwise, stop issuance and report unavailability. Do not replace BCV with parallel or the index. Capture-based history does not replace the archived value date.


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