API pro vytvoření objednávky

Endpoint pro vytvoření objednávky je jediným vstupním bodem, přes který každý externí systém – výkladní skříň e-shopu, terminál prodejního místa, mobilní aplikace, rezervační widget, partnerská integrace – zaznamenává nákup v BizKitHubu. Je záměrně stejným endpointem, ať už platba generuje digitální stahování za 5 € nebo předplatné s dvanáctiměsíčním plánem; flexibilita spočívá v datové zátěži (payloadu), nikoli v matici specializovaných endpointů. Každé pole kromě zákazníka a seznamu položek je volitelné a při vynechání je odvozeno z výchozí konfigurace organizace, takže integrátoři mohou začít s minimálním voláním a rozvíjet se do plného kontraktu, jak se jejich obchodní logika upevňuje.

Tento článek dokumentuje veřejné tvary požadavků a odpovědí, pole, která můžete nastavit, a přesnou sekvenci operací, které platforma provádí vaším jménem při vytváření objednávky. Je to protějšek pro vývojáře k administrátorskému průvodci Objednávky, který popisuje, jak je výsledný záznam následně spravován z administrace.

Endpoint

POST https://api.bizkithub.com/api/v1/order/create

Autentizace probíhá pomocí standardního parametru apiKey (viz článek API klíč). Kromě Content-Type: application/json nejsou vyžadovány žádné další hlavičky.

Minimální funkční datová zátěž

Nejmenší platné volání obsahuje zákazníka identifikovaného jeho e-mailovou adresou a seznam položek – každá položka minimálně s lidsky čitelným popiskem a cenou ve výchozí měně organizace. Vše ostatní lze vynechat, v takovém případě platforma nahradí rozumné výchozí hodnoty definované ve vaší konfiguraci objednávek (skupina objednávek, vstupní stav pracovního postupu, politika expirace, měna).

export type CreateOrderRequest = {
customer: { email: string };
items: { label: string; price: number }[];
};

E-mailová adresa je vždy vyžadována, protože je kotvou, pomocí které platforma páruje příchozí objednávku s existujícím zákaznickým profilem – nebo vytvoří nový, pokud je adresa viděna poprvé. Jakékoli dodatečné zákaznické pole, které dodáte, je sloučeno do profilu pomocí heuristiky hodnocení kvality platformy (pravidla slučování viz Kontakty).

Kompletní datová zátěž

Endpoint pro vytvoření objednávky rozumí podstatně bohatší datové zátěži než minimální. Všechna dodatečná pole jsou volitelná a každé nese specifický systémový význam; existují, aby vám umožnila vyjádřit celý obchodní záměr v jediném volání, namísto vyžadování následných oprav z administrace.

export type CreateOrderRequest = {
customer: Customer;
items: OrderItem[];
orderGroupId?: string;
locale?: string;
currency?: string;
sale?: number;
paymentMethod?: PaymentMethod;
deliveryPrice?: number;
paymentPrice?: number;
expirationDate?: string;
internalNotice?: string;
publicNotice?: string;
tags?: OrderTagList;
returnUrl?: string;
notificationUrl?: string;
};

export type PaymentMethod = "credits" | "money";
export type TagValue = string | number | boolean | null;
export type OrderTagList = Record<string, TagValue | TagValue[]>;
export type OrderItem = {
label: string;
price: number;
vat?: number;
count?: number;
sale?: number;
unit?: string;
productCode?: string;
variantCode?: string;
eventCode?: string;
creditAmount?: number;
};
export type Customer = {
email: string;
name?: string;
phone?: string;
companyName?: string;
companyRegistrationNumber?: string;
taxIdentificationNumber?: string;
streetAddress?: string;
city?: string;
cityPart?: string;
stateRegion?: string;
postalCode?: string;
country?: string;
newsletter?: boolean;
primaryLocale?: string;
};
export type OrderNumber = ${string};
export type PublicOrderCreateResponse = {
orderNumber: OrderNumber;
hash: string;
links: {
orderPageLink: string;
payLink: string;
};
};

Pole CreateOrderRequest

Vlastnost	Typ	Význam
customer	Customer	Identifikační a kontaktní údaje kupujícího. Vyplněno buď z formuláře pokladny, nebo z existujícího zákaznického profilu.
items	OrderItem[]	Položky objednávky. Může být prázdné. Definuje celkovou cenu.
orderGroupId	string	Kód skupiny objednávek (e-shop, POS, rezervace, předplatné, …). Pokud je vynechán, použije se výchozí skupina organizace.
locale	string	Jazyk objednávky – použitý pro oznámení zákazníkům, e-mailové šablony, faktury, stránky platební brány.
currency	string	ISO kód měny, např. CZK, EUR. Objednávka nese přesně jednu měnu; míchání není povoleno.
sale	number	Absolutní sleva na celkovou částku objednávky, vyjádřená v měně objednávky.
paymentMethod	PaymentMethod	Preferovaná platební metoda – buď money (peníze) nebo credits (kredity).
deliveryPrice	number	Cena dopravy v měně objednávky.
paymentPrice	number	Příplatek za platební metodu (např. poplatek za dobírku).
expirationDate	string	ISO datum a čas, do kdy musí být objednávka zaplacena; nezaplacené objednávky po tomto datu jsou automaticky zrušeny.
internalNotice	string	Poznámka viditelná pouze pro operátora administrace.
publicNotice	string	Poznámka dodaná zákazníkem, viditelná v detailu objednávky a na dokumentech.
tags	OrderTagList	Libovolné značky klíč–hodnota pro pozdější filtrování. Až 200 značek na objednávku.
returnUrl	string	Kam přesměrovat zákazníka po dokončení platby na bráně.
notificationUrl	string	Webhook URL volané při každé změně stavu objednávky.

