{ "openapi": "3.0.4", "info": { "title": "api.protank.bclogia.cz", "description": "", "version": "1.0" }, "paths": { "/api/v1/company/list": { "post": { "tags": [ "Companies" ], "summary": "Vrátí seznam firem (sídel i provozoven) po dávkách.", "description": "Firmy jsou seřazené podle verze záznamu (`row_version`). První dávku vyžádejte s prázdným `last_rv`,\r\ndo dalšího požadavku pošlete hodnotu `row_version` z posledního záznamu předchozí dávky.\r\nPrázdný seznam znamená, že další firmy už nejsou. Položka `count` udává celkový počet firem\r\nza zadaným `last_rv` včetně této dávky.\r\nVelikost dávky je 1 až 100, výchozí 20.", "requestBody": { "description": "Verze posledního načteného záznamu a velikost dávky.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRequestModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ListRequestModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ListRequestModel" } } } }, "responses": { "200": { "description": "Dávka firem; může být prázdná.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ListResponseModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ListResponseModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ListResponseModel" } } } }, "400": { "description": "Neplatný požadavek.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Chybí nebo je neplatný přístupový token.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "K této operaci nemáte oprávnění.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/company/read_batch": { "post": { "tags": [ "Companies" ], "summary": "Vrátí detail firem podle seznamu jejich ID.", "description": "Neexistující ID se ve výsledku neobjeví a opakovaná ID se zpracují jednou. Seznam smí obsahovat nejvýše 100 ID.", "requestBody": { "description": "Seznam ID firem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadBatchRequestModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ReadBatchRequestModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ReadBatchRequestModel" } } } }, "responses": { "200": { "description": "Nalezené firmy; může být prázdný seznam.", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerModel" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerModel" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerModel" } } } } }, "400": { "description": "Chybí seznam ID nebo obsahuje víc než 100 položek.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Chybí nebo je neplatný přístupový token.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "K této operaci nemáte oprávnění.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/version": { "get": { "tags": [ "Version" ], "summary": "Vrátí informace o verzi API.", "description": "Hodí se ke kontrole dostupnosti API a platnosti přístupového tokenu.", "responses": { "200": { "description": "Informace o verzi.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/SourceVersionInfo" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SourceVersionInfo" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SourceVersionInfo" } } } }, "401": { "description": "Chybí nebo je neplatný přístupový token.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "K této operaci nemáte oprávnění.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "CompanyType": { "enum": [ "unknown", "business_with_registration_number", "business_without_registration_number", "business_foreign_entity", "business_municipality", "non_business_citizen" ], "type": "string", "description": "Typ firmy (FirTypID). V JSON se přenáší jako text (název hodnoty v snake_case, např. business_with_registration_number)." }, "CustomerModel": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Číselné ID firmy", "format": "int32" }, "firma_typ": { "$ref": "#/components/schemas/CompanyType" }, "ic": { "maxLength": 14, "minLength": 0, "type": "string", "description": "IČ", "nullable": true }, "name": { "maxLength": 40, "minLength": 0, "type": "string", "description": "Název firmy", "nullable": true }, "additional_name": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Pokračování názvu firmy", "nullable": true }, "dic": { "maxLength": 15, "minLength": 0, "type": "string", "description": "DIČ", "nullable": true }, "amk": { "type": "integer", "description": "Kód adresního místa RUIAN", "format": "int32", "nullable": true }, "premises_number": { "type": "integer", "description": "Číslo provozovny (0 = sídlo, větší než 0 = provozovna)", "format": "int32", "nullable": true }, "city": { "type": "string", "description": "Město", "nullable": true }, "street": { "maxLength": 54, "minLength": 0, "type": "string", "description": "Ulice nebo část obce", "nullable": true }, "house_number": { "maxLength": 10, "minLength": 0, "type": "string", "description": "Číslo popisné / orientační / evidenční", "nullable": true }, "zip_code": { "maxLength": 6, "minLength": 0, "type": "string", "description": "PSČ", "nullable": true }, "state": { "maxLength": 3, "minLength": 0, "type": "string", "description": "Stát – třípísmenný kód ISO 3166-1 alpha-3 (např. CZE)", "nullable": true }, "delivery_city": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Doručovací adresa – město", "nullable": true }, "delivery_street_number": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Doručovací adresa – ulice nebo část obce a číslo popisné/orientační/evidenční", "nullable": true }, "delivery_zip_code": { "maxLength": 10, "minLength": 0, "type": "string", "description": "Doručovací adresa – PSČ", "nullable": true }, "delivery_state": { "maxLength": 100, "minLength": 0, "type": "string", "description": "Doručovací adresa – stát", "nullable": true }, "rc": { "maxLength": 11, "minLength": 0, "type": "string", "description": "Rodné číslo", "nullable": true }, "birth_date": { "type": "string", "description": "Datum narození", "format": "date", "nullable": true }, "icp": { "maxLength": 19, "minLength": 0, "type": "string", "description": "IČP", "nullable": true }, "icz": { "maxLength": 50, "minLength": 0, "type": "string", "description": "IČZ", "nullable": true }, "icob": { "maxLength": 30, "minLength": 0, "type": "string", "description": "IČOB", "nullable": true }, "orp": { "type": "string", "description": "Kód ORP", "nullable": true }, "zuj": { "type": "string", "description": "Kód ZUJ", "nullable": true }, "ts_ins": { "type": "string", "description": "Datum a čas založení záznamu", "format": "date-time", "nullable": true }, "ts": { "type": "string", "description": "Datum a čas poslední aktualizace", "format": "date-time", "nullable": true }, "parent_id": { "type": "integer", "description": "ID nadřízené firmy; prázdné, pokud firma nadřízenou nemá", "format": "int32", "nullable": true }, "row_version": { "type": "string", "description": "Verze záznamu (RowVersion); hodnotu z posledního záznamu dávky pošlete jako last_rv v dalším požadavku", "format": "byte", "nullable": true } }, "additionalProperties": false, "description": "Firma (sídlo nebo provozovna) v seznamu firem. Názvy v JSON vycházejí ze zadání pro Protank, převedené na snake_case bez diakritiky." }, "ListRequestModel": { "type": "object", "properties": { "last_rv": { "type": "string", "description": "Verze posledního načteného záznamu (RowVersion). Při prvním požadavku vynechte.", "format": "byte", "nullable": true }, "batch_size": { "type": "integer", "description": "Počet záznamů v dávce (1 až 100, výchozí 20)", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Požadavek na dávku seznamu firem." }, "ListResponseModel": { "type": "object", "properties": { "count": { "type": "integer", "description": "Celkový počet firem za zadanou verzí záznamu (last_rv), včetně této dávky", "format": "int32" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerModel" }, "description": "Firmy v této dávce, seřazené podle verze záznamu" } }, "additionalProperties": false, "description": "Odpověď s dávkou seznamu firem." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": { } }, "ReadBatchRequestModel": { "required": [ "ids" ], "type": "object", "properties": { "ids": { "maxItems": 100, "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Seznam ID firem, nejvýše 100 položek" } }, "additionalProperties": false, "description": "Požadavek na načtení firem podle seznamu ID." }, "SourceVersionInfo": { "type": "object", "properties": { "BuildNumber": { "type": "string", "description": "Číslo buildu (Git commit count)", "nullable": true }, "SourceHash": { "type": "string", "description": "SHA256 hash všech zdrojových souborů (plný)", "nullable": true }, "SourceHashShort": { "type": "string", "description": "SHA256 hash všech zdrojových souborů (zkrácený - prvních 12 znaků)", "nullable": true }, "GitCommitHash": { "type": "string", "description": "Git commit hash (pokud je dostupný)", "nullable": true }, "Version": { "type": "string", "description": "Verze ve formátu BuildNumber-SourceHash", "nullable": true }, "BuildDate": { "type": "string", "description": "Datum a čas buildu (UTC)", "nullable": true }, "FileCount": { "type": "integer", "description": "Počet souborů zahrnutých v hashi", "format": "int32", "nullable": true }, "PathCount": { "type": "integer", "description": "Počet adresářů zahrnutých v hashi", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Obsahuje informace o verzi buildu generované při kompilaci" } }, "securitySchemes": { "Bearer": { "type": "http", "description": "Authorization header using the Bearer scheme.", "scheme": "bearer", "bearerFormat": "JWT" } } }, "security": [ { "Bearer": [ ] } ] }