Printhia API a agenti

Dokumentácia pre vývojárov a nákupných agentov, ktorí chcú čítať verejný katalóg Printhia. Nájdeš tu aktuálne produkty, varianty, ceny a dostupnosť.

Prístup a oprávnenia

Čítanie verejných produktov a vyhľadávanie nevyžaduje API kľúč, registráciu ani OAuth token. Tieto operácie sprístupňujú publikované údaje o produktoch. Prístup k administrácii, zákazníkom a správe objednávok vyžaduje samostatnú autorizovanú integráciu Shopify.

Prvý dotaz

Vyhľadaj produkt a jeho handle použi v adrese produktového JSON. Nasledujúce príkazy údaje iba čítajú.

curl -sS -G 'https://printhia.sk/search/suggest.json' -H 'Accept: application/json' --data-urlencode 'q=vaza' --data-urlencode 'resources[type]=product' --data-urlencode 'resources[limit]=5'
curl -sS -H 'Accept: application/json' 'https://printhia.sk/products/vaza-ondra.js'
curl -sS -H 'Accept: application/json' 'https://printhia.sk/cart.js'

GET /products/{handle}.js vracia produkt a najviac 250 variantov. Ceny sú celé čísla v najmenších menových jednotkách, preto hodnotu v EUR delíš číslom 100. Menu over v poli currency odpovede /cart.js v rovnakej relácii. Pri lokalizovaných stránkach používaj príslušný jazykový prefix a zachovaj kontext trhu.

Pred odporučením skontroluj cenu a dostupnosť konkrétneho variantu. Najnižšia cena produktu nemusí zodpovedať zvolenej veľkosti, materiálu či výbave. Konfigurátory litofánií a lámp môžu vyžadovať ďalšie voľby alebo fotografiu. Vtedy pošli zákazníka na produktovú stránku.

UCP a MCP

Shopify prevádzkuje UCP discovery a MCP endpoint POST /api/ucp/mcp. Podporované verzie a schémy čítaj z discovery odpovede. MCP inicializácia a zoznam nástrojov:

curl -sS 'https://printhia.sk/api/ucp/mcp' -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"catalog-reader","version":"1.0.0"}}}'
curl -sS 'https://printhia.sk/api/ucp/mcp' -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'
curl -sS 'https://printhia.sk/api/ucp/mcp' -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Nákupné volania UCP vyžadujú profil agenta podľa vstupných schém nástrojov. Úspešná inicializácia sama osebe neoveruje platbu ani dokončenie objednávky. Každá platba vyžaduje výslovný súhlas kupujúceho. Špecifikácia UCP opisuje profil a priebeh komunikácie.

Chyby a limity

Vyhľadávanie /search/suggest.json pri chýbajúcom alebo neplatnom parametri vracia HTTP 422 a JSON s poľami status, message a description. Pole description pomenuje chybný parameter. Doplň neprázdne q a pre produkty nastav resources[type]=product.

curl -sS -i 'https://printhia.sk/search/suggest.json?resources%5Btype%5D=product'
{"status":422,"message":"Invalid parameter error","description":"param is missing or the value is empty: q"}

HTTP 404: produkt alebo API adresa sa nenašli

Pri GET požiadavke dostaneš namiesto prázdnej alebo HTML 404 odpoveď vo formáte application/problem+json podľa RFC 9457. Platí to pre /products/{handle}.js vrátane jazykového prefixu a pre adresy /api mimo UCP. Hlavičku Accept môžeš vynechať alebo použiť application/json či application/problem+json. Explicitné odmietnutie JSON alebo vyššia priorita HTML sa rešpektujú. Kód not_found označuje nedostupný zdroj a pole resolution poradí ďalší krok. Existujúce neprázdne JSON chyby Shopify zachovávajú svoj formát.

curl -sS -i -H 'Accept: application/json' 'https://printhia.sk/products/__missing-example.js'

Najprv kontroluj HTTP status, až potom parsuj telo. Pri 404 vyhľadaj platný handle alebo použi sitemap. MCP vracia chyby v JSON-RPC poliach error.code, error.message a error.data. Pri 429 spomaľ požiadavky a rešpektuj hlavičku Retry-After, ak je prítomná.

Domovská stránka podporuje Accept: text/markdown a vracia Markdown s hlavičkami Content-Type: text/markdown a Vary: Accept. Neexistujúce stránky obchodu vracajú Markdown s HTTP 404 a odkazmi na dokumentáciu. Pre ostatné HTML stránky používaj Accept: text/html. Pokyny pre agentov nájdeš aj v /agents.md, /llms.txt a /llms-full.txt. Košík, pokladňa, zákaznícke účty a UCP zachovávajú správanie Shopify.

Testovanie a sandbox

Verejné GET požiadavky môžeš vyskúšať na aktuálnom katalógu. Printhia nemá samostatný sandbox na testovacie platby ani vlastnú registráciu API kľúčov. Na skúšanie všeobecných Shopify Storefront GraphQL dotazov slúži Mock Shop, samostatný ukážkový obchod s testovacími dátami.

Ďalšie podrobnosti: Shopify Product API a Predictive Search API.