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 del riel 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: el riel de bolívares es asíncrono. El desenlace llega por webhook.
Listados paginados por cursor (limit + cursor), no por offset.
Mínimo por operación: 1 token del riel, ~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