Terminais

A API da Nuvende permite o gerenciamento completo de terminais de pagamento, incluindo criação, atualização e listagem. Os terminais são dispositivos físicos utilizados para processar transações de pagamento.

Conceitos Fundamentais

O que são Terminais?

Terminais são dispositivos físicos utilizados para processar pagamentos, como POS (Point of Sale). Cada terminal está associado a um estabelecimento comercial e possui configurações específicas para processamento de transações, incluindo número de série, número lógico e informações do SIM card.

Funcionalidades Disponíveis

• Listar Terminais: Consultar todos os terminais cadastrados com paginação
• Criar Terminal: Cadastrar novo terminal no sistema
• Atualizar Terminal: Modificar configurações de terminal existente

Implementação Técnica

Endpoints Disponíveis

• GET /api/v1/pagamentos/terminals - Listar terminais
• POST /api/v1/pagamentos/terminals - Criar terminal
• PUT /api/v1/pagamentos/terminals/{id} - Atualizar terminal

Estrutura de Dados

Headers Obrigatórios

Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

Estrutura de Terminal

{
  "id": "string (UUID)",
  "merchant_id": "string (UUID)",
  "serial_number": "string",
  "logic_number": "string",
  "model": "string",
  "manufacturer": "string",
  "simcard_serial_number": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

Campos Obrigatórios para Criação

• serial_number: Número de série do terminal
• logic_number: Número lógico do terminal
• merchant_id: ID do comerciante (UUID)
• model: Modelo do terminal
• manufacturer: Fabricante do terminal
• simcard_serial_number: Número de série do SIM card

Implementação em Código

Classe de Gerenciamento de Terminais

const axios = require('axios');

class TerminalService {
  constructor(baseUrl, accessToken) {
    this.baseUrl = baseUrl;
    this.accessToken = accessToken;
  }

  /**
   * Lista todos os terminais com paginação
   * @param {Object} filtros - Filtros de busca (opcional)
   * @returns {Promise<Object>} Lista paginada de terminais
   */
  async listarTerminais(filtros = {}) {
    try {
      console.log('Listando terminais...');
      
      const response = await axios.get(`${this.baseUrl}/api/v1/pagamentos/terminals`, {
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
          'Accept': 'application/json'
        },
        params: filtros
      });

      console.log(`${response.data.data.length} terminais encontrados`);
      return response.data;
      
    } catch (error) {
      console.error('Erro ao listar terminais:', error.response?.data || error.message);
      throw this.tratarErro(error);
    }
  }

  /**
   * Cria um novo terminal
   * @param {Object} dadosTerminal - Dados do terminal
   * @returns {Promise<Object>} Terminal criado
   */
  async criarTerminal(dadosTerminal) {
    try {
      console.log('Criando terminal...');
      
      const response = await axios.post(`${this.baseUrl}/api/v1/pagamentos/terminals`, dadosTerminal, {
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      });

      console.log('Terminal criado com sucesso');
      return response.data;
      
    } catch (error) {
      console.error('Erro ao criar terminal:', error.response?.data || error.message);
      throw this.tratarErro(error);
    }
  }

  /**
   * Atualiza um terminal existente
   * @param {string} id - ID do terminal (UUID)
   * @param {Object} dadosAtualizacao - Dados para atualização
   * @returns {Promise<Object>} Terminal atualizado
   */
  async atualizarTerminal(id, dadosAtualizacao) {
    try {
      console.log(`Atualizando terminal: ${id}`);
      
      const response = await axios.put(`${this.baseUrl}/api/v1/pagamentos/terminals/${id}`, dadosAtualizacao, {
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      });

      console.log('Terminal atualizado com sucesso');
      return response.data;
      
    } catch (error) {
      console.error('Erro ao atualizar terminal:', error.response?.data || error.message);
      throw this.tratarErro(error);
    }
  }

  /**
   * Valida dados de terminal
   * @param {Object} dados - Dados a serem validados
   * @returns {Object} Resultado da validação
   */
  validarDadosTerminal(dados) {
    const erros = [];

    if (!dados.merchant_id || dados.merchant_id.trim().length === 0) {
      erros.push('ID do comerciante é obrigatório');
    }

    if (!dados.serial_number || dados.serial_number.trim().length === 0) {
      erros.push('Número de série é obrigatório');
    }

    if (!dados.logic_number || dados.logic_number.trim().length === 0) {
      erros.push('Número lógico é obrigatório');
    }

    if (!dados.model || dados.model.trim().length === 0) {
      erros.push('Modelo é obrigatório');
    }

    if (!dados.manufacturer || dados.manufacturer.trim().length === 0) {
      erros.push('Fabricante é obrigatório');
    }

    if (!dados.simcard_serial_number || dados.simcard_serial_number.trim().length === 0) {
      erros.push('Número de série do SIM card é obrigatório');
    }

    return {
      valido: erros.length === 0,
      erros: erros
    };
  }

  /**
   * Trata erros da API
   * @param {Error} error - Erro capturado
   * @returns {Error} Erro tratado
   */
  tratarErro(error) {
    const status = error.response?.status;
    const data = error.response?.data;

    switch (status) {
      case 400:
        return new Error(`Dados inválidos: ${data?.message || 'Verifique os parâmetros enviados'}`);
      case 401:
        return new Error('Token de acesso inválido ou expirado');
      case 403:
        return new Error('Permissões insuficientes para gerenciar terminais');
      case 404:
        return new Error('Terminal não encontrado');
      case 422:
        return new Error(`Dados não processáveis: ${data?.message || 'Verifique o formato dos dados'}`);
      case 500:
        return new Error('Erro interno do servidor. Tente novamente mais tarde');
      default:
        return new Error(`Erro inesperado: ${error.message}`);
    }
  }
}

// Exemplo de uso prático
async function exemploGerenciamentoTerminais() {
  const terminalService = new TerminalService(
    'https://api-h.nuvende.com.br',
    'seu_access_token'
  );

  try {
    // Listar terminais
    const terminais = await terminalService.listarTerminais();
    console.log('Terminais:', terminais);

    // Criar novo terminal
    const novoTerminal = {
      merchant_id: '9dd1b184-a167-4131-b68a-27be0c20c2b9',
      serial_number: '9892928371',
      logic_number: 'N9892928371',
      model: 'SPOS920',
      manufacturer: 'Pax',
      simcard_serial_number: 'GMS029810203'
    };

    const validacao = terminalService.validarDadosTerminal(novoTerminal);
    if (!validacao.valido) {
      console.error('Dados inválidos:', validacao.erros);
      return;
    }

    const terminalCriado = await terminalService.criarTerminal(novoTerminal);
    console.log('Terminal criado:', terminalCriado);

  } catch (error) {
    console.error('Erro no exemplo:', error.message);
  }
}