> For the complete documentation index, see [llms.txt](https://napoveda.rocketoo.cz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://napoveda.rocketoo.cz/rocketoo/rozsireni/rocketoo-api.md).

# Rocketoo API

Modul Rocketoo API umožňuje propojit e-shop s externími systémy – účetními programy, ERP, skladovými systémy nebo vlastními aplikacemi. Přes standardní REST rozhraní lze číst, vytvářet, upravovat a mazat data e-shopu v reálném čase.

Modul zajišťuje:

* REST API pro přístup k produktům, objednávkám, zákazníkům, dokladům a dalším datům
* Správu API klíčů s nastavitelnými oprávněními
* Log všech příchozích požadavků pro dohledatelnost
* Interaktivní dokumentaci endpointů (Swagger / OpenAPI)
* Ochranu přístupu pomocí rate limitingu

## Kde najdu modul?

V hlavním menu klikněte na **API**. Zobrazí se záložková nabídka:

* **API klíče** – vytváření a správa přístupových klíčů
* **Log requestů** – přehled všech příchozích požadavků
* **Nastavení** – zapnutí a vypnutí API

## Zprovoznění API

API je po instalaci modulu ve výchozím stavu **vypnuté**. Před prvním použitím je nutné ho zapnout.

### Jak zapnout API?

1. V menu klikněte na **API**
2. Přejděte do **Nastavení**
3. Zapněte přepínač **Povolit API**
4. Klikněte **Uložit**

{% hint style="warning" %}
**Upozornění:** Bez zapnutého API neodpoví žádný endpoint – každý požadavek obdrží chybu `400 Bad Request`.
{% endhint %}

### URL adresa API

Po zapnutí je API dostupné na adrese:

```
https://vas-eshop.cz/api/v1
```

Přesnou adresu s odkazem na dokumentaci najdete v sekci **Nastavení** přímo v administraci.

## API klíče

Každý systém nebo partner, který se k API připojuje, musí mít vlastní API klíč. Klíč identifikuje volajícího a určuje, ke kterým datům má přístup.

### Jak vytvořit nový API klíč?

1. V menu klikněte na **API → API klíče**
2. Klikněte na **Vytvořit API klíč**
3. Vyplňte formulář:
   * **Popis** – interní název pro identifikaci (např. „Pohoda účetnictví" nebo „Skladový systém")
   * **API klíč** – 128znakový klíč se automaticky vygeneruje; v případě potřeby ho zkopírujte a předejte partnerovi
4. Nastavte oprávnění pro jednotlivé skupiny endpointů
5. Klikněte **Vytvořit**

{% hint style="warning" %}
**Důležité:** API klíč se zobrazí a zkopírujete ho pouze při vytváření. Uložte ho na bezpečné místo – zpětně ho v administraci nelze zobrazit v plné délce.
{% endhint %}

### Úprava klíče

1. V seznamu klíčů klikněte na název klíče
2. Upravte popis nebo oprávnění
3. Klikněte **Uložit**

{% hint style="warning" %}
Samotný klíčový řetězec nelze zpětně změnit. Pokud klíč zkompromitujete, klíč smažte a vytvořte nový.
{% endhint %}

### Smazání klíče

1. V seznamu klíčů označte checkbox u daného klíče
2. V **Hromadné akce** vyberte **Smazat označené**
3. Potvrďte smazání

Po smazání klíče přestane okamžitě fungovat – požadavky s tímto klíčem obdrží chybu `403 Forbidden`.

### Přehled klíčů

V seznamu klíčů vidíte:

* **Popis** – interní název klíče
* **API klíč** – zkrácený výpis klíče (pro identifikaci)

## Oprávnění

Každý API klíč má pro každou skupinu endpointů nastaveno jedno ze tří oprávnění:

| Oprávnění         | Co dovoluje                                      |
| ----------------- | ------------------------------------------------ |
| **Zakázat**       | Přístup k dané skupině je zcela zablokován       |
| **Pouze čtení**   | Povoleny jsou výhradně GET požadavky (čtení dat) |
| **Čtení a zápis** | Povoleny jsou GET, POST, PUT i DELETE požadavky  |

### Skupiny endpointů

Oprávnění se nastavují pro tyto skupiny dat:

* **Zákazníci** – čtení a správa zákaznických účtů
* **Adresy** – doručovací a fakturační adresy zákazníků
* **Produkty** – katalog produktů
* **Varianty** – varianty produktů (barva, velikost…)
* **E-shop** – základní nastavení e-shopu
* **Objednávky** – přijímání a správa objednávek
* **Stavy objednávek** – číselník stavů objednávek
* **Faktury** – vydané faktury
* **Zálohové faktury** – proformy
* **Dobropisy** – dobropisové doklady
* **Dodací listy** – dodací listy k objednávkám
* **Platby** – způsoby platby
* **Doprava** – dopravní metody
* **Kategorie** – kategorie produktů
* **Příznaky** – příznaky produktů (např. Novinka, Sleva)
* **Skupiny** – skupiny zákazníků
* **Systém** – healthcheck a výpis dostupných endpointů

### Příklad nastavení oprávnění

**Účetní systém** – potřebuje číst objednávky a doklady, ale jinak nic neměnit:

* Objednávky: **Pouze čtení**
* Faktury: **Pouze čtení**
* Dobropisy: **Pouze čtení**
* Zálohové faktury: **Pouze čtení**
* Vše ostatní: **Zakázat**

**Skladový systém** – potřebuje aktualizovat zásoby a číst objednávky:

* Produkty: **Čtení a zápis**
* Varianty: **Čtení a zápis**
* Objednávky: **Pouze čtení**
* Vše ostatní: **Zakázat**

## Jak se připojit k API

Připojení k API probíhá pomocí standardních HTTP požadavků. V každém požadavku musíte uvést API klíč v hlavičce.

### Autentizace

Přidejte do každého požadavku HTTP hlavičku:

```
x-api-key: VÁŠ_API_KLÍČ
```

### Formát požadavků

Požadavky obsahující data v těle (POST, PUT) musí mít nastavenou hlavičku:

```
Content-Type: application/json
```

### Příklad požadavku

```
GET https://vas-eshop.cz/api/v1/order
x-api-key: abc123...
```

### Ověření připojení

Před prvním nasazením doporučujeme ověřit, zda API klíč a přípojení fungují pomocí healthcheck endpointu:

```
GET https://vas-eshop.cz/api/v1/healthcheck
```

Správná odpověď:

```json
{
  "status": "ok",
  "message": "Connection successful."
}
```

## Dostupné endpointy

Kompletní seznam dostupných endpointů pro váš e-shop zobrazíte dvěma způsoby:

### 1. Endpoint `/endpoint`

```
GET https://vas-eshop.cz/api/v1/endpoint
```

Vrátí JSON se seznamem všech endpointů a vaší úrovní přístupu ke každé skupině:

```json
{
  "endpoints": [
    {
      "service": "order",
      "paths": [
        { "method": "GET", "uri": "https://vas-eshop.cz/api/v1/order" },
        { "method": "POST", "uri": "https://vas-eshop.cz/api/v1/order" }
      ],
      "access": "read"
    }
  ],
  "documentation_link": "https://vas-eshop.cz/api/v1/docs"
}
```

### 2. Swagger dokumentace

Viz sekce [Dokumentace a Swagger](#dokumentace-a-swagger).

## Dokumentace a Swagger

Modul automaticky generuje interaktivní dokumentaci všech endpointů ve formátu OpenAPI (Swagger). Dokumentaci lze použít pro:

* Prohlížení dostupných endpointů a jejich parametrů
* Ruční testování požadavků přímo z prohlížeče
* Sdílení dokumentace s vývojáři partnerského systému

### Jak otevřít dokumentaci?

Dokumentace je dostupná na adrese:

```
https://vas-eshop.cz/api/v1/docs
```

Odkaz najdete také v administraci v sekci **Nastavení API**.

### Co v dokumentaci najdu?

* Přehled všech endpointů rozdělených do skupin
* HTTP metody každého endpointu (GET, POST, PUT, DELETE)
* Parametry požadavku a příklady hodnot
* Formát a příklady odpovědí
* Popis stavových kódů

## Log požadavků

Každý příchozí požadavek na API je automaticky zaznamenán do logu. Log slouží pro monitoring, ladění a dohledání chyb.

### Jak zobrazit log?

1. V menu klikněte na **API → Log requestů**
2. Zobrazí se seznam všech požadavků od nejnovějšího

### Co vidím v logu?

Každý záznam obsahuje:

<table data-search="false"><thead><tr><th>Sloupec</th><th>Popis</th></tr></thead><tbody><tr><td><strong>Datum</strong></td><td>Kdy byl požadavek přijat</td></tr><tr><td><strong>Metoda</strong></td><td>HTTP metoda (GET, POST, PUT, DELETE)</td></tr><tr><td><strong>URL</strong></td><td>Cesta endpointu (např. <code>/api/v1/order</code>)</td></tr><tr><td><strong>API klíč</strong></td><td>Který klíč požadavek odeslal</td></tr><tr><td><strong>Návratový kód</strong></td><td>Stavový kód odpovědi (200, 403, 500…)</td></tr><tr><td><strong>Trvání</strong></td><td>Doba zpracování v milisekundách</td></tr><tr><td><strong>Request</strong></td><td>Tělo odeslaného požadavku</td></tr></tbody></table>

### Filtrování logu

V levém panelu můžete záznamy filtrovat podle:

* **Metody** – GET, POST, PUT, DELETE
* **URL** – konkrétní endpoint
* **API klíče** – požadavky konkrétního klíče
* **Návratového kódu** – např. pouze chyby (4xx, 5xx)

### Tipy pro práci s logem

✅ Po nasazení nového napojení sledujte log prvních pár hodin – rychle odhalíte případné chyby\
✅ Chyba `403 Forbidden` v logu nejčastěji znamená chybějící oprávnění u daného API klíče\
✅ Vysoká hodnota **Trvání** (nad 2 000 ms) může signalizovat přetížení nebo pomalý dotaz\
❌ Log nelze mazat – slouží jako neměnný auditní záznam

## Stavové kódy a chybové odpovědi

API vrací standardní HTTP stavové kódy. Při každé chybě je v odpovědi také JSON se stručným popsem problému.

<table data-search="false"><thead><tr><th>Kód</th><th>Název</th><th>Kdy nastane</th></tr></thead><tbody><tr><td><strong>200</strong></td><td>OK</td><td>Požadavek proběhl úspěšně</td></tr><tr><td><strong>400</strong></td><td>Bad Request</td><td>API je vypnuto v nastavení</td></tr><tr><td><strong>401</strong></td><td>Unauthorized</td><td>Chybí hlavička <code>x-api-key</code></td></tr><tr><td><strong>403</strong></td><td>Forbidden</td><td>Neplatný API klíč, chybějící oprávnění nebo neplatný endpoint</td></tr><tr><td><strong>404</strong></td><td>Not Found</td><td>Špatná URL endpointu nebo neexistující záznam</td></tr><tr><td><strong>429</strong></td><td>Too Many Requests</td><td>Překročen limit počtu požadavků za minutu</td></tr><tr><td><strong>500</strong></td><td>Internal Server Error</td><td>Chyba na straně serveru</td></tr></tbody></table>

### Příklad chybové odpovědi

```json
{
  "status": "failed",
  "message": "API key is missing required permission 'order'."
}
```

### Nejčastější chyby a jejich řešení

**`400 Bad Request` – „Api function is not active"**\
→ Zapněte API v **Nastavení** modulu.

**`401 Unauthorized` – „Missing authorization header"**\
→ Přidejte hlavičku `x-api-key` do každého požadavku.

**`403 Forbidden` – „Request is not authorized or API key not found"**\
→ Zkontrolujte, zda klíč nebyl smazán a zda je správně zadán celý 128znakový řetězec.

**`403 Forbidden` – „API key is missing required permission"**\
→ Otevřete nastavení daného API klíče a přidejte potřebné oprávnění pro danou skupinu endpointů.

**`429 Too Many Requests`**\
→ Požadavky překračují výchozí limit 30 za minutu. Zpomalte frekvenci volání nebo kontaktujte správce.

## Stránkování výsledků

Endpointy vracející seznam záznamů (GET) vrací vždy maximálně **100 položek na stránku**. Pro načtení dalších stránek použijte parametr `page`.

### Parametr stránky

```
GET https://vas-eshop.cz/api/v1/order?page=2
```

### Odpověď se stránkováním

Každá odpověď se seznamem obsahuje objekt `pagination`:

```json
{
  "data": [ ... ],
  "pagination": {
    "current_page": 2,
    "current_page_items": 100,
    "total_pages": 5,
    "total_items": 487
  }
}
```

| Pole                 | Popis                             |
| -------------------- | --------------------------------- |
| `current_page`       | Aktuálně zobrazená stránka        |
| `current_page_items` | Počet záznamů na aktuální stránce |
| `total_pages`        | Celkový počet stránek             |
| `total_items`        | Celkový počet záznamů             |

### Procházení všech záznamů

Pro export kompletního seznamu procházejte stránky ve smyčce – načítejte stránky 1, 2, 3… dokud `current_page` nedosáhne `total_pages`.

## Limity a bezpečnost

### Rate limiting

Každý API klíč může odeslat maximálně **30 požadavků za minutu**. Při překročení limitu API vrátí odpověď `429 Too Many Requests` a informaci o tom, za kolik sekund je možné pokus zopakovat.

Limit se obnoví automaticky v průběhu dalšího intervalu – není třeba žádat o obnovení.

### Doporučení pro bezpečné použití

✅ Vytvořte pro každý systém nebo partnera **samostatný API klíč** s minimálními potřebnými oprávněními\
✅ Klíč nikdy nevkládejte přímo do zdrojového kódu aplikací – používejte proměnné prostředí\
✅ Při kompromitaci klíče ho okamžitě **smažte a vytvořte nový** – starý přestane fungovat okamžitě\
✅ Pravidelně procházejte log a kontrolujte neočekávané požadavky\
❌ Nesdílejte jeden klíč mezi více systémy – v případě problému nelze určit, kdo co volal\
❌ Nepřidávejte oprávnění „Čtení a zápis" tam, kde stačí „Pouze čtení"

## Často kladené otázky

### Obecné

**Q: Musím API zapínat znovu po každé aktualizaci modulu?**\
A: Ne. Nastavení se zachovává i po aktualizaci modulu.

**Q: Může mít e-shop více API klíčů najednou?**\
A: Ano, bez omezení. Každý systém nebo partner dostane vlastní klíč s vlastními oprávněními.

**Q: Jsou přenosy přes API šifrované?**\
A: Ano, pokud e-shop běží na HTTPS (což je výchozí stav). API klíč ani data se nepřenáší nešifrovaně.

**Q: Mohu API dočasně vypnout, aniž bych mazal klíče?**\
A: Ano. V **Nastavení** stačí vypnout přepínač **Povolit API**. Všechny klíče a log zůstanou zachovány a po opětovném zapnutí API bude vše fungovat jako dříve.

### API klíče

**Q: Zapomněl jsem API klíč. Mohu ho zjistit zpětně?**\
A: Ne, klíč je z bezpečnostních důvodů po vytvoření zobrazitelný jen jednou. Starý klíč smažte a vytvořte nový.

**Q: Co se stane s požadavky, když smažu API klíč?**\
A: Okamžitě začnou vracet chybu `403 Forbidden`. Propojení přestane fungovat.

**Q: Mohu jeden klíč použít pro více systémů?**\
A: Technicky ano, ale nedoporučujeme to. Při problému nebo úniku klíče nelze určit, který systém ho způsobil. Vytvořte pro každý systém vlastní klíč.

### Oprávnění

**Q: Jaký je rozdíl mezi „Pouze čtení" a „Čtení a zápis"?**\
A: Pouze čtení povoluje výhradně GET požadavky (načítání dat). Čtení a zápis navíc povoluje POST (vytvoření), PUT (úprava) a DELETE (smazání).

**Q: Mohu oprávnění kdykoli změnit?**\
A: Ano. Změna se projeví okamžitě při příštím požadavku.

**Q: Co se stane, když klíč nemá oprávnění k endpointu, který volá?**\
A: API vrátí `403 Forbidden` s popsem, které oprávnění chybí. Požadavek bude zaznamenán v logu.

### Log požadavků

**Q: Jak dlouho se uchovává log?**\
A: Záznamy se uchovávají trvale a nelze je smazat.

**Q: Vidím v logu požadavky všech API klíčů?**\
A: Ano, v logu jsou záznamy od všech klíčů. Pomocí filtru lze zobrazit záznamy konkrétního klíče.

**Q: Mohu exportovat log?**\
A: Log lze procházet a filtrovat v administraci. Přímý export do souboru není v základní verzi dostupný.

### Stránkování a limity

**Q: Mohu načíst více než 100 záznamů najednou?**\
A: Ne, maximum je 100 na stránku. Pro získání celého seznamu procházejte stránky postupně.

**Q: Co se stane, když překročím limit požadavků?**\
A: API vrátí `429 Too Many Requests` s informací, za kolik sekund lze zkusit znovu. Limit se obnoví automaticky.

**Q: Lze limit 30 požadavků za minutu zvýšit?**\
A: Limit je konfigurovatelný správcem serveru. Kontaktujte technickou podporu.

## Praktické příklady

### Příklad 1: Propojení s účetním systémem

Účetní systém potřebuje pravidelně stahovat nové objednávky a doklady.

1. **Vytvoření klíče:**
   * Vytvořte klíč s popisem „Pohoda – stahování objednávek"
   * Oprávnění: Objednávky → **Pouze čtení**, Faktury → **Pouze čtení**, Dobropisy → **Pouze čtení**, vše ostatní → **Zakázat**
2. **Ověření připojení:**
   * Zavolejte `GET /api/v1/healthcheck` – ověříte, že klíč funguje
3. **Stahování objednávek:**
   * `GET /api/v1/order` vrátí první stránku (100 objednávek)
   * Opakujte s parametrem `?page=2`, `?page=3`… až `total_pages`
4. **Monitoring:**
   * V logu sledujte, zda požadavky vrací `200 OK`

### Příklad 2: Aktualizace skladových zásob

Skladový systém po vyřízení objednávky aktualizuje zásoby variant.

1. **Vytvoření klíče:**
   * Popis: „WMS – skladový systém"
   * Oprávnění: Varianty → **Čtení a zápis**, Objednávky → **Pouze čtení**, vše ostatní → **Zakázat**
2. **Čtení aktuálního stavu:**
   * `GET /api/v1/variant/{id}` – načtení aktuální zásoby varianty
3. **Aktualizace zásoby:**
   * `PUT /api/v1/variant/{id}` s novým množstvím v těle požadavku

### Příklad 3: Kontrola propojení po výpadku

Po hlášeném výpadku propojení:

1. Otevřete **Log requestů**
2. Nastavte filtr na konkrétní API klíč a čas výpadku
3. Zkontrolujte stavové kódy:
   * `403 Forbidden` → klíč byl smazán nebo změněna oprávnění
   * `400 Bad Request` → API bylo dočasně vypnuto
   * `500 Internal Server Error` → chyba na straně e-shopu; kontaktujte podporu
4. Ověřte, zda je API zapnuto v **Nastavení**
5. Zkuste `GET /api/v1/healthcheck` – pokud vrátí `200 OK`, API funguje správně