SpoolOS API od Printhia pre správu filamentu

Bezplatný sandbox: prvá požiadavka bez účtu

Verejný sandbox obsahuje dva vymyslené skladové záznamy. Je bezplatný, len na čítanie a nečíta databázu zákazníkov. Nepotrebuje API kľúč ani formulár. Otvoriť vzorové dáta v JSON.

curl -sS 'https://sklad.printhia.sk/api/sandbox/v1/stock?material=PLA'

Podporuje filtre material, warehouse, below_threshold a limit od 1 do 200. Zápis vráti HTTP 405. Prehľad dostupných rozhraní nájdete na /api, úplnú schému na /openapi.json.

Účet, API kľúče a OAuth

1. Vytvorte si účet cez registráciu. REST API vyžaduje plán Pro alebo Business, MCP vyžaduje Business.
2. Administrátor vytvorí kľúč v Nastavenia API. Vyberie oprávnenia, platnosť a limit požiadaviek. Celý kľúč sa zobrazí iba pri vytvorení.
3. Uložte ho do tajnej premennej prostredia SPOOLOS_API_KEY. Posielajte ho v hlavičke Authorization: Bearer.

curl -sS -H "Authorization: Bearer $SPOOLOS_API_KEY" \
  'https://sklad.printhia.sk/api/v1/stock?limit=10'

Ukážka aplikácie vytvorí dočasný ukážkový sklad po zadaní e-mailu a overení proti botom. Ukážkové účty nemôžu vytvárať živé API kľúče. Verejný sandbox vyššie je samostatná možnosť na skúšanie HTTP požiadaviek.

OAuth je dostupný pre MCP na https://sklad.printhia.sk/mcp. Klient použije RFC 9728 metadata, následne metadata autorizačného servera. Autorizačný server je Supabase; jeho pôvodný issuer zostáva zachovaný. Použite authorization code flow s PKCE S256, overte state a riaďte sa metadátami poskytovateľa. Prihlásenie a súhlas udeľuje používateľ.

OAuth scopes openid, profile, email a offline_access určujú identitu a obnovu tokenu. Žiadajte iba tie, ktoré klient potrebuje. Prístup k skladovým operáciám pri OAuth určuje rola používateľa. Resource permissions z tabuľky nižšie sú oprávnenia API kľúčov, nie vlastné OAuth scopes. REST API prijíma API kľúče; OAuth token patrí na MCP endpoint.

Oprávnenia a limity

Pre čítanie skladových zásob stačí kľúč s oprávnením filaments. Kľúč bez zoznamu oprávnení (scopes: null) má prístup na čítanie; zápis vyžaduje výslovne pridelené oprávnenie. Prázdny zoznam oprávnení nepovoľuje prístup k zdrojom.

Predvolený limit je 120 požiadaviek za minútu na kľúč; administrátor ho môže nastaviť. Organizácia má spoločný limit 600 požiadaviek za minútu. Pri HTTP 429 dodržte Retry-After. Doklady príjemiek a výdajok menia sklad: vyžiadajte súhlas používateľa a pri opakovaní používajte rovnaký Idempotency-Key. Pre návrh dokladu použite POST /api/v1/drafts; schválenie prebieha v aplikácii.

Každá spracovaná požiadavka REST API vracia RateLimit-Policy s kvótou q a oknom w v sekundách. RateLimit obsahuje skutočný zostávajúci počet požiadaviek r a čas do obnovenia t v sekundách. Rozlišujeme limity source-ip, api-key a organization. Pred autentifikáciou sa uplatňuje 600 požiadaviek za minútu na IP.

RateLimit-Policy: "api-key";q=120;w=60
RateLimit: "api-key";r=43;t=27

Príklad znamená 43 zostávajúcich požiadaviek a obnovenie okna o 27 sekúnd. Pri HTTP 429 má prednosť Retry-After. Formát vychádza z aktuálneho návrhu IETF RateLimit header fields, ktorý ešte nie je publikovaným RFC. Pri nedostupnom počítadle odpoveď obsahuje iba politiku. Verejný sandbox nečíta živé kvóty účtu.

MCP cez Streamable HTTP

