Order Management

Zuletzt bearbeitet am: 05.03.2021

OrderManagement Übersicht

Einführung

Die Versandkosten dürfen für Klarna Bestellungen nicht verändert werden. Dies wird entsprechend im Backend verhindert.

Das OrderManagement erlaubt Ihnen diverse Aktionen mit der Bestellung durchzuführen. Es enthält außerdem eine Übersicht der Bestellung.

Klarna Tab

Der Klarna Tab enthält die Oberfläche in der Sie diverse Aktionen manuell tätigen können sowie eine Übersicht der Bestellung.

Öffnen Sie den Klarna Tab für eine bestimmte Bestellung indem Sie zu Kunden -> Bestellungen navigieren.

Wählen Sie nun die Bestellung aus, welche Sie sich gerne anschauen oder bearbeiten möchten.

 

Der Reiter Klarna. wird nur für Bestellungen angezeigt die mit einer Klarna Zahlungsart bezahlt wurden.

Klicken Sie nun auf den Reiter `Klarna.`.

    Hier sehen Sie diverse Informationen der Bestellung:

Name Beschreibung
Gesamtbetrag Der Gesamtbetrag der Bestellung.
Erfasster Betrag Der Betrag, welcher bereits erfasst (abgebucht) wurde.
Erstatteter Betrag Der Betrag, welcher erstattet wurde.
Verbleibender Betrag Der Betrag, welcher noch erfasst werden kann (noch nicht abgebuchter Betrag).
Klarna Referenz Eine Klarna interne ID zur Identifizierung der Bestellung.
Klarna Status Der Bestellstatus, der bei Klarna hinterlegt ist.
Betrugs-Risiko Der Klarna Risiko Check Status.
Läuft ab am An dem Datum läuft die Autorisierung ab. Ab dem Zeitpunkt kann der verbleibende Betrag nicht mehr erfasst werden.

Betrag erfassen

Sie können einen Betrag erfassen indem, Sie auf den Betrag erfassen Button klicken. Es wird Ihnen nun ein neues Fenster angezeigt, indem Sie den Betrag, die Positionen und einen Kommentar festlegen können.

Die Auswahl der Positionen ist optional, Sie können auch einfach einen Betrag manuell eingeben ohne eine Position auszuwählen. In dem Fall erhält Klarna aber nicht die Information welche Positionen bereits erfasst wurden und welche nicht.

Der Kommentar ist auch optional und dient Ihnen zur Verdeutlichung wieso ein Betrag erfasst wurde. Zum Beispiel: "Position XY wurde nicht erfasst, weil diese nicht mehr auf Lager war."

Sobald Sie die gewünschten Positionen und den gewünschten Betrag ausgewählt haben können Sie den Betrag erfassen, indem Sie auf Betrag erfassen klicken.

Sie werden nun abgefragt, ob Sie dies wirklich tun möchten.

Bestätigen Sie die Aktion, indem Sie auf den Vorgehen Button klicken. Oben rechts sehen Sie dann eine Bestätigung.

Betrag rückerstatten

Sie können einen Betrag rückerstatten, indem Sie auf den Betrag rückerstatten Button klicken. Es wird Ihnen nun ein neues Fenster angezeigt, indem Sie den Betrag, die Positionen und einen Kommentar festlegen können.

Die Auswahl der Positionen ist optional, Sie können auch einfach einen Betrag manuell eingeben ohne eine Position auszuwählen. In dem Fall erhält Klarna aber nicht die Information welche Positionen erstattet wurden und welche nicht.

Der Kommentar ist auch optional und dient Ihnen zur Verdeutlichung wieso ein Betrag erstattet wurde. Zum Beispiel: "Position XY wurde erstattet, weil diese nicht mehr auf Lager war."

Sobald Sie die gewünschten Positionen und den gewünschten Betrag ausgewählt haben können Sie den Betrag erstatten, indem Sie auf Betrag rückerstatten klicken.

Sie werden nun abgefragt, ob Sie dies wirklich tun möchten.

Bestätigen Sie die Aktion, indem Sie auf den Vorgehen Button klicken. Oben rechts sehen Sie dann eine Bestätigung.

Autorisierung verlängern

Sie können die Autorisierung einer Zahlung verlängern, indem Sie auf den Authorisierung verlängern Link klicken.

Sie werden nun abgefragt, ob Sie dies wirklich tun möchten.

