Nič sa nenašlo

E-shop API – prehľad

E-shop API prepojí s BulkGate akýkoľvek e-shop. Váš e-shop ním oznamuje BulkGate udalosti v obchode: novú objednávku, zmenu stavu, platbu, nového zákazníka a ďalšie. Portál k udalosti nájde notifikáciu nastavenú pre danú aplikáciu, dosadí do šablóny premenné z požiadavky a odošle správu zákazníkovi, administrátorom obchodu alebo obom.

API samo text správy neurčuje. Keď pre udalosť nie je nastavená žiadna notifikácia, požiadavka prejde a nič sa neodošle.

Endpointy

Všetky endpointy prijímajú POST na adrese https://portal.bulkgate.com/api/1.0/eshop/<oblasť>/<akcia>.

ENDPOINT UDALOSŤ STRÁNKA
eshop/order/new Nová objednávka Objednávky
eshop/order/change-status Zmena stavu objednávky Objednávky
eshop/order/payment Zaplatenie objednávky Objednávky
eshop/order/tracking-number Pridelenie čísla zásielky Objednávky
eshop/order/product-cancel Zrušenie produktu v objednávke Objednávky
eshop/order/slip-add Pridanie dobropisu k objednávke Objednávky
eshop/customer/new Nový zákazník Zákazníci
eshop/product/out-of-stock Produkt sa minul Produkty
eshop/product/on-back-order Produkt na objednávku Produkty
eshop/product/update-quantity Zmena skladového množstva Produkty
eshop/product/delete Odstránenie produktu Produkty
eshop/return/new Nová vratka Vratky
eshop/return/change-status Zmena stavu vratky Vratky
eshop/contact/form Odoslanie kontaktného formulára Kontaktný formulár
eshop/setup Nastavenie jazykov, obchodov a stavov Nastavenia
Poznámka

Ak sa požiadavka nedostane k cieľu, zopakujte ju na záložnom serveri backup1.bulkgate.com.

Parametre požiadavky

Endpointy udalostí (všetky okrem eshop/setup) prijímajú rovnaké parametre. Neznámy parameter na najvyššej úrovni požiadavku odmietne s chybou invalid_input_parameters, údaje udalosti preto patria do objektu variables.

NÁZOV PARAMETRA HODNOTA POVINNÝ PREDVOLENÁ HODNOTA
application_id Aplikačný identifikátor Áno -
application_token Aplikačný overovací token Áno -
language Jazyk zákazníckej notifikácie, napr. sk Nie default
shop_id Identifikátor obchodu, ak ich máte viac Nie 0
variables Údaje udalosti — objekt názov: hodnota, hodnoty sú skalárne Nie {}

Požiadavku posielajte ako application/json.

Ako portál vyberie notifikáciu

Notifikácie sa nastavujú v portáli pre každú aplikáciu zvlášť, v sekciách Zákaznícke SMS a Administrátorské SMS. Každá je viazaná na udalosť, obchod (shop_id) a pri zákazníckych aj na jazyk. Zoznam jazykov, obchodov a stavov objednávok a vratiek, pre ktoré portál notifikácie ponúka, nahrá váš e-shop cez nastavenia.

  • Zákaznícka notifikácia sa hľadá pre jazyk z parametra language. Keď aplikácia nemá zapnuté jazykové mutácie, portál jazyk ignoruje a použije default.
  • Administrátorská notifikácia sa hľadá vždy pre jazyk default a odíde na čísla administrátorov, ktorí sú pri nej nastavení.
  • Zákaznícka aj administrátorská notifikácia sa vyhodnocujú nezávisle — udalosť môže odoslať jednu, obe alebo žiadnu.
Dôležité

Rovnaký text na rovnaké číslo portál počas 24 hodín neodošle druhýkrát. Opakované volanie tej istej udalosti tak zákazníkovi nepošle duplicitnú správu.

Telefónne číslo zákazníka

Číslo zákazníka portál hľadá vo variables. Poradie určuje premenná contact_address_preference:

contact_address_preference PORADIE PREMENNÝCH S ČÍSLOM PORADIE PREMENNÝCH S KRAJINOU
delivery (predvolené) customer_mobile, customer_phone, customer_invoice_mobile, customer_invoice_phone, phone_mobile, phone, phone_number customer_country_id, customer_invoice_country_id, customer_country, customer_invoice_country, iso, country_iso
invoice customer_invoice_mobile, customer_invoice_phone, customer_mobile, customer_phone, phone_mobile, phone, phone_number customer_invoice_country_id, customer_country_id, customer_invoice_country, customer_country, iso, country_iso

