Dela via

Generera QR-koder och skriv ut dem på kvitton för Saudiarabien

  • Artikel

Notering

Funktionen som beskrivs i den här artikeln är avsedd att stödja fas 1-kraven för implementeringen av e-fakturering i Saudiarabien. Information om de funktioner som är avsedda att stödja fas 2-kraven för implementeringen av e-fakturering i Saudiarabien finns i Generera och skicka förenklade elektroniska fakturor för Saudiarabien.

Den här artikeln ger en översikt över funktionerna för att skriva ut QR-koder som är tillgängliga för Saudiarabien i Microsoft Dynamics 365 Commerce.

I en butik som är kopplad till en juridisk person som har sin primära adress i Saudiarabien kan användare skriva ut en QR-kod på kvittot för en hämtköps- eller kundorderförsäljningstransaktion. QR-koden innehåller följande information.

Sekvens Fält Datakälla
1 Företagets namn Namnet på den juridiska personen
2 Företagets momsregistreringsnummer Den juridiska personens momsregistreringsnummer
3 Datum och tid för transaktionen Datum och tid för butikstransaktionen
4 Totalt inleveransbelopp (inklusive mervärdesskatt [moms]) Det totala beloppet för butikstransaktionen
5 Totalt momsbelopp som ingår i kvittot Det totala momsbeloppet för butikstransaktionen

Notering

När kundordertransaktioner skapas beräknas det totala inleveransbeloppet genom att lägga till de totala beloppen för alla transaktionsrader som använder leveransläget Carry-out.

QR-koden genereras genom att tillämpa base64-transformeringen på transaktionsinformationen som kodats i formatet Tag-Length-Value (TLV). Zakat, skatte- och tullmyndigheten (ZATCA) tillhandahåller verktyg som kan användas för att validera QR-koden. Mer information om kraven på elektronisk fakturering och funktionerna för validering av QR-koder finns i ZATCA:s portal för e-fakturering.

Ställ in QR-koder

För att generera QR-koder och skriva ut dem på kvitton för Saudiarabien måste du utföra följande uppgifter.

  1. Konfigurera anpassade fält så att de kan användas i kvittoformat för försäljningskvitton.
  2. Konfigurera kvittoformat.
  3. Ange QR-koddimensioner i Commerce-parametrar.
  4. Aktivera Commerce Runtime-tillägg (CRT).

Konfigurera anpassade fält så att de kan användas i kvittoformat för försäljningskvitton

Du kan konfigurera språk, text och anpassade fält som används i kvittoformat för kassa. På sidan Språktext kan du lägga till följande poster för etiketterna för de anpassade fälten för kvittolayout. Observera att värdena Språk-ID, Text-ID och Text som visas i tabellen bara är exempel. Du kan ändra dem för att uppfylla dina krav. De text-ID-värden som du använder måste dock vara unika och de måste vara lika med eller högre än 900001.

Språk-ID Text-ID Text
sv 900001 QR-kod (SA)

Notering

Standardföretaget för den användare som skapar kvittoinställningen bör vara samma juridiska person där språktextinställningarna skapas. Du kan också skapa samma språktexter i både användarens standardföretag och den juridiska personen i butiken som installationen har skapats för.

På sidan Anpassade fält kan du lägga till följande poster för anpassade fält för kvittolayouter. Observera att värdena Text-ID för rubrik måste motsvara de värden för Text-ID som du angav på sidan språktext.

Namn Typ Text-ID för rubrik
INVOICEQRCODE_SA Inleverans 900001

Konfigurera kvittoformat

För varje kvittoformat som krävs, ändra värdet för fältet Utskriftssätt till Skriv alltid ut.

I kvittoformatdesignern lägger du till följande anpassade fält i avsnittet Sidfot på kvittot. Observera att fältnamn motsvarar de språktexter som du definierade i föregående avsnitt.

  • QR-kod (SA) – Detta fält skriver ut QR-koden på kvittot.

Mer information om hur du arbetar med kvittoformat finns i Ställa in och utforma kvittoformat.

Ange QR-koddimensioner i Commerce-parametrar

