Freigeben über

Im Zusammenhang mit Saudi-Arabien QR-Codes generieren und auf Belege drucken

  • Artikel

Notiz

Die in diesem Artikel beschriebene Funktionalität soll die Anforderungen der Phase 1 der Implementierung der elektronischen Rechnungsstellung im Königreich Saudi-Arabien unterstützen. Informationen zu den Funktionen, die die Anforderungen der Phase 2 der E-Rechnungsimplementierung im Königreich Saudi-Arabien unterstützen, finden Sie unter Vereinfachte elektronische Rechnungen für Saudi-Arabien erstellen und übermitteln.

Dieser Artikel bietet einen Überblick über die Funktion zum Drucken von QR-Codes, die für Saudi-Arabien verfügbar ist Microsoft Dynamics 365 Commerce.

In einem Geschäft, das mit einer juristischen Person verbunden ist, deren Hauptadresse sich in Saudi-Arabien befindet, können Benutzer bei einer Cash-and-Carry- oder Kundenbestellungs-Verkaufstransaktion einen QR-Code auf den Beleg drucken. Der QR-Code enthält folgende Informationen.

Sequenz Feld Datenquelle
1 Unternehmensname Der Name der juristischen Person
2 Umsatzsteuer-Identifikationsnummer des Unternehmens Die Steuernummer der juristischen Person
3 Datum und Uhrzeit der Transaktion Datum und Uhrzeit der Transaktion im Einzelhandel
4 Gesamtbetrag der Quittung (inkl. Mehrwertsteuer) Der Gesamtbetrag der Einzelhandelstransaktion
5 Gesamtbetrag der im Beleg enthaltenen Mehrwertsteuer Der Gesamtsteuerbetrag der Einzelhandelstransaktion

Notiz

Beim Erstellen von Kundenbestelltransaktionen wird der Gesamtbelegbetrag durch die Addition der Gesamtbeträge aller Transaktionszeilen berechnet, für die die Lieferart „Mitnahme“ verwendet wird.

Der QR-Code wird durch Anwenden der Base64-Transformation auf die im Tag-Length-Value (TLV)-Format codierten Transaktionsinformationen generiert. Die Zakat-, Steuer- und Zollbehörde (ZATCA) stellt Tools zur Verfügung, mit denen der QR-Code validiert werden kann. Weitere Informationen zu den Anforderungen von Elektronische Fakturierung und den QR-Code-Validierungsfunktionen finden Sie im E-Invoicing-Portal von ZATCA.

QR-Codes einrichten

Um QR-Codes zu generieren und sie auf Quittungen für Saudi-Arabien zu drucken, müssen Sie die folgenden Aufgaben erledigen.

  1. Konfigurieren Sie benutzerdefinierte Felder, sodass diese in Belegformaten für Verkaufsbelege verwendet werden können.
  2. Konfigurieren Sie Belegformate.
  3. Geben Sie die QR-Code-Abmessungen in den Commerce-Parametern an.
  4. Aktivieren Sie Commerce-Laufzeiterweiterungen (CRT).

Konfigurieren Sie benutzerdefinierte Felder, damit sie in Belegformate für Verkaufsbelege verwendet werden können

Sie können den Sprachtext und die benutzerdefinierten Felder konfigurieren, die in den Quittungsformaten zeigen of Sale (POS) verwendet werden. Fügen Sie auf der Seite Sprachentext die folgenden Datensätze für die Beschriftungen der benutzerdefinierten Felder für Bonlayouts hinzu. Beachten Sie, dass Sprachen-ID, Text-ID und Text-Werte, die in der Tabelle angezeigt werden, nur Beispiele sind. Sie können sie ändern, damit sie Ihre Anforderungen erfüllen. Allerdings müssen die von Ihnen verwendeten Text-ID Werte eindeutig sein und gleich oder höher als 900001 sein.

Sprachkennung Text-ID Text
de-DE 900001 QR-Code (SA)

Notiz

Das Standardunternehmen des Benutzers, der die Boneinrichtung erstellt, sollte die gleiche juristische Person sein, in dem die Sprachtexteinstellung erstellt wird. Alternativ sollten dieselben Sprachtexte im Standardunternehmen des Benutzers und in der juristischen Person des Shops verwendet werden, für den das Setup erstellt wird.

Fügen Sie auf der Seite Benutzerdefinierte Felder die folgenden Datensätze für die benutzerdefinierten Felder für Bonlayouts hinzu. Beachten Sie, dass die Werte für Untertitelrext-ID den Werten Textkennung entsprechen müssen, die Sie auf der Seite Sprachentext angegeben haben.

Name Typ Textkennung Titel
INVOICEQRCODE_SA Zugang 900001

Bonformate konfigurieren

Ändern Sie für jedes erforderliche Belegformat den Wert des Felds Druckverhalten auf Immer drucken.

Fügen Sie im Quittungsformat-Designer dem Abschnitt Fußzeile der Quittung das folgende benutzerdefinierte Feld hinzu. Beachten Sie, dass die Feldnamen den Sprachtexten entsprechen, die Sie im vorherigen Abschnitt definiert haben.

  • QR-Code (SA) – Dieses Feld druckt den QR-Code auf den Beleg.

Weitere Informationen zum Arbeiten mit Belegformaten finden Sie unter Belegformate einrichten und gestalten.

QR-Code-Dimensionen in Commerce-Parametern festlegen

