# API pro AR zobrazovač: hromadné nahrání 3D modelů a přiřazení k produktům

> Napojte svůj systém na doplněk Rozšířená realita u produktů: vytvořte API klíč, nahrajte 3D modely přes URL a hromadně je přiřaďte k produktům.

- **Zdroj:** https://www.webotvurci.cz/navody/ar-zobrazovac-produkty-ve-3d/api-pro-3d-modely/
- **Doplněk / kategorie:** AR zobrazovač – produkty ve 3D (https://www.webotvurci.cz/navody/ar-zobrazovac-produkty-ve-3d/)
- **Datum:** 2026-11-17
- **Autor:** Webotvůrci (https://www.webotvurci.cz/)

---

Máte stovky produktů a 3D modely vám generuje vlastní systém, 3D studio nebo PIM? Nemusíte je do doplňku [Rozšířená realita u produktů](https://doplnky.shoptet.cz/rozsirena-realita-u-produktu) nahrávat ručně jeden po druhém. Doplněk má **API**, přes které váš systém modely založí a přiřadí k produktům sám — až 100 položek v jednom požadavku.

Tento návod je pro vývojáře, kteří napojení programují. Popisuje, jak získat API klíč, jaké endpointy API nabízí, co posílat a co se vrací. Základní nastavení doplňku (FTP, ruční nahrání modelů) najdete v [návodu k nastavení doplňku](https://www.webotvurci.cz/navody/ar-zobrazovac-produkty-ve-3d/rozsirena-realita-u-produktu-navod/).

## Co přes API uděláte

- **Založíte 3D modely**, které leží na vašem úložišti nebo CDN. API přijímá odkaz (URL) na hotový soubor, samotný soubor se přes API nenahrává.
- **Přiřadíte modely k produktům** podle GUID produktu ze Shoptetu.
- **Stáhnete seznam** modelů a produktů, které už model mají, například pro kontrolu nebo synchronizaci.

Mazání a přejmenování modelů zatím probíhá jen v administraci doplňku.

## Vytvoření API klíče

1. Přihlaste se do administrace doplňku na [shoptet.webotvurci.cz](https://shoptet.webotvurci.cz/login) a v levém menu otevřete sekci **API**.
2. Klikněte na **Vytvořit**.
3. Vyplňte **Název** klíče (například „Produkční klíč“ nebo „Testovací klíč“), ať později poznáte, k čemu slouží.
4. Volitelně nastavte **Expiraci**. Když ji nevyplníte, klíč platí, dokud ho nezastavíte nebo nesmažete.
5. Klikněte na **Vygenerovat klíč**.

![Formulář Vytvořit API klíč s poli Název a Expirace a tlačítkem Vygenerovat klíč](https://www.webotvurci.cz/uploads/navody/ar-api-vytvoreni-klice.png)

Nový klíč se zobrazí **jen jednou**, hned po vytvoření. Zkopírujte si ho tlačítkem **Kopírovat** a uložte na bezpečné místo (správce hesel, tajné proměnné vašeho serveru). Po opuštění stránky ho už nikde neuvidíte, uložen je jen jeho otisk. Když klíč ztratíte, vytvořte nový a starý smažte.

![Žlutý panel Nový API klíč se zakrytou hodnotou klíče, tlačítkem Kopírovat a upozorněním, že po opuštění stránky klíč nepůjde znovu zobrazit](https://www.webotvurci.cz/uploads/navody/ar-api-novy-klic.png)

V přehledu **Seznam klíčů** pak u každého klíče vidíte začátek jeho hodnoty, stav, expiraci a kdy byl naposledy použit. Tlačítkem pauzy klíč dočasně **zastavíte** (požadavky s ním vrátí chybu, dokud ho znovu nespustíte), ikonou koše ho **smažete**. Pod seznamem je stručná dokumentace API přímo v administraci.

![Stránka API v administraci doplňku: seznam klíčů se stavem Aktivní a pod ním dokumentace s hlavičkou X-Api-Key, základní URL a tabulkou endpointů](https://www.webotvurci.cz/uploads/navody/ar-api-prehled-klicu-a-dokumentace.png)

Pár pravidel ke klíčům:

- Klíč patří **jednomu e-shopu a jednomu doplňku**. S klíčem z jiného e-shopu nebo jiného doplňku API odpoví chybou.
- Na jeden e-shop a doplněk můžete mít nejvýš **10 klíčů**. Pro testování a produkci si vytvořte samostatné klíče.
- Klíč nikdy nedávejte do JavaScriptu na webu ani do veřejného repozitáře. Volejte API jen ze serveru.

## Základní URL a autentizace

Všechny endpointy mají společný základ:

```
https://shoptet.webotvurci.cz/api/{eshop_id}/ar-product-viewer/
```

Za `{eshop_id}` dosaďte číselné ID svého e-shopu v Shoptetu. Najdete ho v administraci doplňku v levém menu, ve výběru e-shopu před jeho názvem (například `#123456 vas-eshop.myshoptet.com` znamená ID `123456`). Klíč posílejte v hlavičce `X-Api-Key` u každého požadavku. Tělo požadavků i odpovědí je JSON, proto posílejte i hlavičky `Content-Type: application/json` a `Accept: application/json`:

```bash
curl https://shoptet.webotvurci.cz/api/123456/ar-product-viewer/threed-models \
  -H "X-Api-Key: wt-váš-api-klíč" \
  -H "Accept: application/json"
```

## Přehled endpointů

| Metoda | Endpoint | Co dělá |
|---|---|---|
| GET | `threed-models` | seznam 3D modelů e-shopu |
| POST | `threed-models` | založí jeden nebo více 3D modelů |
| GET | `products/threed-models` | seznam produktů, které mají přiřazený aspoň jeden model |
| POST | `products/threed-models` | přiřadí modely k produktům |

## Typický postup napojení

1. **Nahrajte soubory modelů** na své úložiště nebo CDN. Ke každému produktu potřebujete dva soubory: **.glb pro Android** a **.usdz pro iOS**. Tlačítko AR se u produktu zobrazí, jen když má oba.
2. **Založte modely** přes `POST threed-models`. Z odpovědi si uložte `id` každého modelu.
3. **Přiřaďte je k produktům** přes `POST products/threed-models`, vždy jeden model pro Android a jeden pro iOS.
4. **Ověřte výsledek** přes `GET products/threed-models` nebo přímo na produktové stránce e-shopu.

## Založení 3D modelů: POST threed-models

Založí 1 až 100 modelů najednou. Každá položka v poli `data` je jeden soubor pro jednu platformu.

```bash
curl -X POST https://shoptet.webotvurci.cz/api/123456/ar-product-viewer/threed-models \
  -H "X-Api-Key: wt-váš-api-klíč" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": [
      { "name": "Křeslo Oslo – Android", "platform": "android", "url": "https://cdn.example.com/modely/kreslo-oslo.glb" },
      { "name": "Křeslo Oslo – iOS", "platform": "ios", "url": "https://cdn.example.com/modely/kreslo-oslo.usdz" }
    ]
  }'
```

| Pole | Typ | Pravidla |
|---|---|---|
| `data` | pole | 1–100 položek |
| `data.*.name` | text | 3–255 znaků, **unikátní v rámci e-shopu** i v rámci jednoho požadavku |
| `data.*.platform` | text | `android` nebo `ios` |
| `data.*.url` | URL | veřejně dostupný odkaz na soubor; pro `android` musí končit na `.glb`, pro `ios` na `.usdz` (za příponou smí být parametry, např. `?v=2`) |

Protože jméno musí být unikátní, dejte do něj platformu (třeba „– Android“ a „– iOS“). Model se stejným jménem, jaké už v e-shopu existuje, API odmítne.

Soubory zůstávají na vaší adrese, doplněk je nikam nekopíruje. URL proto musí zůstat dostupná, dokud model na e-shopu používáte. Když soubor přesunete, model smažte v administraci a založte znovu s novou adresou.

Požadavek proběhne celý, nebo vůbec: když jedna položka neprojde kontrolou, nezaloží se žádná. Úspěšná odpověď má stav **201** a vrací založené modely i s jejich `id`:

```json
{
  "data": {
    "models": [
      {
        "id": "01jcxk6q8z3v7n2m4p5r6s7t8a",
        "name": "Křeslo Oslo – Android",
        "filename": "Xq3vT9bK2mPz7RwL4cYh8NdF1sGj5aEu.glb",
        "platform": "android",
        "external_url": "https://cdn.example.com/modely/kreslo-oslo.glb"
      },
      {
        "id": "01jcxk6q8z3v7n2m4p5r6s7t8b",
        "name": "Křeslo Oslo – iOS",
        "filename": "Hn6pW2kD9tRc4LvB7zMq1YsJ8fXa3GeK.usdz",
        "platform": "ios",
        "external_url": "https://cdn.example.com/modely/kreslo-oslo.usdz"
      }
    ]
  }
}
```

Hodnoty `id` a `filename` v ukázce jsou smyšlené. `filename` je interní název, který doplněk modelu přidělí; pro napojení ho nepotřebujete.

## Přiřazení modelů k produktům: POST products/threed-models

Přiřadí modely k 1 až 100 produktům najednou.

```bash
curl -X POST https://shoptet.webotvurci.cz/api/123456/ar-product-viewer/products/threed-models \
  -H "X-Api-Key: wt-váš-api-klíč" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": [
      {
        "product_guid": "0f3c9a5e-6b1d-11ee-9a2b-0cc47a6c9c84",
        "threed_model_ids": ["01jcxk6q8z3v7n2m4p5r6s7t8a", "01jcxk6q8z3v7n2m4p5r6s7t8b"]
      }
    ]
  }'
```

| Pole | Typ | Pravidla |
|---|---|---|
| `data` | pole | 1–100 položek |
| `data.*.product_guid` | text | GUID produktu ze Shoptetu; produkt musí být načtený v doplňku |
| `data.*.threed_model_ids` | pole | **přesně 2 ID**: jeden model pro Android a jeden pro iOS, oba z tohoto e-shopu |

Na co si dát pozor:

- **Přiřazení nahrazuje.** Co produkt měl přiřazeno dřív, se odebere a platí jen modely z požadavku. Stejný požadavek proto můžete bez obav poslat znovu.
- **GUID produktu** je identifikátor produktu ve Shoptetu (najdete ho třeba v Shoptet API nebo v exportu produktů). Podle kódu ani názvu produkt přes API nepřiřadíte.
- **Nový produkt nejdřív načtěte.** Doplněk zná jen produkty, které si ze Shoptetu stáhl. Když jste produkt přidali nedávno a API hlásí, že neexistuje, klikněte v administraci doplňku v sekci **Produkty** na **Obnovit produkty** a požadavek zopakujte.
- I tady platí „všechno, nebo nic“: když neprojde jediná položka, nepřiřadí se nic.

Úspěšná odpověď má stav **201** a vrací přijatá data:

```json
{
  "data": [
    {
      "product_guid": "0f3c9a5e-6b1d-11ee-9a2b-0cc47a6c9c84",
      "threed_model_ids": ["01jcxk6q8z3v7n2m4p5r6s7t8a", "01jcxk6q8z3v7n2m4p5r6s7t8b"]
    }
  ]
}
```

## Seznam 3D modelů: GET threed-models

Vrátí všechny modely e-shopu, po stránkách.

```bash
curl "https://shoptet.webotvurci.cz/api/123456/ar-product-viewer/threed-models?per_page=100&page=1" \
  -H "X-Api-Key: wt-váš-api-klíč" \
  -H "Accept: application/json"
```

```json
{
  "data": {
    "models": [
      {
        "id": "01jcxk6q8z3v7n2m4p5r6s7t8a",
        "name": "Křeslo Oslo – Android",
        "filename": "Xq3vT9bK2mPz7RwL4cYh8NdF1sGj5aEu.glb",
        "platform": "android",
        "external_url": "https://cdn.example.com/modely/kreslo-oslo.glb"
      }
    ],
    "paginator": {
      "current_page": 1,
      "last_page": 3,
      "per_page": 100,
      "total": 245
    }
  }
}
```

U modelů nahraných ručně v administraci (soubor přes FTP) je `external_url` prázdné (`null`).

## Seznam produktů s modely: GET products/threed-models

Vrátí jen produkty, které mají přiřazený aspoň jeden model, a u každého jeho modely.

```bash
curl "https://shoptet.webotvurci.cz/api/123456/ar-product-viewer/products/threed-models?per_page=50" \
  -H "X-Api-Key: wt-váš-api-klíč" \
  -H "Accept: application/json"
```

```json
{
  "data": {
    "products": [
      {
        "guid": "0f3c9a5e-6b1d-11ee-9a2b-0cc47a6c9c84",
        "code": "OSLO-01",
        "name": "Křeslo Oslo",
        "threed_models": [
          {
            "id": "01jcxk6q8z3v7n2m4p5r6s7t8a",
            "name": "Křeslo Oslo – Android",
            "filename": "Xq3vT9bK2mPz7RwL4cYh8NdF1sGj5aEu.glb",
            "platform": "android",
            "external_url": "https://cdn.example.com/modely/kreslo-oslo.glb"
          },
          {
            "id": "01jcxk6q8z3v7n2m4p5r6s7t8b",
            "name": "Křeslo Oslo – iOS",
            "filename": "Hn6pW2kD9tRc4LvB7zMq1YsJ8fXa3GeK.usdz",
            "platform": "ios",
            "external_url": "https://cdn.example.com/modely/kreslo-oslo.usdz"
          }
        ]
      }
    ],
    "paginator": {
      "current_page": 1,
      "last_page": 1,
      "per_page": 50,
      "total": 1
    }
  }
}
```

## Stránkování

Oba seznamy (GET) se vracejí po stránkách:

- `per_page` určuje počet záznamů na stránku: **10 až 100**, výchozí **50**. Hodnota mimo rozsah se upraví na nejbližší povolenou.
- `page` určuje, kterou stránku chcete (od 1).
- V odpovědi najdete objekt `paginator`: `current_page`, `last_page`, `per_page` a `total`. Stránky procházejte, dokud `current_page` nedosáhne `last_page`.

## Limity

- **10 požadavků za minutu na jeden klíč.** Při překročení API vrátí stav **429** a hlavičku `Retry-After` s počtem sekund, po kterých to můžete zkusit znovu.
- **10 neúspěšných pokusů o přihlášení za minutu z jedné IP adresy** (chybějící, neplatný nebo neaktivní klíč). Pak API dočasně odpovídá 429 i té IP adrese.
- **100 položek v jednom požadavku** u obou POST endpointů.

S těmito limity zpracujete až 1 000 položek za minutu, proto posílejte data v dávkách po 100 a mezi požadavky nespěchejte. Při odpovědi 429 počkejte, kolik říká `Retry-After`.

## Chybové odpovědi

| Stav | Kdy nastane | Zpráva v `message` |
|---|---|---|
| 401 | chybí hlavička `X-Api-Key` | `API key is required. Provide it via the X-Api-Key header.` |
| 401 | klíč neexistuje nebo je překlepnutý | `Invalid API key.` |
| 403 | klíč vypršel | `API key has expired.` |
| 403 | klíč je zastavený | `API key is inactive.` |
| 403 | klíč patří jinému e-shopu, než je v URL | `API key does not belong to this eshop.` |
| 403 | klíč patří jinému doplňku | `API key is not valid for this addon.` |
| 422 | data neprošla kontrolou | popis chyby, podrobnosti v `errors` |
| 429 | překročený limit požadavků | `Too many requests. Please try again later.` |

U chyby 422 najdete v poli `errors` přesně, která položka neprošla. Klíč odkazuje na pořadí položky v poli `data` (číslováno od nuly):

```json
{
  "message": "Vybraný produkt neexistuje. (and 1 more error)",
  "errors": {
    "data.0.product_guid": ["Vybraný produkt neexistuje."],
    "data.1.threed_model_ids": ["threed_model_ids musí obsahovat přesně jeden existující model pro Android a jeden existující model pro iOS."]
  }
}
```

Nejčastější příčiny chyby 422:

- **„URL musí mít příponu .glb pro platformu android“** (nebo `.usdz` pro iOS): platforma neodpovídá souboru.
- **Jméno modelu už je obsazené**: model se stejným jménem v e-shopu existuje, nebo se jméno opakuje v jednom požadavku.
- **„Vybraný produkt neexistuje.“**: GUID je chybný, nebo doplněk produkt ještě nenačetl (pomůže **Obnovit produkty**).
- **„threed_model_ids musí obsahovat přesně jeden…“**: posíláte dva modely stejné platformy, ID modelu z jiného e-shopu nebo ID, které neexistuje.

## Časté otázky

### Můžu přes API nahrát samotný soubor modelu?

Ne. API přijímá jen URL souboru, který už leží na vašem úložišti. Soubor nahraný přes FTP doplňku založíte ručně v administraci v sekci **3D modely**.

### Jak model přes API smažu nebo přejmenuji?

Zatím nijak. Model přejmenujete nebo smažete v administraci doplňku v sekci **3D modely**.

### Jak zjistím, které produkty ještě model nemají?

`GET products/threed-models` vrací jen produkty s modelem. Porovnejte ho se seznamem produktů ze svého systému nebo ze Shoptetu a zbytek doplňte.

### Funguje API i pro více e-shopů najednou?

Každý klíč platí pro jeden e-shop. Pro každý e-shop si v jeho administraci vytvořte vlastní klíč a v URL použijte jeho ID. Pro jednorázový přenos modelů mezi e-shopy je jednodušší [import a export](https://www.webotvurci.cz/navody/ar-zobrazovac-produkty-ve-3d/import-export-snadne-sireni-modelu-a-nastaveni/).

Potřebujete s napojením pomoct, nebo vám v API něco chybí? Napište nám, rádi poradíme. Více o doplňku najdete na stránce [AR zobrazovač – produkty ve 3D](https://www.webotvurci.cz/sluzby/shoptet/doplnky/ar-zobrazovac-produkty-ve-3d/).

---

*Návod pochází z webu Webotvůrci — Zlatý a Premium partner Shoptetu.*
*Všechny návody: https://www.webotvurci.cz/navody/ · Kontakt: jsme@webotvurci.cz*
