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
• Inicio Rápido
• Configuración
• API Reference
  • Inicialización
  • Verificación de Entorno
  • Gestión de Oficinas
  • Gestión de Tickets
  • Procesamiento de Pagos
  • Impresión de Documentos
• Manejo de Errores
• Tipos de Datos
• Ejemplos

Instalación

NPM

npm i zeroq-sdk-self-service

CDN

<script src="https://cdn.jsdelivr.net/npm/zeroq-sdk-self-service/dist/main.umd.min.js"></script>

Inicio Rápido

import { zeroq } from 'zeroq-sdk-self-service';

// Inicializar el SDK
const init = async () => {
  try {
    const config = await zeroq.init({
      apiKey: "tu-api-key",
    });
    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 |

API Reference

Inicialización

init(options: InitOptions)

Inicializa el SDK con las opciones proporcionadas.

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

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(1234);

Gestión de Tickets

createTicket(params: ICreateTicketParams)

Crea un nuevo ticket.

const ticket = await zeroq.createTicket(1234, {
  meta: {
    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(1234, {
    meta: { 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 'zeroq-sdk-self-service';

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

    // 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(1234);

    // 4. Crear ticket
    const ticket = await zeroq.createTicket(1234, {
      meta: {
        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);
  }
}

Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.