# SpoolOS by Printhia API SpoolOS eviduje filamenty a skladové doklady pre 3D tlač. [OpenAPI](https://sklad.printhia.sk/openapi.json) obsahuje endpointy, typy, operationId, odpovede a oprávnenia API kľúčov. [HTML portál](https://sklad.printhia.sk/developers) obsahuje celý návod. ## Rýchly začiatok Verejný sandbox je bezplatný a iba na čítanie. Vracia dva vymyslené záznamy bez prístupu k databáze: ```sh curl -sS 'https://sklad.printhia.sk/api/sandbox/v1/stock?material=PLA' ``` Filtre: material, warehouse, below_threshold (true/false), limit (1 až 200). Zápis vráti 405. [API index](https://sklad.printhia.sk/api) je tiež verejný. ## Autentifikácia REST vyžaduje API kľúč a plán Pro alebo Business. Administrátor ho vytvorí v [nastaveniach API](https://sklad.printhia.sk/nastavenia/api). Kľúč uložte do SPOOLOS_API_KEY: ```sh curl -sS -H "Authorization: Bearer $SPOOLOS_API_KEY" 'https://sklad.printhia.sk/api/v1/stock?limit=10' ``` Pre tento request stačí oprávnenie filaments. Zápisy vyžadujú explicitný scope s :write. scopes=null povoľuje čítanie; prázdny zoznam nepovoľuje prístup k zdrojom. Čítanie dokladov má samostatné rozsahy prijemky:read, vydajky:read, uhrady:read a drafts:read. Pôvodné :write rozsahy naďalej povoľujú aj čítanie príslušného zdroja. ## OAuth a MCP MCP používa Streamable HTTP na https://sklad.printhia.sk/mcp a vyžaduje Business. Prijíma API kľúč alebo OAuth token. Klient objaví issuer cez [RFC 9728 metadata](https://sklad.printhia.sk/.well-known/oauth-protected-resource) a [authorization-server discovery](https://sklad.printhia.sk/.well-known/oauth-authorization-server). Druhý odkaz vracia priamo JSON dokument skutočného poskytovateľa Supabase; nemení jeho issuer ani endpointy. Zachovajte issuer, použite authorization code flow s PKCE S256 a overte state. OAuth identity scopes: openid, profile, email, offline_access. Požadujte iba potrebné. Nie sú to skladové permissions; prístup k operáciám určuje rola používateľa. REST OAuth tokeny neprijíma. Pri MCP posielajte Accept: application/json, text/event-stream. Po prihlásení použite initialize, tools/list a tools/call. [server.json](https://sklad.printhia.sk/server.json) opisuje transport podľa schémy MCP Registry. ## Bezpečné operácie ### Pracovné postupy cez MCP Sprievodca [Pripojiť AI](https://sklad.printhia.sk/nastavenia/mcp) obsahuje MCP URL, návody pre klientov a kontrolu pripojenia API kľúčom. Kontrola vykoná initialize, tools/list a get_stock. Prístup v externom OAuth klientovi overte reálnym volaním nástroja. - Dokúpenie: `low_stock_report` vráti položky označené ako low alebo empty. Vyžaduje `filaments`. - Materiál na zákazku: cez `find_filament` získajte presné ID, potom zavolajte `check_material_availability` s položkami `{ "filament_id": "UUID", "required_grams": 500 }`. Oba nástroje vyžadujú `filaments`. Požadované gramy musia pochádzať od používateľa alebo zo slicera. Server spočíta opakované ID, načíta skladové stavy vo všetkých skladoch organizácie a odpočíta aktívne rezervácie. Výstup obsahuje `sufficient`, `checked_at` a pri každej položke `shortfall_grams`. Ide o prehľad v danom čase, nevytvára rezerváciu. - Návrh príjemky: po potvrdení dodávateľa a položiek použite `create_prijemka` s `post: false` a rozsahom `drafts:write`. Vznikne čakajúci koncept. Používateľ ho schváli v aplikácii; agent ho nemá označovať za zaúčtovaný doklad. OAuth klienta odpojíte v nastaveniach účtu. Odpojenie zruší obnovovanie tokenov; MCP overuje aj platnosť relácie pri každej požiadavke. API kľúče sa rušia samostatne v nastaveniach API. Pred zápisom potvrďte zámer používateľa. Pre návrhy použite POST /api/v1/drafts. Schválenie dokladu prebieha v aplikácii. Pre opakované POST /api/v1/prijemky a /api/v1/vydajky používajte rovnaký UUID Idempotency-Key. Pri 409 skontrolujte existujúci záznam, automaticky nezapínajte force. REST chyby obsahujú error, code, message a resolution. Pri 429 dodržte Retry-After. Predvolený limit je 120 požiadaviek za minútu na kľúč a spoločný limit organizácie je 600. Kľúč môže mať vlastný limit. ## Verziovanie a ukončenie podpory API Aktívna verzia je /api/v1. Dátum jej ukončenia nie je stanovený. Nekompatibilné zmeny dostanú novú hlavnú verziu; neznáme voliteľné polia majú klienti ignorovať. Pred plánovaným odstránením podporovanej verzie oznámime zmenu najmenej **90 dní vopred**. [Politika ukončenia podpory](https://sklad.printhia.sk/developers#verziovanie) uvedie endpointy, náhradu, migračný postup a dátum ukončenia. Dotknuté odpovede dostanú Deprecation podľa RFC 9745 (dátum ako @ a unixové sekundy), Sunset podľa RFC 8594 (HTTP dátum v GMT) a Link s rel="deprecation". Aktívna v1 posiela odkaz na politiku. Hlavičky Deprecation a Sunset neposiela. ## Hlavičky limitov RateLimit-Policy uvádza politiku, kvótu q a okno w v sekundách. RateLimit uvádza skutočné zostávajúce požiadavky r a čas do obnovenia t v sekundách. Príklad: RateLimit-Policy: "api-key";q=120;w=60 a RateLimit: "api-key";r=43;t=27. Rozlišujeme source-ip (600/min pred autentifikáciou), api-key (štandardne 120/min) a organization (600/min). Pri 429 dodržte Retry-After. Formát používa aktuálny návrh IETF RateLimit header fields, zatiaľ nie publikované RFC. Ak počítadlo nie je dostupné, hlavička uvádza iba politiku bez odhadu zostávajúcej kvóty. ## CLI CLI [@printhia/spoolos-cli](https://www.npmjs.com/package/@printhia/spoolos-cli) vyžaduje Node.js 22 alebo novší: ```sh npm install -g @printhia/spoolos-cli spoolos --sandbox stock spoolos api spoolos stock --query material=PLA ``` Pri čítaní živého skladu nastavte SPOOLOS_API_KEY. CLI je iba na čítanie. Úspech vypíše JSON na stdout, chybu na stderr s nenulovým exit kódom. Bez globálnej inštalácie: `npx @printhia/spoolos-cli --sandbox stock`. Verzia 0.1.0 je dostupná aj ako [priamy download](https://sklad.printhia.sk/downloads/printhia-spoolos-cli-0.1.0.tgz). ## Účet a pomoc [Registrácia](https://sklad.printhia.sk/registracia) je samoobslužná. [Ukážka aplikácie](https://sklad.printhia.sk/vyskusaj) vyžaduje e-mail a overenie proti botom, nepovoľuje vytvorenie živých API kľúčov. Verejný sandbox vyššie nepotrebuje účet. Cenník zostáva na [domovskej stránke](https://sklad.printhia.sk/#pricing). Podpora: [obchod@printhia.sk](mailto:obchod@printhia.sk). [Kontakt](https://sklad.printhia.sk/contact), [ochrana údajov](https://sklad.printhia.sk/privacy), [pokyny pre agentov](https://sklad.printhia.sk/llms.txt).