Haz hoy tu primera llamada a la API de Venly Finance, en tu propio equipo

Desarrolladores

El SDK de TypeScript tiene un modo mock que no necesita registro, credenciales ni red. Instala un paquete, crea una parte (party) y mira cómo pasa por los estados que describe la documentación. Cuando hayamos definido tu flujo contigo, el mismo código funciona en el sandbox con las credenciales que te envía Venly.

Haz tu primera llamada

Solicita credenciales del sandbox

Tres entornos, un mismo código

Modo mock

Hoy

Sin registro, sin credenciales, sin red. Funciona en tu equipo.

Sandbox

Tras una reunión de alcance

Credenciales enviadas directamente a ti. Las llamadas en el sandbox no mueven fondos reales.

Producción

Cuando pases a producción

Credenciales de producción distintas y los scopes que necesita tu flujo.

Las dos APIs se autentican igual: OAuth2 client credentials en un único endpoint de token.

Cuentas para tus clientes: la Finance API

Conversiones de los fondos de tu empresa: Fundflow

Modo mock

Tu primera llamada, en tres comandos

Necesitas Node 18 o posterior y una carpeta vacía. El modo mock es una simulación con estado del ciclo de vida documentado: una creación devuelve un id nuevo que puedes volver a leer, y una parte nueva empieza sin verificar, igual que en el sandbox.

Instala el SDK

Un paquete, sin dependencias en tiempo de ejecución.

Guarda este archivo como first-call.mjs

Sin claves y sin variables de entorno.

Ejecútalo

La parte vuelve ACTIVE con kycStatus VERIFICATION_PENDING, el mismo punto de partida que una integración real.

Lo que imprime tu terminal

Los ids y las fechas cambian en cada ejecución.

Después: una cuenta completa en modo mock

El ejemplo mock-bank monta una experiencia de cuenta sobre el SDK con datos ficticios y sin credenciales. Clónalo, ejecuta npm install y después npm run dev.

El ejemplo mock-bank en GitHub (en inglés)

@venlyfinance/sdk en npm (en inglés)

Datos de prueba

Lleva tú mismo cada estado en modo mock

En modo mock haces de operador de Venly. Una línea aprueba una verificación, abona un IBAN en EUR, o liquida o hace fallar una transferencia, así que tu código pasa por cada uno de esos estados en tus propias pruebas.

El modo mock no necesita credenciales. Las credenciales del sandbox las emite Venly y son distintas de las de producción.

Todos los controles del modo mock en el readme del SDK (en inglés)

Sandbox

Lleva el mismo código al sandbox

Cambia el entorno a staging y añade el Client ID y el Client Secret que te envía Venly. El SDK obtiene, guarda en caché y renueva el token por ti. Sin el SDK, la guía rápida son dos llamadas HTTP: cambia tus credenciales por un token y crea tu primera parte.

Con el SDK: cambia el entorno y añade las credenciales

Con curl, de la guía rápida

La guía rápida en la documentación (en inglés)

Entornos

Las credenciales del sandbox y de producción son distintas. El sandbox es el entorno de staging de la API, y sus llamadas no mueven fondos reales.

De la parte a la primera transferencia

Los estados entre un cliente nuevo y el dinero en movimiento

La guía de integración lleva a un cliente desde una parte nueva hasta una transferencia completada. El paso que condiciona tu diseño es la verificación: una parte está ACTIVE desde el principio, pero su cuenta no puede mover dinero hasta que la verificación devuelve VERIFIED.

POST /parties

Crea una parte

La persona u organización detrás de la cuenta, INDIVIDUAL u ORGANISATION. Queda ACTIVE al instante, y eso no es un resultado de verificación.

ACTIVE

POST /accounts

Abre una cuenta

Vincula la parte con partyId. Su monedero se crea automáticamente, sin una llamada aparte, y la cuenta empieza sin verificar.

VERIFICATION_PENDING

POST /parties/{partyId}/verification

Verifica la parte

Genera un enlace de verificación alojado y entrégaselo a tu cliente. El veredicto llega de forma asíncrona, y el kycStatus de la cuenta pasa a VERIFIED.

VERIFIED

GET /parties/{partyId}/partner-terms

Condiciones de los socios aceptadas

Cuando el estado indica REQUIRED, entrega a tu cliente el enlace de consentimiento. El alta continúa cuando indica ACCEPTED.

ACCEPTED

POST /accounts/{accountId}/virtual-bank-accounts

Emite un IBAN en EUR

Devuelve el referenceCode que cita la transferencia bancaria de tu cliente. Los datos de depósito en EUR pueden llegar un momento después; el webhook VIRTUAL_BANK_ACCOUNT_CREATED te avisa cuando ya se pueden recibir depósitos. Esta llamada lleva una idempotencyKey.

ACTIVE

POST /accounts/{accountId}/transfers/crypto

Envía una transferencia

PENDING mientras se liquida, después COMPLETED con un transactionHash, o FAILED con un errorMessage. Esta llamada también lleva una idempotencyKey.

COMPLETED

La guía de integración, paso a paso (en inglés)