Použije sa prvá premenná, z ktorej sa dá zostaviť platné číslo. Krajinu portál berie ako dvojpísmenový ISO kód (cz, sk, …) a podľa nej doplní predvoľbu pri číslach zadaných bez nej. Keď platné číslo nenájde, zákaznícka notifikácia sa neodošle.

Premenné v šablónach

Šablóna notifikácie používa premenné z variables zápisom <názov>, napr. <order_id>. Predvolenú hodnotu priamo v šablóne zapíšete ako <názov:hodnota>. Portál navyše doplní:

  • shop_name — názov obchodu podľa shop_id zo zoznamu obchodov, ak ho nepošlete sami,
  • language_iso — hodnotu parametra language.

Premenné, ktoré nepošlete, sa v texte nahradia predvolenou hodnotou — pri väčšine prázdnym reťazcom, pri order_id, long_order_id a order_ref pomlčkou. Predvolenú hodnotu majú tieto premenné:

SKUPINA PREMENNÉ
Obchod shop_id, shop_email, shop_name, shop_domain, shop_currency, shop_phone, store_id, lang_id, language_iso
Zákazník customer_id, customer_company, customer_firstname, customer_lastname, customer_name, customer_address, customer_postcode, customer_city, customer_state, customer_country, customer_country_id, customer_phone, customer_mobile, customer_email, customer_vat_number, customer_fax, customer_message, customer_firstname_vokativ, customer_lastname_vokativ
Fakturácia customer_invoice_company, customer_invoice_firstname, customer_invoice_lastname, customer_invoice_address, customer_invoice_postcode, customer_invoice_city, customer_invoice_state, customer_invoice_country, customer_invoice_country_id, customer_invoice_phone, customer_invoice_mobile, customer_invoice_vat_number, customer_invoice_firstname_vokativ, customer_invoice_lastname_vokativ
Objednávka order_id, long_order_id, order_ref, order_reference, order_status, order_status_id, order_status_message, order_message, order_currency, order_payment, order_total_paid, order_total_locale, order_date, order_datetime, order_time, order_date1–order_date7, order_time1, order_products1–order_products8, order_smsprinter1–order_smsprinter4, cart_id, id_address_delivery, id_address_invoice
Doprava carrier_id, order_carrier_name, order_carrier_code, order_carrier_url, order_carrier_delay, order_carrier_tracking_number, order_carrier_tracking_date, order_carrier_price, order_carrier_price_locale, order_carrier_weight, order_tracking
Produkt product_id, product_name, product_quantity, product_minimal_quantity, product_model, product_ref, product_description, product_manufacturer, product_supplier, product_supplier_id, product_supplier_ref, product_price, product_price_locale, product_ean, product_ean13, product_upc, product_isbn, product_jan, product_mpn, product_sku
Vratka return_id, return_status, return_status_id, return_action, return_action_id, return_reason, return_reason_id, return_date, return_customer_message, return_question, return_products1–return_products8
Zamestnanec employee_id, employee_email, employee_firstname, employee_lastname

Poslať môžete aj vlastné premenné — šablóna ich použije rovnako.

Odpoveď

V prípade úspechu vracia objekt data s výsledkom každej odoslanej správy, zvlášť pre zákazníka (customer) a pre administrátorov (admin). Kľúč chýba, keď pre udalosť daná notifikácia nie je nastavená. Nastavená, ale vypnutá zákaznícka notifikácia vráti prázdne pole.

{ "data": { "customer": [ { "status": "accepted", "message_id": "tmpde1bcd4b1d1", "part_id": ["tmpde1bcd4b1d1"], "number": "420777777777", "channel": "sms" } ] } }

Keď pre udalosť nie je nastavená žiadna notifikácia, odpoveď je {"data": []}.

Ak sa notifikáciu nepodarí odoslať (neplatný odosielateľ, číslo na blackliste, duplicitná správa…), požiadavka aj tak skončí úspešne a namiesto výsledku správy obsahuje kód chyby:

{ "data": { "customer": [ ["duplicity_message"] ] } }

V prípade chyby:

{ "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null }

Kde:

  • type a error (popis chyby) nájdete v tabuľke typov chýb
  • code je HTTP kód chyby
  • detail je doplňujúca informácia o chybe

Typy chýb E-shop API

TYP KEDY NASTANE
unknown_identity Chýba application_id alebo application_token, prípadne nie sú platné.
invalid_input_parameters Požiadavka obsahuje neznámy parameter alebo parameter so zlým typom.
unknown_action Akcia v adrese neexistuje, napr. eshop/order/cancel.
Bola táto stránka užitočná?