Kulka Mailingpožadavky na API

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.