NeoClick Merchant API

Transkrypt

1 NeoClick Merchant API Zawartość dokumentacji: Logowanie Zarządzanie przesyłkami Płatność za paczkę i utworzenie przesyłki Usunięcie przesyłki Pobranie przesyłki Edycja przesyłki Pobranie etykiety dla przesyłki Utworzenie przesyłki dla transakcji Pobranie dozwolonych typów przesyłki oraz wariantów wielkościowych Zarządzanie transakcjami pobranie transakcji pobranie wszystkich transakcji dla widgetu/integracji Zarządzanie integracjami/widgetami pobranie widgetu dodanie widgetu pobranie wszystkich widgetów dla użytkownika Zarządzanie Merchantem pobranie danych merchanta Widget Dane aplikacji Przykładowy koszyk Algorytm liczenia sygnatury Button NeoClick NeoClick Merchant API v. 0.2 str. 1 z 24

2 1. Logowanie Żeby zalogować się do NeoClick Merchant API należy przekazać dane metodą "POST" na URL: t.d.neoclick.io/users/login z nagłówkiem: Content Type: application/json oraz z danymi przesłanymi w formacie Json "login": "nasz login", "password": "nasze hasło" login login merchanta password hasło Jeśli dane będą poprawne zostanie przesłany nam unikalny dla każdego użytkownika Neoclick Merchant Token "token": "string" który później będzie wykorzystywany do wszystkich zapytań dla danego użytkownika. Zalecamy zapisanie zmiennej token do sesji. W przypadku błędnie podanych danych zostanie zwrócony nam error: "status": 401, "error": "no_user_with_this_credentials" Od teraz w każdym kolejnym zapytaniu należy ustawić nagłówki: Content Type: application/json Authorization: token 2. Zarządzanie przesyłkami 2.1. Płatność za paczkę i utworzenie przesyłki aby zapłacić za paczkę i utworzyć przesyłkę należy przekazać dane metodą "POST" na URL /shipments/id/pay gdzie id to Id przesyłki znajdującej się w systemie Neoclick, należy też pamiętać o przesłaniu nagłówków wspominanych na końcu poprzedniego rozdziału. Jeśli wszystko wykonało się poprawnie zostanie zwrócona nam wiadomość z danymi przesyłki. NeoClick Merchant API v. 0.2 str. 2 z 24

3 Dane odbierane: "updated_at" : " T06:58:09.859Z", "shipment_receiver" : "company_name" : "Random Company Inc", "first_name" : "John", "last_name" : "Doe", "address_line1" : "MainStreet 1/24", "address_line2" : "string", "city" : "Warsaw", "post_code" : "12 123", " " : "example@example.com", "phone" : " ", "country_code" : "string" "shipment_type" : "inpost_locker_standard", "shipment_data" : "weight" : 0, "length" : 0, "width" : 0, "height" : 0, "parcel_target_point" : "KRA007", "personal_collection_point" : "string" "status" : "new", "charge_type" : "string", "external_id" : "string", "tracking_number" : "string", "variant" : "string" updated_at ostatnie zmiany shipment receiver odbiora przesyłki company_name nazwa instytucji first_name imie last_name nazwisko address_line1 ulica address_line2 numer domu/mieszkania city miasto post_code kod pocztowy adres (wartość wymagana) phone numer telefonu(wartość wymagana) country_code kod kraju do którego jest wysyłana przesyłka np PL shipment_type rodzaj przesyłki shipment data dane przesyłki weight,length,width,height rozmiary paczki, używane tylko w przypadku paczek niestandardowych parcel_target_point numer paczkomatu NeoClick Merchant API v. 0.2 str. 3 z 24

