Automatické zpracování objednávek
a propojení s jiným systémem (účetnictví, CRM ..)

Automatický import stavů objednávek do internetového obchodu systému ClickEshop a export objednávek do účetního nebo výrobního systému.

Automatizované propojení probíhají na pozadí plně autonomní, bez zásahu člověka kde se posílají nebo přijímají data, a tím jsou schopny nahradit některé monotónně operace, jako například každodenní import / export objednávek do internetového obchodu. Neexistence duplicitních procesů sebou přináší ušetřené prostředky k obsluze internetového obchodu ale pomáhá i vyvarovat se zbytečným chybám v podobě nepřesných informací a následnému zklamání zákazníka. Automatizovaný import / export objednávek zajistí pravidelnou aktualizaci objednávek v internetovém obchodě nebo v externích systémech bez ohledu na to jestli jste jako administrátor do internetového obchodu vstoupili.

1 Automatizovaný EXPORT OBJEDNÁVEK

Automatizovaný export je možné využít při automatickém zpracování objednávek z internetového obchodu, které se exportují do účetních, výrobních, expedičních nebo logistických systémů.

1.1 Architektura řešení

Celé řešení je založeno na možnosti naplánovat vlastní automatizovaný export za předpokladu dodržení
stanovených podmínek:

předem si vybrat správný typ formátu pro export (export _format)
připravit vlastní spouštěcí skript s autentifikací, který bude volat API rozhraní na straně webshopu "Automatizovaný export objednávek"
naplánovat automatizované spouštění vlastního scriptu, který bude volat API. Plánování volání API je třeba nastavit v jednotlivých časových intervalech. volat API každou 1 hodinu pro stažení objednávek.

Order export

1.2 API rozhraní

slouží pro automatizované zpracování XML souboru (export XML souboru s informacemi o objednávkách) při propojení ClickEshopu s jinými systémy. Na API rozhraní lze naprogramovat vlastní uživatelskou aplikaci.

Cesta k API rozhraní na automatizovaný export objednávek:

https://api.clickeshop.cz/export_orders/

Metoda volání: Rest API HTTP POST

XML soubor bude exportován jako komprimovaný XML soubor ve formátu ZIP

API parametry pro export objednávek (použití metodou HTTP POST / HTTP GET)

Název parametru	Povinný parametr	Popis
login	Áno	Postup pro vytvoření login je následující: 1) Přihlásit se do administrace daného eshopu 2) Zvolit sekci "Globální nastavení / Uživatelé" 3) Vyplnit "Email uživatele:" 4) Role "STANDARD" Oprávnění: žádné! 5) Uložit Na registrovaný mail přijde heslo
password	Áno	Po vložení nového uživatele v sekci "Globální nastavení / Uživatelé" přijde na zaregistrovaný mail nové heslo, které se použije při autentifikaci
id_project	Áno	Nutné požádat podporu o přidělení ID. Požadavek musí být zaslána z kontaktního formuláře přímo z administrace eshopu "Pomoc / Zákaznická podpora"
stateId	Nie	Které ID stavu objednávky se májí exportovat. Standardně se exportují pouze objednávky ve stavu Nová (stateId = 1). V případě více stavů se tyto oddělují středníkem např. stavy 1; 3; 8 ID stavů objednávek je možné získat ze seznamu dokladů a to po přihlášení do clickeshop administrace daného internetového obchodu / Globální nastavení / Úprava textů / Stavy dokladů. V této sekci naleznete stavy všechny objednávek, které si můžete nastavovat. Po rozkliknutí nějakého stavu např. "Storno" se zobrazí formulář na nastavování konkrétního stavu dokladu a následně v URL internetového prohlížeče hledejte parametr id = 4, což je ID stavu dokladu (stavu objednávky)
export _format	Áno	Nabývá hodnoty: XML-CLICKESHOP - struktura pro import objednávek podporována ClickEshopem. Doporučený formát pro import objednávek do vlastních systémů. příklad: https://clickeshop.cz/admin_eshop/batch/eshop_orders-yyyy-mm-dd.xml XML-MONEY-ORDERS - struktura pro import objednávek ve formátu XML pro účetní systém (Money) XML-MONEY-INVOICES - struktura pro import faktur ve formátu XML pro účetní systém (Money) CSV-OMEGA-ORDERS - struktura pro import objednávek ve formátu CSV pro účetní systém (Omega Kros) MRP-ORDERS - struktura pro import objednávek ve formátu XML pro účetní systém (MRP) MRP-INVOICES - struktura pro import faktur ve formátu XML pro účetní systém (MRP) POHODA-ORDERS - struktura pro import objednávek ve formátu XML pro účetní systém (Pohoda)