Bestätigen Sie die Aktion, indem Sie auf den Vorgehen Button klicken. Oben rechts sehen Sie dann eine Bestätigung.

Verbleibenden Betrag Freigeben

Sie können den verbleibenden Betrag freigeben (Autorisierung aufheben), indem Sie auf den Freigeben Link klicken.

Sie werden nun abgefragt, ob Sie dies wirklich tun möchten.

Bestätigen Sie die Aktion, indem Sie auf den Freigeben Button klicken. Oben rechts sehen Sie dann eine Bestätigung.

Rechnung erneut senden

Sie können eine Rechnung je erfassten Betrag erneut senden. Um eine Übersicht aller erfassten Beträge zu erhalten klicken Sie auf den Details Link.

Sie sehen nun eine Übersicht aller erfassten Beträge und je erfassten Betrag einen Button Rechnung erneut senden. Wenn Sie für einen erfassten Betrag die Rechnung erneut senden möchten klicken Sie den Rechnung erneut senden Button unter dem erfassten Betrag.

Sie werden nun abgefragt, ob Sie dies wirklich tun möchten.

Bestätigen Sie die Aktion, indem Sie auf den Proceed Button klicken. Oben rechts sehen Sie dann eine Bestätigung.

Bestellhistorie

Die Bestellhistorie listet Aktionen auf, welche für die Bestellung durchgeführt wurden.

Spalte Beschreibung
# Die Spalte sagt aus, ob die Aktion erfolgreich war oder nicht. Ein grünes Häkchen sagt aus, dass die Aktion erfolgreich war. Ein rotes X sagt aus, dass die Aktion fehlgeschlagen ist.
Zeitpunkt Der Zeitpunkt an dem die Aktion durchgeführt wurde.
Meldung Die Aktion, welche durchgeführt wurde.
Details Ein Link welcher ein Dialog mit mehr Informationen öffnet.

Folgende Meldungen können auftreten:

Meldung Beschreibung/Informationen
Es wurde ein Betrag erfasst. Welcher Betrag erfasst wurde sieht man im "Details" Dialog.
Es wurde ein Betrag erstattet. Welcher Betrag erstattet wurde sieht man im "Details" Dialog.
Bestelldetails wurden geupdated. Die Bestellung wurde aktualisiert. Zum Beispiel wurde eine Position entfernt.
Der Autorisierungszeitraum wurde verlängert. Wird ausgeführt, wenn man den "Autorisierung verlängern" Link innerhalb des Klarna Tab klickt.
Der verbleibende Betrag wurde freigegeben. Der restliche (noch nicht erfasste Betrag) wurde freigegeben und kann somit nicht mehr erfasst werden.
Bestellung wurde abgebrochen. Die Bestellung wurde bei Klarna storniert und kann nicht mehr erfasst werden.

Details popup:

Bestellung stornieren

Eine Bestellung kann nur storniert werden wenn diese noch nicht (Teil-)erfasst wurde.

Die Stornierung einer Bestellung bei Klarna kann nicht rückgängig gemacht werden.

Um eine Bestellung zu stornieren klicken Sie den `Bestellung stornieren` Button.

Sie werden nun abgefragt, ob Sie dies wirklich tun möchten.

Bestätigen Sie die Aktion, indem Sie auf den Vorgehen Button klicken. Oben rechts sehen Sie dann eine Bestätigung.

Sobald eine Bestellung storniert ist, können keine weiteren Aktion mit dieser Bestellung durchgeführt werden.

Automatische Änderungen

Einführung automatische Änderungen

Bestimmte Aktionen in Shopware können Aktionen in Klarna auslösen. Diese werden hier alle aufgelistet und beschrieben.

Zahlungsstatus

Der Zahlungsstatus wird bei bestimmten Aktionen automatisch von Klarna gesetzt.

Aktion Zahlungsstatus
Teil Capture Teilweise bezahlt
Teil Refund Wiedergutschrift
Volles Capture Komplett bezahlt
Volles Refund Wiedergutschrift

Adressänderungen

Bei Adressänderungen im Backend werden die neuen Daten erst an Klarna übertragen. Wenn Klarna die neue Adresse akzeptiert wird diese in Shopware aktualisiert ansonsten werden die Änderungen nicht gespeichert.

So wird sichergestellt, dass die neue Adresse einmal den Klarna Risikocheck durchläuft.

Bestelländerungen

