PHPackages andreaballarin/acube-italy-receipts - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. andreaballarin/acube-italy-receipts ActiveLibrary[Utility & Helpers](/categories/utility) andreaballarin/acube-italy-receipts =================================== Acube Italy Receipts Library v1.0.11(1mo ago)034MITPHP ^8.3 Since Jul 6Compare [ Source](https://github.com/andreaballarin/acube-italy-receipts)[ Packagist](https://packagist.org/packages/andreaballarin/acube-italy-receipts)[ RSS](/packages/andreaballarin-acube-italy-receipts/feed)WikiDiscussions Synced 1w ago READMEChangelogDependencies (30)Versions (13)Used By (0) Acube eReceipts PHP SDK ======================= [](#acube-ereceipts-php-sdk) SDK PHP 8.3+ per l'integrazione delle API Acube per gli Scontrini Elettronici (Documento Commerciale italiano). Installazione ------------- [](#installazione) ``` composer require andreaballarin/acube-italy-receipts ``` Requisiti --------- [](#requisiti) - **PHP**: ^8.3 - **PSR-18 HTTP Client**: Guzzle ^7.8 (incluso) - **Certificati mTLS**: Rilasciati da Acube per il tuo cash register Quick Start ----------- [](#quick-start) ### 1. Login e ottieni il token JWT [](#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 [](#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 [](#3-registra-il-client-per-lutilizzo-statico) ``` use AndreaBallarin\ACubeItalyReceipts\Resources\Receipt; Receipt::setClient($client); ``` ### 4. Crea uno scontrino [](#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 [](#5-recupera-e-annulla) ``` $fetched = Receipt::get($receipt->uuid); $voided = $fetched->void('Customer returned'); ``` Onboarding: Merchant → PEM → Cash Register ------------------------------------------ [](#onboarding-merchant--pem--cash-register) Prima di poter emettere scontrini serve completare l'onboarding: creare un merchant, creare e attivare un PEM, poi creare il cash register che rilascia il certificato mTLS. Vedi [`examples/complete-supplier-onboarding.php`](examples/complete-supplier-onboarding.php) per il flusso completo. **Importante**: `Merchant`/`Pem::create()`/`Pem::get()`/`Pem::activate()`/`CashRegister::create()` usano la porta standard (nessun mTLS) — solo gli endpoint `/mf1/receipts*` (`Receipt`, `ReceiptDetails`) richiedono mTLS e vengono chiamati automaticamente sulla porta `444` quando il `Client` ha `mtlsCertPath` configurato. Usa quindi **Client separati**: uno senza mTLS per l'onboarding, uno con mTLS per gli scontrini. Poiché `ApiResource::setClient()` condivide un unico slot statico tra tutte le resource, richiama `setClient()` ogni volta che cambi Client. ### 1. Crea un merchant [](#1-crea-un-merchant) ``` use AndreaBallarin\ACubeItalyReceipts\Resources\{Merchant, MerchantDraft}; use AndreaBallarin\ACubeItalyReceipts\ValueObjects\Address; Merchant::setClient($supplierClient); // Client con il token del Supplier, senza mTLS $merchant = Merchant::create(new MerchantDraft( vatNumber: '12345678901', address: new Address( streetAddress: 'street name', streetNumber: 'xx', zipCode: '00000', city: 'City', province: 'XX', ), businessName: 'business name', email: 'merchant@example.com', password: 'MerchantP4$$w0rd', )); ``` ### 2. Crea e attiva un PEM [](#2-crea-e-attiva-un-pem) ``` use AndreaBallarin\ACubeItalyReceipts\Resources\Pem; $pem = Pem::create($merchant->uuid); // ancora col client Supplier Pem::setClient($merchantClient); // Client col token del Merchant, senza mTLS Pem::activate($pem->serialNumber, $pem->registrationKey); ``` ### 3. Crea il cash register (rilascia il certificato mTLS) [](#3-crea-il-cash-register-rilascia-il-certificato-mtls) ``` use AndreaBallarin\ACubeItalyReceipts\Resources\CashRegister; CashRegister::setClient($merchantClient); $cashRegister = CashRegister::create($pem->serialNumber, 'Cash register first floor'); // mtlsCertificate e privateKey sono già "unescaped" (newline reali), pronti per il disco file_put_contents('/var/certs/pems/A2F4-000001/cr-cert.pem', $cashRegister->mtlsCertificate); file_put_contents('/var/certs/pems/A2F4-000001/cr-key.pem', $cashRegister->privateKey); ``` ### 4. Recupera il dettaglio fiscale completo di uno scontrino [](#4-recupera-il-dettaglio-fiscale-completo-di-uno-scontrino) ``` use AndreaBallarin\ACubeItalyReceipts\Resources\ReceiptDetails; $details = ReceiptDetails::get($receipt->uuid); // richiede lo stesso Client mTLS di Receipt echo "Imponibile: {$details->totalTaxableAmount}, IVA: {$details->totalVatAmount}"; foreach ($details->items as $item) { echo "{$item->description}: {$item->unitPrice}\n"; } ``` Login & Autenticazione -------------------------- [](#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 -------- [](#features) ### Punto 1: Dependency Injection [](#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 [](#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 [](#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 [](#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 --------------- [](#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) -------------------------------------- [](#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 ---- [](#test) ``` composer test ``` Struttura --------- [](#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) ValueObjects/ ProblemDetails.php # RFC 7807 Address.php # Indirizzo (merchant/PEM) Resources/ Merchant.php # Merchant registrato (MerchantOutput) MerchantDraft.php # Payload di creazione (MerchantInput) Pem.php # PEM: create/get/activate CashRegister.php # Cash register: create (rilascia mTLS) Receipt.php # Documento emesso (ReceiptOutput) ReceiptDraft.php # Payload di creazione (ReceiptInput) ReceiptItem.php # Riga di dettaglio ReceiptDetails.php # Dettaglio fiscale completo (righe + totali) Enums/ ReceiptType.php ReceiptStatus.php ReceiptItemType.php ``` Licenza ------- [](#licenza) MIT Autore ------ [](#autore) Andrea Ballarin ### Health Score 43 — FairBetter than 89% of packages Maintenance92 Actively maintained with recent releases Popularity10 Limited adoption so far Community2 Small or concentrated contributor base Maturity56 Maturing project, gaining track record How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 12 Last Release 39d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/93cc4238561d067101b8e6a082a03b16d0f34bf4432c4fa8fdbdc63e8d0cb4df?d=identicon)[andreaballarin](/maintainers/andreaballarin) --- Tags italyfiscalacubeereceiptsscontrino-elettronicodocumento-commerciale ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/andreaballarin-acube-italy-receipts/health.svg) ``` [![Health](https://phpackages.com/badges/andreaballarin-acube-italy-receipts/health.svg)](https://phpackages.com/packages/andreaballarin-acube-italy-receipts) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.3k37.6k21](/packages/tempest-framework)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.8M683](/packages/shopware-core)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 86337.5k](/packages/flow-php-flow)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 762297.9k53](/packages/civicrm-civicrm-core)[aws/aws-sdk-php AWS SDK for PHP - Use Amazon Web Services in your PHP project 6.2k555.0M2.8k](/packages/aws-aws-sdk-php)[shopware/platform The Shopware e-commerce core 3.4k1.5M3](/packages/shopware-platform) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)