¿Qué es el operatorId y por qué es obligatorio? – Bitvavo Centro de ayuda

Resumen

Este artículo explica qué es el parámetro operatorId, por qué es obligatorio según la normativa vigente y cómo utilizarlo correctamente al realizar órdenes mediante la API de Bitvavo. Si usas bots o scripts para operar por API, este artículo te ayudará a asignar e implementar correctamente el operatorId dentro del cuerpo de la solicitud.

¿Qué es el operatorId?

El operatorId es un parámetro obligatorio en las solicitudes API relacionadas con operaciones de trading, como la creación de una orden. Este valor se requiere para cumplir con la normativa vigente sobre criptoactivos y permite identificar qué bot, script o sistema ha realizado una determinada orden desde tu cuenta.

Se trata de un número entero de tipo int64 que debes definir tú mismo. Se recomienda utilizar un valor entre 1 y 9.223.372.036.854.775.807.

Si utilizas varios bots o scripts con la misma clave API, puedes asignar un operatorId único a cada uno para saber exactamente cuál ha ejecutado cada orden.

¿Por qué es obligatorio?

Las nuevas regulaciones sobre criptoactivos exigen que plataformas como Bitvavo puedan ofrecer un registro claro y trazable de la actividad comercial. El operatorId permite esto porque:

Identifica qué sistema o componente ha enviado una orden desde tu cuenta
Es obligatorio en todas las solicitudes de trading realizadas por API
No puede omitirse ni desactivarse
Debe ser único para cada bot o script que realice operaciones

¿Cómo se utiliza el operatorId?

El operatorId debe ser un número entero (int64) que tú mismo defines. Por ejemplo: 12234 para un bot y 12235 para otro.

Consejo: Asigna un operatorId único a cada script o bot para facilitar el seguimiento de la actividad.

Así puedes implementarlo:

Incluye el operatorId en el cuerpo de la solicitud al usar el endpoint POST /order (u otros endpoints de trading).
Asegúrate de enviarlo como número, no como texto (sin comillas).

✅ Correcto: "operatorId": 12234
❌ Incorrecto: "operatorId": "12234"

Revisa que todos tus endpoints de trading incluyan este parámetro correctamente.

¿Dónde puedo ver un ejemplo?

Puedes consultar un ejemplo completo en la documentación del endpoint Crear orden de nuestra API.

Este es un ejemplo simplificado con el uso correcto de operatorId:

{
  "market": "BTC-EUR",
  "side": "buy",
  "orderType": "limit",
  "amount": "0.1",
  "price": "25000",
  "operatorId": 12234
}

El operatorId debe incluirse en el cuerpo de la solicitud y debe enviarse como número (sin comillas). Si se omite o se envía de forma incorrecta, la orden será rechazada.

Consejo: Puedes probar tus solicitudes en el entorno de pruebas de Bitvavo antes de enviarlas en producción.

Preguntas frecuentes

¿Debo usar un operatorId diferente para cada orden?

No. Puedes reutilizar el mismo operatorId para todas las órdenes enviadas por el mismo bot o script. El objetivo es diferenciar entre sistemas, no entre órdenes individuales.

¿Qué ocurre si envío el operatorId como texto (entre comillas)?

La orden probablemente será rechazada. El operatorId debe enviarse como número entero (int64), no como cadena de texto.

¿Existe un operatorId por defecto si no lo defino?

No. Debes definir siempre un operatorId. No se asigna ningún valor por defecto automáticamente.

Resumen