Bei Bestelländerungen im Backend werden die neuen Daten erst an Klarna übertragen. Wenn Klarna die neue Bestellung akzeptiert wird diese in Shopware aktualisiert ansonsten werden die Änderungen nicht gespeichert.

Änderungen, die den Autorisierten Betrag erhöhen werden generell abgelehnt.

Tracking Code

Der Tracking Code wird bei Captures automatisch mit an Klarna übermittelt.

Beim Hinzufügen oder Änderung eines Tracking Codes wird dieser an Klarna übertragen.

Zahlungsart ändern

Die Zahlungsart darf nicht von einer Klarna Zahlungsart zu einer anderen Klarna Zahlungsart verändert werden. Also z.B. das Ändern von Pay Now -> Pay Later darf nicht vorkommen und wird somit automatisch, mit entsprechender Fehlermeldung, verhindert.

Das Ändern der Zahlungsart von einer Klarna Zahlungsart zu einer anderen Zahlungsart darf nur ausgeführt werden wenn noch kein Betrag erfasst wurde. In dem Fall wird die Bestellung bei Klarna komplett abgebrochen.

Bestellung löschen

Eine Bestellung darf nur gelöscht werden wenn noch kein Betrag erfasst wurde. In dem Fall wird die Bestellung bei Klarna auch komplett abgebrochen.

Plugin erweitern

API Verwendung

Einführung API

Um die API leicht anzusteuern haben wir Facaden bereitgestellt, welche das Handling vereinfachen.

Die verschiedenen API Endpunkte benötigen die Klarna Order Id. Diese wird als Transaktions Id einer Bestellung in Shopware gespeichert.

Wenn Sie einen "schlauen" Editor verwenden (wie z.B. PhpStorm) werden Ihnen die Methoden alle automatisch vorgeschlagen und Sie können auch leichter Suchen.

### Bestellung abrufen

Um eine Bestellung abzurufen, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die get Methode aufrufen, welche eine Bestellung von Klarna abruft.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->orderFacade->get('klarna-order-id');
    }
}

Betrag erfassen über die API

Das Positions JSON muss so formatiert werden, dass es in ein array von BestitKlarnaOrderManagement\Components\Api\Model\LineItem deserialisiert werden kann.

Um einen Betrag zu erfassen, benötigen Sie die `BestitKlarnaOrderManagement\Components\Facade\Capture` Facade. Über diese können Sie die `create` Methode aufrufen, welche einen Betrag erfasst.

Sie können der Methode auch die Positionen (als JSON), einen Kommentar und Versandinformationen mitgeben.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Capture as CaptureFacade;

class Example
{
    /** @var CaptureFacade */
    protected $captureFacade;

    public function __construct(CaptureFacade $captureFacade)
    {
        $this->captureFacade = $captureFacade;
    }

    public function example()
    {
        $betragInCents = 500;
        
        $klarnaResponse = $this->captureFacade->create('klarna-order-id', $betragInCents);
    }
}

Betrag rückerstatten über die API

Um einen Betrag zu erstatten, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Refund Facade. Über diese können Sie die create Methode aufrufen, welche einen Betrag erstattet.

Sie können der Methode auch die Positionen (als JSON) und einen Kommentar mitgeben.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Refund as RefundFacade;

class Example
{
    /** @var RefundFacade */
    protected $refundFacade;

    public function __construct(RefundFacade $refundFacade)
    {
        $this->refundFacade = $refundFacade;
    }

    public function example()
    {
        $betragInCents = 500;

        $klarnaResponse = $this->refundFacade->create('klarna-order-id', $betragInCents);
    }
}

Bestellung aktualisieren

Um eine Bestellung zu aktualisieren, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die updateOrder Methode aufrufen, welche eine Bestellung aktualisiert.

Diese Methode benötigt die Klarna Order Id, den neuen Gesamtbetrag der Bestellung und ein array von BestitKlarnaOrderManagement\Components\Api\Model\LineItem Instanzen.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Api\Model\LineItem;
use BestitKlarnaOrderManagement\Components\Api\Model\ProductIdentifiers;
use BestitKlarnaOrderManagement\Components\Constants;
use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $lineItem = new LineItem();
        $lineItem->type = Constants::KLARNA_LINE_ITEM_TYPE_PHYSICAL;
        $lineItem->totalTaxAmount = 0;
        $lineItem->totalAmount = 0;
        $lineItem->quantity = 1;
        $lineItem->name = 'Free article';
        $lineItem->productIdentifiers = new ProductIdentifiers(); // ProductIdentifiers are blank intentionally
        $lineItem->taxRate = 0;
        $lineItem->totalDiscountAmount = 0;
        $lineItem->unitPrice = 0;
        $lineItem->quantityUnit = 'Pieces';
        $lineItem->reference = 'SW1000';

        $klarnaResponse = $this->orderFacade->updateOrder('klarna-order-id', 0, [$lineItem]);
    }
}

