unidays php
v1.2.2 Bug fix
Dies ist die PHP-Bibliothek zur Integration mit UNiDAYS. Dies soll für codierte und codelose Integrationen verwendet werden. Die folgende Dokumentation enthält Beschreibungen der Implementierungen und Beispiele.
Wie verwende ich diesen Code?
Direktverfolgung
Codelose Verifizierung
Mitwirken
Hier finden Sie eine Beschreibung aller verfügbaren Parameter. Welche davon Sie uns zur Verfügung stellen, ist abhängig vom vereinbarten Vertrag.
| Parameter | Beschreibung | Datentyp | Beispiel |
|---|---|---|---|
| PartnerId | Ihre von UNiDAYS bereitgestellte PartnerId. Wenn Sie in mehreren geografischen Regionen tätig sind, haben Sie möglicherweise für jede Region eine andere Partner-ID | Base64-codierte Anleitung | XaxptFh0sK8Co6pI== |
| Transaktions-ID | Eine eindeutige ID für die Transaktion in Ihrem System | Zeichenfolge | Bestellen123 |
| Währung | Der ISO 4217-Währungscode | Zeichenfolge | GBP |
Es ist ebenfalls obligatorisch, entweder Code oder MemberID als Parameter anzugeben:
| Parameter | Beschreibung | Datentyp | Beispiel |
|---|---|---|---|
| Code | Der verwendete UNiDAYS-Rabattcode | Zeichenfolge | ABC123 |
| Mitglieds-ID | Nur bereitzustellen, wenn Sie eine codelose Integration verwenden | Base64-codierte Anleitung | 0LTio6iVNaKj861RM9azJQ== |
Beachten Sie, dass alle folgenden Eigenschaften, deren Wert unbekannt ist, in Aufrufen weggelassen werden sollten. Welche der folgenden Werte Sie uns zur Verfügung stellen, hängt von Ihrem vereinbarten Vertrag ab.
| Parameter | Beschreibung | Datentyp | Beispiel |
|---|---|---|---|
| Bestellsumme | Gezahlter Gesamtbetrag, formatiert auf 2 Dezimalstellen | Dezimal | 209,00 |
| ArtikelUNiDAYSRabatt | Gesamtbetrag des UNiDAYS-Rabatts, der auf den Bruttoartikelwert ItemsGross angewendet wird, formatiert auf 2 Dezimalstellen | Dezimal | 13.00 Uhr |
| ArtikelSteuer | Gesamtbetrag der auf Artikel angewendeten Steuer, formatiert auf 2 Dezimalstellen | Dezimal | 34,50 |
| VersandkostenBrutto | Gesamtbetrag der Versandkosten, vor etwaigen Versandrabatten oder Steuern, formatiert auf 2 Dezimalstellen | Dezimal | 5.00 |
| Versandrabatt | Gesamtbetrag des auf die Bestellung angewendeten Versandrabatts (UNiDAYS oder anders), formatiert auf 2 Dezimalstellen | Dezimal | 3,00 |
| ArtikelBrutto | Gesamtgeldbetrag der Artikel, einschließlich Steuern, vor der Anwendung etwaiger Rabatte, formatiert auf 2 Dezimalstellen | Dezimal | 230,00 |
| ArtikelSonstigesRabatt | Gesamter Geldbetrag aller Nicht-UNiDAYS-Rabatte, die auf ItemsGross angewendet werden, formatiert auf 2 Dezimalstellen | Dezimal | 10.00 |
| UNiDAYSDiscountPercentage | Der angewendete UNiDAYS-Rabatt wird als Prozentsatz mit zwei Dezimalstellen formatiert | Dezimal | 10.00 |
| Neuer Kunde | Ist der Benutzer für Sie ein neuer (oder wiederkehrender) Kunde? | Boolescher Wert | wahr oder falsch |
Hier ist ein Beispielkorb mit den Feldern, die sich auf die UNiDAYS-Tracking-Parameter beziehen:
| Artikel | Brutto | UNiDAYS-Rabatt | Anderer Rabatt | Steuer | Nettosumme | Zeilensumme |
|---|---|---|---|---|---|---|
| Schuhe | 100,00 | 0,00 | 0,00 | 16.67 | 83,33 | 100,00 |
| Hemd | 50,00 | 5.00 | 0,00 | 7,50 | 37,50 | 45,00 |
| Jeans | 80,00 | 8.00 | 10.00 | 10.33 | 51,67 | 62,00 |
| Summen | 230,00 | 13.00 Uhr | 10.00 | 34,50 | 172,50 | 207,00 |
| Versand | 5.00 | |||||
| Versandrabatt | 3,00 | |||||
| Bestellsumme | 209,00 |
Nachfolgend finden Sie die drei Optionen zur Umsetzung Ihrer Integration. Diese Beispiele decken sowohl codierte als auch codelose Integrationen ab (Einzelheiten finden Sie im Live-Analyse-PDF) und enthalten alle optionalen Parameter. Sie dienen als Leitfaden für die Umsetzung.
Diese Methode gibt eine URL zurück, mit der Sie die API aufrufen können.
Es ist zwingend erforderlich, dass alle Server-URLs signiert sind. Das bedeutet, dass Sie den Signaturschlüssel, den UNiDAYS Ihnen zur Verfügung stellt, als eines der Argumente übergeben müssen. Der Signaturschlüssel ist eine Base64-codierte GUID. Dieser Endpunkt akzeptiert sowohl GET als auch POST Anfragen.
Die Methode zum Abrufen der URL für eine Server-zu-Server-Anfrage lautet create_server_url($key) . Um diese Methode zu implementieren, müssen Sie zunächst den DirectTrackingDetailsBuilder verwenden, um ein direktes Tracking-Objekt mit den Eigenschaften zu erstellen, die Sie an uns senden möchten. Weitere Details zu diesem Builder finden Sie hier.
Sobald das Objekt mit den Details, die Sie uns senden müssen, erstellt wurde, erstellen Sie einen Tracking-Helfer, geben Sie diese Details als Argument new TrackingHelper($directTrackingDetails) an und rufen Sie ->create_server_url($key) auf, wobei $key der Schlüssel ist, den Sie erhalten haben EINTAGE.
Sie erhalten eine URL zurück, über die Sie dann unsere API aufrufen können. Bei Erfolg wird eine Antwort mit dem Statuscode 204 Kein Inhalt zurückgegeben. Dies funktioniert sowohl für POST als auch für GET -Anfragen.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ key = " someSigningKey " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
$ helper = new TrackingHelper ( $ directTrackingDetails );
$ url = $ helper -> create_server_url ( $ key );Dies wird auch als unsere Client-zu-Server-Integration bezeichnet. Diese Methode gibt eine URL zurück, die in ein Skriptelement auf Ihrer Seite nach der Zahlung/Bestellerfolg platziert werden kann, um die API aufzurufen.
Dies ist eine Option zum Erstellen einer signierten URL für Ihre Skriptanforderung. Dazu müssen Sie uns den Signaturschlüssel senden, den UNiDAYS Ihnen als eines der Argumente für die signierte Methode zur Verfügung stellt.
$url = $helper->create_signed_script_url($key);
anstatt
$url = $helper->create_script_url();
Die Methode zum Abrufen der URL für eine Client-zu-Server-Anfrage ist create_script_url() oder create_signed_script_url($key) wenn Sie sich für die Rückgabe einer signierten URL entschieden haben. Um diese Methode zu implementieren, müssen Sie zunächst den DirectTrackingDetailsBuilder verwenden, um ein direktes Tracking-Objekt mit den Eigenschaften zu erstellen, die Sie an uns senden möchten. Weitere Details zu diesem Builder finden Sie hier.
Sobald das Objekt mit den Details, die Sie uns senden müssen, erstellt wurde, erstellen Sie einen Tracking-Helper, geben Sie diese Details als Argument new TrackingHelper($directTrackingDetails) an und rufen Sie ->create_script_url() für eine nicht signierte URL oder ->create_signed_script_url($key) , wobei $key der Schlüssel ist, der Ihnen von UNiDAYS zur Verfügung gestellt wird.
Sie erhalten eine URL zurück, die in ein Skriptelement auf Ihrer Seite nach Zahlungseingang/Bestellerfolg eingefügt werden kann, um die API aufzurufen. Bei Erfolg wird eine Antwort mit dem Statuscode 200 OK zurückgegeben. Dies funktioniert nur für GET -Anfragen.
Das folgende Beispiel ist eine Anfrage für eine nicht signierte Skript-URL.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
$ helper = new TrackingHelper ( $ directTrackingDetails );
$ url = $ helper -> create_script_url ();Aufrufe an den Tracking-Client ähneln dem Erstellen einer Server-URL, aber anstatt eine URL zurückzugeben, sendet UNiDAYS die Anfrage und gibt eine Antwort zurück.
Es ist zwingend erforderlich, dass alle Tracking-Client-Aufrufe mit einem Schlüssel versehen sind, da die von UNiDAYS gesendeten Anfragen signiert sind.
Um diese Methode zu implementieren, müssen Sie zunächst den DirectTrackingDetailsBuilder verwenden, um ein direktes Tracking-Objekt mit den Eigenschaften zu erstellen, die Sie an uns senden möchten. Weitere Details zu diesem Builder finden Sie hier.
Sobald das Objekt mit den Details, die Sie uns senden müssen, erstellt wurde, erstellen Sie eine Instanz des Tracking-Clients, geben Sie diese Details als Parameter zusammen mit dem Signaturschlüssel an, den UNiDAYS Ihnen mit new TrackingClient($directTrackingDetails, $key) und rufen Sie auf ->sendRequest() .
Eine HttpResponseMessage wird zurückgegeben. Bei Erfolg sollte die Antwort den Statuscode 204 Kein Inhalt haben.
Das folgende Beispiel richtet einige direkte Tracking-Details ein, ruft sendRequest auf dem Client auf und gibt den Antwortcode an die Konsole zurück.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ key = " someSigningKey " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
$ client = new TrackingClient ( $ directTrackingDetails , $ key );
$ response = $ client -> sendRequest ();
echo $ response -> code ; UNiDAYS bietet eine Testendpunktkonfiguration des TrackingHelper Objekts.
Das im Testmodus konfigurierte TrackingHelper-Objekt fügt der URL, die an Sie zurückgegeben oder für Sie gesendet wird, einen zusätzlichen Parameter ( &Test=True ) hinzu.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ key = " someSigningKey " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
// Pass in an aditional argument of true to instantiate the TrackingHelper object in test mode
$ helper = new TrackingHelper ( $ directTrackingDetails , true );
// The url generated will now contain the appended $Test=True parameter, this url will call our test endpoint
$ url = $ helper -> create_server_url ( $ key );Der Zweck des Builders besteht darin, die Erstellung einer Tracking-Anfrage an UNiDAYS einfach und intuitiv zu gestalten.
Die Argumente im Builder sind die obligatorischen Parameter:
$directTrackingDetails = new DirectTrackingDetailsBuilder($partnerId, $currency, $transactionId)
Es stehen dann verschiedene Methoden zur Verfügung, um die Informationen, die Sie uns senden möchten, zusammenzustellen, die anhand des Beispiels verkettet werden können. Diese stimmen mit den Parametern oben in diesem Dokument überein.
base64 encoded guid )string )decimal )decimal )decimal )decimal )decimal )decimal )decimal )decimal )bool )Verketten Sie nur die Werte, zu deren Bereitstellung Sie sich vertraglich verpflichtet haben. Es ist nicht erforderlich, jede Methode anzuwenden.
Der letzte zu verkettende Aufruf ist ->build() der das Objekt erstellt.
<?php
use Unidays ;
$ details = new DirectTrackingDetailsBuilder ( ' somePartnerId ' , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();Wenn Sie zugestimmt haben, UNiDAYS-Mitgliedern neben der direkten Nachverfolgung auch ein codeloses Erlebnis zu bieten, müssen Sie auch die „Codeless API“ implementieren, die Sie beim Parsen und Validieren des signierten Datenverkehrs unterstützt, den wir an Ihre Website weiterleiten.
Rufen Sie zunächst den CodelessUrlVerifier mit dem Schlüssel auf, den Sie von UNiDAYS new CodelessUrlVerifier($key) erhalten. Rufen Sie dann die Methode verify_url_params($ud_s, $ud_t, $ud_h) mit den Werten für ud_s, ud_t und ud_h als Argumente auf.
| Parameter | Beschreibung | Datentyp | Maximale Länge | Beispiel |
|---|---|---|---|---|
| ud_s | Von UNiDAYS verifizierter Studentenausweis | Zeichenfolge | 256 Zeichen | Do/faqh330SGgCnn4t3X4g== |
| ud_t | Zeitstempel für die Anfrage | Zeichenfolge | 64 Bit | 1395741712 |
| ud_h | Hash-Signatur der anderen beiden Parameter | Base64-Zeichenfolge | 256 Zeichen | o9Cg3q2eVElZxYlJsEAQ== |
Wenn die Methode den Hash der eingehenden Anfrage erfolgreich validiert, wird eine DateTime für die Anfrage zurückgegeben; andernfalls wird null zurückgegeben.
<?php
use Unidays ;
// Your key as provided by UNiDAYS
$ key = " someSigningKey " ;
// Obtain parameters from the query string. Be sure to URL Decode them
$ ud_s = " Do/faqh330SGgCnn4t3X4g== " ;
$ ud_t = " 1395741712 " ;
$ ud_h = " i38dJdX+XLKuE4F5tv+Knpl5NPtu5zrdsjnqBQliJEJE4NkMmfurVnUaT46WluRYoD1/f5spAqU36YgeTMCNeg== " ;
$ verifier = new CodelessUrlVerifier ( $ key );
$ verifiedAt = $ verifier -> verify_url_params ( $ ud_s , $ ud_t , $ ud_h );Dieses Projekt ist als Open-Source-Projekt angelegt. Wenn Sie also Vorschläge für Funktionen oder zur Verbesserung des Codes selbst haben oder auf Probleme gestoßen sind; Sie können diese ansprechen und/oder Änderungen bei der Umsetzung vorschlagen.
Wenn Sie daran interessiert sind, zu dieser Codebasis beizutragen, befolgen Sie bitte die Beitragsrichtlinien. Hier finden Sie Anleitungen zum direkten Mitwirken und zum Einreichen von Funktionsanfragen oder Fehlerberichten. Bitte halten Sie sich bei den oben genannten Handlungen an unseren Verhaltenskodex.
