HashCore Docs
API

Trabajo con Postman

6.3.1 Introducción

Postman es una herramienta popular para probar API. El Firmware de VNISH proporciona una REST API disponible en cada miner. En esta guía, explicaremos cómo configurar Postman para trabajar con esta API, comenzando con la configuración inicial del entorno.

6.3.2 Instalación

Descargue e instale la aplicación de escritorio de Postman desde el sitio web oficial, o utilice la versión web de Postman en su navegador.

6.3.3 Obtención e importación de la especificación API

La API de VNISH está descrita en formato OpenAPI. Puede ver y descargar la documentación directamente en el miner:

  • en la interfaz web del Firmware: sección Soporte técnico → API;
  • o abriendo la dirección http://<IP_del_miner>/docs en el navegador. El archivo de especificación (JSON) obtenido se utiliza para importar en Postman, lo que elimina la necesidad de crear todas las solicitudes manualmente: Importar especificación API en Postman
  1. En Postman, haga clic en el icono «Import».
  2. Seleccione la especificación JSON xminer-api y cárguela.
  3. Postman creará la colección xminer-api, organizando todos los endpoints en carpetas.

Importante: Postman agrupa las solicitudes no por las etiquetas de la especificación (auth, mining, etc.), sino por el primer segmento de la URL.

6.3.4 Configuración de entornos

En Postman, hay dos niveles de variables que conviene separar:

  • Global: valores idénticos para todos los miners con Firmware VNISH.
  • Environment: valores únicos para un miner específico.

Paso 1. Variable global

  1. Abra la pestaña Environments en el panel derecho. Seleccione Globals.
  2. En la tabla de variables, haga clic en la fila Add variable.
  3. Cree la variable:
  • Variable: BASE_PATH
  • Value: /api/v1
  1. Guarde (Ctrl+S o el botón de guardar en la esquina superior derecha). Configuración de variable global BASE_PATH Esta es la ruta base común de la API, idéntica para cualquier miner con VNISH.

Paso 2. Entorno para un miner específico

  1. En la pestaña Environments, cree un nuevo entorno (por ejemplo, My Miner).
  2. Agregue la variable:
  • Variable: MINER_IP
  • Value: La dirección IP del miner con el protocolo especificado, por ejemplo http://<IP_del_miner>
  1. También cree una variable vacía AUTH_TOKEN. Se rellenará automáticamente después de iniciar sesión.

Cómo configurar su llenado automático se describe en la sección «Configuración de la obtención y sustitución automática del token bearer».

  1. Guarde el entorno y selecciónelo como activo en la lista desplegable de entornos en la esquina superior derecha de la interfaz web de Postman; sin esto, las variables no se sustituirán en las solicitudes. Selección de entorno activo en Postman

Paso 3. Variable baseUrl en la colección

Al importar la especificación, Postman crea automáticamente una variable baseUrl en la colección, sobre la cual se construye la ruta para todas las solicitudes ({{baseUrl}}/unlock, {{baseUrl}}/status, etc.). Por defecto, solo contiene la ruta base sin la dirección del miner (/api/v1), por lo que debe configurarse adicionalmente.

  1. Abra la colección xminer-api → pestaña Variables.
  2. Encuentre la fila baseUrl.
  3. En la columna Value, reemplace el valor con: 
    {{MINER_IP}}{{BASE_PATH}}
  4. Guarde los cambios. Ahora baseUrl se construye automáticamente a partir de la variable de entorno MINER_IP y la variable global BASE_PATH, y la dirección final se ve así: http://<IP-del-miner>/api/v1.

Al cambiar el miner o su dirección IP, basta con cambiar el valor de MINER_IP en el entorno correspondiente. Todas las solicitudes en la colección adoptarán automáticamente la nueva dirección, sin necesidad de editar manualmente cada solicitud.

6.3.5 Configuración de Postman para la obtención y sustitución automática del token bearer

Para obtener un token a través de /unlock y configurar Postman para que lo sustituya automáticamente en todas las solicitudes posteriores, sin necesidad de copiarlo manualmente cada vez.

Paso 1. Verificación del entorno activo

Asegúrese de que el entorno My Miner esté seleccionado en la esquina superior derecha de Postman.

Paso 2. Creación de la solicitud unlock

  • Método POST, URL: {{baseUrl}}/unlock.
  • Pestaña Body > raw > tipo JSON: Inserte el siguiente JSON como mensaje:
{"pw":"contraseña_del_dispositivo"}

Paso 3. Script de guardado automático del token

Copie y pegue el siguiente script en la pestaña Scripts > Post-response:

pm.environment.unset('AUTH_TOKEN');

pm.test('Status code is 200', function () {
    pm.response.to.have.status(200);
});

const json = pm.response.json();
pm.environment.set('AUTH_TOKEN', json.token);

El script borra el valor antiguo de AUTH_TOKEN, verifica que el servidor respondió 200 OK, extrae el campo token del cuerpo de la respuesta y lo guarda en la variable de entorno AUTH_TOKEN.

Paso 4. Guardar y enviar la solicitud

Guarde y envíe la solicitud. Si la contraseña es correcta, recibirá una respuesta 200 OK, y AUTH_TOKEN en el entorno My Miner se rellenará automáticamente (puede verificarlo en el panel de variables de la solicitud).

Paso 5. Configuración de la autorización de la colección

Abra la colección xminer-api → pestaña Authorization → tipo Bearer Token → en el campo Token escriba {{AUTH_TOKEN}}. Ahora todas las solicitudes de la colección que hereden la autorización de la colección enviarán automáticamente el encabezado necesario.

Paso 6. Uso y actualización del token

Utilice las demás solicitudes como de costumbre. Cuando la sesión expire, envíe de nuevo {{baseUrl}}/unlock, el script actualizará el token.

6.3.6 Cómo obtener un cURL-request desde Postman

Si ocurre un error al trabajar con la API, los desarrolladores o el soporte técnico pueden solicitar que se envíe la solicitud en forma de comando curl. Puede obtener un curl listo directamente desde Postman en un par de pasos, sin reescribir la solicitud manualmente:

  1. Abra la solicitud deseada en la colección.
  2. A la derecha del botón Send, haga clic en el icono </> (Code) — esto abre un menú con el código de solicitud listo en diferentes lenguajes.
  3. En la lista desplegable, encuentre el elemento cURL. Obtener comando cURL desde Postman

Autorización y token de acceso

La API ofrece dos métodos de autorización independientes.

Uso de cURL