@openade/pem

Libreria Punto di Emissione per scontrini fiscali e documenti commerciali italiani.

Funzionalità

• 🧾 Emissione documenti commerciali con generazione PDF
• 📊 Generazione codice a barre Data Matrix
• 📝 Registro hash-chain per immutabilità
• 🔄 Sincronizzazione PEM → PEL in tempo reale
• 🎲 Codici lotteria istantanei/differiti
• 💾 Interfaccia storage flessibile
• 📱 Supporto per vari tipi di dispositivi

Installazione

npm install @openade/pem @openade/common

Guida Rapida

1. Crea Manager PEM

import { PEMManager, EmissionPointType } from '@openade/pem';

const pem = new PEMManager(
  {
    deviceType: EmissionPointType.SOFTWARE_SOLUTION,
    serialNumber: 'PEM001',
    vatNumber: '12345678901',
    businessName: 'My Shop SRL',
    pelUrl: 'https://pel.example.com', // Opzionale: per sincronizzazione in tempo reale
  },
  myStorage
);

2. Apri Sessione Vendita

await pem.openSession();

3. Emetti Scontrino

const lines = [
  {
    description: 'Prodotto 1',
    quantity: 2,
    unitPrice: 10.0,
    vatRate: 22,
  },
  {
    description: 'Prodotto 2',
    quantity: 1,
    unitPrice: 25.0,
    vatRate: 22,
  },
];

const result = await pem.emitReceipt(lines);

console.log('Documento:', result.document);
console.log('Hash:', result.hash);
console.log('Sincronizzato:', result.synced);

4. Chiudi Sessione

await pem.closeSession();

Costruttore Documenti

Crea documenti manualmente:

import { DocumentBuilder } from '@openade/pem';

const builder = new DocumentBuilder({
  vatNumber: '12345678901',
  businessName: 'My Company',
  pemId: 'PEM001',
});

const document = builder
  .setNumber('0001-0001')
  .setDateTime(new Date().toISOString())
  .addLine('Prodotto', 10.0, 22, 1)
  .addPayment('CASH', 10.0)
  .build();

Generazione PDF

Genera PDF con Data Matrix:

import { generateCommercialDocumentPDF } from '@openade/pem';

const pdfBuffer = await generateCommercialDocumentPDF(document, {
  includeDataMatrix: true,
  dataMatrixSize: 200,
});

Gestione Registro

Accedi al registro hash-chain:

const journal = pem.getJournal();
const entries = journal.getEntries();
const lastHash = journal.getLastHash();

Codici Lotteria

Genera codici lotteria:

import { LotteryGenerator } from '@openade/pem';

const generator = new LotteryGenerator({
  vatNumber: '12345678901',
  deviceId: 'PEM001',
});

// Lotteria istantanea
const instantCode = generator.generateInstantLottery();

// Lotteria differita (per il giorno successivo)
const deferredCode = generator.generateDeferredLottery();

Interfaccia Storage

Implementa IPEMStorage per storage personalizzato:

import { IPEMStorage } from '@openade/pem';

class MyStorage implements IPEMStorage {
  async saveDocument(number: string, document: DocumentoCommerciale): Promise<void> {
    // Salva documento
  }

  async loadDocument(number: string): Promise<DocumentoCommerciale | null> {
    // Carica documento
  }

  async saveJournal(entries: JournalEntry[]): Promise<void> {
    // Salva registro
  }

  async loadJournal(): Promise<JournalEntry[]> {
    // Carica registro
  }
}

Client PEL

Connetti al server PEL per sincronizzazione in tempo reale:

import { PELClient } from '@openade/pem';

const pelClient = new PELClient({
  pelBaseUrl: 'https://pel.example.com',
});

// Ottieni seed sessione
const { seed } = await pelClient.getSessionSeed();

// Invia documento
const result = await pelClient.sendDocument(document);

Tipi Dispositivo

• SOFTWARE_SOLUTION: Soluzione software
• HARDWARE_DEVICE: Dispositivo hardware
• MOBILE_APP: Applicazione mobile
• WEB_APP: Applicazione web

Riferimento API

PEMManager

class PEMManager {
  constructor(config: PEMConfig, storage: IPEMStorage);
  openSession(): Promise<void>;
  closeSession(): Promise<void>;
  emitReceipt(
    lines: DocumentLine[]
  ): Promise<{ document: DocumentoCommerciale; hash: string; synced: boolean }>;
  getJournal(): JournalManager;
  syncWithPEL(): Promise<void>;
}

DocumentBuilder

class DocumentBuilder {
  constructor(config: DocumentBuilderConfig);
  setNumber(number: string): DocumentBuilder;
  setDateTime(dateTime: string): DocumentBuilder;
  addLine(
    description: string,
    unitPrice: number,
    vatRate: number,
    quantity?: number
  ): DocumentBuilder;
  addPayment(method: string, amount: number): DocumentBuilder;
  build(): DocumentoCommerciale;
}

JournalManager

class JournalManager {
  openCash(): void;
  closeCash(): void;
  addDocument(document: DocumentoCommerciale): string;
  getEntries(): JournalEntry[];
  getLastHash(): string;
  validateChain(): boolean;
}

Esempi

Vedi examples/pem/ per esempi completi funzionanti.

Specifiche

Basato su:

• Specifiche SSW (Soluzione Software) v1.1
• Regolamenti scontrini fiscali italiani
• Documentazione tecnica Agenzia delle Entrate

Licenza

MIT

Disclaimer

Questa libreria non è affiliata con l'Agenzia delle Entrate. Utilizzare a proprio rischio.