Tema
Lo que espera a una persona
La parte que casi ninguna documentación de API incluye, y la que decide si tus usuarios confían en tus pantallas.
Nada en esta API mueve dinero por su cuenta
Todo cambio y todo retiro es una solicitud que aprueba una persona en Vectrakpital. No hay un umbral por debajo del cual sea automático. Es una decisión de negocio, no una limitación pendiente de levantar, y construir como si fuera temporal produce una interfaz que miente.
Los cuatro momentos de un depósito
- Lo declaras. Recibes el monto exacto a enviar y una dirección.
- Lo envías, exacto.
- Alguien registra la llegada. Hoy no es automático: ningún proceso vigila el mercado. Entre que tu transferencia se confirma en cadena y el depósito aparece en
GET /api/v1/deposits, hay una persona. - Se atribuye. Esta parte sí es automática — la cola rara del monto casa con tu declaración y acredita a tu organización sin que nadie elija.
Así que consulta periódicamente el depósito, no esperes un webhook, y no le digas a tu usuario que llegó hasta que esté en la lista.
Si el monto que enviaste no coincide con la declaración no se rompe nada: el dinero espera a que lo atribuyan a mano. Simplemente deja de ser minutos y pasa a ser horas.
Los dos momentos de un retiro
Es el que más sorprende a quien integra.
venue_settled significa que el dinero salió de la plataforma. paid_out significa que llegó a la cuenta. No son el mismo evento, y entre uno y otro puede haber una noche: un pago cotizado a las cinco de la tarde suele llegar a la mañana siguiente.
Las expectativas de tus usuarios las fija lo que diga tu pantalla. Si dice completado cuando la plataforma dijo el dinero salió, has prometido algo que no puedes ver.
El estado que deberías pintar como «listo» es paid_out
Todo lo anterior es «en curso», y decirlo no cuesta nada.
Por qué un destino no se puede usar de inmediato
Un destino recién registrado es inutilizable hasta que pasen dos cosas: transcurre un período de enfriamiento, y alguien en Vectrakpital lo registra en el mercado.
El enfriamiento es la única defensa que funciona contra una sesión que no es realmente tuya. Quien entre puede añadir su propia cuenta, y nada más en el flujo puede distinguir eso de que lo pidas tú.
Para tu integración esto significa una cosa: registra los destinos mucho antes de necesitarlos. Un flujo que registra una cuenta y retira hacia ella en la misma ejecución va a fallar, siempre, por diseño. Lee usable en el destino y construye alrededor de eso.
De qué depende «el precio»
La tasa que te cotizan es la del mercado, menos lo que cuesta ejecutar, menos el margen de Vectrakpital. Se mueve durante el día, y en unos corredores más que en otros.
Si una cotización vuelve rechazada con quotes.quote_below_executable_rate, el precio ofrecido quedaría por debajo del coste de ejecutarla. Es la plataforma negándose a entregarte una pérdida. Se resuelve solo cuando el mercado se mueve.
Una pantalla de estado que envejezca bien
- Consulta con un horario. Aquí nada cambia segundo a segundo, porque hay una persona en el circuito.
- Muestra el estado de la plataforma, traducido una vez, con tus palabras — no un enum crudo, y no un resumen optimista.
- Distingue solicitado de aprobado de hecho. Juntarlos es el atajo que genera tickets de soporte.
- Cuando un paso espera a una persona, dilo. «En revisión» es información; un spinner no.