{"id":14965648,"url":"https://github.com/baraja-core/heureka-bidding-api","last_synced_at":"2026-03-16T08:02:50.092Z","repository":{"id":37935975,"uuid":"263319541","full_name":"baraja-core/heureka-bidding-api","owner":"baraja-core","description":"Simple PHP API layer for Heureka.","archived":false,"fork":false,"pushed_at":"2023-07-26T04:04:58.000Z","size":62,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-31T07:11:09.766Z","etag":null,"topics":["api","heureka","heureka-api","nette","php"],"latest_commit_sha":null,"homepage":"https://baraja.cz","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/baraja-core.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"janbarasek","custom":["https://brj.app","https://baraja.cz","https://php.baraja.cz"]}},"created_at":"2020-05-12T11:39:01.000Z","updated_at":"2021-12-09T13:51:28.000Z","dependencies_parsed_at":"2024-09-14T00:07:47.371Z","dependency_job_id":"ede80b65-fc82-4d0c-9fa2-4438c52d9272","html_url":"https://github.com/baraja-core/heureka-bidding-api","commit_stats":{"total_commits":22,"total_committers":4,"mean_commits":5.5,"dds":0.2272727272727273,"last_synced_commit":"00a0c5ce01ac9c85700ebbe515e20e11f23a28eb"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baraja-core%2Fheureka-bidding-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baraja-core%2Fheureka-bidding-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baraja-core%2Fheureka-bidding-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baraja-core%2Fheureka-bidding-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/baraja-core","download_url":"https://codeload.github.com/baraja-core/heureka-bidding-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238137840,"owners_count":19422709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","heureka","heureka-api","nette","php"],"created_at":"2024-09-24T13:35:02.898Z","updated_at":"2025-10-25T12:30:26.193Z","avatar_url":"https://github.com/baraja-core.png","language":"PHP","funding_links":["https://github.com/sponsors/janbarasek","https://brj.app","https://baraja.cz","https://php.baraja.cz"],"categories":[],"sub_categories":[],"readme":"Heureka Bidding API v PHP\n=========================\n\nJednoduše použitelná knihovna pro komunikaci s [Heureka API](https://sluzby.heureka.cz/napoveda/bidding-api/) pro strojové získávání dat z Heureky.\n\nV rámci tohoto API můžete stahovat informace o produktech, kategoriích, cenách, dostupnosti a podobně. Data získáváte ve strojově čitelné podobě jako nativní PHP entitu splňující rozhraní `Baraja\\HeurekaBiddingApi\\Response\\Response`.\n\n📦 Instalace\n------------\n\nJednoduše nainstalujeme [Composerem](https://php.baraja.cz/composer):\n\n```shell\n$ composer require baraja-core/heureka-bidding-api\n```\n\nA následně stačí knihovnu použít.\n\nHlavní přednost této knihovny je jednoduché nasazení, přičemž nemá závislost na žádném frameworku a funguje plně automaticky.\n\n🛠️ Použití v základním PHP\n--------------------------\n\nPro vytvoření libovolného požadavku stačí vytvořit instanci služby `HeurekaApi`, předat `accessKey` a pokládat jednotlivé dotazy. Jako odpověď bude vždy typová entita.\n\nNapříklad chceme zjistit, kolik Heureka obsahuje kategorií:\n\n```php\n$api = new \\Baraja\\HeurekaBiddingApi\\HeurekaApi('vas-access-klic');\n\n$response = $api-\u003erun(\\Baraja\\HeurekaBiddingApi\\HeurekaApi::METHOD_CATEGORY_INDEX);\n\necho $response-\u003egetCount();\n```\n\nKonkrétní metody pro volání vám bude napovídat přímo váš editor.\n\n\u003e **POZOR:**\n\u003e\n\u003e Pro volání metod vždy používejte vyhrazené konstanty, které garantují kompatibilitu vaší aplikace s aktuální verzí API.\n\u003e\n\u003e Pokud Heureka API změní, v rámci tohoto balíku vyjde aktualizace (kterou instalujete příkazem `composer update`) a díky použití konstant bude balík stále kompatibilní.\n\nPoužití v Nette\n---------------\n\nKnihovna je dobře kompatibilní s Nette. Pro funkčnost stačí do vašeho projektového `common.neon` vložit tuto konfiguraci (nezapomeňte uvést váš `access klíč`):\n\n```yaml\nservices:\n   heurekaApi: Baraja\\HeurekaBiddingApi\\HeurekaApi('vas-access-klic')\n```\n\n⏫ Pokročilé volání\n-------------------\n\nPro pokročilé sestavení požadavku vždy využijte [oficiální dokumentaci](https://api.heureka.cz/bidding_api/v1/apidoc), přičemž se předávají 3 parametry:\n\nRequest vždy sestavujte přes metodu `run()`, která obsahuje pokročilé validace a mapování výstupu do entit.\n\n| Parametr | Povinný? | Vysvětlení |\n|----------|----------|------------|\n| `method` | ano      | Název API metody, kterou chceme volat. Například `category.index`. Hodnoty získáte v konstantách `METHOD_*`. |\n| `params` | ne       | Volitelné parametry jako array. Parametry se předávají do API a souvisí s konkrétní metodou. Před zavoláním API se vždy podívejte do dokumentace. Knihovna provádí základní validaci vstupních parametrů. |\n| `locale` | ne       | Pro jaké prostředí (jazyk) sestavit request? Výchozí hodnota je `cs` (čeština), akceptuje také `cz` (čeština). Pro slovenštinu `sk`. Jiné jazyky nejsou podporovány. |\n\nPro testování volání API lze poaždavek namířit také na jinou URL. Tyto URL je potřeba nejprve registrovat metodou `setCustomEndpoint(string $locale, string $endpoint)`, které předáme jazyk (například `cs`) a URL (`endpoint`). Vlastní přepisy URL adres mají při routingu vyšší prioritu, než výchozí konstanty. Přepis se provádí v metodě `resolveEndpoint()`, kterou můžete volně zavolat.\n\n🧪 Ošetření chyb\n----------------\n\nPokud při zpracování požadavku nastane jakákoli aplikační chyba, vyhazujeme výjimku `\\Baraja\\HeurekaBiddingApi\\HeurekaException`.\n\nV případě fatálního selhání (například parse error v odpovědi ze serveru) se vyhazuje interní `\\RuntimeException`, kterou bychom neměli zachytávat, ale nechat probublat až na jádro aplikace a tam zalogovat. Runtime chyby se při správné konfiguraci knihovny nebudou nikdy vyhazovat a slouží pouze pro debug.\n\n🔒 Access klíč\n--------------\n\nPro komunikaci s API potřebujete od Heureky získat API klíč. Použití je omezeno podle počtu požadavků a poté se platí. Základní klíč se mi podařilo získat od podpory zdarma e-mailem (pro účely testování), ale raději na to nespoléhejte.\n\nInformace z oficiální dokumentace:\n\n\u003e **Jak probíhá aktivace API?**\n\u003e\n\u003e Nejprve je potřeba potvrdit smlouvu na objednávku této služby, poté vám bude poskytnut přístup/token, dokumentace a další potřebné informace. Následně stačí implementovat API.\n\n👷‍♀️ Potíže s knihovnou a hlášení chyb\n---------------------------------------\n\nJedná se o neoficiální knihovnu, u které není garantována funkčnost na vašem prostředí. Knihovna se i tak snaží splnit co nejvíce obecné rozhraní, aby měla širokou podporu na většině prostředí.\n\nPro korektní funkčnost potřebujete mít `PHP 7.1` nebo novější ([jak zjistit verzi PHP?](https://php.baraja.cz/info)).\n\nPokud se domníváte, že všechno děláte správně a v knihovně je chyba, [nahlašte to založením nové issue](https://github.com/baraja-core/heureka-bidding-api/issues).\n\nKnihovnu vyvíjí [Jan Barášek](https://baraja.cz).\n\n📄 License\n-----------\n\n`baraja-core/heureka-bidding-api` is licensed under the MIT license. See the [LICENSE](https://github.com/baraja-core/heureka-bidding-api/blob/master/LICENSE) file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaraja-core%2Fheureka-bidding-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaraja-core%2Fheureka-bidding-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaraja-core%2Fheureka-bidding-api/lists"}