Del via

Generere QR-koder og udskrive dem på kvitteringer til Saudi-Arabien

  • Artikel

Bemærk!

De funktioner, der beskrives i denne artikel, er beregnet til at understøtte fase 1-kravene i implementeringen af e-fakturering i Saudi-Arabien. Du kan finde oplysninger om de funktioner, der er beregnet til at understøtte fase 2-kravene i implementeringen af e-fakturering i Kongeriget Saudi-Arabien, under Generere og indsende forenklede elektroniske fakturaer for Saudi-Arabien.

Denne artikel indeholder en oversigt over den funktionalitet til udskrivning af QR-koder, der er tilgængelig for Saudi-Arabien i Microsoft Dynamics 365 Commerce.

I en butik, der er knyttet til en juridisk enhed, der har sin primære adresse i Saudi-Arabien, kan brugerne udskrive en QR-kode på kvitteringen for en cash and carry-transaktion eller en kundeordresalgstransaktion. QR-koden indeholder følgende oplysninger.

Rækkefølge Felt Datakilde
1 Firmanavn Navnet på den juridiske enhed
2 CVR-nummer Den juridiske enheds momsregistreringsnummer
3 Dato og klokkeslæt for transaktionen Dato og klokkeslæt for detailbutikstransaktionen
4 Samlet tilgangsbeløb (inkl. moms) Det samlede beløb for detailbutikstransaktionen
5 Samlet momsbeløb inkluderet i kvitteringen Det samlede momsbeløb for detailbutikstransaktionen

Bemærk!

Når der oprettes kundeordretransaktioner, beregnes det samlede tilgangsbeløb ved at tilføje de samlede beløb for alle posteringslinjer, der bruger leveringsmåden overførsel.

QR-koden genereres ved at anvende base64-transformationen på transaktionsoplysningerne, der er kodet i TLV-formatet (Tag-Length-Value). Zakat, skatte- og toldmyndighed (ZATCA) leverer værktøjer, der kan bruges til at validere QR-koden. Du kan finde flere oplysninger om de elektronisk fakturering krav og valideringsfunktioner for QR-kode i portalen E-fakturering fra ZATCA.

Konfigurere QR-koder

Hvis du vil generere QR-koder og udskrive dem på kvitteringer til Saudi-Arabien, skal du udføre følgende opgaver.

  1. Konfigurer brugerdefinerede felter, så de kan bruges i tilgangsformater til salgstilgange.
  2. Konfigurere kvitteringsformater.
  3. Angiv QR-kodedimensioner i Commerce-parametre.
  4. Aktivér Commerce runtime (CRT)-udvidelser.

Konfigurere brugerdefinerede felter, så de kan bruges i kvitteringsformater for salgskvittering

Du kan konfigurere sprog, tekst og brugerdefinerede felter, der bruges i POS-kvitteringsformaterne. På siden Sprogtekst kan du tilføje følgende poster for etiketterne i de brugerdefinerede felter til kvitteringslayout. Bemærk, at værdierne for Sprog-id, Tekst-id og Tekst, der vises i tabellen, kun er eksempler. Du kan ændre dem, så de opfylder dine behov. De Text ID-værdier , du bruger, skal dog være entydige, og de skal være lig med eller højere end 900001.

Sprog-id Tekst-id Tekst
da 900001 QR-kode (SA)

Bemærk!

Standardfirmaet for den bruger, der opretter kvitteringsopsætningen, skal være den samme juridiske enhed, hvor opsætningen af sprogtekster oprettes. Du kan også oprette de samme sprogtekster i både brugerens standardfirma og den juridiske enhed for den butik, som opsætningen oprettes for.

På siden Brugerdefinerede felter kan du tilføje følgende poster for de brugerdefinerede felter til kvitteringslayout. Bemærk, at værdier for Tekst-id for billedtekst skal svare til de værdier for Tekst-id, som du har angivet på siden Sprogtekst.

Name Skriv Tekst-id for billedtekst
INVOICEQRCODE_SA Kvittering 900001

Konfigurere kvitteringsformater

For hvert påkrævet kvitteringsformat skal du ændre værdien i feltet Udskriftsfunktion til Udskriv altid.

I designeren til kvitteringsformat skal du føje følgende brugerdefinerede felt til sektionen Sidefod på kvitteringen. Bemærk, at feltnavnene svarer til de sprogtekster, du har defineret i forrige afsnit.

  • QR-kode (SA) – Dette felt udskriver QR-koden på kvitteringen.

