Trabalhando com Postman

6.3.1 Introdução

Postman é uma ferramenta popular para testar API. O Firmware VNISH fornece uma REST API, acessível em cada minerador. Neste guia, mostraremos como configurar o Postman para trabalhar com esta API, começando pela configuração inicial do ambiente.

6.3.2 Instalação

Baixe e instale o aplicativo de desktop Postman do site oficial, ou use a versão web do Postman no navegador.

6.3.3 Obtenção e importação da especificação da API

A API VNISH é descrita no formato OpenAPI. Você pode visualizar e baixar a documentação diretamente no minerador:

• na interface web do Firmware: seção Suporte Técnico → API;
• ou abrindo o endereço http://<IP_do_minerador>/docs no navegador. O arquivo de especificação (JSON) obtido é usado para importação no Postman, o que elimina a necessidade de criar todas as requisições manualmente: Importar especificação OpenAPI no Postman

1. No Postman, clique no ícone «Import».
2. Selecione a especificação JSON xminer-api e carregue.
3. O Postman criará uma coleção xminer-api, organizando todos os endpoints em pastas.

Importante: O Postman agrupa as requisições não por tags da especificação (auth, mining, etc.), mas pelo primeiro segmento da URL.

6.3.4 Configuração de ambientes

No Postman, existem dois níveis de variáveis que devem ser separados:

• Global: valores idênticos para todos os mineradores com Firmware VNISH.
• Environment: valores únicos para um minerador específico.

Passo 1. Variável Global

1. Abra a aba Environments no painel direito. Selecione Globals.
2. Na tabela de variáveis, clique na linha Add variable.
3. Crie uma variável:

• Variable: BASE_PATH
• Value: /api/v1

4. Salve (Ctrl+S ou o botão de salvar no canto superior direito). Configuração da variável global BASE_PATH Este é o caminho base comum da API, idêntico para qualquer minerador com VNISH.

Passo 2. Ambiente para um minerador específico

1. Na aba Environments, crie um novo ambiente (por exemplo, My Miner).
2. Adicione uma variável:

• Variable: MINER_IP
• Value: O endereço IP do minerador com o protocolo especificado, por exemplo http://<IP_do_minerador>

3. Crie também uma variável vazia AUTH_TOKEN. Ela será preenchida automaticamente após o login.

Como configurar seu preenchimento automático é descrito na seção «Configurando a obtenção e substituição automática do token bearer».

4. Salve o ambiente e selecione-o como ativo na lista suspensa de ambientes no canto superior direito da interface web do Postman — sem isso, as variáveis não serão substituídas nas requisições. Configuração do ambiente para um minerador específico

Passo 3. Variável baseUrl na coleção

Ao importar a especificação, o Postman cria automaticamente uma variável baseUrl na coleção, com base na qual o caminho para todas as requisições é construído ({{baseUrl}}/unlock, {{baseUrl}}/status, etc.). Por padrão, ela contém apenas o caminho base sem o endereço do minerador (/api/v1), portanto, precisa ser configurada adicionalmente.

1. Abra a coleção xminer-api → aba Variables.
2. Encontre a linha baseUrl.
3. Na coluna Value, substitua o valor por:

   {{MINER_IP}}{{BASE_PATH}}
   

4. Salve as alterações. Agora baseUrl é automaticamente montado a partir da variável de ambiente MINER_IP e da variável global BASE_PATH, e o endereço final se parece com: http://<IP_do_minerador>/api/v1.

Ao mudar o minerador ou seu endereço IP, basta alterar o valor de MINER_IP no ambiente correspondente. Todas as requisições na coleção pegarão automaticamente o novo endereço, sem a necessidade de edição manual de cada requisição.

6.3.5 Configurando o Postman para obtenção e substituição automática do token bearer

Para obter o token via /unlock e configurar o Postman para que ele substitua automaticamente este token em todas as requisições subsequentes, sem a necessidade de copiar manualmente a cada vez.

Passo 1. Verificação do ambiente ativo

Certifique-se de que o ambiente My Miner esteja selecionado no canto superior direito do Postman.

Passo 2. Criação da requisição unlock

• Método POST, URL: {{baseUrl}}/unlock.
• Aba Body > raw > tipo JSON: Insira o JSON abaixo como mensagem:

  {"pw":"senha_do_dispositivo"}
  

Passo 3. Script de salvamento automático do token

Copie e cole o script abaixo na aba 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);

O script apaga o valor antigo de AUTH_TOKEN, verifica se o servidor respondeu 200 OK, extrai o campo token do corpo da resposta e o salva na variável de ambiente AUTH_TOKEN.

Passo 4. Salvamento e envio da requisição

Salve e envie a requisição. Se a senha estiver correta, uma resposta 200 OK será recebida, e AUTH_TOKEN no ambiente My Miner será preenchido automaticamente (você pode verificar no painel de variáveis da requisição).

Passo 5. Configuração da autorização da coleção

Abra a coleção xminer-api → aba Authorization → tipo Bearer Token → no campo Token, digite {{AUTH_TOKEN}}. Agora, todas as requisições da coleção que herdaram a autorização da coleção enviarão automaticamente o cabeçalho necessário.

Passo 6. Uso e atualização do token

Use as demais requisições normalmente. Quando a sessão expirar, envie {{baseUrl}}/unlock novamente, e o script atualizará o token.

6.3.6 Como obter um comando cURL do Postman

Se ocorrer um erro ao trabalhar com a API, os desenvolvedores ou o suporte técnico podem solicitar que você envie a requisição como um comando curl. Você pode obter um curl pronto diretamente do Postman em algumas etapas, sem reescrever a requisição manualmente:

1. Abra a requisição desejada na coleção.
2. À direita do botão Send, clique no ícone </> (Code) — ele abre um menu com o código da requisição pronto em diferentes linguagens.
3. Na lista suspensa, encontre o item cURL. Obtendo um comando cURL do Postman