1.3 Výpis zpracování dat ( log )

Výsledek log ze zpracování automatického exportu bude přístupný v sekci: "Globální nastavení / Hromadní import"
Zaznamenaný a zobrazený je poslední log z exportu.

1.4 Omezení

V reálném čase lze zpracovávat najednou pouze jeden požadavek na export.
API je možné volat maximálně 60 krát za 1 konkrétní den pro jeden projekt
API je možné volat maximálně 1 krát za 1 minutu
API je možné volat pouze přes šifrované spojení SSL https:
Exportují se pouze objednávky dle stavů zasílaných jako vstupní parametry a to nejvýše 60 dní staré
(Aktuální den mínus 60 dní)

1.5 Chybové stavy

Server odpověď na output:
{"result":"ERR"} – Chyba, akce se neprovedla
{"result":"OK"} – Akce se provedla

Server odpověď v HTTP header ( HTTP Status Codes ):
200 – request success
400 – error, bad request

1.6 Vzor testovacího HTML formuláře

Pro produkční účely doporučujeme vytvořit si jednoduchou .NET aplikaci na HTTP post parametrů (kód na pár řádků). Pro produkční provoz se taktéž dá použít open-source aplikace CURL, která se zavolá přes parametry a tato umí odeslat kompresovaný XML soubor i s danými parametry na server clickeshop. Více informací o použití CURL v kapitole "3 Příklad použití volání API přes aplikaci CURL".

1.6.1 Předpřipravený ONLINE testovací formulář

Pro testovací účely stačí pro HTTP post následující HTML formulář:
https://clickeshop.cz/admin_eshop/batch/test-export_orders.html

Pro zjednodušení implementace doporučujeme prohlédnout si zdrojový kód HTML testovacího formuláře.

2 Automatizovaný IMPORT STAVŮ OBJEDNÁVEK

Automatizovaný import je možné využít při změně stavů objednávek, které se importují do internetového obchodu (webshopu) z účetních, výrobních, expedičních nebo logistických systémů.

Pro plnohodnotné propojení objednávek mezi WebShop a externím systémem doporučujeme implementovat i tuto část. Objednávky z části "1 Automatizovaný EXPORT OBJEDNÁVEK", které jsme úspěšně zpracovali do externího systému je následně třeba označit ve webshopu stavem "přebraná". Tímto zajistíme, že při dalším zpracování objednávek z části "1 Automatizovaný EXPORT OBJEDNÁVEK" budeme zpracovávat vždy pouze přírůstek s novými objednávkami.

2.1 Architektura řešení

Celé řešení je založeno na možnosti naplánovat vlastní automatizovaný import za předpokladu dodržení
stanovených podmínek:

export objednávek z části "1 Automatizovaný EXPORT OBJEDNÁVEK"
příprava a zpracování XML feedu do předepsané XML struktury. XML feed má obsahovat seznam objednávek, které jsme úspěšně zpracovali do externího systému (např. Účetního systému) z části "1 Automatizovaný EXPORT objednávek"
připravit vlastní spouštěcí skript s autentifikací, který bude volat API rozhraní na straně webshopu "Automatizovaný import stavů objednávek"
naplánovat automatizované spouštění
po úspěšném volání API "2 automatizovaný IMPORT STAVŮ OBJEDNÁVEK" systém změní stav objednávek ze stavu "Nová" na stav "Přebraná"

