Integrar BCV en facturación

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.

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; configura allí COTIZAVE_API_KEY.

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)

Preparar un registro trazable

Ejemplo del servidor con el cliente del inicio rápido. 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.

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.

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.

Documentación

Empezar

API

Venezuela: endpoints

Índices

Guías

Integrar BCV en facturación

Alcance de la integración

Consultar BCV

Preparar un registro trazable

Errores y conservación

​Alcance de la integración

​Consultar BCV

​Preparar un registro trazable

​Errores y conservación

Alcance de la integración

Consultar BCV

Preparar un registro trazable

Errores y conservación