Integracja Mnumi Designer (MnumiWizard) z zewnętrznymi platformami

Dokument dedykowany jest dla deweloperów i zawiera informacje, jak zintegrować usługę Mnumi Designer ze swoim sklepem internetowym.

Jeżeli potrzebujesz dodatkowego wsparcia, zobacz na z Kontakt ze wsparciem Mnumi.

Opis usługi

Dokumentacja ma na celu przedstawienie sposobu wdrożenia edytora on-line w sklepie internetowym za pośrednictwem usługi Mnumi Designer. Dokumentacja podzielona jest na kilka części. Pierwsza to wprowadzenie w integrację. Następna to minimalny przykład wdrożenia edytora w sklepie internetowym w tzw. trybie hosted. Kolejne części poświęcone są na omówienie procesu generowania PDF oraz pobierania pliku PDF.

Materiał ten jest przede wszystkim przeznaczony dla deweloperów, którzy chcą zintegrować usługę edytora on-line ze swoim sklepem internetowym.

Etap pierwszy: Przygotowanie projektu w edytorze on-line przez kupującego

Proces wygląda następująco:

  1. Kupujący klika w przycisk reprezentujący usługę edytora on-line Mnumi Designer.
  2. System Mnumi Designer prezentuje edytor na której kupujący przygotowuje swój projekt. System Mnumi Designer przekierowuje kupującego z powrotem na stronę sklepu, przekazując identyfikator projektu.
  3. System Sprzedawcy zachowuje identyfikator projektu oraz realizuje cały proces zamawiania w sklepie.

Etap drugi: Generowanie pliku PDF

  1. System Sprzedawcy wysyła żądanie wygenerowania pliku PDF. System Mnumi Designer w odpowiedzi przekazuje informację czy plik PDF jest już gotowy do pobrania.
  2. System Sprzedawcy przesyła link do pobrania pliku PDF.

Adres hosta

Domyślny host

http://wizard.mnumi.pl/

Dane testowego kreatora

Testując poprawność integracji z Mnumi Designer można wykorzystać dane następującego dostępu:

Id dostępu (wizard_id):          (w przygotowaniu)
Klucz dostępu (secret_key):      (w przygotowaniu)

W celu dostępu prosimy o Kontakt ze wsparciem Mnumi.

Szyfrowanie zapytania do kreatora

Zapytania kierowane do systemu zawierają dwa zmienne, parametr oraz podpis (signature).

Oto przykład zapytania URL:

http://wizard.mnumi.pl/initOrder
?parameter=eyJhY3Rpb24iOiJjbG9uZSIsImJhY2tVcmwiOiJodHRwOlwvXC9kZW1vLm1udW1pLnBsXC9hZGRX...WF3aXp5dG93ZWtcLyJ9
&signature=W0g9Z3Oj+0frS2W9x85cBQjGkTc=
&id=9999

Opisując podane zapytanie URL, linki jest odzielony znakami końca linii aby był bardziej czytelny.

Oznaczenia parametrów zapytania:

Nazwa Opis
initOrder nazwa komendy
parameter zapytanie w formacie JSON, które jest zakodowane formatem Base64. Z tego parametru liczone jest szyfrowanie (signature)
signature zawiera podpis przekazanego parametru w celu autoryzacji zapytania. Podpis musi odpowaidać podpisowi jakie liczy Mnumi Designer, w innym przypadku system zablokuje zapytanie. przykład podpisu: W0g9Z3Oj+0frS2W9x85cBQjGkTc=. Opis wykonywania podpisu opisany jest poniżej.
id stały identyfikator dostępu

Przygotowanie parametru

Parametry przekazywane do Mnumi Designer są wysyłane są w formie tablicy JSON, zakodowane formatem Base64

$encodedParameter = base64_encode( json_encode($parameter) );

W razie potrzeby analizy przesyłanych informacji do kreatora, zachęcamy do skorzystania z serwisu: https://www.base64decode.org/. Można do niego wkleić całość zakodowanego parametru w celu weryfikacji jego składni w formacie JSON.

Liczenie podpisu

Podpis liczony jest w następujący sposób

$signature = base64_encode( hash_hmac('sha1', $encodedParameter, $secretKey, true) );

Zapytania do serwera

Akcja “initOrder”

Niniejsza akcja służy do przygotowania projektu klienta, w oparciu o dostępne projekty źródłowe.

Przykład parametru JSON przed zakodowaniem

{
   "action":"initOrder",
   "productName":"calendar-a4",
   "wizards":"yDqZLDhzd2,99qZ1Dhztri",
   "backUrl":"http:\/\/your-storefront.mnumi.com\/\/addWizard\/%s\/%s\/%s",
   "count":"1",
   "countChange":true,
   "countMin":1,
   "countMax":26,
   "productTitle":"Calendar A4",
   "productDescription":"Create calendar of your dreams!"
}

Oznaczenia zmiennych

Nazwa Typ Wymagane Opis
action string T Nazwa akcji (zawsze “initOrder”)
productName string T Nazwa produktu
wizards string T Lista identyfikatorów projektów źródłowych Mnumi Designer, oddzielone przecinami
backUrl string T Adres powrotu o sklepu (np. http://company.com/addWizard/%s/%s/%s, gdzie “%s” oznacza kolejno: nazwa projektu, ilość stron, nazwa produktu)
count int T Ilość stron jaką ma mieć projekt
countChange boolean T Czy klient może zmieniać ilość stron (true/false)
countMin int   Ograniczenie ilości stron - minimum
countMax int   Ograniczenie ilości stron - maksimum
productTitle string   Tytuł linku na wpisach Facebook
productDescription string   Opis linu na wpisach Facebook

Akcja “pdfcheck”

Niniejsza akcja służy do przekazania, aby system wygenerował plik PDF z projektu. Akcja zwraca w odpowiedzi informację JSON, ze statusem wygenerowania pliku.

Przykład parametru JSON przed zakodowaniem

{
   "action":"pdfcheck",
   "orderId":"yDqZ4Dhzd2",
   "barcode":"1200000069"
}

Oznaczenia zmiennych

Nazwa Typ Wymagane Opis
action string T Nazwa akcji (zawsze “pdfcheck”)
orderId string T Identyfikator projektu klienta
barcode int   Wartość kodu kreskowego

Przykład odpowiedzi JSON

{
   "result":{
      "status":{
         "code":"pending",
         "description":"Pdf queue entry already created. Waiting..."
      },
      "queueCount":1
   }
}
Zmienna result/status/code określa czy plik PDF jest już gotowy do pobrania:
  • pending: plik PDF oczekuje na wygenerowanie
  • ready: plik PDF jest gotowy

Zmienna result/queueCount określa ilość generowań plików PDF jest oczekujących.

Akcja “pdfstatus”

Niniejsza akcja służy do pobrania wygenerowanego pliku PDF. Akcję należy wywołać gdy akcja “pdfcheck” zwróci status “ready”. W odpowiedzi system zwraca wygenerowany plik PDF.

Przykład parametru JSON przed zakodowaniem

{
   "action":"pdfstatus",
   "orderId":"hBjwY94kEe",
   "barcode":"1200000069"
}

Oznaczenia zmiennych

Nazwa Typ Wymagane Opis
action string T Nazwa akcji (zawsze “pdfstatus”)
orderId string T Identyfikator projektu klienta
barcode int   Wartość kodu kreskowego