import order statuses

2.2 Požadavky na strukturu XML feedu

Systém podporuje automatický import stavů objednávek za předpokladu dodržení standardní struktury XML
feedu.

Kódování = UTF-8
Vzor šablony XML feedu pro import (upload):

<?xml version="1.0"?>
<datapack date="2016-01-14 13:27:10" project="www.myeshop.clickeshop.com">
   <order id="20105816">
     <stateId>1</stateId>
     <sendEmail>1</sendEmail>
     <sendDocument>1</sendDocument>
     <orderDescr><![CDATA[postou pod podacím číslem 70112399/895]]></orderDescr>
   </order>
   <order id="20105815">
     <stateId>4</stateId>
     <sendEmail>0</sendEmail>
     <sendDocument>0</sendDocument>
   </order>
</datapack>

XML soubor bude importován jako komprimovaný XML soubor ve formátu ZIP

Popis parametrů XML feedu:

Název parametru	Popis
order id	Číslo objednávky
stateId	ID stavu objednávky ID stavů objednávek je možné získat ze seznamu dokladů a to po přihlášení do clickeshop administrace daného internetového obchodu / Globální nastavení / Úprava textů / Stavy dokladů. V této sekci naleznete stavy všechny objednávek, které si můžete nastavovat. Po rozkliknutí nějakého stavu např. "Storno" se zobrazí formulář na nastavování konkrétního stavu dokladu a následně v URL internetového prohlížeče hledejte parametr id = 4, což je ID stavu dokladu (stavu objednávky)
sendEmail	1 / odeslat email o změně stavu objednávky 0 / neodeslat email
sendDocument	1 / připojit PDF dokument do emailu 0 / odeslat email bez PDF dokumentu
orderDescr	Dodatečný popis připojen do odesílaného emailu

2.3 API rozhraní

slouží pro automatizované zpracování XML souboru (upload XML souboru s informacemi o aktuálním stavu objednávek) při propojení ClickEshopu s jinými systémy. Na API rozhraní lze naprogramovat uživatelskou aplikaci.

Cesta k API rozhraní na automatizovaný import stavů objednávek:

https://api.clickeshop.cz/import_orders/

Metoda volání: Rest API HTTP POST

XML soubor bude importován jako komprimovaný XML soubor ve formátu ZIP.

API parametry pro import stavů objednávek (použití metodou POST)

Názov parametra	Povinný parameter	Popis
login	Áno	Postup pro vytvoření login je následující: 1) Přihlásit se do administrace daného eshopu 2) Zvolit sekci "Globální nastavení / Uživatelé" 3) Vyplnit "Email uživatele:" 4) Role "STANDARD" Oprávnění: žádné! 5) Uložit Na registrovaný mail přijde heslo
password	Áno	Po vložení nového uživatele v sekci "Globální nastavení / Uživatelé" přijde na zaregistrovaný mail nové heslo, které se použije při autentifikaci
id_project	Áno	Nutné požádat podporu o přidělení ID. Požadavek musí být zaslána z kontaktního formuláře přímo z administrace eshopu "Pomoc / Zákaznická podpora"
file_data	Áno	ve formátu $_FILES['file_data'] ( <form method="post" enctype="multipart/form-data"> ) jako komprimovaný XML soubor ve standardním formátu ZIP (nazov.zip)

2.4 Výpis zpracování dat ( log )

Výsledek log ze zpracování automatického importu bude přístupný přes ClickEshop administrátor v sekci: Globální nastavení / Hromadný import.
Zaznamenaný a zobrazený je vždy poslední log z importu.

2.5 Omezení

Soubor, který se importuje může mít maximálně 10 MB (zip). V případě, že je soubor větší, tak se rozdělí na více dávek. V reálném čase lze zpracovávat najednou pouze jeden import.
API je možné volat maximálně 60 krát za 1 konkrétní den
API je možné volat maximálně 1 krát za 1 minutu
API je možné volat pouze přes šifrované spojení SSL https:

2.6 Chybové stavy