Per utilizzare l’integrazione è necessario che il DeepLink venga aperto da un dispositivo su cui sia installata l’app Scontrina.

L’integrazione consente di inviare automaticamente a Scontrina i dati del documento commerciale da emettere, ad esempio partendo da:

• ordini;

• carrelli;

• comande;

• gestionali;

• e-commerce;

• sistemi di cassa.

Cos’è l’integrazione DeepLink

L’integrazione DeepLink permette di aprire direttamente Scontrina passando:

• voci del documento;

• importi;

• pagamenti;

• operatore;

• riferimenti esterni.

In questo modo il gestionale può preparare automaticamente il documento commerciale all’interno dell’App.

Vantaggi dell’integrazione

L’integrazione DeepLink:

• non richiede accreditamenti specifici;

• può essere implementata rapidamente;

• non richiede hardware dedicato;

• riduce il lavoro manuale;

• consente integrazioni leggere e veloci.

Formato JSON supportato

Il DeepLink deve contenere un payload JSON con le informazioni del documento commerciale.

Esempio di payload JSON semplificato:

  {
   "scontrina" : {

     // voci dello scontrino
     "entries": [
     {
       "description": "Descrizione dell'articolo",
       "price": 10.99,
       "quantity": 2,
       "vatCode": "22"
     },
     // ... altre voci dell'elenco
     ],
     "paidCash": 5.0,
     "paidElectronic": 5.0,
     "noPaid": [
     {
       "amount": 10.0,
       "type": "Tipo di pagamento non effettuato"
     },
     // ... altri dettagli di pagamento non effettuato
     ],
     "lotteryCode": "Codice della lotteria",
     "paidTicketInfo": {
       // Dettagli aggiuntivi sull'importo pagato tramite ticket restaurant
     },
     "operatorId": "ID dell'operatore",
     "operatorName": "Nome dell'operatore",
     "channelId": "Riferimento del tuo gestionale, utile per la riconciliazione"
   }
 }

 Interfaccia TypeScript di riferimento

 // JSON root
 interface IDeepLinkCodeEmitRequest {
     scontrina: IEmitRequest;
 }
 
 interface IEmitRequest {
     entries: ICheckoutEntry[];
     paidCash?: number;
     paidElectronic?: number;
     noPaid?: { amount: number, type: NoPaidType }[];
     lotteryCode?: string;
     paidTicketInfo?: IPaidTicketInfo;
     operatorId?: string;
     operatorName?: string;
     channelId?: string;
 }

 interface ICheckoutEntry {
     description: string;
     price: number;          // should be greater than 0
     quantity: number;       // should be greater than 0
     vatCode: string;        // should be one of the supported codes:
                                 4, 5, 10, 22, N1, N2, N3, N4, N5, N6
 }
       

Campi principali supportati

entries
Voci del documento commerciale.

paidCash
Importo pagato in contanti.

paidElectronic
Importo pagato elettronicamente.

noPaid
Pagamenti non riscossi.

lotteryCode
Codice lotteria degli scontrini.

operatorId / operatorName
Informazioni operatore.

channelId
Riferimento esterno del gestionale utile per riconciliazioni.

Codici IVA supportati

Il campo vatCode supporta i seguenti valori:

• 4

• 5

• 10

• 22

• N1

• N2

• N3

• N4

• N5

• N6

Generazione del DeepLink

Il DeepLink utilizza:

• protocollo: scontrina://

• operazione: issue/1.0

Esempio:

const deepLink =scontrina://issue/1.0?p=${encodeURIComponent(payload)}&c=${encodeURIComponent(callbackURL)}

Callback URL

È possibile specificare una callback URL per riportare l’utente alla propria applicazione dopo l’apertura di Scontrina.

 Codice di esempio in javascript per generare il link

// Oggetto 'doc' contenente i dettagli dello scontrino
const doc = {
 scontrina: {
   entries: [
     {
       description: "Descrizione dell'articolo",
       price: 10,
       quantity: 2,
       vatCode: "22"
     }
   ],
   channelId: "externalId_1234"
 }
};

// Serializzazione dell'oggetto 'doc' in formato JSON
const payload = JSON.stringify(doc);

// URL di callback per reindirizzare alla tua app
const callbackURL = "http://linktoyourapp.com";

// URL personalizzato per l'operazione scontrina
const scontrinaCustomURL = "scontrina://";
const scontrinaOperation = "issue/1.0";

// Creazione del deep link concatenando i parametri
const deepLink = ${scontrinaCustomURL}${scontrinaOperation}?p=${encodeURIComponent(payload)}&c=${encodeURIComponent(callbackURL)};

// Stampa del deep link generato (solo per debugging)
console.log(deepLink);
       

Come testare il DeepLink

Per provare il funzionamento:

1. installa Scontrina sul dispositivo;

2. genera il DeepLink;

3. apri il DeepLink da un dispositivo su cui sia installato Scontrina.