+420 728 089 029EN

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

⏱ 9 min čtení

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

  1. Přihlaste se do administrace doplňku na shoptet.webotvurci.cz 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íč

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

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ů

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í

  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.

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_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):

{
  "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.

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.