Pole OrderItem

Vlastnost	Typ	Význam
label	string	Lidsky čitelný popis položky. Vždy uložen, bez ohledu na to, zda je položka spojena s produktem.
price	number	Konečná prodejní cena jedné jednotky (včetně DPH) v měně objednávky.
vat	number	Základní sazba DPH. Ignorováno, pokud organizace není registrována k DPH.
count	number	Množství položky. Výchozí hodnota je 1.
sale	number	Absolutní sleva na jednotku, v měně objednávky.
unit	string	Měrná jednotka (např. cm, l, g), pokud se položka nepočítá v kusech.
productCode	string	Unikátní kód produktu z vašeho katalogu. Vytváří odkaz na záznam produktu a aktualizuje skladové zásoby a rezervace.
variantCode	string	Unikátní kód varianty – vyžadován, pokud referencovaný produkt má varianty.
eventCode	string	Unikátní kód kalendářní události, kterou položka představuje (rezervace, kurz, vstupenka, …).
creditAmount	number	Částka zákaznického kreditu k doplnění, pokud je objednávka zaplacena.

Pole Customer

Jakékoli pole zákazníka kromě email je volitelné. To, co dodáte, je porovnáno s existujícím profilem pomocí interního skóre kvality a pouze skutečně lepší hodnoty (úplnější, nověji ověřené, specifičtější) přepíší to, co platforma již ví. Proto můžete bezpečně znovu odesílat stejného zákazníka u každé objednávky, aniž byste poškodili ručně opravený profil.

Pokud zákazník představuje společnost, vyplňte companyName spolu s companyRegistrationNumber a taxIdentificationNumber. Pokud jsou přítomny jak název společnosti, tak osobní jméno, platforma považuje společnost za fakturační subjekt a osobní jméno za jednajícího zástupce.

Odpověď

export type PublicOrderCreateResponse = {
orderNumber: OrderNumber;
hash: string;
links: {
orderPageLink: string;
payLink: string;
};
};

Vlastnost	Typ	Význam
orderNumber	OrderNumber	Skutečné číslo objednávky přidělené v rámci vybrané skupiny objednávek.
hash	string	Externí identifikátor objednávky (32znakový neprůhledný řetězec), vhodný pro URL.
links.orderPageLink	string	URL stránky s detailem objednávky pro zákazníky na platformě BizKitHub.
links.payLink	string	URL platební brány; kam posíláte zákazníka k dokončení platby.

hash je stabilní veřejný identifikátor pro objednávku. Uložte si jej na své straně, pokud potřebujete na objednávku později odkazovat, aniž byste drželi sekvenční orderNumber.

Proces vytváření objednávky

Jakmile požadavek dorazí, platforma provede deterministickou sekvenci kroků. Každý krok buď uspěje, nebo zruší celé volání – v databázi neexistuje částečná objednávka. Pochopení tohoto procesu pomáhá při ladění, proč se konkrétní integrační případ nechová tak, jak jste očekávali.

