API

Tema

Primeros pasos ​

De nada a un saldo en pantalla, en cinco minutos.

1 · Consigue una llave ​

Alguien de tu organización con el permiso Llaves de API la emite desde el portal: Equipo → Llaves de API → Emitir. Elige qué puede hacer; dale lo mínimo que funcione.

La respuesta muestra la llave una sola vez:

vk_live_3f9a1c72b40de5a1.hR8xK2mQ...

Se guarda como hash, así que nadie puede volver a leerla — ni tú, ni Vectrakpital. Ponla en tu gestor de secretos antes de cerrar la pestaña. Si la pierdes, revócala y emite otra; no es un caso que valga la pena resolver con ingeniería.

2 · Apunta a sandbox ​

bash
export VECTRAKPITAL_API=https://sanbox-exchange-back.vectrakpital.com
export VECTRAKPITAL_KEY=vk_live_3f9a1c72b40de5a1.hR8xK2mQ...

Mismos endpoints, mismas reglas, mercado apagado. Todo lo que sigue funciona igual contra producción cambiando esa primera variable por https://back.vectrakpital.com — y conviene no hacerlo hasta el final, porque en producción cada solicitud que crees le llega a una persona.

Las diferencias que importan están en entornos; la que más, que las direcciones de depósito de sandbox no son direcciones reales.

3 · Llama a algo inofensivo ​

bash
curl $VECTRAKPITAL_API/api/v1/client \
  -H "X-API-Key: $VECTRAKPITAL_KEY"
json
{
  "success": true,
  "data": {
    "id": "019fb6be-73e6-736c-a255-488446eb819d",
    "name": "Acme Trading SAS",
    "status": "active",
    "canOperate": true,
    "permissions": ["portal:read", "portal:trade"]
  }
}

Vale la pena leer permissions primero: es la intersección entre los alcances de tu llave y el puesto de quien la emitió, que es exactamente lo que el servidor exige. Si más adelante una llamada responde 403, compárala con esto antes de suponer un fallo.

4 · Lee un saldo, bien ​

bash
curl $VECTRAKPITAL_API/api/v1/balances \
  -H "X-API-Key: $VECTRAKPITAL_KEY"
json
{ "data": [{ "assetSymbol": "USDT", "assetDecimals": 6, "amountMinor": "10000000000" }] }

Eso son 10 000 USDT, no diez mil millones. Divide entre 10 ** assetDecimals, y toma los decimales de la respuesta y no de una constante en tu código.

Dos cosas de esa línea, y las dos muerden: el monto es una cadena porque un monto en pesos no cabe en un número JSON, y assetDecimals es 6 aquí y podría ser otro para el mismo símbolo en otro corredor. Ver el modelo de montos, que es la guía que evita el error caro.

5 · Pide un precio ​

bash
curl -X POST $VECTRAKPITAL_API/api/v1/quotes \
  -H "X-API-Key: $VECTRAKPITAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"baseSymbol":"USDT","quoteSymbol":"COPM","amountBaseMinor":"10000000000"}'

Una cotización es un precio sostenido durante una ventana corta. Pedirla no te compromete a nada y no mueve nada, así que consúltala tantas veces como necesites y abandona las que no uses.

6 · Acéptala, y entiende qué significa ​

bash
curl -X POST $VECTRAKPITAL_API/api/v1/orders \
  -H "X-API-Key: $VECTRAKPITAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quoteId":"019fb6be-..."}'

Un 201 aquí es una solicitud, no una operación ejecutada

Se retiene el monto para que un mismo saldo no respalde dos operaciones, y una persona en Vectrakpital la aprueba antes de que nada llegue a un mercado. Consulta el estado en GET /api/v1/orders.

Si construyes suponiendo que 201 significa hecho, lo primero que verán tus usuarios es una pantalla de «completado» por un dinero que no se ha movido.

Y ahora ​