Co potřebujeme z objednávkového systému
Mailingová appka potřebuje vědět, kdo co a kdy koupil, a umět vytvářet slevové kódy. Tady je seznam seřazený podle důležitosti. Nemusí to být hned všechno: pro začátek stačí body 1, 4, 5 a 7. Formát (REST, GraphQL, export) je na vás, přizpůsobíme se.
1. Objednávky (nutné)
Nutné pro F1- Endpoint se seznamem objednávek, filtr podle data změny (updated_since) a stránkování. Např. GET /orders?updated_since=2026-01-01T00:00:00Z&page=2
- U každé objednávky: ID, eshop (doména), email zákazníka, jméno (pokud je), země a jazyk, vytvořeno, zaplaceno, stav (čeká na platbu, zaplaceno, zrušeno, vráceno), celková cena, měna, použitý slevový kód.
- Položky objednávky: služba (platforma Instagram/TikTok, typ sledující/lajky/zhlédnutí), balíček, množství, cena.
- Pokud se ukládá: zdroj návštěvy (UTM parametry), zařízení.
- Jednorázový export celé historie objednávek (CSV nebo JSON) pro první import.
2. Webhooky (velmi užitečné)
F1–F2- POST na naši adresu při událostech: objednávka vytvořena, zaplacena, zrušena, vrácena.
- Obsah stejný jako u objednávky výše. Podepsaný sdíleným tajemstvím (hlavička s HMAC podpisem), ať víme, že jde opravdu od vás.
- Bez webhooků to jde taky, budeme se ptát každých pár minut, jen série po nákupu poběží s malým zpožděním.
3. Nezaplacené objednávky
F2- Objednávky vytvořené s emailem, které nebyly zaplacené. Stačí, když budou v endpointu objednávek se stavem čeká na platbu.
- Odkaz, kterým se zákazník vrátí přímo k zaplacení té objednávky.
4. Souhlasy a odhlášení
Nutné pro F1- Ukládá systém souhlas s marketingovými emaily? Pokud ano: příznak, datum a odkud (checkbox u objednávky, newsletter).
- Pokud ne: jak zní text u objednávky ohledně emailů (kvůli tomu, jestli můžeme psát stávajícím zákazníkům).
- Odhlášení budeme evidovat u nás. Bylo by dobré, kdyby šlo systému poslat informaci, že se někdo odhlásil.
5. Produkty a ceny
F1- Seznam balíčků pro každý eshop: ID, název, platforma, typ, množství, cena v měně eshopu, odkaz na stránku produktu.
- Ideálně odkaz, který rovnou předvyplní balíček (a případně slevový kód) do objednávky.
- Stačí endpoint nebo pravidelný export (JSON nebo XML feed).
6. Slevové kódy
F1- Jedna ze dvou možností:
- A) API pro vytvoření kódu: kód, sleva v % nebo částkou, platnost do, jednorázový, omezení na eshop. A informace, kdy byl kód použit.
- B) Nebo jeden endpoint u nás, kterým se systém při objednávce zeptá, jestli je kód platný. Kódy pak generuje naše appka.
- Varianta A je pro vás jednodušší a běžnější.
7. Technické
F0- Přihlášení API klíčem (hlavička), klíč pro čtení zvlášť od klíče pro zápis kódů.
- Limit požadavků za minutu, ať víme, jak rychle smíme stahovat.
- Testovací prostředí nebo testovací eshop, kde můžeme zkoušet bez skutečných zákazníků.
- Krátká dokumentace nebo aspoň ukázka odpovědi (JSON) pro každý endpoint.
- Posílá systém už nějaké emaily (potvrzení objednávky, faktury)? Odkud a přes co? Transakční emaily necháme u vás.
Kam to poslat
Dokumentaci, klíče a odpovědi pošlete Rudikovi. Klíče prosím nikdy emailem v čistém textu a nikdy do repa, ideálně přes správce hesel.