Guida all'integrazione di RECEIPT

Guida all’integrazione di RECEIPT

Questa guida vi accompagna attraverso l’integrazione dell’API fiskaly RECEIPT per sostituire le ricevute cartacee con ricevute digitali legalmente conformi in tutti i paesi dell’UE.

📘Specifica API dettagliata

Per il riferimento API completo, inclusi tutti gli endpoint, gli schemi e i parametri, consultate la documentazione dell’API RECEIPT. Questa guida tratta il flusso di integrazione concettuale.

Prerequisiti

Prima di iniziare, assicuratevi di avere:

Un’organizzazione fiskaly con RECEIPT attivato (contattate sales@fiskaly.com o il vostro account manager)
Credenziali API (chiave API e segreto) per il servizio RECEIPT
Un sistema di cassa o un’applicazione in grado di effettuare richieste HTTPS

Panoramica dell’integrazione

Il flusso di RECEIPT funziona in tre fasi:

Creare — Il vostro sistema di cassa invia i dati della transazione all’API RECEIPT
Consegnare — L’API genera una ricevuta digitale e restituisce un meccanismo di consegna (codice QR, link, ecc.)
Presentare — Il cliente riceve la ricevuta tramite il suo canale preferito

Integrazione passo dopo passo

Autenticarsi
Ottenete un token di accesso utilizzando le vostre credenziali dell’API RECEIPT:
Terminal window
curl -X POST https://receipt.fiskaly.com/api/v1/auth \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET" }'
La risposta include un access_token valido per 24 ore. Includetelo come token Bearer in tutte le richieste successive.
Configurare il profilo del commerciante
Configurate le informazioni del vostro commerciante che appariranno su tutte le ricevute generate:
- Ragione sociale e forma giuridica
- Indirizzo e informazioni di contatto
- Numeri di identificazione fiscale
- Logo (opzionale)
- Preferenze di personalizzazione delle ricevute

Creare una ricevuta

Dopo ogni transazione, inviate i dati della ricevuta all’API RECEIPT:

curl -X POST https://receipt.fiskaly.com/api/v1/receipts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "description": "Product A",
        "quantity": 2,
        "unit_price": 1299,
        "vat_rate": "19.00"
      }
    ],
    "payment": {
      "method": "card",
      "amount": 2598
    }
  }'

Gli importi sono espressi nell’unità monetaria più piccola (centesimi).

Presentare la ricevuta al cliente
La risposta dell’API include le opzioni di consegna:
- Codice QR — Visualizzare sul display del sistema di cassa o stampare un piccolo codice QR che il cliente può scansionare
- Codice statico — Un codice persistente collegato al commerciante per i clienti abituali
- Link diretto — Un URL che il cliente può aprire in qualsiasi browser
Il cliente visualizza la propria ricevuta su receipt.fiskaly.com — non è richiesto il download di un’app.
Collegare con fiskaly SIGN (opzionale)
Se utilizzate fiskaly SIGN per la conformità fiscale, RECEIPT può collegare automaticamente le ricevute alle transazioni firmate. Questo fornisce:
- Inclusione automatica dei dati di firma fiscale nella ricevuta digitale
- Supporto per la validazione del codice QR
- Catena di audit completa dalla transazione alla consegna della ricevuta

Canali di consegna

Canale	Come funziona	Ideale per
Codice QR	Il cliente scansiona un codice QR visualizzato su schermo o stampato	Sistema di cassa in negozio, servizio rapido
Codice statico	Codice QR persistente collegato alla sede del commerciante	Display al bancone, segnaposto al tavolo
E-mail	Ricevuta inviata direttamente all’e-mail del cliente	E-commerce, prenotazioni
Link	URL condivisibile alla ricevuta ospitata	Qualsiasi canale di consegna

💡Nessuna app necessaria

RECEIPT funziona interamente via web. I clienti visualizzano le ricevute nel loro browser su receipt.fiskaly.com — nessun download di app, creazione di account o registrazione necessaria.

Conformità normativa

Le ricevute digitali generate da RECEIPT sono legalmente conformi in tutti i paesi dell’UE:

Soddisfa i requisiti dei documenti elettronici ai sensi della Direttiva IVA dell’UE
Conforme alle obbligazioni specifiche per paese relative alle ricevute (Germania, Austria, Francia, ecc.)
Sicurezza dei dati garantita dalla certificazione ISO 27001 di fiskaly
Le ricevute sono immutabili una volta create — viene mantenuta la catena di audit completa

Provate ora

Create una ricevuta dimostrativa per vedere l’esperienza del cliente prima di integrare.

Risorse

Per informazioni tecniche più dettagliate, scaricate la guida all’integrazione completa:

Guida all’integrazione (PDF) — Riferimento API completo con esempi di richiesta/risposta
Riferimento API RECEIPT — Specifica OpenAPI completa
Quick Start — Configurazione minima per creare la prima ricevuta
FAQ — Domande frequenti su RECEIPT

Was this page helpful?