Reintentos

Reintenta un movimiento de dinero sin enviarlo dos veces

Las cinco operaciones que crean movimientos de dinero llevan una idempotencyKey, un UUID que generas tú, en el cuerpo de la petición. No es una cabecera. Si reintentas con la misma clave, la operación se ejecuta una sola vez.

Misma clave, mismo cuerpo, la original tuvo éxito

El resultado original

Misma clave, la original sigue en curso

409 idempotency-conflict. Espera y vuelve a leer

Misma clave, cuerpo distinto

422 idempotency-conflict

Misma clave, la original falló

422 idempotency-conflict. Envía una clave nueva

Una operación original fallida gasta su clave. Para reintentar después de un fallo, genera una nueva.

Dónde es obligatoria una clave

Las claves son únicas por empresa en todas estas operaciones. Guarda la clave antes de enviar, para que un reinicio reintente con la misma.

La idempotencia en la documentación (en inglés)

Webhooks

Venly avisa a tu endpoint cuando algo cambia

Registra un endpoint HTTPS y cada cambio de estado se envía a él: pagos entrantes, transferencias, pagos salientes, veredictos de verificación y cuentas bancarias virtuales. Un ping envía un evento de prueba por la ruta real de entrega, con la cabecera de autenticación que comprueba tu handler.

Ningún evento lleva un importe

Un evento dice qué cambió. Lee los importes y los datos bancarios a través de la API autenticada.

Cada webhook recibe todos los eventos

Decide según eventType e ignora los tipos que no necesites.

La entrega es al menos una vez

Procesa según el id del recurso más su estado de destino, para que una repetición no haga nada.

El orden no está garantizado

Compara con el estado que ya tienes. Un pago saliente puede pasar de COMPLETED a RETURNED cuando el banco receptor lo devuelve.

Trece tipos de evento

Los webhooks y el catálogo de eventos (en inglés)

Estados y errores

Estados y códigos de error documentados sobre los que decidir

Cada objeto tiene un ciclo de vida corto y documentado, y cada error lleva un código estable. Decide según el código, nunca según el mensaje. Ignora los valores de enum que no reconozcas: los valores nuevos llegan sin una nueva versión de la API.

Transferencia

PENDING → COMPLETED

O FAILED, con un errorMessage.

Verificación de la cuenta

VERIFICATION_PENDING → VERIFIED

Se lee en el kycStatus de la cuenta.

Solicitud de rampa de Fundflow

AWAITING_APPROVAL → AWAITING_FUNDS → PROCESSING → SUCCEEDED

O FAILED, CANCELLED, REJECTED, DENIED o BLOCKED.

Un fallo devuelve success: false y una lista de errores, cada uno con un código y un mensaje.

Los errores que puede devolver cualquier endpoint

Cuerpo mal formado o parámetros no válidos

Corrige la petición. No la reintentes sin cambios.

Token ausente o caducado

Renueva el token y reintenta.

La operación no está disponible en la configuración de tu empresa

Pide a Venly que la active.

El recurso, o uno al que hace referencia, no existe, por ejemplo account-not-found

Comprueba el id.

Una versión desactualizada en una modificación

Vuelve a leer el recurso, aplica de nuevo tu cambio y reintenta.

Una clave de idempotencia reutilizada con otro cuerpo, o que repite una llamada que falló

Para reintentar un fallo real, usa una clave nueva.

Un error inesperado del servidor

Reintenta con espera exponencial. Si persiste, contacta con Venly.

Todavía no: los controles de verificación

Una cuenta nueva no puede mover dinero hasta que está verificada, y cada operación lo indica con su propio código. Trata cualquiera de ellos como todavía no, en lugar de buscar un único código.

La Finance API no publica límites fijos de peticiones. El SDK reintenta las respuestas 429, 502, 503 y 504 y los errores de red con espera exponencial y jitter, respeta Retry-After y se detiene tras 3 intentos por defecto. Sin el SDK, espera y reintenta ante un 500 y un 429, y haz cada reintento seguro con una clave de idempotencia.

Lanza cualquiera de ellos a propósito en modo mock con failNext, y tu gestión queda probada antes de que el sandbox devuelva uno.

Cada código de error y qué hacer (en inglés)

Para agentes de código

Documentación y herramientas que tu agente de código puede usar

docs.venlyfinance.com publica un índice para modelos de lenguaje y tiene un servidor MCP, así que un agente en tu editor trabaja con la referencia actual de la API en lugar de adivinar endpoints. El MCP de Venly Finance da a ese mismo agente herramientas que funcionan en modo mock.

llms.txt

Un índice de la documentación, una línea por página.

llms-full.txt

Las guías y la referencia de la API en un solo archivo de texto.

Servidor MCP de la documentación

Añade el servidor a tu agente. Puede buscar en la documentación y leer cualquier página.

MCP de Venly Finance, en modo mock

Herramientas basadas en el SDK para partes, cuentas, datos de recepción y transferencias. Sus herramientas de escritura solo funcionan contra el sandbox mock, sin credenciales y sin red, y rechazan cualquier otra URL base.

