Overview

Dispersión de bolívares — API 1.0.0

API para dispersar bolívares: entregamos Bs en Venezuela por pago móvil o por transferencia bancaria.

El recorrido completo son tres llamadas: cotizas (POST /quotes) → das de alta al beneficiario (POST /beneficiaries, o lo mandas en línea) → dispersas (POST /payouts). Todo lo demás que hay aquí sirve para saber qué pasó después: el estado del pago, el extracto, el webhook y tu saldo.

Convenciones:

Montos en minor units (enteros, nunca decimales). BS tiene 2 decimales: 5000000 son 50.000,00 Bs. En la petición van como número entero; en la respuesta, como string.
Cotizar es fijar un lado y recibir los dos: mandas amount en deliver (lo que recibe el beneficiario) o en spend (lo que se te cobra), nunca en los dos. La respuesta es la misma en los dos casos — fixed, spend, deliver, fee y rate—, así que el importe entregado se lee siempre en deliver.amount.
Cotizar es gratis: no reserva saldo, no consume límites y no genera consumo facturable. Cotiza tantas veces como quieras y consume la última.
Toda operación que mueve dinero acepta —y debe llevar— Idempotency-Key.
Errores con código estable: programa contra error.code, nunca contra el mensaje. Ojo: los rechazos de la red de pago NO son error.code — llegan como 201 con status: failed y el motivo en reason.
submitted es el desenlace HABITUAL de una dispersión, no settled: la red de pago de bolívares es asíncrona. El desenlace llega por webhook.
Listados paginados por cursor (limit + cursor), no por offset.
Versión 2026-11-03: la API en inglés que documenta este contrato. Las cuentas anteriores siguen 90 días en 2026-10-22 (los nombres en español); prueba con el header BC-Version: 2026-11-03 y pásate con PUT /tenant/api-version. Usar un nombre viejo responde con los headers Deprecation y Sunset. pago_movil y transferencia no cambian: son los nombres de los métodos de pago venezolanos.
Mínimo por operación: ~925,00 Bs a la tasa medida. El piso está en tokens, así que en bolívares se mueve con la tasa.
Tope por operación en pago móvil: 100.000,00 Bs; en transferencia, 500.000,00 Bs. Los fija el ecosistema bancario venezolano.

Superficie reducida a propósito. Este contrato publica sólo la dispersión de bolívares. La plataforma hace más cosas (banca y cuentas emitidas, onboarding con KYC y firma, tesorería, conciliación, routing, consumo, administración), pero esas rutas no se documentan de momento para que la integración tenga una sola superficie que entender y ninguna decisión que tomar de más.

Las rutas ocultas siguen existiendo y siguen protegidas por los scopes de la API key: no se han quitado de la aplicación. Están al final de la sección paths de este archivo, comentadas y completas. Reactivarlas es quitar el # de esas líneas — y, si toca, descomentar sus tags y sus schemas. Ver la nota que las precede.

Guía narrativa: INTEGRACION.md

Information

OpenAPI version: 3.0.3

Authentication

ApiKeyAuth

Security scheme type: apiKey

Header parameter name: x-api-key

Overview

Dispersión de bolívares — API 1.0.0

Operations

Authentication

ApiKeyAuth