Autorisierung verlängern über die API

Um eine Autorisierung zu verlängern, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die extendAuthTime Methode aufrufen, welche eine Autorisierung verlängert.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->orderFacade->extendAuthTime('klarna-order-id');
    }
}

Verbleibenden Betrag freigeben über API

Um den verbleibenden Betrag freizugeben, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die releaseRemainingAmount Methode aufrufen, welche den verbleibenden Betrag freigibt.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->orderFacade->releaseRemainingAmount('klarna-order-id');
    }
}

Rechnung erneut senden über die API

Um eine Rechnung erneut zu senden, benötigen Sie die BestitKlarnaOrdferManagement\Components\Facade\Capture Facade. Über diese können Sie die resend Methode aufrufen, welche die Rechnung erneut sendet.

Da eine Rechnung per erfassten Betrag erstellt wird, kann auch nur für einen bestimmten erfassten Betrag eine Rechnung erneut versendet werden. Hierzu wird die Capture Id benötigt, welche bei dem Bestellabruf mitgeliefert wird.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Capture as CaptureFacade;

class Example
{
    /** @var CaptureFacade */
    protected $captureFacade;

    public function __construct(CaptureFacade $captureFacade)
    {
        $this->captureFacade = $captureFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->captureFacade->resend('klarna-order-id', 'capture-id');
    }
}

Bestellung stornieren über die API

Um eine Bestellung zu stornieren, benötigen Sie die BestitKlarnaOrderManagement\Components\Facade\Order Facade. Über diese können Sie die cancel Methode aufrufen, welche die Bestellung storniert.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Facade\Order as OrderFacade;

class Example
{
    /** @var OrderFacade */
    protected $orderFacade;

    public function __construct(OrderFacade $orderFacade)
    {
        $this->orderFacade = $orderFacade;
    }

    public function example()
    {
        $klarnaResponse = $this->orderFacade->cancel('klarna-order-id');
    }
}

API Verwendung und Cent Kalkulation

Einführung mit Cent Kalkulation

Standardmäßig verwendet Shopware Dezimal Zahlen als Preise, während Klarna mit Cents und somit mit ganzen Zahlen arbeitet. Wir müssen dementsprechend die Shopware Preise in Cents umwandeln, bevor wir diese an Klarna übertragen.

Hierfür haben wir zwei Methoden, die hier aufgelistet werden.

PHP Kalkulation

Kommazahlen können in PHP nicht 100%ig richtig dargestellt werden und führen somit immer wieder mal zu Rundungsproblemen.

Die erste Methode benutzt die Standard PHP Kalkulation.

Vorteile:

  • Immer verfügbar, keine Server Einstellungen notwendig.

Nachteile:

  • Bei der Methode besteht größere Gefahr von Rundungsfehlern.

BcMath Kalkulation

