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ů 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.
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
- Přihlaste se do administrace doplňku na shoptet.webotvurci.cz a v levém menu otevřete sekci API.
- Klikněte na Vytvořit.
- Vyplňte Název klíče (například „Produkční klíč“ nebo „Testovací klíč“), ať později poznáte, k čemu slouží.
- Volitelně nastavte Expiraci. Když ji nevyplníte, klíč platí, dokud ho nezastavíte nebo nesmažete.
- Klikněte na Vygenerovat klíč.

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.

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.

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:
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í
- 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.
- Založte modely přes
POST threed-models. Z odpovědi si uložteidkaždého modelu. - Přiřaďte je k produktům přes
POST products/threed-models, vždy jeden model pro Android a jeden pro iOS. - Ověřte výsledek přes
GET products/threed-modelsnebo 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.
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:
{
"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.
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:
{
"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.
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"
{
"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.
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"
{
"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_pageurčuje počet záznamů na stránku: 10 až 100, výchozí 50. Hodnota mimo rozsah se upraví na nejbližší povolenou.pageurčuje, kterou stránku chcete (od 1).- V odpovědi najdete objekt
paginator:current_page,last_page,per_pageatotal. Stránky procházejte, dokudcurrent_pagenedosáhnelast_page.
Limity
- 10 požadavků za minutu na jeden klíč. Při překročení API vrátí stav 429 a hlavičku
Retry-Afters 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):
{
"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
.usdzpro 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.
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.