4 personal_collection_point punkt odbioru osobistego przypisanego do danej integracji external_id id w systemie logistycznym tracking_number numer do śledzenia przesyłki variant wariant wielkościowy(a,b,c) Tak jak poprzednio, w przypadku błędnie podanych danych lub innych błędów zostanie nam zwrócony error z wiadomością co poszło nie tak. "status" : 401, "error" : "Token missing or invalid" 2.2. Usunięcie przesyłki aby usunąć przesyłkę należy przekazać dane metodą "DELETE" na URL /shipments/id gdzie id to ID przesyłki. W przypadku usunięcia paczki zwracany jest nam status 204, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością Pobranie przesyłki aby pobrać dane przesyłki należy przekazać dane metodą "GET" na URL /shipments/id gdzie id to ID przesyłki. W przypadku poprawnego pobrania danych do paczki zwracany jest nam status 200 oraz dane, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością Dane odbierane: "updated_at" : " T06:58:09.875Z", "id" : 0, "shipment_receiver" : "company_name" : "Random Company Inc", "first_name" : "John", "last_name" : "Doe", "address_line1" : "MainStreet 1/24", "address_line2" : "string", "city" : "Warsaw", "post_code" : "12 123", " " : "example@example.com", "phone" : " ", "country_code" : "string" "shipment_type" : "inpost_locker_standard", NeoClick Merchant API v. 0.2 str. 4 z 24

5 "shipment_data" : "weight" : 0, "length" : 0, "width" : 0, "height" : 0, "parcel_target_point" : "KRA007", "personal_collection_point" : "string" "status" : "new", "charge_type" : "string", "external_id" : "string", "tracking_number" : "string", "variant" : "string" 2.4. Edycja przesyłki aby edytować dane przesyłki należy przekazać dane metodą "PATCH" na URL /shipments/id gdzie id to ID przesyłki oraz należy przesłać dane: Dane wysyłane: "shipment_receiver" : "company_name" : "Random Company Inc", "first_name" : "John", "last_name" : "Doe", "address_line1" : "MainStreet 1/24", "address_line2" : "string", "city" : "Warsaw", "post_code" : "12 123", " " : "example@example.com", "phone" : " ", "country_code" : "string" "shipment_type" : "inpost_locker_standard", "shipment_data" : "weight" : 0, "length" : 0, "width" : 0, "height" : 0, "parcel_target_point" : "KRA007", "personal_collection_point" : "string" "variant" : "string", "updated_at" : NeoClick Merchant API v. 0.2 str. 5 z 24

6 W przypadku poprawnego pobrania danych do paczki zwracany jest nam status 200 oraz zaktualizowane dane paczki, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością. W tym przypadku należy przesłać dane w formacie Json. Nie musimy wysyłać wszystkich pół, jeśli jakieś pola nie zostaną wysłane, to nie będą aktualizowane. Edycja przesyłki może odbywać się tylko w przypadku gdy ich status jest new Pobranie etykiety dla przesyłki aby pobrać etykietę dla przesyłki należy przekazać dane metodą "GET" na URL /shipments/id/label gdzie id to ID przesyłki. W przypadku poprawnego pobrania danych do paczki zwracany jest nam status 200 oraz plik w formacie pdf który należy przetworzyć, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością Utworzenie przesyłki dla transakcji aby utworzyć przesyłke należy przekazać dane metodą "POST" na URL /transactions/id/shipments gdzie id to ID przesyłki. W przypadku poprawnego pobrania utworzenia nowej przesyłki zwracany jest nam status 200 oraz dane utworzonej przesyłki, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością Dane wysyłane: "shipment_receiver" : "company_name" : "Random Company Inc", "first_name" : "John", "last_name" : "Doe", "address_line1" : "MainStreet 1/24", "address_line2" : "string", "city" : "Warsaw", "post_code" : "12 123", " " : "example@example.com", "phone" : " ", "country_code" : "string" "shipment_type" : "inpost_locker_standard", "shipment_data" : "weight" : 0, "length" : 0, "width" : 0, "height" : 0, "parcel_target_point" : "KRA007", NeoClick Merchant API v. 0.2 str. 6 z 24