Do klienta podporujúceho vzdialené MCP pridajte URL https://sklad.printhia.sk/mcp. Podporuje OAuth prihlásenie alebo API kľúč. Server po autentifikácii obsluhuje initialize, tools/list a tools/call. Klient musí posielať Accept: application/json, text/event-stream. HTTP 401 bez tokenu je očakávaná ochrana účtu.

Manifest server.json používa schému MCP Registry a uvádza vzdialený transport. Publikovanie súboru neznamená registráciu v centrálnom katalógu. Staršia adresa /api/mcp zostáva dostupná iba pre API kľúče.

Pripojenie AI a pracovné postupy

V nastaveniach otvorte Pripojiť AI. Sprievodca obsahuje adresu MCP servera, návody pre klientov, ukážkový sklad a kontrolu pripojenia API kľúčom.

• low_stock_report vráti podlimitné filamenty s oprávnením filaments.
• find_filament nájde ID. Následne check_material_availability prijme položky s filament_id a required_grams, spočíta ich a odpočíta platné rezervácie zo skladových stavov. Gramy zadajte podľa slicera alebo pokynu používateľa. Výsledok nič nerezervuje.
• create_prijemka s post: false a drafts:write vytvorí koncept na schválenie v aplikácii. Pred uložením potvrďte dodávateľa, položky a ceny.

OAuth klienta odpojíte v nastaveniach účtu. MCP pri každej požiadavke overuje platnosť relácie. API kľúč zrušíte samostatne v nastaveniach API. Podrobný postup pre agentov.

Verziovanie a ukončenie podpory API

Aktuálna verzia /api/v1 je aktívna a dátum jej ukončenia nie je stanovený. Zmeny, ktoré by porušili existujúce integrácie, vydáme pod novou hlavnou verziou. Pridanie voliteľného poľa nie je zmena hlavnej verzie; klient má neznáme polia ignorovať.

Pred plánovaným odstránením podporovanej verzie oznámime zmenu najmenej 90 dní vopred. Na tejto stránke zverejníme dotknuté endpointy, náhradnú verziu, migračný postup a presný dátum ukončenia. Dovtedy zostane oznámená verzia dostupná.

Dotknuté odpovede označíme hlavičkou Deprecation podľa RFC 9745 (znak @ a čas v unixových sekundách) a hlavičkou Sunset podľa RFC 8594 (HTTP dátum v GMT). Odkaz Link s rel="deprecation" vedie na túto politiku aj pred oznámením ukončenia. Aktívna v1 hlavičky Deprecation a Sunset neposiela.

Oficiálny CLI nástroj

CLI vyžaduje Node.js 22 alebo novší. Balík @printhia/spoolos-cli nainštalujete z npm registra. Podporuje čítanie v JSON.

npm install -g @printhia/spoolos-cli
spoolos --sandbox stock
spoolos api
spoolos stock --query material=PLA

Bez globálnej inštalácie použite npx @printhia/spoolos-cli --sandbox stock. Verziu 0.1.0 môžete tiež stiahnuť priamo.

Pri poslednom príkaze nastavte SPOOLOS_API_KEY. Ďalšie príkazy: filaments, suppliers, prijemky, vydajky, uhrady, drafts. Chyby idú na stderr a vracajú nenulový exit kód. CLI nevykonáva zápisy ani automatické opakovanie požiadaviek.

Chyby a bezpečné opakovanie

REST chyby majú JSON polia error, code, message a resolution. HTTP 401 znamená neplatné prihlásenie, 402 chýbajúci plán, 403 nedostatočné oprávnenie, 404 neexistujúci zdroj, 409 konflikt, 429 prekročený limit. Pri 409 skontrolujte existujúci doklad pred opakovaním. Pri príjemke nikdy automaticky nezapínajte force, ktoré obchádza kontrolu duplicity faktúry.

{ "error": "Požadovaný API endpoint neexistuje.", "code": "not_found",
  "message": "Požadovaný API endpoint neexistuje.",
  "resolution": "Skontrolujte cestu v /openapi.json a identifikátor zdroja vo svojej organizácii." }

Rozhranie pracuje s gramami a sumami v EUR. Pole spool_weight_g znamená kapacitu kotúča. Pre zásoby čítajte /api/v1/stock; hodnota skladu vychádza zo skladových vrstiev FIFO. Katalógový current_weight_g je zobrazovací údaj a neslúži na účtovné ocenenie.