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 |
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žijedefault. - Administrátorská notifikácia sa hľadá vždy pre jazyk
defaulta 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.
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ľashop_idzo zoznamu obchodov, ak ho nepošlete sami,language_iso— hodnotu parametralanguage.
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.
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:
V prípade chyby:
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. |
Ďakujeme za spätnú väzbu.