Tasa de cambio
Si tu saldo está en una moneda y pagas en otra, necesitas saber a qué tasa se convierte antes de emitir la operación. GET /v2/rate te devuelve la tasa que Alibanca publicó y sostiene para tu moneda — no una referencia de mercado ni un indicativo. Esta página explica qué te devuelve, cuándo no te devuelve nada (y por qué eso es deliberado), y cómo debe reaccionar tu integración en cada caso.
Cuándo lo necesitas (y cuándo no)
Depende de una sola cosa: la moneda de tu saldo.
Si tu saldo está en USD y dispersas bolívares, cada operación implica una conversión, y la tasa es el número que la define. La consultas antes de emitir, se la muestras a tu usuario, y decides si sigues.
Si tu saldo ya está en bolívares, no hay nada que convertir: fondeas en VES y pagas en VES. En ese caso este endpoint te responde 404 a propósito — ver más abajo.
GET /v2/rate — la tasa vigente para tu moneda
Devuelve la tasa publicada que aplica a tu moneda, cotizada contra la moneda de pago (bolívares). No recibe parámetros: el par sale de la moneda de tu saldo, así que dos clientes con monedas distintas que llamen al mismo endpoint reciben tasas distintas, cada uno la suya.
Autenticación
Es un endpoint autenticado: lleva x-api-key, x-nonce y x-signature con la firma del envelope canónico, igual que GET /v2/me. No mueve dinero, así que es seguro llamarlo tantas veces como necesites. El detalle del envelope está en Autenticación y firma →.
# GET /v2/rate — necesita x-api-key + x-nonce + x-signature (no mueve dinero)
curl https://api.alibanca.com/v2/rate \
-H "x-api-key: sk_test_..." \
-H "x-nonce: $NONCE" \
-H "x-signature: $FIRMA"{
"status": "ok",
"traceId": "01J9…",
"payload": {
"rateId": "184",
"base": "USD",
"quote": "VES",
"rate": "35000.500000000000",
"validFrom": "2026-09-13T14:02:11.000Z",
"expiresAt": "2026-09-13T20:02:11.000Z"
}
}Los campos, uno por uno
rate viaja como texto, no como número. Y no es un detalle de estilo: la tasa tiene doce decimales, y el tipo numérico de JavaScript (y el de muchos lenguajes) los pierde en silencio al parsear el JSON. Si la conviertes a float para mostrarla está bien; si la usas para calcular un monto, léela con un tipo decimal exacto. Un céntimo perdido por operación, multiplicado por tu volumen, deja de ser un céntimo.
rateId identifica esa publicación, no el número. Si publicamos otra vez el mismo valor, el rateId es distinto. Guárdalo junto a la operación: es lo que te permite decir después «cotizé contra ésta».
base y quote te dicen la dirección. rate son unidades de quote por una de base. Con base: "USD" y quote: "VES", un rate de 35000.5 significa 35.000,5 bolívares por dólar.
validFrom y expiresAt son la ventana. Fuera de ella el endpoint deja de servir esa tasa — no la sirve «vencida pero igual».
Los dos casos en que NO te devuelve una tasa
Este endpoint falla cerrado: cuando no puede darte una tasa buena, no te da ninguna. Nunca devuelve 0, nunca devuelve 1, y nunca te sirve una tasa vencida. Son dos situaciones distintas y te las distingue con dos códigos distintos, porque lo que tienes que hacer en cada una es distinto.
1 cuando no hay tasa convierte 100 dólares en 100 bolívares. Servir la última aunque haya vencido te cotiza contra un precio de hace tres días, que en este mercado no es un número viejo: es otro precio. Devolver 0 deja el monto destino en cero y el error aparece tres pasos después, donde nadie lo entiende. Preferimos decirte que no podemos.503 — no hay tasa vigente ahora mismo
{ "error": "no rate in force for USD/VES" }Existe el par y normalmente hay tasa, pero en este momento no hay ninguna vigente: o todavía no se publicó la primera, o la última venció y aún no se publicó la siguiente. Es temporal.
Qué debe hacer tu integración: reintentar con espera, y no emitir la operación mientras tanto. Si tu flujo le muestra la tasa a un usuario final, muéstrale «tasa no disponible, intenta en unos minutos» en vez de un cero o un campo vacío. Si tienes alertas, ésta es una que vale la pena escuchar: significa que del lado de Alibanca hay una tasa por renovar.
404 — tu saldo ya está en la moneda de pago
{ "error": "no rate applies: your wallet is already in VES" }Tu saldo está en bolívares y pagas en bolívares: no hay conversión que cotizar. Es estructural, no temporal — reintentar no cambia nada, y por eso no es un 503.
Qué debe hacer tu integración: no llamar a este endpoint. Si tu código lo llama de forma genérica para cualquier cliente, trátalo como «sin conversión» y sigue: tus operaciones en bolívares no necesitan tasa.
503 quiere decir «vuelve más tarde». 404 quiere decir «esta pregunta no aplica a ti». Si los tratas igual, vas a reintentar para siempre algo que nunca va a cambiar, o vas a dar por imposible algo que se arregla en minutos.Cómo usarla sin sorpresas
Consúltala cerca del momento de emitir, no al arrancar el proceso. La tasa tiene vigencia; una que leíste hace horas puede haber vencido. Si entre la consulta y la emisión pasa tiempo —porque hay un humano decidiendo en el medio— vuelve a consultarla antes de emitir.
Guarda rateId con la operación. Cuando alguien pregunte por qué el monto salió como salió, ese identificador es la respuesta, y es más útil que el número suelto.
No la caches más allá de expiresAt. Si la guardas en memoria para no consultarla en cada request, usa ese campo como vencimiento del caché. Cachearla «por cinco minutos» sin mirar la ventana es reintroducir por tu lado exactamente el problema que el 503 evita del nuestro.
Trata el 503 como un freno, no como un error de red. No es un fallo transitorio de infraestructura que se resuelva reintentando en 200 ms: es que no hay precio publicado. Espera y reintenta, pero no emitas.