Du kan finde flere oplysninger om, hvordan du arbejder med kvitteringsformater, i Konfigurere og designe kvitteringsformater.

Angive QR-kodedimensioner i Commerce-parametre

På fanen Konfigurationsparametre på siden Commerce-parametre skal du tilføje følgende konfigurationsparametre:

  • QrCodeWidth - Bredden af QR-kodebilledet i pixels. Angiv en passende værdi for parameteren.
  • QrCodeHeight - Højden på QR-kodebilledet i pixels. Angiv en passende værdi for parameteren.

Bemærk!

Det er obligatorisk at angive værdierne for disse konfigurationsparametre for at udskrive QR-koder i kvitteringer. Understøttelse af standardværdier for parametrene kan tilføjes i fremtidige opdateringer.

Aktivere CRT-udvidelser

Alarm

Denne lokaliseringsfunktionalitet kan ikke bruges sammen med den nye uafhængige emballage- og udvidelsesmodel og Commerce SDK (Software Development Kit). Du skal bruge den tidligere version af Retail SDK på en virtuel maskine til udviklere (VM) i Microsoft Dynamics Lifecycle Services (LCS). Du kan finde oplysninger om lokaliseringsfunktionerne for Saudi-Arabien, der er tilgængelige i Commerce SDK, under Generere og sende forenklede elektroniske fakturaer for Saudi-Arabien

Udviklingsmiljø

Følg disse trin for at konfigurere et udviklingsmiljø, så du kan teste og udvide lokaliseringsfunktionen.

  1. Find konfigurationsfilen til CRT-udvidelse:

    • Retail Server: Filen hedder commerceruntime.ext.config, og den kan findes i mappen bin\ext under Internet Information Services (IIS) Retail Server-webstedets placering.
    • Lokal CRT på Modern POS: Filen hedder CommerceRuntime.MPOSOffline.Ext.config, og den kan findes under den lokale CRT klientmæglerplacering.

  2. CRT Registrer ændringen i udvidelseskonfigurationsfilen, som vist i følgende eksempel.

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

Produktionsmiljø

Følg disse trin for at oprette installerbare pakker, der indeholder Commerce-komponenter, og for at anvende disse pakker i et produktionsmiljø.

  1. Føj følgende linjer til kompositionsafsnittet i pakkekonfigurationsfilerne commerceruntime.ext.config og CommerceRuntime.MPOSOffline.Ext.config i mappen RetailSdk\Assets .

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

  2. Åbn MSBuild-kommandoprompten for Visual Studio hjælpeprogram, og kør msbuild under mappen Retail SDK for at oprette installerbare pakker.

  3. Anvend pakkerne via LCS eller manuelt. Du kan finde flere oplysninger under Oprette installerbare pakker.

Når du bruger en OPOS-printer (Object Linking and Embedding for Retail POS), skal du muligvis implementere yderligere tilpasninger for at understøtte printerspecifikke krav til QR-kodebilledet. Det kan f.eks. være nødvendigt at konvertere QR-kodebilledet fra PNG-formatet til BMP-formatet. Dette afsnit viser et eksempel på denne type tilpasning.

Bemærk!

Dette tilpasningseksempel blev testet ved hjælp af EPSON TM-T88V OPOS-printeren. Det skal muligvis ændres for at understøtte forskellige printermærker eller -modeller.

Følg disse trin for at oprette en ny udvidelse og føje den til dit miljø.

  1. Installer Retail SDK. Du kan finde flere oplysninger i Retail SDK (Software Development Kit).

  2. Brug følgende kode, baseret på din Commerce-version, i Retail SDK til at oprette et C#-projekt under løsningen CommerceRuntimeSamples.sln 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 skal også ændre værdien af elementet HintPath , så det refererer til Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting.DLL bibliotek under IIS Retail Server-webstedets placering.

  3. Brug følgende kode, baseret på din Commerce-version, til at oprette en udvidelsesklasse.

    /**
 * 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 konfigurationsfilerne commerceruntime.ext.config og CommerceRuntime.MPOSOffline.Ext.config under mappen RetailSdk\Assets skal du føje følgende linjer til kompositionsafsnittet .

    <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 Customization.settings-pakketilpasning under mappen BuildTools skal du tilføje følgende linjer for at medtage udvidelserne CRT i de installerbare pakker.

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

  6. Start MSBuild-kommandoprompten for Visual Studio-hjælpeværktøjet, og kør msbuild under Retail SDK-mappen for at oprette installationspakkerne.

  7. Anvend pakkerne via LCS eller manuelt. Du kan finde flere oplysninger under Oprette installerbare pakker.