7 "personal_collection_point" : "string" "variant" : "string", "updated_at" : Wymagane pola to : s, phone, shipment_type, variant Pobranie dozwolonych typów przesyłki oraz wariantów wielkościowych aby pobrać dozwolone typy przesyłki oraz warianty wielkościowe należy przekazać dane metodą "GET" na URL /shipments/id/allowed_shipment_type s gdzie id to ID przesyłki. W przypadku poprawnego pobrania utworzenia nowej przesyłki zwracany jest nam status 200 oraz dane typów oraz wariantów, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością Dane odbierane: "personal_collection" : [ "default" "inpost_locker_standard" : [ "small" "inpost_courier_standard" : [ "below_2kg", "below_1kg" ] personal_collection domyślna wartość default inpost_locker_standard standard wielkości szafki(small,medium,large) inpost_courier_standard standard wielkości paczki dla kuriera( below_1kg, below_2kg, below_5kg, below_10kg, below_30kg, below_50kg ) NeoClick Merchant API v. 0.2 str. 7 z 24

8 3. Zarządzanie transakcjami 3.1. pobranie transakcji aby pobrać transakcje należy przekazać dane metodą "GET" na URL /transactions/id gdzie id to ID przesyłki. W przypadku poprawnego pobrania transakcji zwracany jest nam status 200 oraz dane transakcji, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością Dane odbierane: "transaction_id" : "string" "shipments" : [ "updated_at" : " T06:58:09.916Z", "id" : 0, "shipment_receiver" : "company_name" : "Random Company Inc", "first_name" : "John", "last_name" : "Doe", "address_line1" : "MainStreet 1/24", "address_line2" : "string", "city" : "Warsaw", "post_code" : "12 123", " " : "example@example.com", "phone" : " ", "country_code" : "string" "shipment_type" : "inpost_locker_standard", "shipment_data" : "weight" : 0, "length" : 0, "width" : 0, "height" : 0, "parcel_target_point" : "KRA007", "personal_collection_point" : "string" "status" : "new", "external_id" : "string", "tracking_number" : "string", "variant" : "string" ] transaction_id = numer transakcji status = status transakcji(new) NeoClick Merchant API v. 0.2 str. 8 z 24

9 shipments paczki(dane opisane w rozdziale zarządzanie paczką) 3.2. pobranie wszystkich transakcji dla widgetu/integracji aby pobrać transakcje należy przekazać dane metodą "GET" na URL /intetgrations/id/transactions gdzie id to ID widgetu/integracji. W przypadku poprawnego pobrania transakcji zwracany jest nam status 200 oraz dane transakcji, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością Dane odbierane [ ] "transaction_id" : "string", "status" : 0, "shipments" : [ "updated_at" : " T06:58:09.944Z", "id" : 0, "shipment_receiver" : "company_name" : "Random Company Inc", "first_name" : "John", "last_name" : "Doe", "address_line1" : "MainStreet 1/24", "address_line2" : "string", "city" : "Warsaw", "post_code" : "12 123", " " : "example@example.com", "phone" : " ", "country_code" : "string" "shipment_type" : "inpost_locker_standard", "shipment_data" : "weight" : 0, "length" : 0, "width" : 0, "height" : 0, "parcel_target_point" : "KRA007", "personal_collection_point" : "string" "status" : "new", "charge_type" : "string", "external_id" : "string", "tracking_number" : "string", "variant" : "string" ] NeoClick Merchant API v. 0.2 str. 9 z 24

10 charge_type Określa sposób w jaki konto merchanta zostało obciążone za utworzenie przesyłki (ze środków pre paid lub post paid). NeoClick Merchant API v. 0.2 str. 10 z 24

11 4. Zarządzanie integracjami/widgetami 4.1. pobranie widgetu aby pobrać integracje/widget należy przekazać dane metodą "GET" na URL /intetgrations/id/ gdzie id to ID widgetu/integracji. W przypadku poprawnego pobrania transakcji zwracany jest nam status 200 oraz daneintegracji, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością Dane odbierane "secret" : "secret", "label" : "label", "app_id" : "1", "currency" : "PLN", "allowed_payments" : [ "name" : "ECARD_CARD", "price" : 0 "config_options" : [ "key" : "dotpaytestmode", "value" : "1" "key" : "dotpaysellerpin", "value" : "4" "key" : "dotpaysellerid", "value" : "4161" "key" : "ecardtestmode", "value" : "1" "key" : "ecardmerchantnumber", "value" : "0" "key" : "ecardsecretkey", "value" : "78" NeoClick Merchant API v. 0.2 str. 11 z 24

12 "key" : "ecardclientidkey", "value" : "737" "key" : "signingkey", "value" : "498109" "key" : "paymentunsuccessfulurl", "value" : " "key" : "paymentsuccessfulurl", "value" : " ut et enim ex eveniet facere sunt" "key" : "sitelogolargeurl", "value" : " sunt et quidem est accusamus aut.html" "key" : "sitelogomedurl", "value" : " amet et est ut" "key" : "sitelogostdurl", "value" : " officia aut aut.html" "key" : "sitetermsandconditionsurl", "value" : " sed a nam" "key" : "siteurl", "value" : " saepe provident esse hic eligendi.html" "shipment_types_prices" : [ "variant" : "default", "type" : "personal_collection", "price" : 0 "variant" : "small", "type" : "inpost_locker_standard", "price" : 1750 "variant" : "below_2kg", "type" : "inpost_courier_standard", "price" : 1650 NeoClick Merchant API v. 0.2 str. 12 z 24

13 "variant" : "below_1kg", "type" : "inpost_courier_standard", "price" : 750 "shipment_services_prices" : [ "name" : "cod", "price" : 0 "name" : "cod", "price" : 0 "name" : "cod", "price" : 0 "name" : "cod_under_1000", "price" : 350 "name" : "cod_under_1000", "price" : 500 "dispatch_points" : [ "id" : 1, "name" : "Stanford Bins", "city" : "Port Maynardport", "country_code" : "MM", "post_code" : "12 123", "street" : "Hillary Plains", "building_number" : "8" "personal_collection_points" : [ "id" : 1, "name" : "nostrum", "street" : "Conroy Harbors", "house_number" : "2", "flat_number" : "1", "postal_code" : "12 123", "city" : "Port Derick", "phone_number" : " ", "opening_hours" : "doloribus" "promotions" : [], NeoClick Merchant API v. 0.2 str. 13 z 24

14 "href" : " secret label nazwa widgetu app_id id w systemie logistycznym currency waluta allowed_payments dozwolone płatności name nazwa płatności price? config_options opcje konfiguracyjne key nazwa opcja value wartość shipment_type_prices rodzaje płatności za przesyłki variant wariant przesyłki type typ przesyłki price cena shipment_services_prices? name nazwa value cena dispatch_ points miejsca wysyłki id numer name nazwa city miasto country_code kod państwa post_code kod pocztowy street ulica building_number numer budynku personal_collection_points punkt odbioru osobistego id numer name nazwa street ulica house_number numer domu flat_number numer bloku postal_code kod pocztowy city 0 miasto phone_number numer telefonu opening_hours godziny otwarcia 4.2. dodanie widgetu aby utworzyć nową integracje/widget należy przekazać dane metodą "POST" na URL /intetgrations/id/ gdzie id to ID widgetu/integracji. W przypadku poprawnego pobrania transakcji zwracany jest nam status 200 oraz daneintegracji, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością. NeoClick Merchant API v. 0.2 str. 14 z 24

15 Dane wysyłane: [ "secret" : "string", "label" : "string", "app_id" : "string", "currency" : "string", "allowed_payments" : [ "name" : "string", "price" : 0 "config_options" : [ "key" : "string", "value" : "string" "shipment_types_prices" : [ "variant" : "string", "type" : "string", "price" : "string" "shipment_services_prices" : [ "type" : "string", "name" : "string", "price" : 0 "dispatch_points" : [ "phone" : "string", " " : "string", "name" : "string", "office_hours" : "string", "comments" : "string", "extra_data" : "string" "personal_collection_points" : [ "name" : "string", "street" : "string", "house_number" : "string", "flat_number" : "string", "postal_code" : "string", NeoClick Merchant API v. 0.2 str. 15 z 24

16 ] "city" : "string", "phone_number" : "string", "opening_hours" : "string" "promotions" : [ "external_id" : "string", "name" : "string", "payment_type" : "string", "shipment_type" : "string", "shipment_services_exclusion" : "string", "shipment_discount_price" : 0, "shipment_discount_percentage" : 0 ] Dane odbierane: "secret" : "string", "label" : "string", "app_id" : "string", "currency" : "string", "allowed_payments" : [ "name" : "string", "price" : 0 ], "config_options" : [ "key" : "string", "value" : "string" "shipment_types_prices" : [ "variant" : "string", "type" : "string", "price" : "string" "shipment_services_prices" : [ "type" : "string", "name" : "string", "price" : 0 NeoClick Merchant API v. 0.2 str. 16 z 24

17 "dispatch_points" : [ "phone" : "string", " " : "string", "name" : "string", "office_hours" : "string", "comments" : "string", "extra_data": "string" ], "personal_collection_points": [ "name": "string", "street": "string", "house_number": "string", "flat_number": "string", "postal_code": "string", "city": "string", "phone_number": "string", "opening_hours": "string" ], "promotions": [ "external_id": "string", "name": "string", "payment_type": "string", "shipment_type": "string", "shipment_services_exclusion": "string", "shipment_discount_price": 0, "shipment_discount_percentage": 0 ] 4.3. pobranie wszystkich widgetów dla użytkownika aby pobrać integracje/widgety należy przekazać dane metodą "GET" na URL /merchants/id/integration s gdzie id to ID merchanta. W przypadku poprawnego pobrania transakcji zwracany jest nam status 200 oraz dane integracji, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością. NeoClick Merchant API v. 0.2 str. 17 z 24

18 Dane odbierane: [ "secret" : "string", "label" : "string", "app_id" : "string", "currency" : "string", "allowed_payments" : [ "name" : "string", "price" : 0 "config_options" : [ "key" : "string", "value" : "string" "shipment_types_prices" : [ "variant" : "string", "type" : "string", "price" : "string" "shipment_services_prices" : [ "type" : "string", "name" : "string", "price" : 0 "dispatch_points" : [ "phone" : "string", " " : "string", "name" : "string", "office_hours" : "string", "comments" : "string", "extra_data" : "string" "personal_collection_points" : [ "name" : "string", "street" : "string", "house_number" : "string", NeoClick Merchant API v. 0.2 str. 18 z 24

19 ] "flat_number" : "string", "postal_code" : "string", "city" : "string", "phone_number" : "string", "opening_hours" : "string" "promotions" : [ "external_id" : "string", "name" : "string", "payment_type" : "string", "shipment_type" : "string", "shipment_services_exclusion" : "string", "shipment_discount_price" : 0, "shipment_discount_percentage" : 0 ] NeoClick Merchant API v. 0.2 str. 19 z 24

20 5. Zarządzanie Merchantem 5.1. pobranie danych merchanta aby pobrać dane merchanta należy przekazać dane metodą "GET" na URL /users/merchant/. W przypadku poprawnego pobrania transakcji zwracany jest nam status 200 oraz dane integracji, a w przypadku błędu tak jak w poprzednich przypadkach error z wiadomością Dane odbierane: "id" : 0, "name" : "John Doe", "address_line1" : "Some street", "address_line2" : "1/24B", "city" : "Warsaw", "post_code" : "12 123", " " : "string", "phone" : "string", "tax_id" : " ", "account_balance" : 100.9, "debit_limit" : 10.6, "country_code" : "PL", "shipment_types" : [ "id" : 0, "name" : "inpost_courier_standard" ] id numer użytkownika name imie i nazwisko address_line1 ulica address_line2 numer domu city miasto post_code kod pocztowy adres phone numer telefonu tax_id numer rachunku account_ballance bilans konta debit limit limit devetowy country_code kod kraju shipment_types typy przesyłek id numer typu name nazwa NeoClick Merchant API v. 0.2 str. 20 z 24

21 6. Widget 6.1. Dane aplikacji: appid: signingkey: a3174b e b937ee4c Przykładowy koszyk: "appid": " ", "currency": "PLN", "type": "real", "correlationid": "AAAA ", "articles": [ "id": "producta", "name": "T shirt", "price": 2500, "quantity": 1, "dimensions": "width": 50, "height": 30, "depth": 5, "weight": 300, "id": "productb", "name": "Kubek biały", "price": 300, "quantity": 5, "dimensions": "width": 20, "height": 20, "depth": 30, "weight": 500 ], "dimensions": "width": 300, "height": 400, "depth": 500, "weight": 600, "signature": "" NeoClick Merchant API v. 0.2 str. 21 z 24

22 6.3. Algorytm liczenia sygnatury: 1. oznaczenie appid wartość pola appid 2. oznaczenie [articles[x].namearticles[x].id] sekwencja liczona dla każdego artykułu z listy articles 3. jeżeli wartość dla danego pola nie istnieje, uznajemy że jej wartość to pusty napis Ciąg wejściowy zbudowany jest z: input = appid[articles[x].dimensions.deptharticles[x].dimensions.height articles[x].dimensions.weigtharticles[x].dimensions.widtharticles[x].id articles[x].namearticles[x].quantityarticles[x].price]correlationidc urrencydimensions.depthdimensions.heightdimensions.weigthdimensions.w idthtype Wartość sygnatury: signature = sha256( input + signingkey ) Przykład dla powyższego koszyka: input = producta + T shirt productb + Kubek biały AAAA PLN real zatem: input = productAT shirt productbkubek biały5300aaaa PLN real signature = sha256 ( productAT shirt productbkubek biały5 300AAAA PLN real + a3174b e b937ee4c890) signature: 49820c421bd57993e5b e88c0e7bbd52ac3aa6bba655ab66ee7f1da Button NeoClick: <div class="neo click button" data layout="standard" data position="right"></div> KOD JavaScript: window.neoclickasyncinit = function() NeoClick.init( appid: " ", redirecturi: ' ); NeoClick.setBasket( NeoClick Merchant API v. 0.2 str. 22 z 24

23 ; "currency": "PLN", "type": "real", "correlationid": "AAAA ", "articles": [ "id": "producta", "name": "T shirt", "price": 2500, "quantity": 1, "dimensions": "width": 50, "height": 30, "depth": 5, "weight": 300, "id": "productb", "name": "Kubek biały", "price": 300, "quantity": 5, "dimensions": "width": 20, "height": 20, "depth": 30, "weight": 500 ], "dimensions": "width": 300, "height": 400, "depth": 500, "weight": 600, "signature": "" ); (function(d) var js, id = 'neoclick jssdk', ref = d.getelementsbytagname('script')[0]; if (d.getelementbyid(id)) return; js = d.createelement('script'); js.id = id; js.async = true; js.src = " click.js"; ref.parentnode.insertbefore(js, ref); (document)); Opis wymaganych metod i parametrów w JavaScript SDK. Skrypt linkujący bibliotekę JavaScript SDK służącą do wywołania widgetu, oraz przycisku kupuję z NeoClick należy umieścić przed znacznikiem <body>! (function(d) NeoClick Merchant API v. 0.2 str. 23 z 24

24 var js, id = 'neoclick jssdk', ref = d.getelementsbytagname('script')[0]; if (d.getelementbyid(id)) return; js = d.createelement('script'); js.id = id; js.async = true; js.src = " click.js"; ref.parentnode.insertbefore(js, ref); (document)); Metoda inicjująca widget NeoClick.init() parametry: appid identyfikator aplikacji redirecturi url ustawiany przez merchanta Metoda do konfiguracji koszyka NeoClick.setBasket() parametry: currency waluta type real (produkty fizyczne), virtual (produkt wirtualny) correlationid identyfikator nadawany przez merchanta dla koszyka w celu późniejszej identyfikacji zamówień, nie jest wymagany articles tablica produktow dimensions rozmiary paczki dla wszystkich produktow (opcjonalne) signature wartość sygnatury (algorytm liczenia powyżej) W tablicy articles również występuje pole dimensions. Istnieją 2 sposoby ustawiania parametru dimensions: 1. Dla kazdego produktu osobno (wtedy główny parametr dimensions nie jest ustawiany). 2. Dla całego zamówienia (wtedy w tablicy articles nie ustawiamy dimensions dla zadnego produktu). NeoClick Merchant API v. 0.2 str. 24 z 24