Die Methode verwendet die bcmath Extension. Diese arbeitet intern mit strings und nicht mit [Dezimalzahlen] (http://php.net/manual/de/language.types.float.php) und kann somit eine genauere Berechnung durchführen.

Vorteile:

  • Geringere Gefahr von Rundungsfehlern.

Nachteile:

  • Die Extension muss auf dem Server installiert und konfiguriert werden.

PHP Kalkulation erweitern

Um die PHP Kalkulation zu erweitern kann das Decorator Pattern verwendet werden.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Calculator\CalculatorInterface;

class Example implements CalculatorInterface
{
    /** @var CalculatorInterface */
    protected $decoratedCalculator;

    public function __construct(CalculatorInterface $decoratedCalculator)
    {
        $this->decoratedCalculator = $decoratedCalculator;
    }

    public function isSupported()
    {
        return $this->decoratedCalculator->isSupported();
    }

    public function toCents($amount)
    {
        return $amount * 100;
    }

    public function toMajorUnit($amount)
    {
        return $this->decoratedCalculator->toMajorUnit($amount);
    }
}

In der service.xml muss dann der neue Service als Dekorator markiert werden:

<service
        class="App\Example\Example"
        id="app.example.example"
        decorates="bestit_klarna_order_management.components.calculator.php_calculator">
    <argument type="service" id="app.example.example.inner"/>
</service>

Einführung in den Positions Modus

Shopware speichert einen Modus für jede Position (eine interne Id), welche aussagt, was für ein Typ die Positionen haben. Klarna kennt diese interne Id nicht und somit müssen diese Modus so konvertiert werden, dass Klarna die Typen auch versteht.

Dazu haben wir für jeden Modus eine Converter Klasse erstellt, welche den Modus zu einem Klarna Typ konvertieren.

Alle Converter müssen das BestitKlarnaOrderManagement\Components\Converter\ModeInterface implementieren.

Converter modifizieren

In dem Beispiel wird der Converter des Modus "2" (Shopware Rabattgutschein) modifiziert, sodass dieser immer den Typ gift_card zurück gibt.

<?php

namespace App\Example;

use BestitKlarnaOrderManagement\Components\Constants;
use BestitKlarnaOrderManagement\Components\Converter\ModeInterface;
use BestitKlarnaOrderManagement\Components\Exception\NoSupportedModeException;

class Example implements ModeInterface
{
    /** @var ModeInterface */
    protected $decoratedConverter;

    public function __construct(ModeInterface $decoratedConverter)
    {
        $this->decoratedConverter = $decoratedConverter;
    }

    public function isSupported($mode)
    {
        return $this->decoratedConverter->isSupported($mode);
    }

    public function convert($mode, $price = null)
    {
        if (!$this->isSupported($mode)) {
            throw new NoSupportedModeException();
        }

        return Constants::KLARNA_LINE_ITEM_TYPE_GIFT_CARD;
    }
}

In der service.xml muss dann der neue Service als Dekorator markiert werden:

<service
        class="App\Example\Example"
        id="app.example.example"
        decorates="bestit_klarna_order_management.components.converter.voucher">
    <argument type="service" id="app.example.example.inner"/>
</service>

Sonstiges

Automatische Klarna Aktionen

Die Plugin Konfiguration wird hier genauer erklärt.

Es können Captures und Refunds, wenn konfiguriert, automatisch ausgeführt werden.

Automatisches Capture

Wenn sich der Bestellstatus auf den konfigurierten Capture on Bestellstatus ändert, wird ein volles Capture automatisch ausgeführt. Die Aktion wird immer dann getriggered, wenn sich der Bestellstatus über den Doctrine ORM verändert. Nicht aber wenn der Wert manuell in der Datenbank verändert wird. So wird sichergestellt, dass die Aktion von der Shopware API und auch von anderen Plugins getriggered werden kann.

Automatisches Refund

Wenn sich der Bestellstatus auf den konfigurierten Refund on Bestellstatus ändert, wird ein volles Capture automatisch ausgeführt. Die Aktion wird immer dann getriggered, wenn sich der Bestellstatus über den Doctrine ORM verändert. Nicht aber wenn der Wert manuell in der Datenbank verändert wird. So wird sichergestellt, dass die Aktion von der Shopware API und auch von anderen Plugins getriggered werden kann.

Fehlermeldungen

Es kann natürlich vorkommen, dass mal ein Fehler auftritt. Hier listen wir alle Fehler, die im normalen Betrieb auftreten können.

Bestellanlage schlägt fehl

Wenn es mal vorkommt, dass die Bestellanlage bei Klarna fehlschlägt, wird die Bestellung in Shopware dennoch erstellt. Allerdings erhält die Bestellung dann den Zahlungsstatus Überprüfung notwendig.

In diesem Fall müssen Sie den Kunden kontaktieren und die Zahlung auf eine andere Art abwickeln bzw. der Kunde tätigt die Bestellung erneut.

Beliebiger API Call schlägt fehlt

Wenn ein API Call fehlschlägt, wird dies entsprechend in die Klarna Log Dateien geschrieben (wenn das Logging aktiv ist). Und es wird immer entsprechend an eine Bestellung geschrieben, diese Fehler kann man in der Bestellungsübersicht (im Klarna Tab) einsehen.

In dem "Details" Fenster werden dann mehr Informationen angezeigt, welche von der Klarna API zurückgegeben wurden: