API: tasa de cambio

Leer la tasa del BCV y la del negocio, y fijar la tasa manual o volver a la oficial desde tu sistema.

Revisado el 28 de octubre de 2026

Cómo funciona la tasa

Los precios del negocio van en su moneda base (dólares o euros) y se convierten a bolívares con una tasa. El negocio elige entre dos modos:

bcv: la tasa oficial del Banco Central de Venezuela, que se actualiza sola.
manual: una tasa fija que pone el negocio (o tu integración). Se aplica solo a la moneda base; las demás siguen con la del BCV.

Con la API tu sistema puede leer las dos y fijar la manual, por ejemplo para que el bot cotice con la misma tasa que usa tu caja.

Leer la tasa

GET/rate

json

{
  "object": "rate",
  "mode": "manual",
  "manual_rate": "38.5000",
  "base_currency": "USD",
  "bcv": { "usd": 36.52, "eur": 39.87, "source": "bcv", "value_date": "2026-10-19" },
  "effective": { "usd": 38.5, "eur": 39.87 }
}

Campo	Tipo	Qué es
`object`	texto	Siempre `rate`.
`mode`	texto	`bcv` o `manual`: el modo en que está el negocio.
`manual_rate`	importe \| null	La tasa manual guardada, en bolívares por 1 unidad de la moneda base, con 4 decimales. Se conserva aunque el negocio esté en modo bcv.
`base_currency`	texto	La moneda base: `USD` o `EUR`.
`bcv.usd`	número	Bolívares por 1 dólar según el BCV. bcv.eur, lo mismo por 1 euro.
`bcv.source`	texto \| null	De dónde salen `bcv.usd` y `bcv.eur`: `bcv` si las publicó el BCV, `fallback` si el BCV no respondió y son una tasa de referencia (no la llames «del BCV»). `null` si todavía no hay tasa.
`bcv.value_date`	fecha \| null	Fecha valor de esa tasa (AAAA-MM-DD). La del BCV suele ser el día hábil siguiente al que la publica.
`effective.usd`	número	La tasa que usa el negocio ahora para el dólar (y `effective.eur`, para el euro): en modo manual, la manual para la moneda base y la del BCV para la otra; en modo bcv, las del BCV. Es la que tienes que usar para convertir como lo hace el bot.

Cambiar la tasa

PUT/rate

Cuerpo (hay que mandar al menos uno de los dos):

Campo	Qué es
`mode`	`bcv` o `manual`.
`manual_rate`	Número mayor que 0: bolívares por 1 unidad de la moneda base. Se guarda con 4 decimales.

Mandas	Qué pasa
`{ "manual_rate": 38.5 }`	Guarda la tasa y pasa el negocio a modo manual.
`{ "mode": "manual" }`	Pasa a modo manual con la tasa que ya tenía guardada. Si no tiene ninguna: `400 missing_manual_rate`.
`{ "mode": "manual", "manual_rate": 38.5 }`	Las dos cosas.
`{ "mode": "bcv" }`	Vuelve a la tasa del BCV. La manual queda guardada para la próxima vez.
`{ "mode": "bcv", "manual_rate": 38.5 }`	Guarda esa tasa manual, pero el negocio sigue con la del BCV.

curl

curl -X PUT https://api.atiendefacil.com/api/v1/rate \
  -H "Authorization: Bearer af_live_TU_CLAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "manual_rate": 38.5 }'

curl

curl -X PUT https://api.atiendefacil.com/api/v1/rate \
  -H "Authorization: Bearer af_live_TU_CLAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "bcv" }'

Responde 200 con la tasa como la de GET /rate, ya con el cambio. Se puede repetir sin miedo: mandar lo mismo dos veces deja lo mismo.

Qué pasa al cambiarla

El bot cotiza con la tasa nueva desde el siguiente mensaje, y el panel y la app la enseñan igual que si el dueño la hubiera cambiado en Ajustes.
Los pedidos que ya existen no cambian: cada uno guarda la tasa con la que se hizo.
Queda en la auditoría: «fijó la tasa manual en 38.5 desde la API».
Sale el webhook rate.updated, con source para que tu sistema reconozca que el cambio lo hizo él.

Errores

Respuesta	Cuándo
400 invalid_body	No mandaste ni mode ni manual_rate, mode no es bcv ni manual, o manual_rate no es un número mayor que 0.
400 missing_manual_rate	Pediste modo manual sin manual_rate y el negocio no tiene ninguna guardada.

El webhook rate.updated

Sale cuando cambia el modo, la tasa manual o la moneda base del negocio, lo haga quien lo haga: el dueño en el panel, alguien en la app o tu integración. No sale cuando el BCV publica una tasa nueva: para la del BCV, consulta GET /rate.

json

{
  "object": { "object": "rate", "mode": "manual", "manual_rate": "38.5000", "base_currency": "USD" },
  "mode": "manual",
  "manual_rate": 38.5000,
  "base_currency": "USD",
  "previous_mode": "bcv",
  "previous_manual_rate": null,
  "source": "api:9f1c2b3a-4d5e-4f60-8a7b-1c2d3e4f5a6b"
}

data.object es la tasa guardada (sin bcv ni effective).
data.mode, data.manual_rate y data.base_currency son los valores nuevos del momento del cambio; data.previous_mode y data.previous_manual_rate, los de antes. Aquí las tasas vienen como número, no como texto.
data.source solo viene si el cambio se hizo por la API: api: y el id de la clave.

Preguntas frecuentes

¿Puedo cambiar la moneda base por la API?

No. Se cambia en Ajustes → Tasa de cambio, en el panel o la app.

¿Cada cuánto conviene fijar la tasa?

Cuando cambie la tuya. La tasa manual no se actualiza sola: si tu sistema deja de mandarla, el negocio sigue cotizando con la última.

AnteriorAPI: citas y viajes Siguiente API: recetas paso a paso

¿No encontraste lo que buscabas?

Escríbenos y te responde una persona del equipo.

WhatsApp Soporte