Service-kiosk NPM

ZeroQ SDK

SDK de JavaScript para interactuar con la aplicación Electron de ZeroQ. Este SDK proporciona una interfaz para realizar operaciones como la creación de tickets, procesamiento de pagos e impresión de documentos.

Tabla de Contenidos

Instalación

NPM

npm install service-kiosk

CDN

<script src="https://cdn.jsdelivr.net/npm/service-kiosk@0.0.21/dist/service-kiosk.umd.min.js"></script>

Inicio Rápido

import { zeroq } from 'service-kiosk';

// Inicializar el SDK
const init = async () => {
  try {
    const config = await zeroq.init({
      apiKey: "tu-api-key",
      officeId: 123 // opcional
    });
    console.log('SDK inicializado:', config);
  } catch (error) {
    console.error('Error al inicializar:', error);
  }
};

Configuración

La configuración del SDK requiere los siguientes parámetros:

Parámetro	Tipo	Requerido	Descripción
apiKey	string	Sí	Clave de API para autenticación
officeId	number	No	ID de la oficina para operaciones específicas

API Reference

Inicialización

`init(options: InitOptions)`

Inicializa el SDK con las opciones proporcionadas.

const config = await zeroq.init({
  apiKey: "tu-api-key",
  officeId: 123
});

Verificación de Entorno

`isKiosk()`

Verifica si la aplicación está corriendo en un kiosko.

const isKiosk = await zeroq.isKiosk();

`getElectronApiStatus()`

Obtiene el estado de la API de Electron.

const status = zeroq.getElectronApiStatus();
// Retorna: { isAvailable: boolean, api: any, windowApi: any }

Gestión de Oficinas

`getOffices()`

Obtiene la lista de oficinas disponibles.

const offices = await zeroq.getOffices();

Respuesta:

interface Office {
  id: number;
  slug: string;
  name: string;
  options: any;
  timezone: string;
  code: string | null;
  street: string | null;
  phone: string | null;
  category_id: number;
  automatic: boolean;
}

`getLines(officeId: number)`

Obtiene las líneas/trámites de una oficina específica.

const lines = await zeroq.getLines(123);

Gestión de Tickets

`createTicket(params: ICreateTicketParams)`

Crea un nuevo ticket.

const ticket = await zeroq.createTicket(123, {
  metadata: {
    dni: "12345678",
    print: true
  }
});

Procesamiento de Pagos

`processPayment(params: IProcessPaymentParams)`

Procesa un pago.

const payment = await zeroq.processPayment({
  amount: 10000,
  meta: {
    voucher: true,
    description: "Pago de trámite",
    reference_id: "ABC123"
  }
});

Impresión de Documentos

`printDocument(params: IPrintDocumentParams)`

Imprime un documento.

const result = await zeroq.printDocument({
  printerType: "thermalPrinter",
  content: "<h1>Ticket de atención</h1>",
  contentType: "html"
});

Manejo de Errores

El SDK utiliza un sistema de errores tipados:

enum ErrorType {
  INITIALIZATION = "INITIALIZATION_ERROR",
  NETWORK = "NETWORK_ERROR",
  VALIDATION = "VALIDATION_ERROR",
  PRINTER = "PRINTER_ERROR",
  PAYMENT = "PAYMENT_ERROR",
  OFFICE = "OFFICE_ERROR",
  LINE = "LINE_ERROR",
  CREATETICKET = "CREATE_TICKET_ERROR",
  UNKNOWN = "UNKNOWN_ERROR"
}

interface SDKError {
  type: ErrorType;
  code: string;
  message: string;
  details?: unknown;
}

Ejemplo de manejo de errores:

try {
  await zeroq.createTicket(123, {
    metadata: { dni: "12345678" }
  });
} catch (error) {
  if (error.type === ErrorType.VALIDATION) {
    console.error('Error de validación:', error.message);
  }
}

Tipos de Datos

Estado del SDK

interface SDKStatus {
  initialized: boolean;
  apiKeyValid: boolean;
  recommendations?: string[];
}

Respuesta de Pago

interface PaymentTransbankResponse {
  functionCode: number;
  responseCode: number;
  responseMessage: string;
  commerceCode: number;
  terminalId: string;
  successful: boolean;
  ticket?: number;
  authorizationCode: string | null;
  amount: number;
  last4Digits: number;
  operationNumber: string;
}

interface PaymentNiubizResponse {
  date: string;
  time: string;
  authNumber: string;
  transactionId: string;
  voucherMerchant: string;
  voucherClient: string;
}

Ejemplos

Flujo Completo de Creación de Ticket

import { zeroq } from 'service-kiosk';

async function crearTicket() {
  try {
    // 1. Inicializar SDK
    await zeroq.init({
      apiKey: "tu-api-key",
      officeId: 123
    });

    // 2. Verificar si estamos en un kiosko
    const isKiosk = await zeroq.isKiosk();
    if (!isKiosk) {
      throw new Error('Esta aplicación debe correr en un kiosko');
    }

    // 3. Obtener líneas disponibles
    const lines = await zeroq.getLines(123);

    // 4. Crear ticket
    const ticket = await zeroq.createTicket(123, {
      metadata: {
        dni: "12345678",
        print: true
      }
    });

    console.log('Ticket creado:', ticket);
  } catch (error) {
    console.error('Error:', error);
  }
}

Procesamiento de Pago con Impresión

async function procesarPago() {
  try {
    // 1. Procesar el pago
    const payment = await zeroq.processPayment({
      officeId: "123",
      ticketId: "789",
      amount: 10000,
      meta: {
        voucher: true,
        description: "Pago de servicio"
      }
    });

    // 2. Imprimir comprobante
    if (payment.successful) {
      await zeroq.printDocument({
        printerType: "thermalPrinter",
        content: `
          <h1>Comprobante de Pago</h1>
          <p>Monto: ${payment.amount}</p>
          <p>Autorización: ${payment.authorizationCode}</p>
        `,
        contentType: "html"
      });
    }
  } catch (error) {
    console.error('Error en el proceso:', error);
  }
}