Integrate BCV into invoicing - Cotizave

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.

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. Run these examples on your server. JavaScript and Python use the clients in the quickstart; configure COTIZAVE_API_KEY there.

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"

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

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

from cotizave import cotizave

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

Prepare a traceable record

Server example using the quickstart client. 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.

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.

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.