{"openapi":"3.0.3","info":{"title":"Moduł wyliczenia materiałowego i kalkulacji komponentów dachu PV - API v1","version":"1.0.0","description":"Kontrakt referencyjny (demonstrator Softwise). Wejście: dane z modułu geolokalizacji / modelu 3D (obrys, połacie z wysokościami, linie charakterystyczne, przeszkody, wybrane produkty i układ). Wyjście do konfiguratora: zestawienie materiałów, lista cięć, projekt elektryczny, instrukcja montażu, sumy. Kontrakt jest przygotowany do dostosowania do specyfikacji API zamawiającego (nazwy pól, układy współrzędnych, autoryzacja). Dane produktowe przykładowe."},"servers":[{"url":"https://dach-pv.softwise.dev"}],"tags":[{"name":"Wyliczenia"},{"name":"Parametry"},{"name":"Produkty"}],"paths":{"/api/v1/calculations":{"post":{"tags":["Wyliczenia"],"summary":"Nowe wyliczenie (adres albo geometria 3D)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculationRequest"},"examples":{"adres":{"summary":"Tylko adres: obrys z OSM, dach z NMPT","value":{"location":{"address":"Michałowice, Raszyńska 23"},"products":{"topology":"mikrofalowniki"}}},"model3d":{"summary":"Połacie 3D z modułu geolokalizacji, przeszkoda (komin)","value":{"location":{"address":"Przykładowa 1, 00-001 Miejscowość","lat":52.2299,"lon":21.0122,"voivodeship":"mazowieckie","snowZone":2,"windZone":1},"building":{"eaveHeight":4.5,"footprint":{"type":"Polygon","crs":"EPSG:2180","coordinates":[[[637000,486000],[637012,486000],[637012,486009],[637000,486009],[637000,486000]]]}},"roof":{"planes":[{"id":"S","polygon":{"type":"Polygon","crs":"EPSG:2180","coordinates":[[[637000,486000,4.5],[637012,486000,4.5],[637012,486004.5,7.65],[637000,486004.5,7.65],[637000,486000,4.5]]]}},{"id":"N","polygon":{"type":"Polygon","crs":"EPSG:2180","coordinates":[[[637012,486009,4.5],[637000,486009,4.5],[637000,486004.5,7.65],[637012,486004.5,7.65],[637012,486009,4.5]]]}}],"keyLines":[{"type":"kalenica","length":12}],"obstacles":[{"type":"komin","clearance":0.3,"polygon":{"type":"Polygon","crs":"EPSG:2180","coordinates":[[[637003,486002],[637003.6,486002],[637003.6,486002.6],[637003,486002.6],[637003,486002]]]}}]},"products":{"covering":"blachodachowka","mountingSystem":"zintegrowany","module":"BPV-2M8","fillerModule":"BPV-1M4","topology":"mikrofalowniki"},"options":{"gutters":true,"snowGuards":true,"vatRate":23}}}}}}},"responses":{"201":{"description":"Utworzono wyliczenie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calculation"}}}},"400":{"description":"Błędne dane","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Adres nie znaleziony","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/calculations/{id}":{"get":{"tags":["Wyliczenia"],"summary":"Pełny wynik wyliczenia","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Wynik","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calculation"}}}},"404":{"description":"Brak wyliczenia"}}}},"/api/v1/calculations/{id}/bom":{"get":{"tags":["Wyliczenia"],"summary":"Zestawienie materiałów","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"BOM","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"bom":{"type":"array","items":{"$ref":"#/components/schemas/BomLine"}}}}}}}}}},"/api/v1/calculations/{id}/cut-list":{"get":{"tags":["Wyliczenia"],"summary":"Lista cięć profili AL (rozkrój sztang, obróbka)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Lista cięć"}}}},"/api/v1/calculations/{id}/electrical":{"get":{"tags":["Wyliczenia"],"summary":"Projekt elektryczny: łańcuchy lub grupy MLPE, trasy, zabezpieczenia","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Elektryka"}}}},"/api/v1/calculations/{id}/instruction":{"get":{"tags":["Wyliczenia"],"summary":"Instrukcja montażu: kroki z materiałami, narzędzia, lista pakowania, adres wersji do druku/PDF","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Instrukcja"}}}},"/api/v1/parameters":{"get":{"tags":["Parametry"],"summary":"Reguły obliczeń: wartości domyślne, jednostki, status, źródła","parameters":[{"name":"profile","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Reguły"}}},"put":{"tags":["Parametry"],"summary":"Zapis profilu nadpisań (reguły, produkty, MLPE, falowniki, profile)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Overrides"},"example":{"rules":{"gutter_hook_spacing_m":0.5,"saw_kerf_mm":3},"templates":{"BPV-2M8":{"elec":{"voc":22.4,"betaVoc":-0.29}}}}}}},"responses":{"201":{"description":"parametersProfileId"},"422":{"description":"Nieznana reguła lub wartość"}}}},"/api/v1/products":{"get":{"tags":["Produkty"],"summary":"Katalog: pokrycia, systemy montażu, elementy PV (schematy mikropaneli), MLPE, falowniki, profile","responses":{"200":{"description":"Katalog"}}}}},"components":{"schemas":{"GeoPolygon":{"type":"object","required":["type","coordinates"],"properties":{"type":{"type":"string","enum":["Polygon"]},"crs":{"type":"string","enum":["EPSG:4326","EPSG:2180"],"default":"EPSG:4326","description":"EPSG:4326: [lon, lat, z]; EPSG:2180: [x (wschód), y (północ), z]; z = wysokość nad terenem [m]"},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":3}}}}},"CalculationRequest":{"type":"object","required":["location"],"properties":{"location":{"type":"object","properties":{"address":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"voivodeship":{"type":"string"},"altitude":{"type":"number"},"snowZone":{"type":"integer","minimum":1,"maximum":5},"windZone":{"type":"integer","minimum":1,"maximum":3}}},"building":{"type":"object","properties":{"footprint":{"$ref":"#/components/schemas/GeoPolygon"},"eaveHeight":{"type":"number"},"height":{"type":"number"}}},"roof":{"type":"object","properties":{"type":{"type":"string","enum":["dwuspadowy","czterospadowy","jednospadowy","plaski"]},"pitch":{"type":"number"},"overhang":{"type":"number"},"planes":{"type":"array","description":"Połacie z wierzchołkami 3D; nachylenie, azymut i krawędzie (okap, kalenica, szczyt, naroże) wyliczane z geometrii","items":{"type":"object","required":["id","polygon"],"properties":{"id":{"type":"string"},"polygon":{"$ref":"#/components/schemas/GeoPolygon"},"pitch":{"type":"number"},"azimuth":{"type":"number"}}}},"keyLines":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["kalenica","okap","naroże","kosz","szczyt"]},"length":{"type":"number"},"line":{"type":"object"}}}},"obstacles":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["komin","okno","wyłaz","strefa_cienia","inne"]},"polygon":{"$ref":"#/components/schemas/GeoPolygon"},"clearance":{"type":"number","default":0.3}}}}}},"products":{"type":"object","properties":{"covering":{"type":"string","enum":["blachodachowka","rabek","istniejace"]},"mountingSystem":{"type":"string","enum":["zintegrowany","rabek_bipv","rabek","szyny","balast"]},"module":{"type":"string"},"fillerModule":{"type":"string","nullable":true},"topology":{"type":"string","enum":["string","optymalizatory","mikrofalowniki"]}}},"layout":{"type":"object","description":"Układ z konfiguratora; bez niego układ jest optymalizowany","properties":{"modules":{"type":"array","items":{"type":"object","required":["planeId","row","u","w"],"properties":{"planeId":{"type":"string"},"row":{"type":"integer"},"col":{"type":"integer"},"u":{"type":"number","description":"m od lewej krawędzi połaci wzdłuż okapu"},"w":{"type":"number","description":"m od okapu wzdłuż spadku"},"rotation":{"type":"integer","enum":[0,90]},"sku":{"type":"string"}}}}}},"options":{"type":"object","properties":{"gutters":{"type":"boolean"},"snowGuards":{"type":"boolean"},"vatRate":{"type":"number"},"enabledPlanes":{"type":"array","items":{"type":"string"}}}},"parameters":{"$ref":"#/components/schemas/Overrides"},"parametersProfileId":{"type":"string"},"energyYield":{"type":"boolean","default":false,"description":"Produkcja energii z PVGIS (wywołanie zewnętrzne)"}}},"Overrides":{"type":"object","properties":{"rules":{"type":"object","additionalProperties":{"type":"number"}},"templates":{"type":"object","additionalProperties":{"type":"object"}},"inverters":{"type":"object","additionalProperties":{"type":"object"}},"mlpe":{"type":"object","additionalProperties":{"type":"object"}},"profiles":{"type":"object","additionalProperties":{"type":"object"}}}},"BomLine":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"qty":{"type":"number"},"unit":{"type":"string"},"unitPrice":{"type":"number"},"net":{"type":"number"},"installStep":{"type":"string"}}},"Calculation":{"type":"object","properties":{"id":{"type":"string"},"apiVersion":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"location":{"type":"object"},"roof":{"type":"object","description":"Połacie (nachylenie, azymut, krawędzie), długości kalenicy/naroży/szczytów/okapów, złożoność"},"layout":{"type":"array","description":"Elementy PV per połać: sku, rząd, pozycja u/w, wymiary, obrót"},"bom":{"type":"array","items":{"$ref":"#/components/schemas/BomLine"}},"cutList":{"type":"array","description":"Per profil: sztangi, elementy z długością i obróbką, odpad, dolne ograniczenie"},"electrical":{"type":"object","description":"Topologia, falownik lub MLPE (z porównaniem kandydatów), grupy, łańcuchy, kable, zabezpieczenia"},"instruction":{"type":"object","description":"pdfUrl + kroki montażu z materiałami, kontrolami, narzędziami i listą pakowania"},"energy":{"type":"object"},"totals":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"links":{"type":"object"}}}}}}