Fügen Sie auf der Seite „Commerce-Parameter“ auf der Registerkarte Konfigurationsparameter die folgenden Konfigurationsparameter hinzu:

  • QrCodeWidth – Die Breite des QR-Codebildes in Pixeln. Geben Sie einen geeigneten Wert für den Parameter an.
  • QrCodeHeight – Die Höhe des QR-Codebildes in Pixeln. Geben Sie einen geeigneten Wert für den Parameter an.

Notiz

Um QR-Codes in Quittungen zu drucken, müssen die Werte dieser Konfigurationsparameter angegeben werden. Die Unterstützung für Standardwerte der Parameter wird möglicherweise in zukünftigen Updates hinzugefügt.

Aktivieren der CRT Erweiterungen

Achtung

Diese Lokalisierungsfunktion kann nicht mit dem neuen unabhängigen Verpackungs- und Erweiterungsmodell und dem Commerce Software Development Kit (SDK) verwendet werden. Sie müssen die vorherige Version des Retail SDK auf einer virtuellen Maschine (VM) für Entwickler in Microsoft Dynamics Lifecycle Services (LCS) verwenden. Informationen zu den Lokalisierungsfunktionen für Saudi-Arabien, die im Commerce SDK verfügbar sind, finden Sie unter Erstellen und Senden vereinfachter elektronischer Rechnungen für Saudi-Arabien.

Entwicklungsumgebung

Gehen Sie folgendermaßen vor, um eine Entwicklungsumgebung einzurichten, damit Sie die Lokalisierungsfunktionalität testen und erweitern können.

  1. Suchen Sie die Erweiterungskonfigurationsdatei für CRT:

    • Retail Server: Die Datei trägt den Namen commerceruntime.ext.config und befindet sich im Ordner bin\ext unter dem Site-Speicherort Internetinformationsdienste (IIS) Retail Server.
    • Lokal CRT auf Modern POS: Die Datei trägt den Namen CommerceRuntime.MPOSOffline.Ext.config und ist am lokalen CRT Client-Broker-Speicherort zu finden.

  2. Registrieren Sie die CRT Änderung in der Erweiterungskonfigurationsdatei, wie im folgenden Beispiel gezeigt.

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

Produktionsumgebung

Folgen Sie diesen Schritten, um bereitstellbare Pakete zu erstellen, die Commerce-Komponenten enthalten, und um diese Pakete in einer Produktionsumgebung anzuwenden.

  1. Fügen Sie in den Paketkonfigurationsdateien commerceruntime.ext.config und CommerceRuntime.MPOSOffline.Ext.config im Ordner RetailSdk\Assets dem Abschnitt Composition die folgenden Zeilen hinzu.

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

  2. Öffnen Sie die MSBuild-Eingabeaufforderung für das Dienstprogramm Visual Studio und führen Sie msbuild im Ordner „Retail SDK“ aus, um bereitstellbare Pakete zu erstellen.

  3. Übernehmen Sie die Pakete über Lifecycle Services (LCS) oder manuell. Weitere Informationen finden Sie unter Bereitstellbare Pakete erstellen.

Wenn Sie einen OPOS-Drucker (Object Linking and Embedding for Retail POS) verwenden, müssen Sie möglicherweise zusätzliche Anpassungen implementieren, um druckerspezifische Anforderungen für das QR-Codebild zu unterstützen. Beispielsweise müssen Sie möglicherweise das QR-Code-Bild vom PNG-Format in das Format BMP konvertieren. Dieser Abschnitt zeigt ein Beispiel für diese Art der Anpassung.

Notiz

Dieses Anpassungsbeispiel wurde mit dem EPSON TM-T88V OPOS-Drucker getestet. Es müssen möglicherweise Änderungen vorgenommen werden, um verschiedene Druckermarken oder -modelle zu unterstützen.

Folgen diese Schritte, um eine neue Erweiterung zu erstellen und sie zu Ihrem Umgebung hinzuzufügen.

  1. Installieren Sie das Retail SDK. Weitere Informationen finden Sie unter Software Development Kit (SDK) für den Einzelhandel.

  2. Verwenden Sie im Retail SDK basierend auf Ihrer Commerce-Version den folgenden Code, um ein C#-Projekt unter der Lösung CommerceRuntimeSamples.sln in RetailSdk\SampleExtensions\CommerceRuntime zu erstellen.

    <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>

    Sie müssen außerdem den Wert des Elements HintPath ändern, um auf die Bibliothek Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting.DLL unter dem Sitespeicherort des IIS Retail Servers zu verweisen.

  3. Verwenden Sie basierend auf Ihrer Commerce-Version den folgenden Code, um eine Erweiterungsklasse zu erstellen.

    /**
 * 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. Fügen Sie in den Konfigurationsdateien commerceruntime.ext.config und CommerceRuntime.MPOSOffline.Ext.config im Ordner RetailSdk\Assets dem Abschnitt Composition die folgenden Zeilen hinzu.

    <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. Fügen Sie in der Paketanpassungskonfigurationsdatei Customization.settings im Ordner BuildTools die folgenden Zeilen hinzu, um die CRT Erweiterungen in die bereitstellbaren Pakete aufzunehmen.

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

  6. Starten Sie die MSBuild-Eingabeaufforderung für Visual Studio-Hilfsprogramm und führen Sie msbuild unter dem Ordner Retail SDK aus, um bereitstellbare Pakete zu erstellen.

  7. Übernehmen Sie die Pakete über Lifecycle Services (LCS) oder manuell. Weitere Informationen finden Sie unter Bereitstellbare Pakete erstellen.