{"openapi":"3.1.0","info":{"title":"Circly Public REST API","version":"1.0.0","description":"Oficiální veřejné rozhraní pro napojení e-shopů (Shoptet, WooCommerce), účetních systémů (Pohoda) a automatizačních nástrojů na půjčovní systém Circly.cz."},"servers":[{"url":"/api/v1","description":"Produkční API endpoint"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"circ_live_...","description":"Zadejte tajný API klíč půjčovny vygenerovaný v administraci Circly (Nastavení → Integrace → API klíče)."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"statusCode":{"type":"integer","example":400},"statusMessage":{"type":"string","example":"Bad Request"},"message":{"type":"string","example":"Popis chyby v češtině"}},"required":["statusCode","message"]},"EquipmentItem":{"type":"object","properties":{"id":{"type":"integer","example":42},"name":{"type":"string","example":"Vibrační deska 90 kg"},"category":{"type":"string","example":"Hutnicí technika"},"categoryId":{"type":"integer","nullable":true,"example":5},"inventoryCode":{"type":"string","example":"VD-001"},"serialNumber":{"type":"string","nullable":true,"example":"SN-987654"},"description":{"type":"string","nullable":true,"example":"Profesionální vibrační deska pro hutnění zeminy."},"dailyRate":{"type":"number","example":650},"deposit":{"type":"number","example":5000},"totalQuantity":{"type":"integer","example":3},"availableQuantity":{"type":"integer","example":2},"status":{"type":"string","enum":["available","rented","reserved","maintenance","retired"],"example":"available"},"accessories":{"type":"array","items":{"type":"string"},"example":["Tlumicí podložka","Pojezdová kola"]},"primaryImage":{"type":"string","nullable":true,"example":"https://circly.cz/media/equipment/vd-001.webp"}},"required":["id","name","category","inventoryCode","dailyRate","deposit","totalQuantity","status"]},"AvailabilityResponse":{"type":"object","properties":{"equipmentId":{"type":"integer","example":42},"name":{"type":"string","example":"Vibrační deska 90 kg"},"inventoryCode":{"type":"string","example":"VD-001"},"from":{"type":"string","example":"2026-12-01"},"to":{"type":"string","example":"2026-12-05"},"isAvailable":{"type":"boolean","example":true},"availableQuantity":{"type":"integer","example":2},"totalQuantity":{"type":"integer","example":3}},"required":["equipmentId","name","from","to","isAvailable","availableQuantity","totalQuantity"]},"Customer":{"type":"object","properties":{"id":{"type":"integer","example":101},"type":{"type":"string","enum":["individual","company"],"example":"individual"},"name":{"type":"string","example":"Jan Novák"},"phone":{"type":"string","example":"+420 777 123 456"},"email":{"type":"string","nullable":true,"example":"jan.novak@example.cz"},"address":{"type":"string","nullable":true,"example":"Dlouhá 15, Praha 1"},"idCardNumber":{"type":"string","nullable":true,"example":"204859123"},"ico":{"type":"string","nullable":true,"example":"12345678"},"dic":{"type":"string","nullable":true,"example":"CZ12345678"}},"required":["id","type","name","phone"]},"CreateRentalRequest":{"type":"object","properties":{"customerId":{"type":"integer","example":101},"startDate":{"type":"string","format":"date","example":"2026-12-01"},"expectedReturnDate":{"type":"string","format":"date","example":"2026-12-05"},"depositAmount":{"type":"number","example":5000},"notes":{"type":"string","example":"Rezervace z e-shopu Shoptet"},"items":{"type":"array","items":{"type":"object","properties":{"equipmentId":{"type":"integer","example":42},"quantity":{"type":"integer","example":1},"rentPrice":{"type":"number","example":2600}},"required":["equipmentId","rentPrice"]}}},"required":["customerId","startDate","expectedReturnDate","items"]},"RentalCreatedWebhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"event":{"type":"string","example":"rental.created"},"createdAt":{"type":"string","format":"date-time","example":"2026-11-10T14:30:00.000Z"},"organizationId":{"type":"integer","example":1},"data":{"type":"object","properties":{"rentalId":{"type":"integer","example":42},"rentalNumber":{"type":"string","example":"VYP-2026-00042"},"customerId":{"type":"integer","example":101},"customerName":{"type":"string","example":"Jan Novák"},"startDate":{"type":"string","example":"2026-12-01"},"expectedReturnDate":{"type":"string","example":"2026-12-05"},"status":{"type":"string","example":"reserved"},"totalPrice":{"type":"string","example":"2400.00"}},"required":["rentalId","rentalNumber","customerId","customerName","startDate","expectedReturnDate","status","totalPrice"]}},"required":["id","event","createdAt","organizationId","data"]},"RentalHandedOverWebhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"6ba7b810-9dad-11d1-80b4-00c04fd430c8"},"event":{"type":"string","example":"rental.handed_over"},"createdAt":{"type":"string","format":"date-time","example":"2026-12-01T08:15:00.000Z"},"organizationId":{"type":"integer","example":1},"data":{"type":"object","properties":{"rentalId":{"type":"integer","example":42},"rentalNumber":{"type":"string","example":"VYP-2026-00042"},"customerId":{"type":"integer","example":101},"customerName":{"type":"string","example":"Jan Novák"},"status":{"type":"string","example":"active"},"handedOverAt":{"type":"string","format":"date-time","example":"2026-12-01T08:15:00.000Z"}},"required":["rentalId","rentalNumber","customerId","customerName","status","handedOverAt"]}},"required":["id","event","createdAt","organizationId","data"]},"RentalReturnedWebhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"7ca7b810-9dad-11d1-80b4-00c04fd430c9"},"event":{"type":"string","example":"rental.returned"},"createdAt":{"type":"string","format":"date-time","example":"2026-12-05T16:45:00.000Z"},"organizationId":{"type":"integer","example":1},"data":{"type":"object","properties":{"rentalId":{"type":"integer","example":42},"rentalNumber":{"type":"string","example":"VYP-2026-00042"},"customerId":{"type":"integer","example":101},"customerName":{"type":"string","example":"Jan Novák"},"status":{"type":"string","example":"closed"},"actualReturnDate":{"type":"string","nullable":true,"example":"2026-12-05"},"returnedAt":{"type":"string","format":"date-time","example":"2026-12-05T16:45:00.000Z"}},"required":["rentalId","rentalNumber","customerId","customerName","status","returnedAt"]}},"required":["id","event","createdAt","organizationId","data"]},"RentalCancelledWebhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"8da7b810-9dad-11d1-80b4-00c04fd430ca"},"event":{"type":"string","example":"rental.cancelled"},"createdAt":{"type":"string","format":"date-time","example":"2026-11-20T10:00:00.000Z"},"organizationId":{"type":"integer","example":1},"data":{"type":"object","properties":{"rentalId":{"type":"integer","example":42},"rentalNumber":{"type":"string","example":"VYP-2026-00042"},"customerId":{"type":"integer","example":101},"customerName":{"type":"string","example":"Jan Novák"},"status":{"type":"string","example":"cancelled"},"cancellationReason":{"type":"string","nullable":true,"example":"Zrušeno zákazníkem z důvodu špatného počasí"}},"required":["rentalId","rentalNumber","customerId","customerName","status"]}},"required":["id","event","createdAt","organizationId","data"]},"CustomerCreatedWebhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"9ea7b810-9dad-11d1-80b4-00c04fd430cb"},"event":{"type":"string","example":"customer.created"},"createdAt":{"type":"string","format":"date-time","example":"2026-11-10T14:20:00.000Z"},"organizationId":{"type":"integer","example":1},"data":{"type":"object","properties":{"customerId":{"type":"integer","example":101},"name":{"type":"string","example":"Jan Novák"},"email":{"type":"string","nullable":true,"example":"jan.novak@example.cz"},"phone":{"type":"string","example":"+420 777 123 456"},"type":{"type":"string","enum":["individual","company"],"example":"individual"},"ico":{"type":"string","nullable":true,"example":null}},"required":["customerId","name","phone","type"]}},"required":["id","event","createdAt","organizationId","data"]},"EquipmentStatusChangedWebhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"af0e8400-e29b-41d4-a716-446655440099"},"event":{"type":"string","example":"equipment.status_changed"},"createdAt":{"type":"string","format":"date-time","example":"2026-11-10T15:00:00.000Z"},"organizationId":{"type":"integer","example":1},"data":{"type":"object","properties":{"equipmentId":{"type":"integer","example":42},"name":{"type":"string","example":"Vibrační deska 90 kg"},"inventoryCode":{"type":"string","example":"VD-001"},"previousStatus":{"type":"string","example":"available"},"newStatus":{"type":"string","enum":["available","rented","reserved","maintenance","retired"],"example":"maintenance"}},"required":["equipmentId","name","inventoryCode","previousStatus","newStatus"]}},"required":["id","event","createdAt","organizationId","data"]}}},"paths":{"/equipment":{"get":{"summary":"Katalog techniky a strojů","description":"Vrátí seznam techniky v inventáři dané půjčovny se sazbami, kaucemi a dostupností.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Číslo stránky"},{"name":"limit","in":"query","schema":{"type":"integer","default":50},"description":"Počet položek na stránku (max. 100)"},{"name":"categoryId","in":"query","schema":{"type":"integer"},"description":"Filtr dle ID kategorie"},{"name":"status","in":"query","schema":{"type":"string","enum":["available","rented","reserved","maintenance","retired"]},"description":"Filtr stavu"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Vyhledávání v názvu nebo kódu"}],"responses":{"200":{"description":"Úspěšný seznam techniky","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/EquipmentItem"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"description":"Neplatný nebo chybějící API klíč","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Překročen limit požadavků (60 req/min)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/equipment/{id}/availability":{"get":{"summary":"Ověření dostupnosti techniky v termínu","description":"Zkontroluje, zda je konkrétní stroj volný k zapůjčení v zadaném časovém rozmezí (od–do).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID položky techniky"},{"name":"from","in":"query","required":true,"schema":{"type":"string"},"description":"Datum začátku (např. 2026-12-01)"},{"name":"to","in":"query","required":true,"schema":{"type":"string"},"description":"Datum konce (např. 2026-12-05)"}],"responses":{"200":{"description":"Informace o dostupnosti v termínu","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/AvailabilityResponse"}}}}}},"404":{"description":"Položka techniky nebyla nalezena","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/customers":{"get":{"summary":"Vyhledání zákazníků","description":"Umožní najít zákazníka podle jména, IČO, telefonu nebo e-mailu.","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Hledaný výraz"},{"name":"type","in":"query","schema":{"type":"string","enum":["individual","company"]}}],"responses":{"200":{"description":"Seznam nalezených zákazníků","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}}}}}}}},"post":{"summary":"Založení nového zákazníka","description":"Vytvoří nového zákazníka (fyzickou osobu nebo firmu).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["individual","company"],"default":"individual"},"name":{"type":"string","example":"Petr Svoboda"},"phone":{"type":"string","example":"+420 608 123 456"},"email":{"type":"string","example":"petr@svoboda.cz"},"address":{"type":"string","example":"Nová 5, Brno"},"idCardNumber":{"type":"string","example":"123456789"}},"required":["type","name","phone"]}}}},"responses":{"200":{"description":"Zákazník úspěšně vytvořen"},"400":{"description":"Validační chyba ve vstupních datech"}}}},"/rentals":{"post":{"summary":"Vytvoření nové rezervace / výpůjčky","description":"Vytvoří v Circly novou rezervaci ze zadaného e-shopu nebo externí aplikace.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRentalRequest"}}}},"responses":{"200":{"description":"Rezervace úspěšně vytvořena"},"400":{"description":"Neplatná vstupní data"},"409":{"description":"Kolize v termínu (vybavení je v daném termínu vyčerpáno)"}}}}},"webhooks":{"ping":{"post":{"summary":"Testovací ping spojení","description":"Odesílá se při manuálním testu dostupnosti webhooku z administrace půjčovny.","requestBody":{"description":"Testovací zpráva pro ověření konektivity a HMAC SHA-256 podpisu","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"event":{"type":"string","example":"ping"},"createdAt":{"type":"string","format":"date-time","example":"2026-11-10T14:30:00.000Z"},"organizationId":{"type":"integer","example":1},"data":{"type":"object","properties":{"ping":{"type":"string","example":"pong"},"message":{"type":"string","example":"Testovací ověření spojení z Circly"}},"required":["ping","message"]}},"required":["id","event","createdAt","organizationId","data"]}}}},"responses":{"200":{"description":"Potvrzení o úspěšném přijetí testovacího pingu"}}}},"rental.created":{"post":{"summary":"Nová výpůjčka / rezervace","description":"Odesílá se bezprostředně po vytvoření nové rezervace výpůjčky přes webovou výlohu, administraci nebo veřejné REST API.","requestBody":{"description":"Notifikace o nově vytvořené výpůjčce","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalCreatedWebhook"}}}},"responses":{"200":{"description":"Potvrzení o úspěšném přijetí webhooku (očekává se HTTP 2xx do 3 sekund)"}}}},"rental.handed_over":{"post":{"summary":"Vydání techniky a podpis protokolu","description":"Odesílá se při fyzickém předání techniky zákazníkovi a podepsání předávacího protokolu.","requestBody":{"description":"Notifikace o výdeji techniky","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalHandedOverWebhook"}}}},"responses":{"200":{"description":"Potvrzení o úspěšném přijetí webhooku"}}}},"rental.returned":{"post":{"summary":"Vrácení techniky a vratkový protokol","description":"Odesílá se při vrácení techniky, zkontrolování stavu a finančním vyúčtování kauce.","requestBody":{"description":"Notifikace o vrácení výpůjčky","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalReturnedWebhook"}}}},"responses":{"200":{"description":"Potvrzení o úspěšném přijetí webhooku"}}}},"rental.cancelled":{"post":{"summary":"Zrušení / storno výpůjčky","description":"Odesílá se při stornování výpůjčky zákazníkem nebo personálem půjčovny.","requestBody":{"description":"Notifikace o stornování výpůjčky","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalCancelledWebhook"}}}},"responses":{"200":{"description":"Potvrzení o úspěšném přijetí webhooku"}}}},"customer.created":{"post":{"summary":"Založení nového zákazníka","description":"Odesílá se při registraci nebo ručním založení nového zákazníka v půjčovně.","requestBody":{"description":"Notifikace o vytvoření zákazníka","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCreatedWebhook"}}}},"responses":{"200":{"description":"Potvrzení o úspěšném přijetí webhooku"}}}},"equipment.status_changed":{"post":{"summary":"Změna stavu techniky (servis, vyřazení, dostupnost)","description":"Odesílá se při změně provozního stavu techniky (např. přesun do servisu, oprava, vyřazení z provozu).","requestBody":{"description":"Notifikace o změně stavu techniky","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentStatusChangedWebhook"}}}},"responses":{"200":{"description":"Potvrzení o úspěšném přijetí webhooku"}}}}}}