Condividi tramite

Generare codici QR e stamparli sulle ricevute per l'Arabia Saudita

  • Articolo

Nota

La funzionalità descritta in questo articolo è pensata per supportare i requisiti della Fase 1 dell'implementazione della fatturazione elettronica nel Regno dell'Arabia Saudita. Per informazioni sulle funzionalità pensate per supportare i requisiti della Fase 2 dell'implementazione della fatturazione elettronica nel Regno dell'Arabia Saudita, vedere Generare e inviare fatture elettroniche semplificate per l'Arabia Saudita.

Questo articolo fornisce una panoramica delle funzionalità per la stampa di codici QR disponibili in Arabia Saudita Microsoft Dynamics 365 Commerce.

In un negozio collegato a un'entità giuridica con sede principale in Arabia Saudita, gli utenti possono stampare un codice QR sulla ricevuta per una transazione di vendita cash-and-carry o per un ordine del cliente. Il codice QR contiene le seguenti informazioni.

Sequenza Campo Origine dati
1 Nome società Il nome della persona giuridica
2 Numero di partita IVA dell'azienda Il numero di registrazione fiscale della persona giuridica
3 Data e ora della transazione La data e l'ora della transazione nel negozio al dettaglio
4 Importo totale della ricevuta (inclusa l'imposta sul valore aggiunto [IVA]) L'importo totale della transazione del negozio al dettaglio
5 Importo totale dell'IVA incluso nella ricevuta L'importo totale dell'imposta sulla transazione del negozio al dettaglio

Nota

Quando vengono create transazioni di ordini cliente, l'importo totale della ricevuta viene calcolato sommando gli importi totali di tutte le righe di transazione che utilizzano la modalità di consegna con asporto.

Il codice QR viene generato applicando la trasformazione base64 alle informazioni sulla transazione codificate nel formato Tag-Length-Value (TLV). L'Autorità fiscale e doganale (ZATCA) fornisce strumenti che possono essere utilizzati per convalidare il codice QR. Per maggiori informazioni sui requisiti fatturazione elettronica e sulle capacità di convalida del codice QR, consultare Portale di fatturazione elettronica di ZATCA.

Imposta i codici QR

Per generare codici QR e stamparli sulle ricevute per l'Arabia Saudita, è necessario completare le seguenti attività.

  1. Configurare i campi personalizzati in modo che possano essere utilizzati nei formati di ricevuta per le ricevute di vendita.
  2. Configura i formati delle ricevute.
  3. Specificare le dimensioni del codice QR nei parametri di Commercio.
  4. Abilita le estensioni runtime Commerce (CRT).

Configurare i campi personalizzati in modo che possano essere utilizzati nei formati per ricevute di vendita

È possibile configurare il testo della lingua e i campi personalizzati utilizzati nei formati delle ricevute di vendita (POS) puntare. Nella pagina Testo lingua aggiungi i record seguenti per le etichette dei campi personalizzati per i layout di ricevuta. Tieni presente che i valori ID lingua, ID testo e Testo visualizzati nella seguente tabella sono solo esempi. È possibile modificarli in base alle esigenze. Tuttavia, i valori ID testo utilizzati devono essere univoci e devono essere uguali o superiori a 900001.

ID lingua ID testo Testo
it-IT 900001 Codice QR (SA)

Nota

La società predefinita dell'utente che crea l'impostazione della ricevuta deve essere la stessa persona giuridica in cui viene creata l'impostazione del testo della lingua. In alternativa, i testi nella stessa lingua devono essere creati sia nella società predefinita dell'utente sia nella persona giuridica del negozio per cui è stata creata l'impostazione.

Nella pagina Campi personalizzati, aggiungi i record seguenti per i campi personalizzati per i layout di ricevuta. Tieni presente che i valori ID testo didascalia devono corrispondere ai valori ID testo specificati nella pagina Testo lingua.

Name Tipo ID testo didascalia
CODICEQR FATTURA_SA Ricevimento 900001

Configurare i formati di ricevuta

Per tutti i formati di ricevuta richiesti, modifica il valore del campo Comportamento stampa su Stampa sempre.

Nel progettista del formato della ricevuta, aggiungi il seguente campo personalizzato alla sezione Piè di pagina della ricevuta. Tieni presente che i nomi dei campi corrispondono ai testi in lingua definiti nella sezione precedente.

  • Codice QR (SA) – Questo campo stampa il codice QR sulla ricevuta.

Per ulteriori informazioni su come lavorare con i formati delle ricevute, vedere Impostare e progettare i formati delle ricevute.

Specificare le dimensioni del codice QR nei parametri di Commercio

Nella scheda Parametri di configurazione della pagina Parametri di commercio, aggiungi i seguenti parametri di configurazione:

  • QrCodeWidth - Larghezza dell'immagine del codice QR, in pixel. Specificare un valore appropriato per il parametro.
  • QrCodeHeight - Altezza dell'immagine del codice QR, in pixel. Specificare un valore appropriato per il parametro.

Nota

Per stampare i codici QR sulle ricevute è obbligatorio specificare i valori di questi parametri di configurazione. Il supporto per i valori predefiniti dei parametri potrebbe essere aggiunto in aggiornamenti futuri.

Abilitare le estensioni CRT

Avviso

Questa funzionalità di localizzazione non può essere utilizzata con il nuovo modello di estensione e confezionamento indipendente e con il kit di sviluppo software (SDK) per il commercio. È necessario utilizzare la versione precedente di Retail SDK su una macchina virtuale per sviluppatori (VM) in Microsoft Dynamics Lifecycle Services (LCS). Per informazioni sulle funzionalità di localizzazione per l'Arabia Saudita disponibili in Commerce SDK, vedere Generare e inviare fatture elettroniche semplificate per l'Arabia Saudita

Ambiente di sviluppo

Seguire Ecco i passaggi per impostare uno sviluppo ambiente in modo da poter testare ed estendere la funzionalità di localizzazione.

  1. Individua il file di configurazione dell'estensione per CRT:

    • Server al dettaglio: Il file è denominato commerceruntime.ext.config e può essere trovato nella cartella bin\ext nel percorso del sito del server al dettaglio Internet Information Services (IIS).
    • Locale CRT su Modern POS: il file è denominato CommerceRuntime.MPOSOffline.Ext.config e può essere trovato nella posizione del broker client locale CRT .

  2. Registrare la CRT modifica nel file di configurazione dell'estensione, come mostrato nel seguente esempio.

    <add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ReceiptsSaudiArabia" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting" />

Ambiente di produzione

Attenersi alla procedura seguente per creare pacchetti distribuibili contenenti componenti Commerce e per applicare quei pacchetti a un ambiente di produzione.

  1. Nei file di configurazione del pacchetto commerceruntime.ext.config e CommerceRuntime.MPOSOffline.Ext.config nella cartella RetailSdk\Assets , aggiungere le seguenti righe alla sezione composition .

    <add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ReceiptsSaudiArabia" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting" />

  2. Aprire il prompt dei comandi di MSBuild per Visual Studio l'utilità ed eseguire msbuild nella cartella Retail SDK per creare pacchetti distribuibili.

  3. Applica i pacchetti via LCS o manualmente. Per ulteriori informazioni, vedere Creare pacchetti distribuibili.

Quando si utilizza una stampante Object Linking and Embedding for Retail POS (OPOS), potrebbe essere necessario implementare personalizzazioni aggiuntive per supportare i requisiti specifici della stampante per l'immagine del codice QR. Ad esempio, potrebbe essere necessario convertire l'immagine del codice QR dal formato PNG al formato BMP. Questa sezione mostra un esempio di questo tipo di personalizzazione.

Nota

Questo esempio di personalizzazione è stato testato utilizzando la stampante EPSON TM-T88V OPOS. Potrebbe essere necessario modificarlo per supportare marche o modelli di stampanti diversi.

Seguire segui questi passaggi per creare una nuova estensione e aggiungerla al tuo ambiente.

  1. Installa l'SDK Retail. Per ulteriori informazioni, vedere Kit di sviluppo software per la vendita al dettaglio (SDK).

  2. Nel Retail SDK, utilizzare il seguente codice, in base alla versione di Commerce, per creare un progetto C# sotto Campioni di Runtime di Commerce.sln soluzione in RetailSdk\Estensioni di esempio\CommerceRuntime.

    <Project Sdk="Microsoft.NET.Sdk">
    <Import Project="..\..\..\BuildTools\Microsoft.Dynamics.RetailSdk.Build.props" />
    <Import Project="..\..\..\BuildTools\Common.props" />
    <Import Project="..\..\..\BuildTools\Microsoft.Dynamics.RetailSdk.Build.settings" />

    <PropertyGroup>
        <TargetFramework>netstandard2.0</TargetFramework>
        <AssemblyName>$(AssemblyNamePrefix).Commerce.Runtime.QrCodeExtension</AssemblyName>
        <RootNamespace>Contoso.Commerce.Runtime.QrCodeExtension</RootNamespace>
        <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
    </PropertyGroup>

    <Import Project="..\..\..\BuildTools\Microsoft.Dynamics.RetailSdk.Build.targets" />

    <ItemGroup>
        <PackageReference Include="Microsoft.Dynamics.Commerce.Runtime.Framework" Version="$(FrameworkRepoPackagesVersion)" />
        <PackageReference Include="Microsoft.Dynamics.Commerce.Runtime.Services.Messages" Version="$(ChannelRepoPackagesVersion)" />
        <PackageReference Include="System.Drawing.Common" Version="4.7.0" />
    </ItemGroup>

    <ItemGroup>
        <Reference Include="Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting">
            <HintPath>..\..\..\..\..\nuget packages\microsoft.dynamics.commerce.runtime.electronicreporting.9.35.21321.4\lib\netstandard2.0\Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting.dll</HintPath>
        </Reference>
    </ItemGroup>

    <ItemGroup>
        <Folder Include="Properties\" />
    </ItemGroup>
</Project>

    È inoltre necessario modificare il valore dell'elemento HintPath per fare riferimento alla libreria Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting.DLL nel percorso del sito IIS Retail Server.

  3. Per creare una classe di estensione, utilizza il seguente codice, in base alla tua versione di Commerce.

    /**
 * SAMPLE CODE NOTICE
 * 
 * THIS SAMPLE CODE IS MADE AVAILABLE AS IS. MICROSOFT MAKES NO WARRANTIES, WHETHER EXPRESS OR IMPLIED,
 * OF FITNESS FOR A PARTICULAR PURPOSE, OF ACCURACY OR COMPLETENESS OF RESPONSES, OF RESULTS, OR CONDITIONS OF MERCHANTABILITY.
 * THE ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS SAMPLE CODE REMAINS WITH THE USER.
 * NO TECHNICAL SUPPORT IS PROVIDED. YOU MAY NOT DISTRIBUTE THIS CODE UNLESS YOU HAVE A LICENSE AGREEMENT WITH MICROSOFT THAT ALLOWS YOU TO DO SO.
 */

using System.Drawing;
using System.Drawing.Imaging;
using System.IO;

namespace Contoso
{
    namespace Commerce.Runtime.QrCodeExtension
    {
        using System;
        using System.Collections.Generic;
        using System.Threading.Tasks;
        using Microsoft.Dynamics.Commerce.Runtime;
        using Microsoft.Dynamics.Commerce.Runtime.Messages;
        using Microsoft.Dynamics.Commerce.Runtime.Services.Messages;

        /// <summary>
        /// The extension for QR code printing.
        /// </summary>
        internal class QrCodeServiceExtension : IRequestHandlerAsync
        {
            /// <summary>
            /// Printer horizontal resolution for image.
            /// </summary>
            private const float PrinterXDpi = 60f;

            /// <summary>
            /// Printer vertical resolution for image.
            /// </summary>
            private const float PrinterYDpi = 90f;

            /// <summary>
            /// Printer pixel format for image.
            /// </summary>
            private const PixelFormat PrinterPixelFormat = PixelFormat.Format8bppIndexed;

            /// <summary>
            /// Gets the collection of supported request types by this service.
            /// </summary>
            public IEnumerable<Type> SupportedRequestTypes
            {
                get => new[] {typeof(EncodeQrCodeServiceRequest)};
            }

            /// <summary>
            /// Processes the request.
            /// </summary>
            /// <param name="request">The request.</param>
            /// <returns>The response.</returns>
            public async Task<Response> Execute(Request request)
            {
                ThrowIf.Null(request, nameof(request));

                switch (request)
                {
                    case EncodeQrCodeServiceRequest encodeQrCodeServiceRequest:
                    {
                        EncodeQrCodeServiceResponse nextResponse = await this.ExecuteNextAsync<EncodeQrCodeServiceResponse>(encodeQrCodeServiceRequest).ConfigureAwait(false);

                        if (nextResponse != null)
                        {
                            var qrCodeBmp = string.IsNullOrWhiteSpace(nextResponse.QRcode) ? nextResponse.QRcode : ConvertToGenericCompatibilityImage(nextResponse.QRcode);
                            return new EncodeQrCodeServiceResponse(qrCodeBmp);
                        }

                        return nextResponse;
                    }
                }

                return new NotHandledResponse();
            }

            /// <summary>
            /// Converts QR code image from any format to compatible with printer.
            /// </summary>
            /// <param name="base64data">Base64 image.</param>
            /// <returns>Image that Compatible with printer.</returns>
            private static string ConvertToGenericCompatibilityImage(string base64data)
            {
                string convertedQrCode = base64data;
                byte[] imageBytes = Convert.FromBase64String(convertedQrCode);
                using (MemoryStream msOriginal = new MemoryStream(imageBytes))
                using (MemoryStream msConverted = new MemoryStream())
                {
                    var bitmapOriginal = new Bitmap(msOriginal);
                    if (!IsFormatCompatible(bitmapOriginal) || !AreResolutionAndPixelFormatCompatible(bitmapOriginal))
                    {
                        var bitmapConverted = bitmapOriginal;

                        if (!AreResolutionAndPixelFormatCompatible(bitmapOriginal))
                        {
                            var rectangle = new Rectangle(0, 0, bitmapOriginal.Width, bitmapOriginal.Height);
                            bitmapConverted = bitmapOriginal.Clone(rectangle, PrinterPixelFormat);
                            bitmapConverted.SetResolution(PrinterXDpi, PrinterYDpi);
                        }

                        bitmapConverted.Save(msConverted, ImageFormat.Bmp);
                    }

                    convertedQrCode = Convert.ToBase64String(msConverted.ToArray());
                }

                return convertedQrCode;
            }

            /// <summary>
            /// Verifies if the resolution and pixel format of bitmap are compatible with printer requirements.
            /// </summary>
            /// <param name="source">Bitmap.</param>
            /// <returns>True if compatible; otherwise false.</returns>
            private static bool AreResolutionAndPixelFormatCompatible(Bitmap source)
            {
                return source.VerticalResolution == PrinterYDpi &&
                       source.HorizontalResolution == PrinterXDpi &&
                       source.PixelFormat == PrinterPixelFormat;
            }

            /// <summary>
            /// Verifies if the format of bitmap is compatible with printer requirements.
            /// </summary>
            /// <param name="source">Bitmap.</param>
            /// <returns>True if compatible; otherwise false.</returns>
            private static bool IsFormatCompatible(Bitmap source)
            {
                return source.RawFormat.Equals(ImageFormat.Bmp);
            }
        }
    }
}

  4. Nei file di configurazione commerceruntime.ext.config e CommerceRuntime.MPOSOffline.Ext.config nella cartella RetailSdk\Assets , aggiungere le seguenti righe alla sezione composition .

    <add source="assembly" value="Contoso.Commerce.Runtime.QrCodeExtension" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ReceiptsSaudiArabia" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting" />

  5. Nel file di configurazione della personalizzazione del pacchetto Customization.settings nella cartella BuildTools , aggiungere le seguenti righe per includere le CRT estensioni nei pacchetti distribuibili.

    <ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.QrCodeExtension.dll" />

  6. Avviare il prompt dei comandi di MSBuild per l'utilità Visual Studio ed eseguire msbuild nella cartella Retail SDK per creare pacchetti distribuibili.

  7. Applica i pacchetti via LCS o manualmente. Per ulteriori informazioni, vedere Creare pacchetti distribuibili.