## Průvodce pro partnery a vývojáře Vítejte v API rozhraní platformy Eshop-rychle. Tento dokument slouží jako ucelený průvodce, který vás provede od prvního přihlášení až po úspěšné nasazení vaší aplikace do ostrého provozu. ### 1. Dvě oddělená prostředí (DEV vs. PROD) Pro bezpečný vývoj využíváme dvě striktně oddělená prostředí. **Důležité:** Přístupové údaje a API klíče z testovacího prostředí nebudou fungovat v produkci a naopak. * **TEST / DEV (.dev):** Prostředí určené výhradně pro vývoj a ladění vaší integrace. * API Administrace: [api.eshop‑rychle.dev](https://api.eshop-rychle.dev/login) – zde spravujete své klíče a webhooky pro vývoj. * Testovací e-shop: [Přihlášení](https://account.eshop-rychle.dev/cs/login) – zde simulujete chování e-shopaře a testujete aktivaci své aplikace. * **OSTRÉ / PROD (.cz):** Produkční prostředí pro reálné e-shopy. * API Administrace: [api.eshop‑rychle.cz](https://api.eshop-rychle.cz/login). Po navázání partnerství obdržíte e-mailem přístupy do obou administrací a k vašemu testovacímu e-shopu na prostředí .dev. ### 2. Příprava testovacího prostředí (Krok za krokem) Aby bylo možné na testovacím e-shopu cokoli zkoušet, musí mít aktivní placený tarif. Na DEV prostředí můžete využít tento postup pro aktivaci bez reálné platby: 1. **Aktivace tarifu:** V administraci testovacího e-shopu (.dev) klikněte vlevo dole na „Objednat placenou verzi". 2. **Volba tarifu:** Zvolte ideálně tarif Business na 2 roky (obsahuje plnou funkčnost). 3. **Platební trik:** Při výběru platby zvolte GoPay → Online bankovní převod → Česká spořitelna. 4. **Výsledek:** Systém objednávku automaticky uhradí „zadními vrátky" a tarif ihned aktivuje. ### 3. Interaktivní dokumentace a testování volání Přímo na svém e-shopu můžete využít interaktivní dokumentaci na adrese: `https://VASE-URL/api-engine` (např. `https://123456789.s11.eshop-rychle.dev/api-engine`) Stačí zde vložit váš vygenerovaný token a můžete si okamžitě vyzkoušet jednotlivá volání API přímo v prohlížeči. Dokumentace pro vás zároveň automaticky generuje odpovídající curl příkazy. Příklad pro získání seznamu objednávek: ```bash curl -X 'GET' \ 'https://YOUR-URL/api-engine/orders?page=1' \ -H 'accept: application/ld+json' \ -H 'X-AUTH-TOKEN: YOUR-TOKEN' ``` ### 4. Aktivace aplikace a práce s webhooky Vaši aplikaci (balíček) vám v systému založíme my na základě smlouvy. Vaším úkolem je ji na testovacím e-shopu najít a aktivovat. * **Kde aplikaci najít:** V administraci testovacího e-shopu v sekci Aplikace → Správa aplikací (typicky v kategorii Partneři). * **Webhooky:** V momentě, kdy e-shopař (vy) klikne na „Aktivovat", odešleme webhook na vaši nastavenou URL. * **Doporučení pro vývoj:** * Idempotence: Webhook může přijít opakovaně (např. při výpadku spojení), vaše strana by na to měla být připravena. * Asynchronita: Pokud zpracování webhooku trvá déle, odpovězte ihned kódem 2xx a operaci dokončete na pozadí. * Retry logika: Pokud váš server neodpoví úspěšně, pokusíme se webhook odeslat znovu ještě 3× v 10minutových intervalech. ### 5. Výkonnostní limity a cena požadavků Přístup k API je standardně omezen, aby byla zajištěna stabilita systému: * **Souběžná připojení:** Maximálně 2 aktivní spojení na jeden e-shop. * **Frekvence:** Limit 3 600 požadavků za hodinu a 21 600 požadavků za den na jeden e-shop. * **Cena požadavků:** Standardní požadavek má cenu 1. U hromadných (batch) požadavků je cena rovna počtu změněných položek děleno 10 (zaokrouhleno nahoru, min. 1). Každá odpověď nese v hlavičkách aktuální stav limitu: * `X-RateLimit-Request-Cost` – cena právě odbaveného požadavku. * `X-RateLimit-Hourly-Remaining` – zbývající požadavky v aktuální hodině. * `X-RateLimit-Daily-Remaining` – zbývající požadavky v aktuálním dni. Při překročení limitu vrátí API `429 Too Many Requests` s hlavičkou `Retry-After`. ### 6. Přechod na ostrý provoz (PROD) Jakmile máte na DEV vše otestováno a funkční, ozvěte se nám k dokončení onboardingu: 1. **Prezentační call:** Kontaktujte Jiřího Košťála ([jiri.kostal@golemos.com](mailto:jiri.kostal@golemos.com)) pro domluvení krátké ukázky funkčnosti aplikace. 2. **Založení na PROD:** Po schválení vám aplikaci založíme na produkci, kde si vygenerujete nové ostré API klíče. 3. **Marketing:** Pro zveřejnění v našem Marketplace je podmínkou dodání [medailonku aplikace](https://docs.google.com/document/d/1vgASfEHpR0BIMs5-xD-PW87mhbU0U7A42AKQjhoCxb8/edit?usp=sharing) a podkladů pro blog či newsletter. Medailonek zároveň obsahuje statické instrukce, které se uživateli objeví po instalaci vaší aplikace. ### 7. Troubleshooting (Časté dotazy) * **Aplikaci nevidím na e-shopu:** Zkontrolujte, zda má testovací e-shop aktivní tarif (viz bod 2). * **Webhooky nechodí:** Ověřte, že váš endpoint je dostupný přes HTTPS a neblokuje ho firewall nebo WAF. * **API klíč nefunguje:** Ujistěte se, že používáte klíč pro správné prostředí (DEV vs. PROD) a správný formát autorizace v hlavičkách. ### Kontakty a podpora * Technické dotazy: [api@eshop-rychle.cz](mailto:api@eshop-rychle.cz) / [+420 608 474 914](tel:+420608474914) * Onboarding a procesy: [jiri.kostal@golemos.com](mailto:jiri.kostal@golemos.com) --- ### Strojově čitelná specifikace (pro AI a automatizaci) Kompletní specifikace API ve formátu OpenAPI 3.1.0 (JSON) je dostupná na [/api-engine/docs.jsonopenapi](/api-engine/docs.jsonopenapi). Souhrn pro LLM a AI agenty: [/api-engine/llms.txt](/api-engine/llms.txt).
Replaces the CategoryLinkProductBatch resource.
Retrieves a CategoryLinkProductBatch resource.
Replaces the CategoryProductSortingBatch resource.
Retrieves a CategoryProductSortingBatch resource.
Replaces the ConnectedProductsBatch resource.
Retrieves a ConnectedProductsBatch resource.
Updates the NewsletterContactUnsubscribe resource.
Retrieves a NewsletterContactUnsubscribe resource.
Replaces the ProductAttachmentBatch resource.
Retrieves a ProductAttachmentBatch resource.
Replaces the ProductCommonBatch resource.
Retrieves a ProductCommonBatch resource.
Replaces the ProductEnergyLabelBatch resource.
Retrieves a ProductEnergyLabelBatch resource.
Replaces the ProductHasUnitBatch resource.
Retrieves a ProductHasUnitBatch resource.
Replaces the ProductImageBatch resource.
Replaces the ProductItemInfoBatch resource.
Retrieves a ProductItemInfoBatch resource.
Replaces the ProductLinkParameterValueBatch resource.
Retrieves a ProductLinkParameterValueBatch resource.
Replaces the ProductOriginBatch resource.
Retrieves a ProductOriginBatch resource.
Replaces the ProductOriginLabelBatch resource.
Retrieves a ProductOriginLabelBatch resource.
Replaces the ProductPriceLevelBatch resource.
Retrieves a ProductPriceLevelBatch resource.
Replaces the ProductSimilarsBatch resource.
Retrieves a ProductSimilarsBatch resource.
Replaces the ProductVariantDefinitionBatch resource.
Retrieves a ProductVariantDefinitionBatch resource.
Replaces the ProductVideoBatch resource.
Retrieves a ShopBillingDetails resource.
Retrieves a UploadCategoryImage resource.
Retrieves a UploadCategoryInfoOgImage resource.
Retrieves a UploadProductAttachment resource.
Retrieves a UploadProductEnergyLabel resource.
Retrieves a UploadProductImages resource.
Retrieves a UploadProductItemInfoOgImage resource.
Retrieves a WishlistTopProduct resource.
Retrieves a CategoryAccessRestriction resource.
Updates the CategoryAccessRestriction resource.
Deletes the CategoryAccessRestriction resource.
Retrieves a CategoryLinkProduct resource.
Deletes the CategoryLinkProduct resource.
Updates the CategoryLinkProduct resource.
Retrieves a CategoryProductSorting resource.
Deletes the CategoryProductSorting resource.
Updates the CategoryProductSorting resource.
Retrieves a CustomCodeCleanupOrder resource.
Deletes the CustomCodeCleanupOrder resource.
Retrieves a CustomerRegistration resource.
1 - Main image, 2 - Preview image, 3 - Generated image, 4 - Zoom image, 11-16 - Additional images. Generated and Zoom images are generated by the system and cannot be used for POST and PATCH operations.
Poměr získávání bodů: 1 bod za každých X Kč.
Počet dní do aktivace bodů (0 = okamžitě).
Maximální výše slevy z věrnostních bodů v % z hodnoty zboží.
Minimální hodnota objednávky pro využití bodů (bez dopravy a platby).
Zda je zapnuto získávání bodů za registraci.
Zda je zapnuto získávání bodů za odběr newsletteru.
URL odkazu pro proklik z detailu produktu na počet bodů.
Zda je zapnuto automatické posílání e-mailu před expirací bodů.
Počet dní před expirací, kdy má být odeslán e-mail (0 = v den expirace).
Retrieves a LoyaltyPointsSettings resource.
Počet bodů (kladné pro získání, záporné pro využití).
Zbývající počet bodů (pouze pro transactionType='earned', NULL pro ostatní).
Stav transakce (pouze pro transactionType='earned', NULL pro ostatní).
Datum aktivace (kdy se body stanou využitelnými).
Retrieves a LoyaltyPointsTransaction resource.
Retrieves a NewsletterContactStatusLog resource.
Updates the NewsletterContactStatusLog resource.
Retrieves a OrderDeliveryPayment resource.
Updates the OrderDeliveryPayment resource.
Retrieves a ParameterDetailDisplay resource.
Updates the ParameterDetailDisplay resource.
Retrieves a ProductEnergyLabel resource.
Deletes the ProductEnergyLabel resource.
Retrieves a ProductLinkParameterValue resource.
Deletes the ProductLinkParameterValue resource.
Retrieves a ProductOriginLabel resource.
Updates the ProductOriginLabel resource.
Deletes the ProductOriginLabel resource.
Retrieves a ProductStockMovement resource.
Retrieves a ProductVariantDefinition resource.
Updates the ProductVariantDefinition resource.
Retrieves a UrlItemLinkCuteUrl resource.
Deletes the UrlItemLinkCuteUrl resource.
The collection of OrderStateChanges resources
The collection of UploadCategoryImage resources
The collection of UploadCategoryInfoOgImage resources
Creates a UploadCategoryInfoOgImage resource.
The collection of UploadProductAttachment resources
Creates a UploadProductAttachment resource.
The collection of UploadProductEnergyLabel resources
Creates a UploadProductEnergyLabel resource.
The collection of UploadProductImages resources
The collection of UploadProductItemInfoOgImage resources
Creates a UploadProductItemInfoOgImage resource.
The collection of WishlistTopProduct resources
Retrieves the collection of WishlistTopProduct resources.
The collection of Availability resources
Retrieves the collection of Availability resources.
The collection of AvailabilityRule resources
Retrieves the collection of AvailabilityRule resources.
Retrieves the collection of Category resources.
The collection of CategoryAccessRestriction resources
Retrieves the collection of CategoryAccessRestriction resources.
Creates a CategoryAccessRestriction resource.
The collection of CategoryDetail resources
Retrieves the collection of CategoryDetail resources.
The collection of CategoryImage resources
Retrieves the collection of CategoryImage resources.
The collection of CategoryInfo resources
Retrieves the collection of CategoryInfo resources.
The collection of CategoryLinkProduct resources
Retrieves the collection of CategoryLinkProduct resources.
The collection of CategoryLock resources
Retrieves the collection of CategoryLock resources.
The collection of CategoryProductSorting resources
Retrieves the collection of CategoryProductSorting resources.
Creates a CategoryProductSorting resource.
Retrieves the collection of CustomCode resources.
The collection of CustomCodeCleanupOrder resources
Creates a CustomCodeCleanupOrder resource.
Retrieves the collection of CustomCodeCleanupOrder resources.
Retrieves the collection of Customer resources.
The collection of CustomerFlag resources
Retrieves the collection of CustomerFlag resources.
The collection of DiscountCoupon resources
Retrieves the collection of DiscountCoupon resources.
The collection of LoyaltyPointsTransaction resources
Retrieves the collection of LoyaltyPointsTransaction resources.
The collection of NewsletterContactStatusLog resources
Retrieves the collection of NewsletterContactStatusLog resources.
Creates a NewsletterContactStatusLog resource.
Retrieves the collection of Order resources.
Retrieves the collection of OrderCode resources.
The collection of OrderProduct resources
Retrieves the collection of OrderProduct resources.
Retrieves the collection of OrderState resources.
The collection of OriginSubject resources
Retrieves the collection of OriginSubject resources.
Retrieves the collection of OriginType resources.
The collection of OriginTypeSubject resources
Retrieves the collection of OriginTypeSubject resources.
Retrieves the collection of Parameter resources.
The collection of ParameterDetailDisplay resources
Retrieves the collection of ParameterDetailDisplay resources.
The collection of ParameterValue resources
Retrieves the collection of ParameterValue resources.
Retrieves the collection of PriceLevel resources.
Retrieves the collection of Product resources.
The collection of ProductAttachment resources
Retrieves the collection of ProductAttachment resources.
The collection of ProductCommon resources
Retrieves the collection of ProductCommon resources.
The collection of ProductConnected resources
Retrieves the collection of ProductConnected resources.
Retrieves the collection of ProductDial resources.
The collection of ProductDialValue resources
Retrieves the collection of ProductDialValue resources.
The collection of ProductEnergyLabel resources
Retrieves the collection of ProductEnergyLabel resources.
The collection of ProductImage resources
Retrieves the collection of ProductImage resources.
The collection of ProductHasUnit resources
Retrieves the collection of ProductHasUnit resources.
The collection of ProductVideo resources
Retrieves the collection of ProductVideo resources.
Retrieves the collection of ProductItem resources.
The collection of ProductItemInfo resources
Retrieves the collection of ProductItemInfo resources.
The collection of ProductLinkParameterValue resources
Retrieves the collection of ProductLinkParameterValue resources.
Creates a ProductLinkParameterValue resource.
The collection of ProductOldVariant resources
Retrieves the collection of ProductOldVariant resources.
The collection of ProductOrigin resources
Retrieves the collection of ProductOrigin resources.
The collection of ProductOriginLabel resources
Retrieves the collection of ProductOriginLabel resources.
The collection of ProductPriceLevel resources
Retrieves the collection of ProductPriceLevel resources.
The collection of ProductSimilar resources
Retrieves the collection of ProductSimilar resources.
The collection of ProductStockMovement resources
Retrieves the collection of ProductStockMovement resources.
The collection of ProductVariantDefinition resources
Retrieves the collection of ProductVariantDefinition resources.
Retrieves the collection of StockDetail resources.
Retrieves the collection of UnitsCustom resources.
Retrieves the collection of UnitsSystem resources.
The collection of UrlItemLinkCuteUrl resources
Retrieves the collection of Wishlist resources.
The collection of WishlistItem resources
Retrieves the collection of WishlistItem resources.
The message associated with the violation