På fliken Konfigurationsparametrar på sidan Commerce-parametrar lägger du till följande konfigurationsparametrar:

  • QrCodeWidth – Bredden på QR-kodbilden i pixlar. Ange ett lämpligt värde för parametern.
  • QrCodeHeight – Höjden på QR-kodbilden i pixlar. Ange ett lämpligt värde för parametern.

Notering

Det är obligatoriskt att ange värdena för dessa konfigurationsparametrar för att skriva ut QR-koder i kvitton. Stöd för standardvärden för parametrarna kan läggas till i framtida uppdateringar.

Aktivera CRT-tillägg

Varning

Den här lokaliseringsfunktionen kan inte användas med den nya oberoende paketerings- och tilläggsmodellen och SDK (Software Development Kit) för Commerce. Du måste använda föregående version av Retail SDK på en virtuell utvecklare (VM) i Microsoft Dynamics Lifecycle Services (LCS). Mer information om de lokaliseringsfunktioner för Saudiarabien som är tillgängliga i Commerce SDK finns i Generera och skicka förenklade elektroniska fakturor för Saudiarabien

Utvecklingsmiljö

Följ de här stegen för att konfigurera en utvecklingsmiljö så att du kan testa och utöka lokaliseringsfunktionerna.

  1. Hitta konfigurationsfilen för tillägget för CRT:

    • Retail Server: Filen heter commerceruntime.ext.config och finns i mappen bin\ext under webbplatsplatsen Internet Information Services (IIS) Retail Server.
    • Lokal CRT på Modern POS: Filen heter CommerceRuntime.MPOSOffline.Ext.config och finns under den lokala CRT klientkoordinatorns plats.

  2. Registrera CRT ändringen i tilläggskonfigurationsfilen, som du ser i följande exempel.

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

Produktionsmiljö

Följ dessa steg för att skapa distribuerbara paket som innehåller Commerce-komponenter och för att tillämpa dessa paket i en produktionsmiljö.

  1. I paketkonfigurationsfilerna commerceruntime.ext.config och CommerceRuntime.MPOSOffline.Ext.config under mappen RetailSdk\Assets lägger du till följande rader i kompositionsavsnittet .

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

  2. Öppna MSBuild-kommandotolken för Visual Studio verktyget och kör msbuild under mappen Retail SDK för att skapa distribuerbara paket.

  3. Tillämpa paketen via LCS eller manuellt. Mer information finns i skapa distribuerbara paket.

När du använder en OPOS-skrivare (Object Linking and Embedding for Retail POS) kan du behöva implementera ytterligare anpassningar för att stödja skrivarspecifika krav för QR-kodbilden. Du kan till exempel behöva konvertera QR-kodbilden från PNG-formatet till BMP-formatet. I det här avsnittet visas ett exempel på den här typen av anpassning.

Notering

Det här anpassningsexemplet testades med hjälp av EPSON TM-T88V OPOS-skrivaren. Den kan behöva modifieras för att stödja olika skrivarmärken eller modeller.

Följ dessa steg för att skapa ett nytt tillägg och lägga till det i din miljö.

  1. Installera SDK för Retail. Mer information finns i Software Development Kit (SDK) för Retail.

  2. I SDK för Retail använder du följande kod, baserat på din Commerce-version, för att skapa ett C#-projekt under CommerceRuntimeSamples.sln lösningen i RetailSdk\SampleExtensions\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>

    Du måste också ändra värdet för HintPath-elementet för att referera till Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting.DLL -biblioteket under webbplatsplatsen för IIS Retail Server.

  3. Använd följande kod, baserat på din Commerce-version, för att skapa en tilläggsklass.

    /**
 * 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. I konfigurationsfilerna commerceruntime.ext.config och CommerceRuntime.MPOSOffline.Ext.config under mappen RetailSdk\Assets lägger du till följande rader i kompositionsavsnittet .

    <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. I konfigurationsfilen för anpassning av Customization.settings-paketet under mappen BuildTools lägger du till följande rader för att inkludera tilläggen i de distribuerbara paketen CRT .

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

  6. Starta MSBuild-Kommandotolken för Visual Studio-verktyget och kör MSBuild under mappen Retail SDK för att skapa distribuerbara paket.

  7. Tillämpa paketen via LCS eller manuellt. Mer information finns i skapa distribuerbara paket.