1. Validace vstupu. Tělo požadavku je validováno proti výše zdokumentovanému schématu. Chybně formátované datové zátěže jsou zamítnuty s dokumentovaným chybovým kódem před jakýmkoli vedlejším efektem.
2. Řešení skupiny objednávek. Zadané orderGroupId – nebo výchozí nastavení organizace – je vyřešeno. Skupina určuje číselnou řadu, povolené stavy pracovního postupu, fakturační subjekt a výchozí politiku expirace.
3. Vstupní stav pracovního postupu. Počáteční stav nové objednávky je odvozen z konfigurace pracovního postupu skupiny.
4. Vyhledání nebo vytvoření zákaznického profilu. customer.email je normalizováno a vyhledáno v databázi kontaktů organizace. Pokud existuje, profil je načten; pokud ne, je vytvořen nový profil. Jakákoli nová pole dodaná v požadavku, která profil dosud neobsahuje, jsou sloučena.
5. Kontroly přístupu. Zákazník je zkontrolován na zákazy na úrovni organizace, příznaky podvodů a další blokující politiky. Zablokovaný zákazník způsobí zamítnutí objednávky v tomto kroku.
6. Přihlášení k odběru newsletteru. Pokud se zákazník přihlásil (customer.newsletter: true), je přidán do seznamu newsletteru organizace.
7. Přidělení čísla objednávky. Nové unikátní číslo objednávky je přiděleno v rámci číselné řady cílové skupiny.
8. Sestavení výchozích hodnot. Jakákoli volitelná pole objednávky, která nejsou dodána volajícím, jsou vyplněna výchozími hodnotami skupiny.
9. Pokus o persistenci. Řádek je vložen do úložiště objednávek. Při vzácných selháních kolize čísel platforma zkusí opakování až dvacetkrát s náhodným zpožděním 10–200 ms, než chybu předá volajícímu.
10. Interní a externí identifikátory. Nově persistentní objednávce jsou přiděleny jak interní (číselné), tak externí (neprůhledný hash) identifikátory.
11. Základní logování. Je zapsán záznam do auditního logu zaznamenávající vytvoření; další změny stavu se připojí do stejného logu.
12. Zaznamenávání stavu pracovního postupu. Počáteční stav je uložen a je otevřen log historie stavů.
13. Položky objednávky. Každá OrderItem je persistována, spolu s vyřešenými odkazy na produkt, variantu, kalendářní událost a kredity, kde je to relevantní.
14. Manipulace s kreditním dluhem. Pokud má zákazník záporný zůstatek kreditu, je automaticky připojena další položka objednávky, aby byl dluh vyrovnán spolu s objednávkou.
15. Výpočet celkové ceny. Celková částka objednávky je vypočtena z položek, dostupných kreditů zákazníka a preferované platební metody.
16. Zápis celkové částky. Vypočtená celková částka je persistována do řádku objednávky.
17. Automatická platba kredity. Pokud lze objednávku zcela uhradit z kreditního zůstatku zákazníka, kredity jsou okamžitě odečteny a je přidána odpovídající položka objednávky pro aplikaci kreditu.
18. Potvrzovací e-mail. Oznámení o vytvoření je zařazeno do fronty pro zákazníka pomocí výchozí šablony organizace pro tuto událost, směrované přes e-mailový systém platformy (viz článek E-mailový systém).
19. Zkrácení s nulovou celkovou částkou. Pokud je konečná celková částka nulová (typicky proto, že celá objednávka byla zaplacena kredity), objednávka je okamžitě označena jako zaplacená a je proveden pracovní postup zaplacené objednávky – včetně jejích oznámení.
20. Plánování expirace. Pokud bylo nastaveno expirationDate a objednávka je nezaplacená, je naplánována úloha na pozadí, která objednávku v daný čas zruší, pokud platba nedorazí dříve.
21. Zápis značek. Jakékoli tags dodané v požadavku jsou uloženy k nové objednávce.
22. Odpověď. Volajícímu je vrácena PublicOrderCreateResponse.

Celý proces je z pohledu volajícího idempotentní v tom smyslu, že druhý, materiálně identický požadavek vytvoří druhou, odlišnou objednávku – vytváření objednávek není deduplikováno podle obsahu. Pokud pro konkrétní integraci potřebujete sémantiku 'maximálně jednou', vygenerujte si na své straně stabilní klíč idempotence a uložte jej do tags objednávky, než zkontrolujete, zda předchozí odeslání již proběhlo úspěšně.

Měna, cena a zaokrouhlování

Měna objednávky je rozhodnuta jako první a každá následující peněžní hodnota v požadavku je interpretována v této měně. Objednávka nemůže kombinovat měny. Různé objednávky mohou nést odlišnou měnu bez omezení; výběr měny pro konkrétní objednávku je zcela na uvážení volajícího.

Ceny uvedené u položek jsou vždy konečné prodejní ceny – včetně DPH, kde je to relevantní. Pole vat popisuje platnou sazbu pro účetnictví a následné fakturace, ale nemění hodnotu price. Slevy (sale v požadavku nebo na položku) jsou vyjádřeny jako absolutní částky v měně objednávky, nikdy jako procenta.

Anonymní objednávky

Objednávka bez skutečného zákazníka – typická pro fyzické pokladny na prodejních místech – je směrována na vestavěný účet organizace pro anonymního zákazníka. Viz Kontakty pro sémantiku tohoto účtu, včetně toho, proč jej nelze smazat a jak interaguje s doručováním e-mailů.

Webhooky a URL pro návrat

Dvě volitelné URL vám umožňují uzavřít smyčku mezi platformou a vaším systémem bez dotazování (pollingu). notificationUrl je webhook typu server-to-server: platforma na něj odesílá malou datovou zátěž se změnou stavu pokaždé, když se stav objednávky změní, včetně počátečního vytvoření a konečného přechodu na zaplaceno/zrušeno. returnUrl je URL viditelné v prohlížeči, na které platební brána přesměruje kupujícího po dokončení platby – zde zobrazíte stránku „děkujeme“.

Pokud jsou dodány obě URL, obdržíte změnu stavu na obou kanálech. Webhook je autoritativní signál; URL pro návrat v prohlížeči je pohodlí UX a může být zmeškáno, pokud kupující zavře záložku před dokončením přesměrování.

Související články

• Objednávky — administrátorský průvodce popisující, co se s objednávkou stane po vytvoření.
• Pracovní postup objednávek — jak jsou modelovány stavy objednávek, přechody a automatizované akce.
• API klíč — jak autentizovat tento požadavek.
• Chybové kódy — jak interpretovat chybové odpovědi z tohoto endpointu.