README

SDK PHP 8.3+ per l'integrazione delle API Acube per gli Scontrini Elettronici (Documento Commerciale italiano).

Installazione

composer require andreaballarin/acube-italy-receipts

Requisiti

• PHP: ^8.3
• PSR-18 HTTP Client: Guzzle ^7.8 (incluso)
• Certificati mTLS: Rilasciati da Acube per il tuo cash register

Quick Start

1. Login e ottieni il token JWT

use AndreaBallarin\ACubeItalyReceipts\{AuthenticationService, Environment};

$auth = new AuthenticationService(environment: Environment::Sandbox);
$token = $auth->login(
    email: 'your@email.com',
    password: 'your-password',
);

2. Setup del Client

use AndreaBallarin\ACubeItalyReceipts\Client;

$client = new Client(
    bearerToken: $token,
    environment: Environment::Sandbox,
    mtlsCertPath: '/path/to/cert.pem',
    mtlsKeyPath: '/path/to/key.pem',
    mtlsKeyPassphrase: 'passphrase-if-any', // opzionale
);

3. Registra il Client per l'utilizzo statico

use AndreaBallarin\ACubeItalyReceipts\Resources\Receipt;

Receipt::setClient($client);

4. Crea uno scontrino

use AndreaBallarin\ACubeItalyReceipts\Resources\{ReceiptDraft, ReceiptItem};

$item = new ReceiptItem(
    quantity: '1.00',
    description: 'Espresso',
    unitPrice: '1.20',
    vatRateCode: '10.00',
);

$draft = new ReceiptDraft(
    items: [$item],
    cashPaymentAmount: '1.20',
);

$receipt = Receipt::create($draft);
echo "UUID: " . $receipt->uuid;
echo "Documento: " . $receipt->documentNumber;

5. Recupera e annulla

$fetched = Receipt::get($receipt->uuid);
$voided = $fetched->void('Customer returned');

Login & Autenticazione

L'SDK include AuthenticationService per gestire il login presso Acube:

use AndreaBallarin\ACubeItalyReceipts\AuthenticationService;

$auth = new AuthenticationService(environment: Environment::Sandbox);
try {
    $token = $auth->login(email: 'user@example.com', password: 'secret');
    // Usa il token con il Client
} catch (AcubeAuthenticationException $e) {
    echo "Login failed: invalid credentials";
}

Note:

• AuthenticationService chiama POST https://common-sandbox.api.acubeapi.com/login (endpoint separato)
• Non richiede mTLS (diversamente da eReceipts)
• Ritorna direttamente il JWT Bearer token
• Il token è necessario per creare il Client che accede agli scontrini

Features

Punto 1: Dependency Injection

Due modalità di utilizzo:

• Statica (Service Locator): Receipt::setClient($client) + Receipt::create(...)
• Instance-based (DI-friendly): Passa il client al costruttore se la tua classe lo supporta

Punto 2: DecimalAmount Validation

Tutti gli importi/quantità sono string per preservare la precisione. DecimalAmount::assertValid() fallisce velocemente:

new ReceiptItem(
    quantity: '1.00',      // validato automaticamente
    unitPrice: '10.50',    // validato
);

Punto 3: UUID Validation

UuidValidator valida localmente prima di fare richieste HTTP:

Receipt::get('invalid-uuid'); // InvalidArgumentException locale, non 404 da Acube

Punto 4: PSR-3 Logging

Inietta un logger PSR-3 per registrare:

• Richieste POST critiche (creazione documenti)
• Errori API (status ≥400)
• Errori di trasporto

$client = new Client(
    bearerToken: $token,
    logger: $myLogger, // Psr\Log\LoggerInterface
);

Gestione Errori

use AndreaBallarin\ACubeItalyReceipts\Exceptions\{
    AcubeValidationException,
    AcubeNotFoundException,
    AcubeException,
};

try {
    $receipt = Receipt::create($draft);
} catch (AcubeValidationException $e) {
    foreach ($e->violations() as $field => $msg) {
        echo "$field: $msg";
    }
} catch (AcubeNotFoundException $e) {
    echo "Document not found";
} catch (AcubeException $e) {
    echo "API Error [{$e->problem->status}]: {$e->problem->detail}";
}

Idempotenza (Best-Effort, Client-Side)

$receipt = Receipt::create(
    draft: $draft,
    idempotencyKey: 'unique-key-123',
    idempotencyWindowSeconds: 60,
);
// Se ripeti la stessa chiave entro 60 secondi: AcubeDuplicateRequestException

Nota: Questa guardia protegge solo dentro lo stesso processo. Acube non offre idempotency key server-side, quindi un timeout di rete potrebbe causare duplicati.

Test

composer test

Struttura

src/
  Client.php                    # Transport PSR-18, logging PSR-3
  Environment.php               # Enum Sandbox|Production
  Model.php                     # Base per i dati
  ApiResource.php               # Base per le risorse (setClient/client)
  Internal/
    DecimalAmount.php           # Validazione importi
    UuidValidator.php           # Validazione UUID RFC 4122
    IdempotencyGuard.php        # Guardia client-side idempotenza
  Exceptions/
    AcubeException.php          # Base astratta
    AcubeAuthenticationException.php    # 401
    AcubeValidationException.php        # 422
    ... (e altre per 403, 404, 409, 500, 503)
  Resources/
    Receipt.php                 # Documento emesso (ReceiptOutput)
    ReceiptDraft.php            # Payload di creazione (ReceiptInput)
    ReceiptItem.php             # Riga di dettaglio
    Enums/
      ReceiptType.php
      ReceiptStatus.php
      ReceiptItemType.php

Licenza

MIT

Autore

Andrea Ballarin ballarinandrea@icloud.com