Añádelo a la configuración MCP de tu agente

Herramientas que tu agente puede llamar en modo mock

El servidor ofrece 35 herramientas en total; estas son las que sirven para montar un flujo de cuenta. Esto devolvió create_party en modo mock:

Escrituras, solo en mock

Lecturas

El readme del MCP de Venly Finance (en inglés)

Construye tu propia interfaz

SDK, componentes React y herramientas MCP para crear tu propia experiencia de cliente.

Explora el SDK y el MCP en GitHub (en inglés)

Dos APIs

Dónde empieza la documentación de cada API

Finance API

Cuentas, monederos, datos para recibir USD y EUR, transferencias y pagos salientes para tus clientes.

Primera llamada: POST /v1/parties

Guía de integración (en inglés)

Referencia de la Finance API (en inglés)

Especificación OpenAPI (YAML, en inglés)

Qué hace la Finance API

Fundflow API

Solicitudes de rampa que convierten los fondos de tu empresa entre fiat y stablecoins, con la comisión calculada antes.

Primera llamada: GET /v1/company, que devuelve tu kybStatus

Guía de integración de Fundflow (en inglés)

Estados de una solicitud de rampa (en inglés)

Especificación OpenAPI (YAML, en inglés)

Qué hace Fundflow

Camino a producción

Del modo mock al dinero real, y quién hace cada paso

El acceso al sandbox y a producción no es de autoservicio, porque todos los flujos funcionan sobre socios regulados y cada empresa se configura para su propia cobertura. Hasta entonces, puedes construir y probar tu integración en modo mock.

Construye en modo mock

Tú, hoy

Tu integración, tus pruebas y tus caminos de fallo, sin credenciales.

Escríbenos

Tú

Elige tu flujo y añade unas líneas sobre él.

Una reunión de alcance

Tú y Venly

El recorrido de la API para tu stack, la cobertura que aplica y un plan de puesta en marcha.

Credenciales del sandbox

Venly

Te llegan directamente. Cambia el entorno a staging y ejecuta el mismo código.

Producción

Venly y tú

Venly configura la cuenta de tu empresa y después emite credenciales de producción distintas, con los scopes de las áreas que integras.

Los plazos dependen de tu flujo y de su cobertura. La reunión de alcance los fija en tu plan de puesta en marcha.

Antes de tu primera llamada real

Solicita credenciales del sandbox

Detalles para tu equipo técnico

¿Cómo consigo credenciales del sandbox?

Venly genera un Client ID y un Client Secret para tu empresa y te los envía directamente. El acceso no es de autoservicio: escríbenos sobre tu flujo y las credenciales llegan después de una reunión de alcance.

¿Las llamadas en el sandbox mueven dinero?

No. Las llamadas en el sandbox no mueven fondos reales, y las credenciales del sandbox y de producción son distintas.

¿Podemos probar la API antes de tener credenciales del sandbox?

Sí. El SDK de TypeScript tiene un modo mock que funciona sin credenciales y sin red. Los tres comandos de esta página hacen tu primera llamada.

¿Hay un SDK para mi lenguaje?

El SDK es de TypeScript. Desde cualquier otro stack, llama directamente a la API REST; las especificaciones OpenAPI de las dos APIs están publicadas, así que puedes generar un cliente a partir de ellas.

¿Cuánto dura un token de acceso?

300 segundos. Pide un token nuevo antes de que caduque; basta con un margen de 30 segundos. Un 401 significa que el token ha caducado: vuelve a autenticarte y reintenta la petición una vez.

¿Qué permisos necesita mi token?

Cada endpoint de la Finance API exige un scope, como manage:accounts, manage:transfers o manage:webhooks. Pide a Venly los scopes de las áreas que integras. Un token sin el scope correcto se rechaza con 403 forbidden, no con 401.

¿Hay límites de peticiones?

La Finance API no publica límites numéricos fijos. Guarda tu token en caché, reintenta con espera exponencial y jitter ante un 500 o un 429, y confirma los límites con tu contacto de Venly si esperas volúmenes altos.

¿Cómo se gestionan los cambios incompatibles?

La versión mayor está en la URL (/v1). Un cambio incompatible llega como una nueva versión mayor, anunciada al menos seis meses antes de retirar la anterior, y ambas funcionan en paralelo hasta entonces.

Autenticación, scopes y renovación del token (en inglés)

Convenciones de paginación, versiones e idempotencia (en inglés)

Cómo se construye una propuesta

Empieza hoy en modo mock

Cuando quieras el sandbox, cuéntanos qué estás construyendo. Después de una reunión de alcance sobre tu flujo, Venly te envía directamente tus credenciales del sandbox.

Solicita credenciales del sandbox

Lee la documentación

Haz tu primera llamada

Dónde se ejecutan tus llamadas de prueba

Credenciales distintas por entorno. Las credenciales del sandbox y de producción se emiten por separado, y las llamadas en el sandbox no mueven fondos reales.

Certificación SOC 2 Type 2. Nuestras propias licencias están en curso y hoy los flujos se ejecutan a través de rieles de socios con licencia.