ACube eReceipts JS SDK

SDK ufficiale per l'integrazione con la piattaforma ACube eReceipt in applicazioni Expo/React Native.

Caratteristiche

• Gestione completa scontrini elettronici (creazione, annullo, reso)
• Autenticazione JWT e mTLS
• Gestione stati app (NORMAL, WARNING, BLOCKED, OFFLINE)
• Polling automatico - Notifiche e telemetria con polling configurabile
• TypeScript first con tipizzazione completa
• Ottimizzato per Expo e React Native

Quick Start

Installazione

# Con bun (consigliato)
bun add @a-cube-io/ereceipts-js-sdk

# Con npm
npm install @a-cube-io/ereceipts-js-sdk

# Con yarn
yarn add @a-cube-io/ereceipts-js-sdk

Dipendenze Expo

expo install expo-secure-store @react-native-async-storage/async-storage

Dipendenza mTLS (per operazioni fiscali)

Per utilizzare l'autenticazione mTLS (richiesta per creare scontrini, annulli, PEM, ecc.):

npx expo install @a-cube-io/expo-mutual-tls

Nota: mTLS richiede un development build, non funziona con Expo Go.

Utilizzo con SDKManager (Raccomandato)

import { SDKManager } from '@a-cube-io/ereceipts-js-sdk';

// 1. Configura (una volta all'avvio)
SDKManager.configure({
  environment: 'sandbox',
  notificationPollIntervalMs: 30000,
});

// 2. Inizializza
const manager = SDKManager.getInstance();
await manager.initialize();

// 3. Osserva lo stato dell'app
manager.appState$.subscribe(state => {
  console.log('Mode:', state.mode); // NORMAL, WARNING, BLOCKED, OFFLINE
});

// 4. Usa i servizi
const services = manager.getServices();
await services.login({ email: '[email protected]', password: 'password' });
const receipts = await services.receipts.list();

// 5. Cleanup
SDKManager.destroy();

Utilizzo Base (Alternativo)

import { createACubeSDK } from '@a-cube-io/ereceipts-js-sdk';

// Inizializza SDK
const sdk = await createACubeSDK({
  environment: 'sandbox',
});

// Login
const user = await sdk.login({
  email: '[email protected]',
  password: 'password',
});

// Crea scontrino
const receipt = await sdk.receipts.create({
  items: [
    {
      description: 'Prodotto esempio',
      quantity: '1',
      unitPrice: '10.00',
      vatRateCode: '22',
    },
  ],
});

console.log('Scontrino creato:', receipt.documentNumber);

Documentazione

Getting Started

• Installazione
• Configurazione
• Setup Expo
• Autenticazione

API Reference

• SDKManager - API semplificata per produzione
• ACubeSDK - API completa
• AppStateService - Gestione stati app
• Notifications - Sistema notifiche
• Telemetry - Telemetria PEM

Esempi

• Esempi Base
• Notifiche e Telemetria - Esempio Expo completo

Troubleshooting

• Problemi Comuni

Ambienti Disponibili

| Ambiente | URL API | Descrizione | |----------|---------|-------------| | sandbox | https://ereceipts-it-sandbox.acubeapi.com | Test e sviluppo | | development | https://ereceipts-it.dev.acubeapi.com | Sviluppo interno | | production | https://ereceipts-it.acubeapi.com | Produzione |

Requisiti

• Expo SDK 50+
• React Native 0.73+
• TypeScript 5.0+
• iOS 13+ / Android API 24+

Repository API

L'SDK espone i seguenti repository tramite SDKManager.getServices() o sdk:

| Repository | Descrizione | |------------|-------------| | receipts | Gestione scontrini | | merchants | Gestione esercenti | | cashiers | Gestione cassieri | | cashRegisters | Gestione registratori di cassa | | pointOfSales | Gestione POS | | suppliers | Gestione fornitori | | pems | Gestione PEM (MF2) | | dailyReports | Report giornalieri | | journals | Gestione giornali | | notifications | Notifiche sistema | | telemetry | Telemetria PEM |

Stati App

Il sistema gestisce automaticamente gli stati dell'applicazione basandosi sulle notifiche dal backend:

| Stato | Trigger | Descrizione | |-------|---------|-------------| | NORMAL | SYS-I-01 | App funziona normalmente | | WARNING | SYS-W-01 | Banner avviso con countdown | | BLOCKED | SYS-C-01 | Solo visualizzazione telemetria | | OFFLINE | No network | Ultimo stato disponibile |

Licenza

Proprietary - ACube S.r.l.