{ "openapi": "3.1.0", "info": { "title": "NEXO CRM API", "version": "1.0.0", "summary": "Strojový kontrakt NEXO Developer Platform.", "description": "OpenAPI 3.1 kontrakt vytvorený z rovnakého katalógu ako dokumentačná knižnica. Všetkých 216 operácií je aktívnych a každá uvádza požadovaný bezpečnostný režim.", "contact": { "name": "NEXO Developer Platform", "url": "https://api.nexocrm.sk/" } }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://api.nexocrm.sk", "description": "Produkčné API v1" } ], "tags": [ { "name": "Aktuálny principal" }, { "name": "Asynchrónne joby" }, { "name": "Audit a história" }, { "name": "Detail kontaktnej osoby" }, { "name": "Detail obchodného prípadu" }, { "name": "Detail projektu" }, { "name": "Doručenia" }, { "name": "E-mailové kampane" }, { "name": "E-mailové ponuky" }, { "name": "Fakturácia" }, { "name": "Hárky" }, { "name": "Import a export" }, { "name": "Import Center" }, { "name": "Kalendár a úlohy" }, { "name": "Katalóg udalostí" }, { "name": "Klienti" }, { "name": "Kontaktné osoby" }, { "name": "Leady" }, { "name": "Notifikácie" }, { "name": "Obchodné prípady" }, { "name": "Objednávky" }, { "name": "Obsah a metadáta" }, { "name": "Odbery" }, { "name": "Odoslanie" }, { "name": "Používatelia a tímy" }, { "name": "Prehľad aktivít" }, { "name": "Prepojenia na CRM" }, { "name": "Prílohy" }, { "name": "Procesy" }, { "name": "Produkty a cenníky" }, { "name": "Profilové médiá" }, { "name": "Projekty" }, { "name": "Publikované CRM tabuľky" }, { "name": "Publikum" }, { "name": "Riadky" }, { "name": "Schéma tabuľky" }, { "name": "Schémy a číselníky" }, { "name": "Sklad" }, { "name": "Súhlasy a supresie" }, { "name": "Synchronizácia" }, { "name": "Šablóny a obsah" }, { "name": "Štítky" }, { "name": "Terénne kampane" }, { "name": "Uložené pohľady" }, { "name": "Výsledky kampane" }, { "name": "Zdieľanie" }, { "name": "Značka" }, { "name": "Zoznamy a segmenty" } ], "paths": { "/v1/clients": { "get": { "operationId": "clients-list", "tags": [ "Klienti" ], "summary": "Zoznam klientov", "description": "Vráti klientov v povolenom owner scope. status_id, relationship_type_id, category_id, source_id a territory_id sú návrh v1 adaptéra nad pozorovanými tenantovými textovými hodnotami — nie tvrdenie, že CRM už používa natívne cudzie kľúče.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Fulltext v názve, kóde, IČO, e-mailoch a telefónoch.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Klienti viditeľní pod zvoleným vlastníkom.", "schema": { "type": "string" } }, { "name": "status_id", "in": "query", "required": false, "description": "Stabilné verejné ID mapované na pozorovanú tenantovú textovú hodnotu stavu.", "schema": { "type": "string" } }, { "name": "relationship_type_id", "in": "query", "required": false, "description": "Stabilné verejné ID mapované na pozorovanú textovú hodnotu vzťahu klienta.", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "required": false, "description": "Stabilné verejné ID mapované na pozorovanú textovú kategóriu klienta.", "schema": { "type": "string" } }, { "name": "source_id", "in": "query", "required": false, "description": "Stabilné verejné ID mapované na pozorovaný zdroj kontaktu.", "schema": { "type": "string" } }, { "name": "territory_id", "in": "query", "required": false, "description": "Stabilné verejné ID mapované na pozorované obchodné teritórium.", "schema": { "type": "string" } }, { "name": "registration_number", "in": "query", "required": false, "description": "Presne normalizované IČO.", "schema": { "type": "string" } }, { "name": "tag_id", "in": "query", "required": false, "description": "Klienti s priradeným štítkom podľa verejného opaque ID z GET /v1/tags.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Explicitne povolené radenie; prefix - znamená DESC.", "schema": { "type": "string", "format": "date" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "client_01J8Y6K2…", "type": "client", "attributes": { "code": "K-2026-00428", "name": "Ukážková spoločnosť s. r. o.", "person_type": "company", "status": { "id": "client_status_active", "label": "Aktívny" }, "category": { "id": "client_category_b2b", "label": "B2B" }, "source": { "id": "source_referral", "label": "Odporúčanie" }, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "registration_number": "12345678", "tag_ids": [ "tag_01J8Y6P7…" ], "updated_at": "2026-08-25T16:30:00Z", "revision": "rev_42" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "clients.read", "x-nexo-crm-permission": "clients.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "client.updated" }, "post": { "operationId": "clients-create", "tags": [ "Klienti" ], "summary": "Nový klient", "description": "Vytvorí firmu alebo fyzickú osobu s pozorovanými údajmi NEXO vrátane vlastníka, stavu, vzťahu, kategórie, zdroja, servisných poskytovateľov, viazaností a obchodného follow-upu. Verejné ID číselníkov a arrays emails/phones sú výslovne v1 adaptéry.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "description": "Navrhovaný stabilný identifikátor externého systému; vyžaduje samostatný mapovací register, nejde o potvrdený natívny stĺpec." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Iba polia označené v matici ako povinné alebo zapisovateľné a explicitne povolené gateway allowlistom.", "properties": { "emails": { "type": "array", "items": { "type": "string" }, "description": "Návrh pohodlného poľa nad dvoma pozorovanými e-mailovými stĺpcami; server ho mapuje bez rozšírenia natívnej kapacity." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Návrh pohodlného poľa nad dvoma pozorovanými telefónmi a ich typmi; server odmietne nepodporovaný počet." }, "service_profile": { "type": "object", "additionalProperties": true, "description": "Verejný objekt internet.provider/commitment, voice.provider/other_provider/commitment, television.provider/commitment a other.service/detail/commitment nad pozorovanými NEXO poľami. Vnútorné slovenské názvy stĺpcov nie sú verejný kontrakt." }, "sales_follow_up": { "type": "object", "additionalProperties": true, "description": "Verejný objekt verification_call_status, quote_sent a last_contact_at nad pozorovaným stavom verifikačného hovoru, odoslaním ponuky a dátumom posledného kontaktu." } } }, "relationships": { "type": "array", "items": { "type": "string" }, "description": "Povolené väzby na existujúce záznamy v rovnakom tenantovi." }, "tag_ids": { "type": "array", "items": { "type": "string" }, "description": "Verejné opaque ID existujúcich štítkov z GET /v1/tags; interné numerické ID ani neznáme názvy sa neprijímajú." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Aktívne zapisovateľné vlastné polia podľa publikovanej schémy a explicitného gateway allowlistu." } }, "required": [ "attributes" ] }, "example": { "external_id": "erp:client-42851", "attributes": { "name": "Ukážková spoločnosť s. r. o.", "person_type": "company", "owner_id": "user_01J8Y6…", "status_id": "client_status_active", "relationship_type_id": "client_relationship_customer", "category_id": "client_category_b2b", "source_id": "source_referral", "registration_number": "12345678", "tax_number": "2020000000", "vat_number": "SK2020000000", "vat_payer": true, "emails": [ { "type": "work", "value": "office@example.sk", "primary": true } ], "phones": [ { "type": "work", "value": "+421900000000", "primary": true } ], "website": "https://example.sk", "address": { "street": "Ukážková 1", "city": "Bratislava", "postal_code": "811 01", "country_code": "SK" }, "service_profile": { "internet": { "provider": "Ukážkový poskytovateľ", "commitment": "do 2027-06" }, "voice": { "provider": "Ukážkový poskytovateľ", "commitment": null }, "television": { "provider": null, "commitment": null }, "other": { "service": null, "detail": null, "commitment": null } }, "sales_follow_up": { "verification_call_status": "completed", "quote_sent": true, "last_contact_at": "2026-08-25T12:30:00Z" }, "note": "Partner pre ukážkovú integráciu." }, "tag_ids": [ "tag_01J8Y6P7…" ], "custom_fields": { "contract_tier": "standard" } } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "client_01J8Y6K2…", "type": "client", "attributes": { "code": "K-2026-00428", "name": "Ukážková spoločnosť s. r. o.", "person_type": "company", "status": { "id": "client_status_active", "label": "Aktívny" }, "category": { "id": "client_category_b2b", "label": "B2B" }, "source": { "id": "source_referral", "label": "Odporúčanie" }, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "registration_number": "12345678", "tag_ids": [ "tag_01J8Y6P7…" ], "updated_at": "2026-08-25T16:30:00Z", "revision": "rev_42" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "clients.write", "x-nexo-crm-permission": "clients.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "client.created" } }, "/v1/clients/{client_id}": { "get": { "operationId": "clients-detail", "tags": [ "Klienti" ], "summary": "Detail klienta", "description": "Vráti bezpečný detail pozorovaných klientskych polí. Verejné referencie, nepriehľadné ID a revision/ETag sú cieľový v1 kontrakt a vyžadujú gateway mapovanie.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "client_01J8Y6K2…", "type": "client", "attributes": { "code": "K-2026-00428", "name": "Ukážková spoločnosť s. r. o.", "person_type": "company", "status": { "id": "client_status_active", "label": "Aktívny" }, "category": { "id": "client_category_b2b", "label": "B2B" }, "source": { "id": "source_referral", "label": "Odporúčanie" }, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "registration_number": "12345678", "tag_ids": [ "tag_01J8Y6P7…" ], "updated_at": "2026-08-25T16:30:00Z", "revision": "rev_42" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "clients.read", "x-nexo-crm-permission": "clients.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "clients-update", "tags": [ "Klienti" ], "summary": "Upraviť klienta", "description": "Čiastočne upraví názov, vlastníka, stav, vzťah, zdroj, kategóriu, servisný profil, kontaktné údaje alebo poznámku. Arrays emails/phones sú limitovaný v1 adapter nad pevnými natívnymi stĺpcami; povinný If-Match je nový ochranný kontrakt gateway.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "description": "Navrhovaný stabilný identifikátor externého systému; vyžaduje samostatný mapovací register, nejde o potvrdený natívny stĺpec." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Iba polia označené v matici ako povinné alebo zapisovateľné a explicitne povolené gateway allowlistom.", "properties": { "emails": { "type": "array", "items": { "type": "string" }, "description": "Návrh pohodlného poľa nad dvoma pozorovanými e-mailovými stĺpcami; server ho mapuje bez rozšírenia natívnej kapacity." }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Návrh pohodlného poľa nad dvoma pozorovanými telefónmi a ich typmi; server odmietne nepodporovaný počet." }, "service_profile": { "type": "object", "additionalProperties": true, "description": "Verejný objekt internet.provider/commitment, voice.provider/other_provider/commitment, television.provider/commitment a other.service/detail/commitment nad pozorovanými NEXO poľami. Vnútorné slovenské názvy stĺpcov nie sú verejný kontrakt." }, "sales_follow_up": { "type": "object", "additionalProperties": true, "description": "Verejný objekt verification_call_status, quote_sent a last_contact_at nad pozorovaným stavom verifikačného hovoru, odoslaním ponuky a dátumom posledného kontaktu." } } }, "relationships": { "type": "array", "items": { "type": "string" }, "description": "Povolené väzby na existujúce záznamy v rovnakom tenantovi." }, "tag_ids": { "type": "array", "items": { "type": "string" }, "description": "Verejné opaque ID existujúcich štítkov z GET /v1/tags; interné numerické ID ani neznáme názvy sa neprijímajú." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Aktívne zapisovateľné vlastné polia podľa publikovanej schémy a explicitného gateway allowlistu." } }, "required": [ "attributes" ] }, "example": { "attributes": { "name": "Ukážková spoločnosť SK, s. r. o.", "owner_id": "user_01J8Y6…", "status_id": "client_status_active", "category_id": "client_category_key_account", "source_id": "source_referral", "service_profile": { "internet": { "provider": "Ukážkový poskytovateľ", "commitment": "do 2027-06" } }, "sales_follow_up": { "verification_call_status": "completed", "quote_sent": true, "last_contact_at": "2026-08-25T12:30:00Z" }, "note": "Aktualizované cez ERP integráciu." } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "client_01J8Y6K2…", "type": "client", "attributes": { "code": "K-2026-00428", "name": "Ukážková spoločnosť s. r. o.", "person_type": "company", "status": { "id": "client_status_active", "label": "Aktívny" }, "category": { "id": "client_category_b2b", "label": "B2B" }, "source": { "id": "source_referral", "label": "Odporúčanie" }, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "registration_number": "12345678", "tag_ids": [ "tag_01J8Y6P7…" ], "updated_at": "2026-08-25T16:30:00Z", "revision": "rev_42" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "clients.write", "x-nexo-crm-permission": "clients.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "client.updated" } }, "/v1/contacts": { "get": { "operationId": "contacts-list", "tags": [ "Kontaktné osoby" ], "summary": "Zoznam kontaktov", "description": "Vyhľadá kontaktné osoby podľa mena, klienta, vlastníka, kategórie, stavu alebo bezpečného typu kanála.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Fulltext v mene a povolených komunikačných kanáloch.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Kontakty s aktívnou väzbou na klienta.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Vlastník kontaktnej osoby.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Bežný lifecycle; anonymizované záznamy nie sú verejný filter.", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "required": false, "description": "Kategória kontaktnej osoby.", "schema": { "type": "string" } }, { "name": "language_code", "in": "query", "required": false, "description": "Preferovaný jazyk kontaktu.", "schema": { "type": "string" } }, { "name": "channel_type", "in": "query", "required": false, "description": "Kontakt obsahujúci aktívny e-mail, telefón, web alebo povolenú sociálnu sieť.", "schema": { "type": "string" } }, { "name": "tag_id", "in": "query", "required": false, "description": "Kontakt s priradeným štítkom podľa verejného opaque ID z GET /v1/tags.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Explicitne povolené radenie; prefix - znamená DESC.", "schema": { "type": "string", "format": "date" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "contact_01J8Y6K2…", "type": "contact", "attributes": { "display_name": "Ukážkové Meno", "first_name": "Ukážkové", "last_name": "Meno", "status": "active", "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "category": { "id": "contact_category_decision_maker", "label": "Rozhodovateľ" }, "language_code": "sk-SK", "communication_tone": "positive", "is_favorite": true, "tag_ids": [ "tag_01J8Y6Q8…" ], "updated_at": "2026-08-25T16:35:00Z", "revision": "rev_17" }, "relationships": { "primary_client": { "id": "client_01J8Y6…", "position_title": "Konateľ" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.read", "x-nexo-crm-permission": "contacts.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "contact.updated" }, "post": { "operationId": "contacts-create", "tags": [ "Kontaktné osoby" ], "summary": "Nový kontakt", "description": "Vytvorí kontaktnú osobu spolu s povolenou primárnou väzbou, kanálmi a adresou v jednej transakcii. Stav sa pri vytvorení nastaví serverom na active a nie je voľným vstupom.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "description": "Navrhovaná externá mapovacia referencia; nie potvrdený natívny stĺpec kontaktu." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Osobné polia, vlastník, kategória a jazyk podľa explicitného gateway allowlistu. status, communication_tone a is_favorite sa nastavia serverom a menia samostatnými akciami." }, "relationships": { "type": "array", "items": { "type": "string" }, "description": "Voliteľné počiatočné väzby na viditeľných klientov." }, "channels": { "type": "array", "items": { "type": "string" }, "description": "Voliteľné validované komunikačné kanály; label môže byť null." }, "addresses": { "type": "array", "items": { "type": "string" }, "description": "Voliteľné štruktúrované adresy." }, "tag_ids": { "type": "array", "items": { "type": "string" }, "description": "Verejné opaque ID existujúcich štítkov z GET /v1/tags; ďalšie zmeny používajú idempotentné tag endpointy." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Aktívne zapisovateľné polia publikovanej contact schémy a gateway allowlistu." } }, "required": [ "attributes" ] }, "example": { "external_id": "erp:contact-1708", "attributes": { "first_name": "Ukážkové", "last_name": "Meno", "owner_id": "user_01J8Y6…", "category_id": "contact_category_decision_maker", "language_code": "sk-SK", "salutation": "Dobrý deň" }, "relationships": [ { "client_id": "client_01J8Y6…", "position_title": "Konateľ", "department": "Vedenie", "buying_role": "decision_maker", "is_primary": true } ], "channels": [ { "type": "email", "label": "Pracovný e-mail", "value": "kontakt@example.sk", "is_primary": true }, { "type": "mobile", "label": "Mobil", "value": "+421900000000", "is_primary": true } ], "addresses": [ { "type": "work", "label": "Pracovisko", "street": "Ukážková 1", "city": "Bratislava", "postal_code": "811 01", "country_code": "SK", "is_primary": true } ], "tag_ids": [ "tag_01J8Y6Q8…" ] } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "contact_01J8Y6K2…", "type": "contact", "attributes": { "display_name": "Ukážkové Meno", "first_name": "Ukážkové", "last_name": "Meno", "status": "active", "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "category": { "id": "contact_category_decision_maker", "label": "Rozhodovateľ" }, "language_code": "sk-SK", "communication_tone": "positive", "is_favorite": true, "tag_ids": [ "tag_01J8Y6Q8…" ], "updated_at": "2026-08-25T16:35:00Z", "revision": "rev_17" }, "relationships": { "primary_client": { "id": "client_01J8Y6…", "position_title": "Konateľ" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.write", "x-nexo-crm-permission": "contacts.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "contact.created" } }, "/v1/contacts/{contact_id}": { "get": { "operationId": "contacts-detail", "tags": [ "Kontaktné osoby" ], "summary": "Detail kontaktu", "description": "Vráti pozorované osobné polia vrátane communication_tone a is_favorite a odkazy na samostatné kolekcie klientskych väzieb, kanálov, adries, poznámok a record links.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "contact_01J8Y6K2…", "type": "contact", "attributes": { "display_name": "Ukážkové Meno", "first_name": "Ukážkové", "last_name": "Meno", "status": "active", "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "category": { "id": "contact_category_decision_maker", "label": "Rozhodovateľ" }, "language_code": "sk-SK", "communication_tone": "positive", "is_favorite": true, "tag_ids": [ "tag_01J8Y6Q8…" ], "updated_at": "2026-08-25T16:35:00Z", "revision": "rev_17" }, "relationships": { "primary_client": { "id": "client_01J8Y6…", "position_title": "Konateľ" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.read", "x-nexo-crm-permission": "contacts.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "contacts-update", "tags": [ "Kontaktné osoby" ], "summary": "Upraviť kontakt", "description": "Upraví osobné polia, vlastníka, kategóriu, jazyk alebo poznámku. status, communication_tone ani is_favorite sa týmto PATCH nikdy nemenia; majú samostatné doménové akcie.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "description": "Navrhovaná externá mapovacia referencia; nie potvrdený natívny stĺpec kontaktu." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Iba osobné polia, vlastník, kategória, jazyk a poznámka. status, communication_tone, is_favorite, relationships, channels a addresses sa na tejto ceste odmietnu." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Iba publikované a gateway-allowlisted vlastné polia kontaktu." } }, "required": [ "attributes" ] }, "example": { "attributes": { "title_before": "Ing.", "first_name": "Ukážkové", "last_name": "Meno", "owner_id": "user_01J8Y6…", "category_id": "contact_category_decision_maker", "language_code": "sk-SK" } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "contact_01J8Y6K2…", "type": "contact", "attributes": { "display_name": "Ukážkové Meno", "first_name": "Ukážkové", "last_name": "Meno", "status": "active", "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "category": { "id": "contact_category_decision_maker", "label": "Rozhodovateľ" }, "language_code": "sk-SK", "communication_tone": "positive", "is_favorite": true, "tag_ids": [ "tag_01J8Y6Q8…" ], "updated_at": "2026-08-25T16:35:00Z", "revision": "rev_17" }, "relationships": { "primary_client": { "id": "client_01J8Y6…", "position_title": "Konateľ" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.write", "x-nexo-crm-permission": "contacts.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "contact.updated" } }, "/v1/contacts/{contact_id}/communication-tone": { "patch": { "operationId": "contacts-communication-tone", "tags": [ "Kontaktné osoby" ], "summary": "Zmeniť tón komunikácie", "description": "Samostatná v1 cesta nad pozorovanou setCommunicationTone akciou. Validuje presný enum, row visibility a oprávnenie bez otvorenia všeobecného PATCH poľa.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "communication_tone": { "type": "string", "description": "Cieľový pozorovaný tón komunikácie." } }, "required": [ "communication_tone" ] }, "example": { "communication_tone": "positive" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "contact_01J8Y6K2…", "type": "contact", "attributes": { "display_name": "Ukážkové Meno", "first_name": "Ukážkové", "last_name": "Meno", "status": "active", "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "category": { "id": "contact_category_decision_maker", "label": "Rozhodovateľ" }, "language_code": "sk-SK", "communication_tone": "positive", "is_favorite": true, "tag_ids": [ "tag_01J8Y6Q8…" ], "updated_at": "2026-08-25T16:35:00Z", "revision": "rev_17" }, "relationships": { "primary_client": { "id": "client_01J8Y6…", "position_title": "Konateľ" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.write", "x-nexo-crm-permission": "contacts.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "contact.communication_tone_changed" } }, "/v1/contacts/{contact_id}/favorite": { "put": { "operationId": "contacts-favorite", "tags": [ "Kontaktné osoby" ], "summary": "Nastaviť obľúbený kontakt", "description": "Idempotentná v1 cesta nad pozorovanou setFavorite akciou nastaví alebo zruší obľúbenosť bez zmeny ostatných polí kontaktu.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "is_favorite": { "type": "boolean", "description": "true označí kontakt ako obľúbený, false označenie zruší." } }, "required": [ "is_favorite" ] }, "example": { "is_favorite": true } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "contact_01J8Y6K2…", "type": "contact", "attributes": { "display_name": "Ukážkové Meno", "first_name": "Ukážkové", "last_name": "Meno", "status": "active", "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "category": { "id": "contact_category_decision_maker", "label": "Rozhodovateľ" }, "language_code": "sk-SK", "communication_tone": "positive", "is_favorite": true, "tag_ids": [ "tag_01J8Y6Q8…" ], "updated_at": "2026-08-25T16:35:00Z", "revision": "rev_17" }, "relationships": { "primary_client": { "id": "client_01J8Y6…", "position_title": "Konateľ" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.write", "x-nexo-crm-permission": "contacts.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "contact.favorite_changed" } }, "/v1/contacts/{contact_id}/invalidate": { "post": { "operationId": "contacts-deactivate", "tags": [ "Kontaktné osoby" ], "summary": "Deaktivovať kontakt", "description": "V1 projekcia pozorovaného doménového invalidate príkazu nastaví kontakt na inactive, zachová väzby aj audit a vyžaduje Idempotency-Key. Nejde o DELETE.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "description": "Auditovateľný dôvod deaktivácie." }, "note": { "type": "string", "description": "Voliteľná interná poznámka." } } }, "example": { "reason": "Kontakt už nie je aktívny", "note": "Overené správcom adresára." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "contact_01J8Y6K2…", "type": "contact", "attributes": { "display_name": "Ukážkové Meno", "first_name": "Ukážkové", "last_name": "Meno", "status": "active", "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "category": { "id": "contact_category_decision_maker", "label": "Rozhodovateľ" }, "language_code": "sk-SK", "communication_tone": "positive", "is_favorite": true, "tag_ids": [ "tag_01J8Y6Q8…" ], "updated_at": "2026-08-25T16:35:00Z", "revision": "rev_17" }, "relationships": { "primary_client": { "id": "client_01J8Y6…", "position_title": "Konateľ" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.status", "x-nexo-crm-permission": "contacts.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "contact.invalidated" } }, "/v1/contacts/{contact_id}/restore": { "post": { "operationId": "contacts-restore", "tags": [ "Kontaktné osoby" ], "summary": "Obnoviť kontakt", "description": "V1 projekcia pozorovaného restore príkazu obnoví inactive kontakt na active po opätovnej kontrole oprávnenia a viditeľnosti; anonymizovaný kontakt obnoviť nemožno.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "note": { "type": "string", "description": "Voliteľná auditná poznámka." } } }, "example": { "note": "Kontakt bol znovu potvrdený klientom." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "contact_01J8Y6K2…", "type": "contact", "attributes": { "display_name": "Ukážkové Meno", "first_name": "Ukážkové", "last_name": "Meno", "status": "active", "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "category": { "id": "contact_category_decision_maker", "label": "Rozhodovateľ" }, "language_code": "sk-SK", "communication_tone": "positive", "is_favorite": true, "tag_ids": [ "tag_01J8Y6Q8…" ], "updated_at": "2026-08-25T16:35:00Z", "revision": "rev_17" }, "relationships": { "primary_client": { "id": "client_01J8Y6…", "position_title": "Konateľ" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.status", "x-nexo-crm-permission": "contacts.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "contact.restored" } }, "/v1/contacts/{contact_id}/anonymize": { "post": { "operationId": "contacts-anonymize", "tags": [ "Kontaktné osoby" ], "summary": "Anonymizovať kontakt", "description": "Samostatný nezvratný príkaz po retention a právnej kontrole odstráni alebo nahradí osobné údaje, zachová povinný audit a nikdy sa nevystaví ako PATCH či DELETE. Vyžaduje samostatné oprávnenie, If-Match a Idempotency-Key.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "description": "Kategória právneho alebo retenčného dôvodu." }, "confirmation": { "type": "string", "description": "Explicitná ochrana pred náhodným spustením." }, "note": { "type": "string", "description": "Auditná poznámka bez kopírovania osobných údajov." } }, "required": [ "reason", "confirmation" ] }, "example": { "reason": "data_subject_request", "confirmation": "ANONYMIZE", "note": "Schválené oprávnenou rolou po retenčnej kontrole." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "contacts.anonymize", "x-nexo-crm-permission": "contacts.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "contact.anonymized" } }, "/v1/contacts/{contact_id}/relationships": { "get": { "operationId": "contacts-relationships-list", "tags": [ "Detail kontaktnej osoby" ], "summary": "Väzby na klientov", "description": "Vráti aktívne väzby kontaktu na klientov vrátane pozície, oddelenia, nákupnej roly a primárnosti.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.read", "x-nexo-crm-permission": "contacts.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "contacts-relationships-create", "tags": [ "Detail kontaktnej osoby" ], "summary": "Pridať väzbu na klienta", "description": "Pridá auditovateľnú väzbu na viditeľného klienta; nová primárna väzba atómovo zruší predchádzajúcu primárnosť.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "client_id": { "type": "string", "description": "Viditeľný klient v rovnakom tenantovi." }, "position_title": { "type": "string", "description": "Pozícia kontaktu u klienta." }, "department": { "type": "string", "description": "Oddelenie." }, "buying_role": { "type": "string", "description": "Nákupná alebo rozhodovacia rola." }, "note": { "type": "string", "description": "Poznámka platná iba pre túto väzbu." }, "is_primary": { "type": "boolean", "description": "Najviac jedna aktívna primárna väzba." }, "is_active": { "type": "boolean", "description": "Deaktivácia zachová audit namiesto mazania." }, "sort_order": { "type": "integer", "format": "int32", "description": "Stabilné poradie vo výpise." } }, "required": [ "client_id" ] }, "example": { "client_id": "client_01J8Y6…", "position_title": "Konateľ", "department": "Vedenie", "buying_role": "decision_maker", "is_primary": true, "is_active": true, "sort_order": 0 } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.relationships.write", "x-nexo-crm-permission": "contacts.edit_relationships", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "contact.relationship_added" } }, "/v1/contacts/{contact_id}/relationships/{relationship_id}": { "patch": { "operationId": "contacts-relationships-update", "tags": [ "Detail kontaktnej osoby" ], "summary": "Upraviť väzbu na klienta", "description": "Upraví pozíciu, oddelenie, rolu, poznámku, poradie alebo aktivitu väzby. Deaktivácia zachová históriu.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "relationship_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "client_id": { "type": "string", "description": "Viditeľný klient v rovnakom tenantovi." }, "position_title": { "type": "string", "description": "Pozícia kontaktu u klienta." }, "department": { "type": "string", "description": "Oddelenie." }, "buying_role": { "type": "string", "description": "Nákupná alebo rozhodovacia rola." }, "note": { "type": "string", "description": "Poznámka platná iba pre túto väzbu." }, "is_primary": { "type": "boolean", "description": "Najviac jedna aktívna primárna väzba." }, "is_active": { "type": "boolean", "description": "Deaktivácia zachová audit namiesto mazania." }, "sort_order": { "type": "integer", "format": "int32", "description": "Stabilné poradie vo výpise." } } }, "example": { "position_title": "Obchodný riaditeľ", "department": "Obchod", "buying_role": "economic_buyer", "is_primary": true, "is_active": true } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.relationships.write", "x-nexo-crm-permission": "contacts.edit_relationships", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "contact.relationship_updated" } }, "/v1/contacts/{contact_id}/channels": { "get": { "operationId": "contacts-channels-list", "tags": [ "Detail kontaktnej osoby" ], "summary": "Komunikačné kanály", "description": "Vráti iba kanály, ktoré môže principal vidieť podľa explicitného allowlistu API gateway.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.read", "x-nexo-crm-permission": "contacts.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "contacts-channels-create", "tags": [ "Detail kontaktnej osoby" ], "summary": "Pridať komunikačný kanál", "description": "Pridá validovaný e-mail, telefón, web alebo podporovaný sociálny kanál.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "email, phone, mobile, work_phone, fax, podporované sociálne siete, website alebo other." }, "label": { "type": "string", "description": "Voliteľný používateľský popis kanála; natívny model povoľuje null." }, "value": { "type": "string", "description": "Validovaná a normalizovaná hodnota." }, "is_primary": { "type": "boolean", "description": "Najviac jeden aktívny primárny kanál rovnakého typu." }, "is_active": { "type": "boolean", "description": "Deaktivácia zachová audit." }, "sort_order": { "type": "integer", "format": "int32", "description": "Stabilné poradie." } }, "required": [ "type", "value" ] }, "example": { "type": "email", "label": "Pracovný e-mail", "value": "kontakt@example.sk", "is_primary": true, "is_active": true, "sort_order": 0 } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.channels.write", "x-nexo-crm-permission": "contacts.edit_channels", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "contact.channel_added" } }, "/v1/contacts/{contact_id}/channels/{channel_id}": { "patch": { "operationId": "contacts-channels-update", "tags": [ "Detail kontaktnej osoby" ], "summary": "Upraviť komunikačný kanál", "description": "Upraví popis, hodnotu, primárnosť, poradie alebo aktivitu kanála cez If-Match.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "email, phone, mobile, work_phone, fax, podporované sociálne siete, website alebo other." }, "label": { "type": "string", "description": "Voliteľný používateľský popis kanála; natívny model povoľuje null." }, "value": { "type": "string", "description": "Validovaná a normalizovaná hodnota." }, "is_primary": { "type": "boolean", "description": "Najviac jeden aktívny primárny kanál rovnakého typu." }, "is_active": { "type": "boolean", "description": "Deaktivácia zachová audit." }, "sort_order": { "type": "integer", "format": "int32", "description": "Stabilné poradie." } } }, "example": { "label": "Hlavný pracovný e-mail", "value": "kontakt@example.sk", "is_primary": true, "is_active": true } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.channels.write", "x-nexo-crm-permission": "contacts.edit_channels", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "contact.channel_updated" } }, "/v1/contacts/{contact_id}/addresses": { "get": { "operationId": "contacts-addresses-list", "tags": [ "Detail kontaktnej osoby" ], "summary": "Adresy kontaktu", "description": "Vráti povolené osobné, korešpondenčné, pracovné a iné adresy.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.read", "x-nexo-crm-permission": "contacts.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "contacts-addresses-create", "tags": [ "Detail kontaktnej osoby" ], "summary": "Pridať adresu kontaktu", "description": "Pridá štruktúrovanú adresu s typom, primárnosťou a poradím.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "Typ adresy." }, "label": { "type": "string", "description": "Voliteľný používateľský názov adresy; natívny model povoľuje null." }, "street": { "type": "string", "description": "Ulica a číslo." }, "city": { "type": "string", "description": "Mesto alebo obec." }, "postal_code": { "type": "string", "description": "PSČ." }, "region": { "type": "string", "description": "Kraj alebo región." }, "country_code": { "type": "string", "description": "Kód krajiny." }, "is_primary": { "type": "boolean", "description": "Najviac jedna aktívna primárna adresa rovnakého typu." }, "is_active": { "type": "boolean", "description": "Deaktivácia zachová audit." }, "sort_order": { "type": "integer", "format": "int32", "description": "Stabilné poradie." } }, "required": [ "type", "country_code" ] }, "example": { "type": "work", "label": "Pracovisko", "street": "Ukážková 1", "city": "Bratislava", "postal_code": "811 01", "region": "Bratislavský kraj", "country_code": "SK", "is_primary": true, "is_active": true } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.addresses.write", "x-nexo-crm-permission": "contacts.edit_addresses", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "contact.address_added" } }, "/v1/contacts/{contact_id}/addresses/{address_id}": { "patch": { "operationId": "contacts-addresses-update", "tags": [ "Detail kontaktnej osoby" ], "summary": "Upraviť adresu kontaktu", "description": "Upraví adresu, typ, primárnosť, poradie alebo aktivitu bez vymazania auditu.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "address_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "Typ adresy." }, "label": { "type": "string", "description": "Voliteľný používateľský názov adresy; natívny model povoľuje null." }, "street": { "type": "string", "description": "Ulica a číslo." }, "city": { "type": "string", "description": "Mesto alebo obec." }, "postal_code": { "type": "string", "description": "PSČ." }, "region": { "type": "string", "description": "Kraj alebo región." }, "country_code": { "type": "string", "description": "Kód krajiny." }, "is_primary": { "type": "boolean", "description": "Najviac jedna aktívna primárna adresa rovnakého typu." }, "is_active": { "type": "boolean", "description": "Deaktivácia zachová audit." }, "sort_order": { "type": "integer", "format": "int32", "description": "Stabilné poradie." } } }, "example": { "label": "Hlavné pracovisko", "street": "Ukážková 2", "city": "Bratislava", "postal_code": "811 01", "country_code": "SK", "is_primary": true, "is_active": true } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "contacts.addresses.write", "x-nexo-crm-permission": "contacts.edit_addresses", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "contact.address_updated" } }, "/v1/contacts/{contact_id}/notes": { "get": { "operationId": "contact-notes-list", "tags": [ "Detail kontaktnej osoby" ], "summary": "Poznámky kontaktu", "description": "Bezpečná v1 projekcia pozorovaných note entries vráti iba poznámky povolené explicitným gateway allowlistom a aktuálnou row visibility.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "contacts.read", "x-nexo-crm-permission": "contacts.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "contact-notes-create", "tags": [ "Detail kontaktnej osoby" ], "summary": "Pridať poznámku ku kontaktu", "description": "Pridá časovú poznámku bez prepísania histórie; text prejde limitom, sanitizáciou a auditom autora.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "description": "Text poznámky bez aktívneho HTML." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Voliteľný biznisový čas; auditný created_at vždy nastaví server." } }, "required": [ "text" ] }, "example": { "text": "Kontaktná osoba preferuje komunikáciu e-mailom.", "occurred_at": "2026-08-25T12:30:00Z" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "contacts.notes.write", "x-nexo-crm-permission": "contacts.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "contact.note_added" } }, "/v1/contacts/{contact_id}/record-links": { "get": { "operationId": "contact-record-links-list", "tags": [ "Detail kontaktnej osoby" ], "summary": "Prepojené záznamy kontaktu", "description": "Vráti iba pozorované prepojenia na záznamy, ktoré môže principal samostatne vidieť; väzba nikdy nerozšíri oprávnenie k cieľu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "contacts.read", "x-nexo-crm-permission": "contacts.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "contact-record-links-create", "tags": [ "Detail kontaktnej osoby" ], "summary": "Prepojiť kontakt so záznamom", "description": "Vytvorí explicitnú auditovanú väzbu na viditeľný lead, deal alebo projekt v rovnakom tenantovi; nepodporované typy skončia validačnou chybou.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "target_type": { "type": "string", "description": "Typ povoleného cieľového záznamu." }, "target_id": { "type": "string", "description": "Viditeľný cieľ v rovnakom tenantovi." }, "role": { "type": "string", "description": "Voliteľný význam väzby." } }, "required": [ "target_type", "target_id" ] }, "example": { "target_type": "deal", "target_id": "deal_01J8Y6…", "role": "decision_maker" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "contacts.relationships.write", "x-nexo-crm-permission": "contacts.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "contact.record_link_added" } }, "/v1/leads": { "get": { "operationId": "leads-list", "tags": [ "Leady" ], "summary": "Zoznam leadov", "description": "Vyhľadá leady podľa predmetu, vlastníka, stavu, zdroja, kategórie, teritória, kontaktu alebo štítka. Priorita sa zámerne neponúka ako potvrdený filter: bola pozorovaná iba v Import Center a podmienenom stĺpci, nie v jednom kanonickom detailnom kontrakte.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Fulltext v predmete, firme, mene, e-maile a telefóne.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Vlastník leadu.", "schema": { "type": "string" } }, { "name": "status_id", "in": "query", "required": false, "description": "Stabilné verejné ID mapované na pozorovaný tenantový textový stav workflow.", "schema": { "type": "string" } }, { "name": "source_id", "in": "query", "required": false, "description": "Stabilné verejné ID mapované na pozorovaný zdroj kontaktu.", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "required": false, "description": "Stabilné verejné ID mapované na pozorovanú kategóriu leadu.", "schema": { "type": "string" } }, { "name": "territory_id", "in": "query", "required": false, "description": "Stabilné verejné ID mapované na pozorované obchodné teritórium.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Presne normalizovaný e-mail pre deduplikáciu.", "schema": { "type": "string", "format": "email" } }, { "name": "converted", "in": "query", "required": false, "description": "Filtrovanie úspešne konvertovaných leadov.", "schema": { "type": "boolean" } }, { "name": "tag_id", "in": "query", "required": false, "description": "Lead s priradeným štítkom podľa verejného opaque ID z GET /v1/tags.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Potvrdený návrh radenia; received_at sa nezverejní, kým nebude kanonické pole overené.", "schema": { "type": "string", "format": "date" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "lead_01J8Y6K2…", "type": "lead", "attributes": { "code": "L-2026-00921", "subject": "Záujem o ukážku riešenia", "status": { "id": "lead_status_new", "label": "Nový" }, "source": { "id": "source_website", "label": "Web" }, "category": { "id": "lead_category_inbound", "label": "Inbound" }, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "tag_ids": [ "tag_01J8Y6K2…" ], "updated_at": "2026-08-25T16:40:00Z", "revision": "rev_8" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "leads.read", "x-nexo-crm-permission": "leads.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "lead.updated" }, "post": { "operationId": "leads-create", "tags": [ "Leady" ], "summary": "Nový lead z formulára alebo systému", "description": "Vytvorí lead atomicky so zdrojom, existujúcimi štítkami, servisnými poskytovateľmi, viazanosťami, obchodným follow-upom a samostatným auditom súhlasov. Je vhodný aj pre serverové kontaktné formuláre; verejné source/category/status ID sú v1 adapter nad pozorovanými textovými hodnotami.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "subject": { "type": "string", "description": "Zrozumiteľný predmet leadu bez skladania interných tokenov." }, "person": { "type": "object", "additionalProperties": true, "description": "Meno, e-mail a telefón po normalizácii a validácii." }, "note": { "type": "string", "description": "Správa alebo požiadavka z formulára." }, "address": { "type": "object", "additionalProperties": true, "description": "Voliteľná štruktúrovaná adresa; nie voľný databázový payload." }, "source_id": { "type": "string", "description": "Povinné verejné ID povoleného zdroja, ktoré gateway mapuje na pozorovaný tenantový zdroj." }, "source_context": { "type": "object", "additionalProperties": true, "description": "Voliteľný kontext pôvodu; pre formulár obsahuje external_form_id. Nemení source_id ani nevytvára nový zdroj." }, "tag_ids": { "type": "array", "items": { "type": "string" }, "description": "Verejné opaque ID existujúcich štítkov z GET /v1/tags. API ich nevytvára implicitne a interné numerické ID neprijíma." }, "consents": { "type": "array", "items": { "type": "string" }, "description": "Samostatný audit súhlasov; GDPR, VOP ani marketing sa neevidujú iba štítkom." }, "external_reference": { "type": "object", "additionalProperties": true, "description": "Jedinečné ID odoslania z formulára pre deduplikáciu." }, "company": { "type": "object", "additionalProperties": true, "description": "Voliteľný názov firmy a registračné údaje pred konverziou." }, "owner_id": { "type": "string", "description": "Viditeľný aktívny vlastník; ak chýba, použije sa bezpečný default integračného principalu." }, "relationship_type_id": { "type": "string", "description": "Stabilné ID mapované na pozorovanú tenantovú textovú hodnotu vzťahu leadu." }, "category_id": { "type": "string", "description": "Stabilné ID mapované na pozorovanú kategóriu leadu." }, "territory_id": { "type": "string", "description": "Stabilné ID mapované na pozorované obchodné teritórium." }, "service_profile": { "type": "object", "additionalProperties": true, "description": "Verejný objekt internet.provider/commitment, voice.provider/other_provider/commitment, television.provider/commitment a other.service/detail/commitment nad pozorovanými NEXO poľami. Vnútorné slovenské názvy stĺpcov nie sú verejný kontrakt." }, "sales_follow_up": { "type": "object", "additionalProperties": true, "description": "Verejný objekt verification_call_status, quote_sent a last_contact_at nad pozorovaným stavom verifikačného hovoru, odoslaním ponuky a dátumom posledného kontaktu." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Iba aktívne polia publikovanej lead schémy a explicitného gateway allowlistu." } }, "required": [ "subject", "person", "source_id", "external_reference" ] }, "example": { "subject": "Záujem z kontaktného formulára", "person": { "full_name": "Ukážkový kontakt", "email": "kontakt@example.sk", "phone": "+421900000000" }, "note": "Prosím o spätný kontakt.", "address": { "street": "Ukážková 1", "country_code": "SK" }, "owner_id": "user_01J8Y6…", "relationship_type_id": "lead_relationship_prospect", "category_id": "lead_category_inbound", "territory_id": "territory_west", "source_id": "source_website_contact_form", "source_context": { "external_form_id": "contact-general" }, "service_profile": { "internet": { "provider": "Ukážkový poskytovateľ", "commitment": "do 2027-06" }, "voice": { "provider": null, "commitment": null }, "television": { "provider": null, "commitment": null }, "other": { "service": "Iná požadovaná služba", "detail": "Doplňujúci opis", "commitment": null } }, "sales_follow_up": { "verification_call_status": null, "quote_sent": false, "last_contact_at": null }, "tag_ids": [ "tag_01J8Y6K2…", "tag_01J8Y6M4…" ], "consents": [ { "purpose": "marketing_email", "status": "granted", "text_version": "v3", "captured_at": "2026-08-25T12:00:00Z", "source": { "type": "web_form", "submission_id": "submission_01J8Y6…" } } ], "external_reference": { "system": "wordpress_cf7", "id": "submission_01J8Y6…" } } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "lead_01J8Y6K2…", "type": "lead", "attributes": { "code": "L-2026-00921", "subject": "Záujem o ukážku riešenia", "status": { "id": "lead_status_new", "label": "Nový" }, "source": { "id": "source_website", "label": "Web" }, "category": { "id": "lead_category_inbound", "label": "Inbound" }, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "tag_ids": [ "tag_01J8Y6K2…" ], "updated_at": "2026-08-25T16:40:00Z", "revision": "rev_8" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "leads.write", "x-nexo-crm-permission": "leads.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "lead.created" } }, "/v1/leads/{lead_id}": { "get": { "operationId": "leads-detail", "tags": [ "Leady" ], "summary": "Detail leadu", "description": "Vráti bezpečný detail leadu vrátane stavu, vzťahu, zdroja, kategórie, vlastníka, servisného profilu a konverzie. Priorita je označená iba ako podmienené pole; nepriehľadné ID a revision/ETag sú cieľový v1 gateway kontrakt.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lead_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "lead_01J8Y6K2…", "type": "lead", "attributes": { "code": "L-2026-00921", "subject": "Záujem o ukážku riešenia", "status": { "id": "lead_status_new", "label": "Nový" }, "source": { "id": "source_website", "label": "Web" }, "category": { "id": "lead_category_inbound", "label": "Inbound" }, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "tag_ids": [ "tag_01J8Y6K2…" ], "updated_at": "2026-08-25T16:40:00Z", "revision": "rev_8" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "leads.read", "x-nexo-crm-permission": "leads.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "leads-update", "tags": [ "Leady" ], "summary": "Upraviť lead", "description": "Upraví predmet, osobu alebo firmu, vlastníka, vzťah, zdroj, kategóriu, teritórium, kontakt, adresu, servisný profil, follow-up alebo poznámku. Priorita ostáva podmienená a nie je potvrdený PATCH; stav a konverzia majú samostatné príkazy.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lead_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "description": "Navrhovaný stabilný identifikátor externého systému; vyžaduje samostatný mapovací register, nejde o potvrdený natívny stĺpec." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Iba polia označené v matici ako povinné alebo zapisovateľné a explicitne povolené gateway allowlistom.", "properties": { "service_profile": { "type": "object", "additionalProperties": true, "description": "Verejný objekt internet.provider/commitment, voice.provider/other_provider/commitment, television.provider/commitment a other.service/detail/commitment nad pozorovanými NEXO poľami. Vnútorné slovenské názvy stĺpcov nie sú verejný kontrakt." }, "sales_follow_up": { "type": "object", "additionalProperties": true, "description": "Verejný objekt verification_call_status, quote_sent a last_contact_at nad pozorovaným stavom verifikačného hovoru, odoslaním ponuky a dátumom posledného kontaktu." } } }, "relationships": { "type": "array", "items": { "type": "string" }, "description": "Povolené väzby na existujúce záznamy v rovnakom tenantovi." }, "tag_ids": { "type": "array", "items": { "type": "string" }, "description": "Verejné opaque ID existujúcich štítkov z GET /v1/tags; interné numerické ID ani neznáme názvy sa neprijímajú." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Aktívne zapisovateľné vlastné polia podľa publikovanej schémy a explicitného gateway allowlistu." } }, "required": [ "attributes" ] }, "example": { "attributes": { "subject": "Záujem o rozšírenú ukážku", "owner_id": "user_01J8Y6…", "relationship_type_id": "lead_relationship_prospect", "source_id": "source_website", "category_id": "lead_category_inbound", "territory_id": "territory_west", "service_profile": { "internet": { "provider": "Ukážkový poskytovateľ", "commitment": "do 2027-06" } }, "sales_follow_up": { "verification_call_status": "completed", "quote_sent": true, "last_contact_at": "2026-08-25T12:30:00Z" }, "note": "Termín prezentácie potvrdený." } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "lead_01J8Y6K2…", "type": "lead", "attributes": { "code": "L-2026-00921", "subject": "Záujem o ukážku riešenia", "status": { "id": "lead_status_new", "label": "Nový" }, "source": { "id": "source_website", "label": "Web" }, "category": { "id": "lead_category_inbound", "label": "Inbound" }, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "tag_ids": [ "tag_01J8Y6K2…" ], "updated_at": "2026-08-25T16:40:00Z", "revision": "rev_8" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "leads.write", "x-nexo-crm-permission": "leads.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "lead.updated" } }, "/v1/leads/{lead_id}/status": { "post": { "operationId": "leads-status", "tags": [ "Leady" ], "summary": "Zmeniť stav leadu", "description": "Doménový príkaz overí pozorované workflow pravidlá, oprávnenie a zapíše nemennú históriu. Prevedený vzniká iba konverziou a nemožno ho znovu otvoriť; návrat z Kvalifikovaný na Nový vyžaduje explicitné potvrdenie reštartu automatizácie.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lead_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status_id": { "type": "string", "description": "Cieľový stav z /v1/dictionaries/lead-statuses mapovaný na povolenú tenantovú textovú hodnotu." }, "reason": { "type": "string", "description": "Povinný auditný dôvod pri stavoch, ktoré lead uzatvárajú." }, "confirm_automation_restart": { "type": "boolean", "description": "Povinné true iba pri potvrdenom návrate z Kvalifikovaný na Nový." }, "note": { "type": "string", "description": "Voliteľná auditná poznámka." } }, "required": [ "status_id" ] }, "example": { "status_id": "lead_status_qualified", "note": "Lead bol kvalifikovaný po úvodnom hovore." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "lead_01J8Y6K2…", "type": "lead", "attributes": { "code": "L-2026-00921", "subject": "Záujem o ukážku riešenia", "status": { "id": "lead_status_new", "label": "Nový" }, "source": { "id": "source_website", "label": "Web" }, "category": { "id": "lead_category_inbound", "label": "Inbound" }, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "tag_ids": [ "tag_01J8Y6K2…" ], "updated_at": "2026-08-25T16:40:00Z", "revision": "rev_8" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "leads.status", "x-nexo-crm-permission": "leads.change_status", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "lead.status_changed" } }, "/v1/leads/{lead_id}/convert": { "post": { "operationId": "leads-convert", "tags": [ "Leady" ], "summary": "Konvertovať lead", "description": "Riadená doménová operácia atómovo vytvorí alebo prepojí klienta, kontakt a obchod podľa zvoleného scenára; nikdy nejde o priame prepisovanie tabuliek.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lead_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "client": { "type": "string", "description": "Vytvoriť klienta alebo použiť viditeľný existujúci záznam." }, "contact": { "type": "string", "description": "Voliteľná kontaktná osoba a jej primárna väzba." }, "deal": { "type": "string", "description": "Voliteľný obchodný prípad." }, "copy_tag_ids": { "type": "boolean", "description": "Kontrolované prenesenie podporovaných štítkov." }, "note": { "type": "string", "description": "Auditný dôvod konverzie." } }, "required": [ "client" ] }, "example": { "client": { "mode": "create" }, "contact": { "mode": "create" }, "deal": { "mode": "create", "type_id": "deal_type_sales", "stage_id": "deal_stage_qualification" }, "copy_tag_ids": true, "note": "Konverzia po kvalifikácii." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "leads.convert", "x-nexo-crm-permission": "leads.convert", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "lead.converted" } }, "/v1/deals": { "get": { "operationId": "deals-list", "tags": [ "Obchodné prípady" ], "summary": "Zoznam obchodov", "description": "Vyhľadá obchodné prípady podľa potvrdených polí: predmet, klient, vlastník, typ, fáza, status, hodnota, plánovaná aktivita alebo verejné ID štítka. Filtre source_id a category_id nie sú aktívnou súčasťou kontraktu; zostanú vypnuté, kým sa v DealModeli nepotvrdia kanonické väzby.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Fulltext v predmete a povolenom klientskom kontexte; deal code sa bez potvrdeného zdroja neindexuje.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Obchody viditeľného klienta.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Vlastník obchodu.", "schema": { "type": "string" } }, { "name": "type_id", "in": "query", "required": false, "description": "Typ obchodu a jeho pipeline.", "schema": { "type": "string" } }, { "name": "stage_id", "in": "query", "required": false, "description": "Aktuálna fáza pipeline.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Výsledný stav obchodu.", "schema": { "type": "string" } }, { "name": "min_value", "in": "query", "required": false, "description": "Minimálna hodnota v kombinácii s currency.", "schema": { "type": "number" } }, { "name": "max_value", "in": "query", "required": false, "description": "Maximálna hodnota v kombinácii s currency.", "schema": { "type": "number" } }, { "name": "planned_before", "in": "query", "required": false, "description": "Najbližšia plánovaná aktivita pred časom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "tag_id", "in": "query", "required": false, "description": "Obchod s priradeným štítkom podľa verejného opaque ID z GET /v1/tags.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Explicitne povolené radenie; prefix - znamená DESC.", "schema": { "type": "string", "format": "date" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "deal_01J8Y6K2…", "type": "deal", "attributes": { "subject": "Rozšírenie služieb 2026", "type": { "id": "deal_type_sales", "label": "Predaj" }, "stage": { "id": "deal_stage_qualification", "label": "Kvalifikácia" }, "status": "open", "value": { "amount": 12500, "currency": "EUR" }, "success_probability": 35, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "planned_activity_at": "2026-09-02T09:00:00Z", "tag_ids": [ "tag_01J8Y6R9…" ], "updated_at": "2026-08-25T16:45:00Z", "revision": "rev_25" }, "relationships": { "client": { "id": "client_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "deals.read", "x-nexo-crm-permission": "deals.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "deal.updated" }, "post": { "operationId": "deals-create", "tags": [ "Obchodné prípady" ], "summary": "Nový obchod", "description": "Vytvorí obchod s pozorovanými povinnými poľami type_id, stage_id, client_id, owner_id, subject a value a s povolenou menou či pravdepodobnosťou. contact_id, project_id, source_id, category_id a external_id sú iba podmienené v1 adaptéry.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "description": "Navrhovaný stabilný identifikátor externého systému; vyžaduje samostatný mapovací register, nejde o potvrdený natívny stĺpec." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Iba polia označené v matici ako povinné alebo zapisovateľné a explicitne povolené gateway allowlistom." }, "relationships": { "type": "array", "items": { "type": "string" }, "description": "Povolené väzby na existujúce záznamy v rovnakom tenantovi." }, "tag_ids": { "type": "array", "items": { "type": "string" }, "description": "Verejné opaque ID existujúcich štítkov z GET /v1/tags; interné numerické ID ani neznáme názvy sa neprijímajú." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Aktívne zapisovateľné vlastné polia podľa publikovanej schémy a explicitného gateway allowlistu." } }, "required": [ "attributes" ] }, "example": { "attributes": { "subject": "Rozšírenie služieb 2026", "owner_id": "user_01J8Y6…", "type_id": "deal_type_sales", "stage_id": "deal_stage_qualification", "value": 12500, "currency": "EUR", "success_probability": 35, "planned_activity_at": "2026-09-02T09:00:00Z", "notes": "Dohodnuté ďalšie predstavenie riešenia." }, "relationships": { "client": { "id": "client_01J8Y6…" } }, "tag_ids": [ "tag_01J8Y6R9…" ] } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "deal_01J8Y6K2…", "type": "deal", "attributes": { "subject": "Rozšírenie služieb 2026", "type": { "id": "deal_type_sales", "label": "Predaj" }, "stage": { "id": "deal_stage_qualification", "label": "Kvalifikácia" }, "status": "open", "value": { "amount": 12500, "currency": "EUR" }, "success_probability": 35, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "planned_activity_at": "2026-09-02T09:00:00Z", "tag_ids": [ "tag_01J8Y6R9…" ], "updated_at": "2026-08-25T16:45:00Z", "revision": "rev_25" }, "relationships": { "client": { "id": "client_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "deals.write", "x-nexo-crm-permission": "deals.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "deal.created" } }, "/v1/deals/{deal_id}": { "get": { "operationId": "deals-detail", "tags": [ "Obchodné prípady" ], "summary": "Detail obchodu", "description": "Vráti pozorovaný obchodný detail s klientom, vlastníkom, typom, fázou, statusom, hodnotou, kontaktnými míľnikmi a poznámkami. Deal code ani close_reason sa bez potvrdeného zdroja nezverejnia; contact/project/source/category väzby a revision sú iba podmienené alebo cieľové v1 projekcie.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "deal_01J8Y6K2…", "type": "deal", "attributes": { "subject": "Rozšírenie služieb 2026", "type": { "id": "deal_type_sales", "label": "Predaj" }, "stage": { "id": "deal_stage_qualification", "label": "Kvalifikácia" }, "status": "open", "value": { "amount": 12500, "currency": "EUR" }, "success_probability": 35, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "planned_activity_at": "2026-09-02T09:00:00Z", "tag_ids": [ "tag_01J8Y6R9…" ], "updated_at": "2026-08-25T16:45:00Z", "revision": "rev_25" }, "relationships": { "client": { "id": "client_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "deals.read", "x-nexo-crm-permission": "deals.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "deals-update", "tags": [ "Obchodné prípady" ], "summary": "Upraviť obchod", "description": "Upraví predmet, vlastníka, hodnotu, menu, pravdepodobnosť, plánovanú aktivitu, kontaktné míľniky alebo poznámky. Pipeline a výsledný status zostávajú doménové príkazy.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "external_id": { "type": "string", "description": "Navrhovaný stabilný identifikátor externého systému; vyžaduje samostatný mapovací register, nejde o potvrdený natívny stĺpec." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Iba polia označené v matici ako povinné alebo zapisovateľné a explicitne povolené gateway allowlistom." }, "relationships": { "type": "array", "items": { "type": "string" }, "description": "Povolené väzby na existujúce záznamy v rovnakom tenantovi." }, "tag_ids": { "type": "array", "items": { "type": "string" }, "description": "Verejné opaque ID existujúcich štítkov z GET /v1/tags; interné numerické ID ani neznáme názvy sa neprijímajú." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Aktívne zapisovateľné vlastné polia podľa publikovanej schémy a explicitného gateway allowlistu." } }, "required": [ "attributes" ] }, "example": { "attributes": { "subject": "Rozšírenie služieb a podpory 2026", "owner_id": "user_01J8Y6…", "value": 14800, "currency": "EUR", "success_probability": 55, "planned_activity_at": "2026-09-04T13:30:00Z", "quote_sent": true, "quote_method": "email", "notes": "Ponuka bola odoslaná." } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "deal_01J8Y6K2…", "type": "deal", "attributes": { "subject": "Rozšírenie služieb 2026", "type": { "id": "deal_type_sales", "label": "Predaj" }, "stage": { "id": "deal_stage_qualification", "label": "Kvalifikácia" }, "status": "open", "value": { "amount": 12500, "currency": "EUR" }, "success_probability": 35, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "planned_activity_at": "2026-09-02T09:00:00Z", "tag_ids": [ "tag_01J8Y6R9…" ], "updated_at": "2026-08-25T16:45:00Z", "revision": "rev_25" }, "relationships": { "client": { "id": "client_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "deals.write", "x-nexo-crm-permission": "deals.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "deal.updated" } }, "/v1/deals/{deal_id}/stage": { "post": { "operationId": "deals-stage", "tags": [ "Obchodné prípady" ], "summary": "Zmeniť fázu obchodu", "description": "Doménový príkaz overí, že cieľová fáza patrí typu obchodu, prechod je povolený a všetky povinné polia sú vyplnené.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "stage_id": { "type": "string", "description": "Cieľová fáza z pipeline aktuálneho typu obchodu." }, "note": { "type": "string", "description": "Auditná poznámka k prechodu." } }, "required": [ "stage_id" ] }, "example": { "stage_id": "deal_stage_proposal", "note": "Ponuka bola odoslaná klientovi." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "deal_01J8Y6K2…", "type": "deal", "attributes": { "subject": "Rozšírenie služieb 2026", "type": { "id": "deal_type_sales", "label": "Predaj" }, "stage": { "id": "deal_stage_qualification", "label": "Kvalifikácia" }, "status": "open", "value": { "amount": 12500, "currency": "EUR" }, "success_probability": 35, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "planned_activity_at": "2026-09-02T09:00:00Z", "tag_ids": [ "tag_01J8Y6R9…" ], "updated_at": "2026-08-25T16:45:00Z", "revision": "rev_25" }, "relationships": { "client": { "id": "client_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "deals.stage", "x-nexo-crm-permission": "deals.change_stage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "deal.stage_changed" } }, "/v1/deals/{deal_id}/status": { "post": { "operationId": "deals-status", "tags": [ "Obchodné prípady" ], "summary": "Zmeniť výsledný stav obchodu", "description": "Riadený prechod na won, lost, cancelled alebo open zachová pozorované doménové účinky: mimo open sa vyčistí fáza, prepočíta pravdepodobnosť a won môže spustiť objednávkový tok. Verejný close reason je iba podmienený návrh v1.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Cieľový výsledný stav." }, "note": { "type": "string", "description": "Auditná poznámka." } }, "required": [ "status" ] }, "example": { "status": "won", "note": "Objednávka bola potvrdená." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "deal_01J8Y6K2…", "type": "deal", "attributes": { "subject": "Rozšírenie služieb 2026", "type": { "id": "deal_type_sales", "label": "Predaj" }, "stage": { "id": "deal_stage_qualification", "label": "Kvalifikácia" }, "status": "open", "value": { "amount": 12500, "currency": "EUR" }, "success_probability": 35, "owner": { "id": "user_01J8Y6…", "display_name": "Ukážkový vlastník" }, "planned_activity_at": "2026-09-02T09:00:00Z", "tag_ids": [ "tag_01J8Y6R9…" ], "updated_at": "2026-08-25T16:45:00Z", "revision": "rev_25" }, "relationships": { "client": { "id": "client_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "deals.status", "x-nexo-crm-permission": "deals.change_status", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "deal.status_changed" } }, "/v1/deals/{deal_id}/items": { "get": { "operationId": "deal-items-list", "tags": [ "Detail obchodného prípadu" ], "summary": "Položky obchodu", "description": "Podmienený v1 pohľad na pozorované samostatné produktové položky obchodu. Sprístupní sa až po potvrdení cenových, daňových a viditeľnostných pravidiel produktu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "deals.read", "x-nexo-crm-permission": "deals.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "deal-items-create", "tags": [ "Detail obchodného prípadu" ], "summary": "Pridať položku obchodu", "description": "Pridá jednu produktovú položku atómovo a prepočíta odvodené sumy na serveri; klient nikdy neposiela dôveryhodný výsledný total.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "product_id": { "type": "string", "description": "Viditeľný produkt z /v1/products; presná väzba je súčasťou podmieneného v1 kontraktu." }, "name": { "type": "string", "description": "Snapshot názvu položky pre audit dokladu." }, "quantity": { "type": "number", "description": "Kladné množstvo podľa pravidiel produktu." }, "unit_price": { "type": "string", "description": "Jednotková cena v mene obchodu; server znovu overí pricing oprávnenie." }, "discount_percent": { "type": "number", "description": "Voliteľná zľava v povolenom limite." }, "tax_rate": { "type": "number", "description": "Voliteľná sadzba; finančný engine zostáva zdrojom výpočtu." }, "sort_order": { "type": "integer", "format": "int32", "description": "Stabilné poradie položky." } }, "required": [ "name", "quantity", "unit_price" ] }, "example": { "product_id": "product_01J8Y6…", "name": "Ukážková služba", "quantity": 1, "unit_price": { "amount": 120, "currency": "EUR" }, "discount_percent": 0, "tax_rate": 23, "sort_order": 0 } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "deals.items.write", "x-nexo-crm-permission": "deals.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "deal.item_added" } }, "/v1/deals/{deal_id}/items/{item_id}": { "patch": { "operationId": "deal-items-update", "tags": [ "Detail obchodného prípadu" ], "summary": "Upraviť položku obchodu", "description": "Upraví povolené vstupy položky cez If-Match a nechá cenu, daň aj výsledné sumy znovu vypočítať serverom. Odstránenie sa v tejto bezpečnej kandidátnej knižnici nevystavuje.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "item_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "product_id": { "type": "string", "description": "Viditeľný produkt z /v1/products; presná väzba je súčasťou podmieneného v1 kontraktu." }, "name": { "type": "string", "description": "Snapshot názvu položky pre audit dokladu." }, "quantity": { "type": "number", "description": "Kladné množstvo podľa pravidiel produktu." }, "unit_price": { "type": "string", "description": "Jednotková cena v mene obchodu; server znovu overí pricing oprávnenie." }, "discount_percent": { "type": "number", "description": "Voliteľná zľava v povolenom limite." }, "tax_rate": { "type": "number", "description": "Voliteľná sadzba; finančný engine zostáva zdrojom výpočtu." }, "sort_order": { "type": "integer", "format": "int32", "description": "Stabilné poradie položky." } } }, "example": { "quantity": 2, "unit_price": { "amount": 115, "currency": "EUR" }, "discount_percent": 5, "sort_order": 0 } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "deals.items.write", "x-nexo-crm-permission": "deals.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "deal.item_updated" } }, "/v1/email-offer-templates": { "get": { "operationId": "email-offer-templates-list", "tags": [ "E-mailové ponuky" ], "summary": "Zoznam šablón ponúk", "description": "NEXO má pozorovaný systém e-mailových šablón, preview batchov a potvrdeného odoslania — nie generickú obchodnú ponuku s položkami a PDF. Vrátia sa iba viditeľné šablóny bez provider tajomstiev.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "email_offers.read", "x-nexo-crm-permission": "email_offers.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/email-offer-previews": { "post": { "operationId": "email-offer-previews-create", "tags": [ "E-mailové ponuky" ], "summary": "Pripraviť náhľad ponuky", "description": "Vytvorí neodoslaný preview batch, overí vlastníctvo leadov, povinné polia, prílohy a duplicity. Verejné odoslanie zostáva vypnuté do samostatného bezpečnostného auditu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_id": { "type": "string" }, "lead_ids": { "type": "array", "items": { "type": "string" } }, "subject_override": { "type": "string" } }, "required": [ "template_id", "lead_ids", "subject_override" ], "additionalProperties": false }, "example": { "template_id": "email_offer_template_01J8Y6…", "lead_ids": [ "lead_01J8Y6A…", "lead_01J8Y6B…" ], "subject_override": "Individuálna ponuka služieb" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "email_offers.preview", "x-nexo-crm-permission": "email_offers.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "email_offer.preview_ready" } }, "/v1/email-offer-batches/{batch_id}": { "get": { "operationId": "email-offer-batches-detail", "tags": [ "E-mailové ponuky" ], "summary": "Detail preview batchu", "description": "Vráti redigované výsledky preview, duplicity a validačné chyby. Nevracia filesystem cesty, SMTP odpovede ani plné adresy bez PII scope.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "email_offers.read", "x-nexo-crm-permission": "email_offers.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/orders": { "get": { "operationId": "orders-list", "tags": [ "Objednávky" ], "summary": "Zoznam objednávok", "description": "Pozorovaný zoznam objednávok v owner scope. Citlivé historické identifikačné polia sa vo verejnom kontrakte nikdy nevracajú.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Vyhľadávanie v bezpečnom klientskom, produktovom a kontaktnom kontexte.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "V1 anglický adapter nad pozorovanými slovenskými stavmi.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Objednávky viditeľného vlastníka.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "orders.read", "x-nexo-crm-permission": "orders.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "order.updated" } }, "/v1/orders/{order_id}": { "get": { "operationId": "orders-detail", "tags": [ "Objednávky" ], "summary": "Detail objednávky", "description": "Vráti vlastníka, bezpečný klientsky a doručovací snapshot, text produktu, poznámku, stav a auditné časy. Rodné číslo ani číslo dokladu nie sú súčasťou ordinary API.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "orders.read", "x-nexo-crm-permission": "orders.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "orders-update", "tags": [ "Objednávky" ], "summary": "Upraviť objednávku", "description": "Upraví iba povolené neworkflow polia cez If-Match a owner pravidlá. Stav sa mení samostatným príkazom.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "owner_id": { "type": "string", "description": "Viditeľný aktívny vlastník." }, "client_snapshot": { "type": "object", "additionalProperties": true, "description": "Redukované meno a doručovacie kontakty bez osobitných identifikátorov." }, "product_text": { "type": "string", "description": "Pozorovaný text objednanej služby." }, "note": { "type": "string", "description": "Poznámka." }, "admin_note": { "type": "string", "description": "Interná poznámka iba s citlivým scope." } } }, "example": { "owner_id": "user_01J8Y6…", "note": "Doručenie potvrdené telefonicky." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "orders.write", "x-nexo-crm-permission": "orders.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "order.updated" } }, "/v1/orders/{order_id}/status": { "post": { "operationId": "orders-status", "tags": [ "Objednávky" ], "summary": "Zmeniť stav objednávky", "description": "Doménový príkaz mapuje new, processed, returned, cancelled a paid na pozorovaný tenantový workflow, vyžaduje If-Match, Idempotency-Key a auditný dôvod.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Cieľový povolený stav." }, "reason": { "type": "string", "description": "Auditný dôvod prechodu." } }, "required": [ "status" ] }, "example": { "status": "processed", "reason": "Objednávka bola skontrolovaná." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "orders.status", "x-nexo-crm-permission": "orders.change_status", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "order.status_changed" } }, "/v1/products": { "get": { "operationId": "products-list", "tags": [ "Produkty a cenníky" ], "summary": "Zoznam produktov", "description": "Vracajú sa pozorované katalógové polia, aktívny stav a verejné tag_id. Nákladová cena vyžaduje samostatný citlivý scope a interný image_path sa nikdy nepublikuje.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Kód, názov a popis.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Lifecycle produktu.", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "required": false, "description": "Tenantová kategória.", "schema": { "type": "string" } }, { "name": "product_line_id", "in": "query", "required": false, "description": "Produktový rad.", "schema": { "type": "string" } }, { "name": "unit_id", "in": "query", "required": false, "description": "Merná jednotka.", "schema": { "type": "string" } }, { "name": "vat_rate", "in": "query", "required": false, "description": "Tenantom povolená sadzba DPH.", "schema": { "type": "number" } }, { "name": "tag_id", "in": "query", "required": false, "description": "Verejné ID štítka.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "products.read", "x-nexo-crm-permission": "products.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "product.updated" }, "post": { "operationId": "products-create", "tags": [ "Produkty a cenníky" ], "summary": "Vytvoriť produkt", "description": "Vytvorí produkt z tenantových číselníkov a typovanej ceny. Obrázok sa pripája ako autorizované médium, nikdy filesystem path.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "standard_price": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "vat_rate": { "type": "integer" }, "unit_id": { "type": "string" }, "product_line_id": { "type": "string" }, "category_id": { "type": "string" }, "description": { "type": "string" }, "valid_from": { "type": "string" }, "tag_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "name", "standard_price", "vat_rate", "unit_id", "product_line_id", "category_id", "description", "valid_from", "tag_ids" ], "additionalProperties": false }, "example": { "code": "SVC-100", "name": "Spravovaná služba", "standard_price": { "amount": 120, "currency": "EUR" }, "vat_rate": 23, "unit_id": "unit_month", "product_line_id": "product_line_services", "category_id": "product_category_managed", "description": "Mesačná spravovaná služba.", "valid_from": "2026-09-01", "tag_ids": [ "tag_01J8Y6…" ] } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "products.write", "x-nexo-crm-permission": "products.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "product.created" } }, "/v1/products/{product_id}": { "get": { "operationId": "products-detail", "tags": [ "Produkty a cenníky" ], "summary": "Detail produktu", "description": "Vráti code, name, standard_price, currency, vat_rate, unit, product_line, category, description, validity, aktívny stav, médium a štítky. cost_price iba s products.cost.read.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "products.read", "x-nexo-crm-permission": "products.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "products-update", "tags": [ "Produkty a cenníky" ], "summary": "Upraviť produkt", "description": "Upraví povolené katalógové polia cez If-Match; cost_price vyžaduje osobitný scope a aktívny stav sa nemení PATCHom.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "standard_price": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "valid_to": { "type": "string" } }, "required": [ "name", "standard_price", "valid_to" ], "additionalProperties": false }, "example": { "name": "Spravovaná služba Plus", "standard_price": { "amount": 135, "currency": "EUR" }, "valid_to": "2027-12-31" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "products.write", "x-nexo-crm-permission": "products.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "product.updated" } }, "/v1/products/{product_id}/archive": { "post": { "operationId": "products-archive", "tags": [ "Produkty a cenníky" ], "summary": "Archivovať produkt", "description": "Idempotentný lifecycle príkaz zachová produkt v historických položkách a cenníkoch.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "Produkt sa už nepredáva." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "products.write", "x-nexo-crm-permission": "products.archive", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "product.archived" } }, "/v1/products/{product_id}/restore": { "post": { "operationId": "products-restore", "tags": [ "Produkty a cenníky" ], "summary": "Obnoviť produkt", "description": "Obnoví produkt iba ak jeho tenantové číselníky, mena a platnosť zostávajú validné.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "products.write", "x-nexo-crm-permission": "products.restore", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "product.restored" } }, "/v1/price-lists": { "get": { "operationId": "price-lists-list", "tags": [ "Produkty a cenníky" ], "summary": "Zoznam cenníkov", "description": "Zoznam rešpektuje owner visibility, menu, platnosť, tenantovú kategóriu, aktívny stav a verejné štítky.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "price_lists.read", "x-nexo-crm-permission": "price_lists.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "price-lists-create", "tags": [ "Produkty a cenníky" ], "summary": "Vytvoriť cenník", "description": "Vytvorí hlavičku cenníka s validnou menou, kurzom, platnosťou a viditeľným vlastníkom.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "base_currency": { "type": "string" }, "exchange_rate": { "type": "integer" }, "valid_from": { "type": "string" }, "owner_id": { "type": "string" }, "category_id": { "type": "string" }, "tag_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "name", "currency", "base_currency", "exchange_rate", "valid_from", "owner_id", "category_id", "tag_ids" ], "additionalProperties": false }, "example": { "code": "PL-2026-B2B", "name": "B2B cenník 2026", "currency": "EUR", "base_currency": "EUR", "exchange_rate": 1, "valid_from": "2026-09-01", "owner_id": "user_01J8Y6…", "category_id": "price_list_category_b2b", "tag_ids": [ "tag_01J8Y6…" ] } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "price_lists.write", "x-nexo-crm-permission": "price_lists.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "price_list.created" } }, "/v1/price-lists/{price_list_id}": { "get": { "operationId": "price-lists-detail", "tags": [ "Produkty a cenníky" ], "summary": "Detail cenníka", "description": "Vráti hlavičku cenníka; položky majú vlastnú kurzorovú kolekciu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "price_list_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "price_lists.read", "x-nexo-crm-permission": "price_lists.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "price-lists-update", "tags": [ "Produkty a cenníky" ], "summary": "Upraviť cenník", "description": "Upraví hlavičku cez If-Match. Zmena meny alebo kurzu prejde finančnou validáciou a neprepisuje historické doklady.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "price_list_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "valid_to": { "type": "string" } }, "required": [ "name", "valid_to" ], "additionalProperties": false }, "example": { "name": "B2B cenník 2026 · aktualizovaný", "valid_to": "2027-08-31" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "price_lists.write", "x-nexo-crm-permission": "price_lists.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "price_list.updated" } }, "/v1/price-lists/{price_list_id}/archive": { "post": { "operationId": "price-lists-archive", "tags": [ "Produkty a cenníky" ], "summary": "Archivovať cenník", "description": "Archivuje cenník bez odstránenia historických cien a väzieb.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "price_list_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "Cenník bol nahradený." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "price_lists.write", "x-nexo-crm-permission": "price_lists.archive", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "price_list.archived" } }, "/v1/price-lists/{price_list_id}/restore": { "post": { "operationId": "price-lists-restore", "tags": [ "Produkty a cenníky" ], "summary": "Obnoviť cenník", "description": "Obnoví cenník po kontrole meny, platnosti, vlastníka a aktívnych produktov.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "price_list_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "price_lists.write", "x-nexo-crm-permission": "price_lists.restore", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "price_list.restored" } }, "/v1/price-lists/{price_list_id}/items": { "get": { "operationId": "price-list-items-list", "tags": [ "Produkty a cenníky" ], "summary": "Položky cenníka", "description": "Vráti aktívne produktové ceny, minimálne množstvá, zľavy, poznámky a poradie.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "price_list_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "price_lists.read", "x-nexo-crm-permission": "price_lists.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "put": { "operationId": "price-list-items-replace", "tags": [ "Produkty a cenníky" ], "summary": "Nahradiť položky cenníka", "description": "Atómovo nahradí celý zoznam položiek cez If-Match. Omitted memberships sa archivujú; server overí aktívne produkty, menu, platnosť, cenu a duplicity.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "price_list_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "unit_price": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "min_quantity": { "type": "integer" }, "discount_percent": { "type": "integer" }, "note": { "type": "string" }, "position": { "type": "integer" } }, "required": [ "product_id", "unit_price", "min_quantity", "discount_percent", "note", "position" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "example": { "items": [ { "product_id": "product_01J8Y6…", "unit_price": { "amount": 110, "currency": "EUR" }, "min_quantity": 1, "discount_percent": 0, "note": "Základná cena", "position": 10 } ] } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "price_lists.write", "x-nexo-crm-permission": "price_lists.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "price_list.items_replaced" } }, "/v1/activities": { "get": { "operationId": "activities-list", "tags": [ "Prehľad aktivít" ], "summary": "Zoznam aktivít", "description": "Read-only polymorfný feed nad kalendárom, procesnými úlohami a e-mailami. Každá položka vracia source_type a source_id; mutácie používajú konkrétny zdrojový resource.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Typ zdrojovej aktivity.", "schema": { "type": "string", "format": "email" } }, { "name": "period", "in": "query", "required": false, "description": "Časové obdobie.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Normalizovaný stav feedu.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Viditeľný vlastník.", "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "description": "Bezpečné fulltext hľadanie.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet aktivít.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "activities.read", "x-nexo-crm-permission": "activities.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/calendar-events": { "get": { "operationId": "calendar-list", "tags": [ "Kalendár a úlohy" ], "summary": "Zoznam udalostí", "description": "Typované kalendárne udalosti v owner scope.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "calendar.read", "x-nexo-crm-permission": "calendar.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "calendar-create", "tags": [ "Kalendár a úlohy" ], "summary": "Nová udalosť", "description": "Vytvorí kalendárnu udalosť, nie generickú aktivitu. Tenantové reminder, conflict a completion pravidlá sa overia serverom.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "starts_at": { "type": "string" }, "ends_at": { "type": "string" }, "owner_id": { "type": "string" }, "related_entity": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false }, "note": { "type": "string" } }, "required": [ "title", "starts_at", "ends_at", "owner_id", "related_entity", "note" ], "additionalProperties": false }, "example": { "title": "Prezentácia riešenia", "starts_at": "2026-09-03T09:00:00Z", "ends_at": "2026-09-03T10:00:00Z", "owner_id": "user_01J8Y6…", "related_entity": { "type": "client", "id": "client_01J8Y6…" }, "note": "Online prezentácia." } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "calendar.write", "x-nexo-crm-permission": "calendar.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "calendar_event.created" } }, "/v1/calendar-events/{event_id}": { "get": { "operationId": "calendar-detail", "tags": [ "Kalendár a úlohy" ], "summary": "Detail udalosti", "description": "Detail udalosti. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "event_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "calendar.read", "x-nexo-crm-permission": "calendar.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "calendar-update", "tags": [ "Kalendár a úlohy" ], "summary": "Upraviť udalosť", "description": "Upraví bežné polia udalosti cez If-Match; stav a completion result majú samostatný príkaz.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "event_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "starts_at": { "type": "string" }, "ends_at": { "type": "string" }, "note": { "type": "string" } }, "required": [ "starts_at", "ends_at", "note" ], "additionalProperties": false }, "example": { "starts_at": "2026-09-03T10:00:00Z", "ends_at": "2026-09-03T11:00:00Z", "note": "Termín posunutý po dohode." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "calendar.write", "x-nexo-crm-permission": "calendar.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "calendar_event.updated" } }, "/v1/calendar-events/{event_id}/status": { "post": { "operationId": "calendar-status", "tags": [ "Kalendár a úlohy" ], "summary": "Zmeniť stav udalosti", "description": "Doménový príkaz mapuje planned, completed, cancelled alebo moved na pozorované tenantové stavy a vynúti povinný výsledok dokončenia, ak ho tenant vyžaduje.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "event_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "completion_result_id": { "type": "string" }, "note": { "type": "string" } }, "required": [ "status", "completion_result_id", "note" ], "additionalProperties": false }, "example": { "status": "completed", "completion_result_id": "calendar_result_success", "note": "Prezentácia prebehla." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "calendar.status", "x-nexo-crm-permission": "calendar.change_status", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "calendar_event.status_changed" } }, "/v1/tasks": { "get": { "operationId": "tasks-list", "tags": [ "Kalendár a úlohy" ], "summary": "Zoznam úloh", "description": "Samostatná kolekcia úloh v owner scope; nejde o mutáciu polymorfného /activities feedu.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "tasks.read", "x-nexo-crm-permission": "tasks.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "tasks-create", "tags": [ "Kalendár a úlohy" ], "summary": "Nová úloha", "description": "Podmienený gateway kontrakt vytvorí úlohu s viditeľným riešiteľom a bezpečnou väzbou; presné tenantové priority a typy sa čítajú zo schémy.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "assignee_id": { "type": "string" }, "due_at": { "type": "string" }, "priority_id": { "type": "string" }, "related_entity": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false }, "note": { "type": "string" } }, "required": [ "title", "assignee_id", "due_at", "priority_id", "related_entity", "note" ], "additionalProperties": false }, "example": { "title": "Ozvať sa klientovi", "assignee_id": "user_01J8Y6…", "due_at": "2026-09-04T14:00:00Z", "priority_id": "task_priority_normal", "related_entity": { "type": "client", "id": "client_01J8Y6…" }, "note": "Potvrdiť termín realizácie." } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "tasks.write", "x-nexo-crm-permission": "tasks.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "task.created" } }, "/v1/tasks/{task_id}/complete": { "post": { "operationId": "tasks-complete", "tags": [ "Kalendár a úlohy" ], "summary": "Dokončiť úlohu", "description": "Doménový príkaz dokončí iba viditeľnú úlohu, vyžaduje If-Match a prípadný tenantom povinný výsledok.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "result_id": { "type": "string" }, "note": { "type": "string" } }, "required": [ "result_id", "note" ], "additionalProperties": false }, "example": { "result_id": "task_result_done", "note": "Klient potvrdil realizáciu." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "tasks.complete", "x-nexo-crm-permission": "tasks.complete", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "task.completed" } }, "/v1/projects": { "get": { "operationId": "projects-list", "tags": [ "Projekty" ], "summary": "Zoznam projektov", "description": "Zoznam projektov v owner a scope policy viditeľnosti; typy, stavy, health a priority sú tenantové číselníky.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "projects.read", "x-nexo-crm-permission": "projects.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "project.updated" }, "post": { "operationId": "projects-create", "tags": [ "Projekty" ], "summary": "Nový projekt", "description": "Vytvorí projekt s povinným názvom, tenantovým typom, vlastníkom a bezpečnou scope policy. Vnorené úlohy, míľniky a dokumenty sa nevytvárajú vo voľnom JSON.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type_id": { "type": "string" }, "owner_id": { "type": "string" }, "manager_id": { "type": "string" }, "starts_on": { "type": "string" }, "ends_on": { "type": "string" }, "priority_id": { "type": "string" }, "relationships": { "type": "object", "properties": { "client_id": { "type": "string" } }, "required": [ "client_id" ], "additionalProperties": false } }, "required": [ "name", "description", "type_id", "owner_id", "manager_id", "starts_on", "ends_on", "priority_id", "relationships" ], "additionalProperties": false }, "example": { "name": "Migrácia integračnej vrstvy", "description": "Riadený projekt API gateway.", "type_id": "project_type_implementation", "owner_id": "user_01J8Y6…", "manager_id": "user_01J8Y7…", "starts_on": "2026-09-01", "ends_on": "2026-12-15", "priority_id": "project_priority_high", "relationships": { "client_id": "client_01J8Y6…" } } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "projects.write", "x-nexo-crm-permission": "projects.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "project.created" } }, "/v1/projects/{project_id}": { "get": { "operationId": "projects-detail", "tags": [ "Projekty" ], "summary": "Detail projektu", "description": "Vráti pozorované základné polia, progress, version a autorizované súvisiace kolekcie. Ciele, míľniky, úlohy, riziká, poznámky, dokumenty, metriky, audit a členovia majú oddelené scopes.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "projects.read", "x-nexo-crm-permission": "projects.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/projects/{project_id}/status": { "post": { "operationId": "projects-status", "tags": [ "Projekty" ], "summary": "Zmeniť stav projektu", "description": "Použije pozorovanú doménovú transition operáciu, očakávanú version a tenantom povolený cieľový stav. Všeobecný PATCH projektu sa bez potvrdeného modelu nevystavuje.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status_id": { "type": "string" }, "expected_version": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "status_id", "expected_version", "note" ], "additionalProperties": false }, "example": { "status_id": "project_status_in_progress", "expected_version": 7, "note": "Projekt bol schválený na realizáciu." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "projects.status", "x-nexo-crm-permission": "projects.change_status", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "project.status_changed" } }, "/v1/projects/{project_id}/tasks": { "get": { "operationId": "project-tasks-list", "tags": [ "Detail projektu" ], "summary": "Úlohy projektu", "description": "Úlohy projektu. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "projects.tasks.read", "x-nexo-crm-permission": "projects.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "project-tasks-create", "tags": [ "Detail projektu" ], "summary": "Pridať úlohu projektu", "description": "Vytvorí projektovú úlohu s viditeľným riešiteľom a termínom; stav a completion lifecycle sa nemení pri create.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "assignee_id": { "type": "string" }, "due_at": { "type": "string" }, "priority_id": { "type": "string" } }, "required": [ "title", "assignee_id", "due_at", "priority_id" ], "additionalProperties": false }, "example": { "title": "Pripraviť mapovanie dát", "assignee_id": "user_01J8Y6…", "due_at": "2026-09-10T15:00:00Z", "priority_id": "task_priority_high" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "projects.tasks.write", "x-nexo-crm-permission": "projects.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "project.task_created" } }, "/v1/projects/{project_id}/entities": { "get": { "operationId": "project-entities-list", "tags": [ "Detail projektu" ], "summary": "Prepojené CRM záznamy", "description": "Vráti iba linky, pri ktorých principal vidí projekt aj cieľový CRM záznam.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "projects.read", "x-nexo-crm-permission": "projects.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/projects/{project_id}/entities/{entity_type}/{entity_id}": { "put": { "operationId": "project-entity-assign", "tags": [ "Detail projektu" ], "summary": "Prepojiť CRM záznam", "description": "Idempotentný gateway adapter používa uzavretú capability maticu a overí viditeľnosť oboch strán; syntakticky ľubovoľný entity_type sa neprijíma.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "projects.write", "x-nexo-crm-permission": "projects.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "project.entity_linked" } }, "/v1/processes": { "get": { "operationId": "processes-list", "tags": [ "Procesy" ], "summary": "Zoznam procesov", "description": "Zoznam procesov. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "processes.read", "x-nexo-crm-permission": "processes.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/processes/{process_id}": { "get": { "operationId": "processes-detail", "tags": [ "Procesy" ], "summary": "Detail procesu", "description": "Detail procesu. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "process_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "processes.read", "x-nexo-crm-permission": "processes.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/invoices": { "get": { "operationId": "invoices-list", "tags": [ "Fakturácia" ], "summary": "Zoznam faktúr", "description": "Zoznam faktúr. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "invoices.read", "x-nexo-crm-permission": "invoices.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "invoice.updated" }, "post": { "operationId": "invoices-create", "tags": [ "Fakturácia" ], "summary": "Vystaviť faktúru", "description": "Finančný zápis vyžaduje samostatné oprávnenie, Idempotency-Key a nemenný audit. Server znovu overí klienta, sadzby, menu a vypočíta základ, daň aj total; klient neposiela dôveryhodný výsledok.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "client_id": { "type": "string", "description": "Viditeľný fakturačný klient." }, "issue_date": { "type": "string", "format": "date", "description": "Dátum vystavenia v povolenom období." }, "due_date": { "type": "string", "format": "date", "description": "Dátum splatnosti." }, "currency": { "type": "string", "description": "Povolená mena dokladu." }, "items": { "type": "array", "items": { "type": "string" }, "description": "Produktový alebo textový snapshot s množstvom, jednotkovou cenou a sadzbou dane." }, "note": { "type": "string", "description": "Voliteľná poznámka." }, "external_reference": { "type": "object", "additionalProperties": true, "description": "Deduplikačná referencia zdrojového systému." } }, "required": [ "client_id", "issue_date", "due_date", "currency", "items" ] }, "example": { "client_id": "client_01J8Y6…", "issue_date": "2026-09-01", "due_date": "2026-09-15", "currency": "EUR", "items": [ { "product_id": "product_01J8Y6…", "name": "Spravovaná služba", "quantity": 1, "unit_price": 120, "tax_rate": 23 } ], "note": "Fakturácia za september.", "external_reference": { "system": "erp", "id": "invoice-42851" } } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "invoices.issue", "x-nexo-crm-permission": "invoices.issue", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "invoice.issued" } }, "/v1/invoices/{invoice_id}": { "get": { "operationId": "invoices-detail", "tags": [ "Fakturácia" ], "summary": "Detail faktúry", "description": "Detail faktúry. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "invoices.read", "x-nexo-crm-permission": "invoices.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/payments": { "get": { "operationId": "payments-list", "tags": [ "Fakturácia" ], "summary": "Zoznam úhrad", "description": "Zoznam úhrad. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "payments.read", "x-nexo-crm-permission": "payments.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "payment.received" } }, "/v1/warehouses": { "get": { "operationId": "warehouses-list", "tags": [ "Sklad" ], "summary": "Zoznam skladov", "description": "Zoznam skladov. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "warehouses.read", "x-nexo-crm-permission": "warehouses.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/stock": { "get": { "operationId": "stock-list", "tags": [ "Sklad" ], "summary": "Stav zásob", "description": "Stav zásob. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "stock.read", "x-nexo-crm-permission": "stock.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "stock.changed" } }, "/v1/stock-movements": { "post": { "operationId": "stock-movements", "tags": [ "Sklad" ], "summary": "Nový skladový pohyb", "description": "Pohyb je nemenný účtovný príkaz s Idempotency-Key; nevystavujeme priamy prepis množstva. Server overí sklad, položku, disponibilitu, jednotku a dôvod.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "warehouse_id": { "type": "string", "description": "Viditeľný aktívny sklad." }, "inventory_item_id": { "type": "string", "description": "Aktívna skladová položka." }, "direction": { "type": "string", "description": "Typ pohybu." }, "quantity": { "type": "number", "description": "Kladné množstvo v jednotke položky." }, "target_warehouse_id": { "type": "string", "description": "Povinné iba pri transfer." }, "reason_id": { "type": "string", "description": "Povolený dôvod pohybu." }, "reference": { "type": "object", "additionalProperties": true, "description": "Voliteľná väzba na objednávku, doklad alebo externý systém." } }, "required": [ "warehouse_id", "inventory_item_id", "direction", "quantity", "reason_id" ] }, "example": { "warehouse_id": "warehouse_01J8Y6…", "inventory_item_id": "inventory_item_01J8Y6…", "direction": "issue", "quantity": 2, "reason_id": "stock_reason_order", "reference": { "type": "order", "id": "order_01J8Y6…" } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "stock.move", "x-nexo-crm-permission": "stock.move", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "stock.moved" } }, "/v1/stock-reservations": { "get": { "operationId": "reservations-list", "tags": [ "Sklad" ], "summary": "Zoznam rezervácií", "description": "Zoznam rezervácií. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "stock.read", "x-nexo-crm-permission": "stock.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "reservations-create", "tags": [ "Sklad" ], "summary": "Nová rezervácia", "description": "Vytvorí idempotentnú rezerváciu iba z disponibilného množstva a pre viditeľný obchodný subjekt. Expirácia a uvoľnenie sú doménové operácie, nie priamy prepis skladu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "warehouse_id": { "type": "string", "description": "Viditeľný sklad." }, "inventory_item_id": { "type": "string", "description": "Aktívna položka." }, "quantity": { "type": "number", "description": "Rezervované množstvo." }, "subject": { "type": "object", "additionalProperties": true, "description": "Povolená objednávka, obchod alebo projekt." }, "expires_at": { "type": "string", "format": "date-time", "description": "Voliteľná budúca expirácia v tenantovom limite." }, "note": { "type": "string", "description": "Auditná poznámka." } }, "required": [ "warehouse_id", "inventory_item_id", "quantity", "subject" ] }, "example": { "warehouse_id": "warehouse_01J8Y6…", "inventory_item_id": "inventory_item_01J8Y6…", "quantity": 2, "subject": { "type": "order", "id": "order_01J8Y6…" }, "expires_at": "2026-09-05T12:00:00Z", "note": "Rezervácia pre potvrdenú objednávku." } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "stock.reserve", "x-nexo-crm-permission": "stock.reserve", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "stock.reserved" } }, "/v1/crm-tables": { "get": { "operationId": "crm-tables-list", "tags": [ "Publikované CRM tabuľky" ], "summary": "Zoznam CRM tabuliek", "description": "Verejná projekcia pozorovaného NEXO tableLibrary vráti iba tabuľky explicitne publikované pre API a viditeľné aktuálnemu principalu. Nejde o prístup k databázovým tabuľkám ani internému action routeru.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Vyhľadávanie iba v názve a publikovaných metadátach tabuľky.", "schema": { "type": "string" } }, { "name": "folder_id", "in": "query", "required": false, "description": "Voliteľný publikovaný priečinok; interné numerické ID sa neprijíma.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Predvolene sa vracajú iba aktívne tabuľky.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Tabuľky zmenené od UTC času.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor pre stabilné stránkovanie.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov; predvolené 50.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "crm_table_01J8Y6K2…", "type": "crm_table", "attributes": { "name": "D2D západ · publikovaný pohľad", "status": "active", "api_access": "published", "row_count": 428, "sheet_count": 3, "schema_version": 12, "updated_at": "2026-08-25T17:20:00Z", "revision": "rev_31" }, "relationships": { "folder": { "id": "table_folder_01J8Y6…", "name": "D2D kampane" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.read", "x-nexo-crm-permission": "crm_tables.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "crm_table.updated" }, "post": { "operationId": "crm-tables-create", "tags": [ "Publikované CRM tabuľky" ], "summary": "Vytvoriť CRM tabuľku", "description": "Admin-only návrh nad pozorovanou createTable operáciou. Gateway vytvorí bezpečnú predvolenú schému; publikovanie pre API je samostatné explicitné rozhodnutie.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Názov CRM tabuľky." }, "folder_id": { "type": "string", "description": "Viditeľný cieľový priečinok." }, "api_access": { "type": "string", "description": "Navrhovaná gateway politika. Publikovanie vyžaduje správcu a explicitný allowlist schémy." } }, "required": [ "name" ] }, "example": { "name": "D2D západ", "folder_id": "table_folder_01J8Y6…", "api_access": "private" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "crm_table_01J8Y6K2…", "type": "crm_table", "attributes": { "name": "D2D západ · publikovaný pohľad", "status": "active", "api_access": "published", "row_count": 428, "sheet_count": 3, "schema_version": 12, "updated_at": "2026-08-25T17:20:00Z", "revision": "rev_31" }, "relationships": { "folder": { "id": "table_folder_01J8Y6…", "name": "D2D kampane" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.manage", "x-nexo-crm-permission": "crm_tables.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "crm_table.created" } }, "/v1/crm-tables/{table_id}": { "get": { "operationId": "crm-tables-detail", "tags": [ "Publikované CRM tabuľky" ], "summary": "Detail CRM tabuľky", "description": "Vráti bezpečné metadáta, počty, publikovanú verziu schémy a oprávnené akcie bez interných názvov tabuliek.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "crm_table_01J8Y6K2…", "type": "crm_table", "attributes": { "name": "D2D západ · publikovaný pohľad", "status": "active", "api_access": "published", "row_count": 428, "sheet_count": 3, "schema_version": 12, "updated_at": "2026-08-25T17:20:00Z", "revision": "rev_31" }, "relationships": { "folder": { "id": "table_folder_01J8Y6…", "name": "D2D kampane" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.read", "x-nexo-crm-permission": "crm_tables.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "crm-tables-update", "tags": [ "Publikované CRM tabuľky" ], "summary": "Upraviť CRM tabuľku", "description": "Upraví názov, priečinok alebo API publikovanie cez If-Match. Zmena schémy používa samostatné operácie a novú schema_version.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Názov CRM tabuľky." }, "folder_id": { "type": "string", "description": "Viditeľný cieľový priečinok." }, "api_access": { "type": "string", "description": "Navrhovaná gateway politika. Publikovanie vyžaduje správcu a explicitný allowlist schémy." } } }, "example": { "name": "D2D západ 2026", "api_access": "published" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "crm_table_01J8Y6K2…", "type": "crm_table", "attributes": { "name": "D2D západ · publikovaný pohľad", "status": "active", "api_access": "published", "row_count": 428, "sheet_count": 3, "schema_version": 12, "updated_at": "2026-08-25T17:20:00Z", "revision": "rev_31" }, "relationships": { "folder": { "id": "table_folder_01J8Y6…", "name": "D2D kampane" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.manage", "x-nexo-crm-permission": "crm_tables.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.updated" } }, "/v1/crm-tables/{table_id}/duplicate": { "post": { "operationId": "crm-tables-duplicate", "tags": [ "Publikované CRM tabuľky" ], "summary": "Duplikovať CRM tabuľku", "description": "Auditovateľná kópia pozorovanej tabuľky. Nová kópia je vždy private a musí sa publikovať samostatne; veľké kópie môže gateway neskôr presunúť do jobu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Názov novej kópie." } }, "required": [ "name" ] }, "example": { "name": "D2D západ · kópia" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.manage", "x-nexo-crm-permission": "crm_tables.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "crm_table.duplicated" } }, "/v1/crm-tables/{table_id}/archive": { "post": { "operationId": "crm-tables-archive", "tags": [ "Publikované CRM tabuľky" ], "summary": "Archivovať CRM tabuľku", "description": "Idempotentný lifecycle príkaz skryje tabuľku a súvisiace terénne kampane bez hard delete. Vyžaduje vlastníctvo alebo explicitné manage oprávnenie a aktuálny If-Match.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.manage", "x-nexo-crm-permission": "crm_tables.archive", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.archived" } }, "/v1/crm-tables/{table_id}/restore": { "post": { "operationId": "crm-tables-restore", "tags": [ "Publikované CRM tabuľky" ], "summary": "Obnoviť CRM tabuľku", "description": "Obnoví archivovanú tabuľku do viditeľného priečinka. API publikovanie zostane vypnuté, kým ho správca znovu nepotvrdí.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "type": "string" } }, "required": [ "folder_id" ], "additionalProperties": false }, "example": { "folder_id": "table_folder_01J8Y6…" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "crm_table_01J8Y6K2…", "type": "crm_table", "attributes": { "name": "D2D západ · publikovaný pohľad", "status": "active", "api_access": "published", "row_count": 428, "sheet_count": 3, "schema_version": 12, "updated_at": "2026-08-25T17:20:00Z", "revision": "rev_31" }, "relationships": { "folder": { "id": "table_folder_01J8Y6…", "name": "D2D kampane" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.manage", "x-nexo-crm-permission": "crm_tables.restore", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.restored" } }, "/v1/crm-tables/{table_id}/schema": { "get": { "operationId": "crm-table-schema", "tags": [ "Schéma tabuľky" ], "summary": "Publikovaná schéma stĺpcov", "description": "Vráti iba verejné column_key, typ, label, required, read_only, filterable a writable. Interné numerické column_id, SQL typy a skryté systémové stĺpce sa nezverejnia.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "crm_table_schema_01J8Y6…_v12", "type": "crm_table_schema", "attributes": { "version": 12, "columns": [ { "key": "municipality", "label": "Obec", "type": "text", "required": true, "read_only": false, "filterable": true, "writable": true }, { "key": "status", "label": "Stav", "type": "status", "required": true, "read_only": false, "filterable": true, "writable": true, "options": [ "not_visited", "visited_no_answer", "not_interested", "excluded_address", "informed", "come_later", "contact_without_gdpr", "contact_obtained", "connected", "competitor_connected", "order_created" ] } ] } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.read", "x-nexo-crm-permission": "crm_tables.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/crm-tables/{table_id}/columns": { "post": { "operationId": "crm-table-columns-create", "tags": [ "Schéma tabuľky" ], "summary": "Pridať stĺpec", "description": "Admin-only operácia pridá typovaný nesystémový stĺpec a zvýši schema_version. Typy aj šírky sú z allowlistu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string", "description": "Nemenný verejný kľúč stĺpca." }, "label": { "type": "string", "description": "Používateľský názov." }, "type": { "type": "number", "description": "Typ pozorovaný v aktuálnom NEXO table modeli." }, "options": { "type": "array", "items": { "type": "string" }, "description": "Povolené hodnoty pre select; status používa serverový lifecycle." }, "width": { "type": "integer", "format": "int32", "description": "Prezentačná šírka." } }, "required": [ "key", "label", "type" ] }, "example": { "key": "service_interest", "label": "Záujem o službu", "type": "select", "options": [ "internet", "tv", "voice" ], "width": 180 } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.schema.write", "x-nexo-crm-permission": "crm_tables.manage_schema", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.schema_changed" } }, "/v1/crm-tables/{table_id}/columns/{column_id}": { "patch": { "operationId": "crm-table-columns-update", "tags": [ "Schéma tabuľky" ], "summary": "Upraviť stĺpec", "description": "Upraví label, kompatibilný typ, options alebo šírku cez If-Match. Systémový stĺpec ani jeho verejný key nemožno prepísať.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "column_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "width": { "type": "integer" } }, "required": [ "label", "options", "width" ], "additionalProperties": false }, "example": { "label": "Primárny záujem", "options": [ "internet", "tv", "voice", "other" ], "width": 200 } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.schema.write", "x-nexo-crm-permission": "crm_tables.manage_schema", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.schema_changed" } }, "/v1/crm-tables/{table_id}/columns/order": { "put": { "operationId": "crm-table-columns-reorder", "tags": [ "Schéma tabuľky" ], "summary": "Zmeniť poradie stĺpcov", "description": "Idempotentne nastaví poradie viditeľných stĺpcov a novú schema_version; chýbajúci alebo cudzí stĺpec skončí 422.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "column_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "column_ids" ], "additionalProperties": false }, "example": { "column_ids": [ "table_column_01J8Y6A…", "table_column_01J8Y6B…" ] } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.schema.write", "x-nexo-crm-permission": "crm_tables.manage_schema", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.schema_changed" } }, "/v1/crm-tables/{table_id}/sheets": { "get": { "operationId": "crm-table-sheets-list", "tags": [ "Hárky" ], "summary": "Zoznam hárkov", "description": "Vráti viditeľné hárky, stabilné poradie, farbu a počty bez riadkových dát.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.read", "x-nexo-crm-permission": "crm_tables.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "crm-table-sheets-create", "tags": [ "Hárky" ], "summary": "Vytvoriť hárok", "description": "Vytvorí hárok v povolenej tabuľke; seed prázdnych riadkov je serverová politika, nie voľný počet z API.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "name", "color" ], "additionalProperties": false }, "example": { "name": "Bratislavský kraj", "color": "#087FA2" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.write", "x-nexo-crm-permission": "crm_tables.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.sheet_created" } }, "/v1/crm-tables/{table_id}/sheets/{sheet_id}": { "patch": { "operationId": "crm-table-sheets-update", "tags": [ "Hárky" ], "summary": "Upraviť hárok", "description": "Upraví názov alebo farbu hárka cez If-Match. Presuny riadkov ostávajú samostatné auditované operácie.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "sheet_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "name", "color" ], "additionalProperties": false }, "example": { "name": "Bratislava a okolie", "color": "#075E75" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.write", "x-nexo-crm-permission": "crm_tables.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.sheet_updated" } }, "/v1/crm-tables/{table_id}/sheets/{sheet_id}/duplicate": { "post": { "operationId": "crm-table-sheets-duplicate", "tags": [ "Hárky" ], "summary": "Duplikovať hárok", "description": "Vytvorí auditovanú kópiu hárka v rovnakej tabuľke bez zmeny prístupov.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "sheet_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Bratislava · kópia" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.write", "x-nexo-crm-permission": "crm_tables.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.sheet_duplicated" } }, "/v1/crm-tables/{table_id}/rows": { "get": { "operationId": "crm-table-rows-list", "tags": [ "Riadky" ], "summary": "Zoznam riadkov", "description": "Vracajú sa iba riadky, stĺpce a prepojené entity, ktoré principal smie vidieť. Filter je odvodený z publikovanej schémy; raw LIKE, SQL a interný filter_json sú zakázané.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "sheet_id", "in": "query", "required": false, "description": "Voliteľný viditeľný hárok tabuľky.", "schema": { "type": "string" } }, { "name": "view_id", "in": "query", "required": false, "description": "Publikovaný uložený pohľad s vopred schválenými filtrami a stĺpcami.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Povolený riadkový stav z publikovanej schémy.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Vlastník v rámci aktuálneho owner-tree scope.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "required": false, "description": "Iba typované filtre stĺpcov označených v schéme ako filterable; bez SQL, LIKE alebo vlastných výrazov.", "schema": { "type": "object", "additionalProperties": true } }, { "name": "changed_since", "in": "query", "required": false, "description": "Riadky zmenené alebo dotknuté od UTC času.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet riadkov; predvolené 100.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "table_row_01J8Y6K2…", "type": "crm_table_row", "attributes": { "row_number": 42, "status": "not_visited", "values": { "municipality": "Ukážková obec", "street": "Hlavná", "street_number": "12" }, "visibility": "private", "updated_at": "2026-08-25T17:25:00Z", "revision": "rev_18" }, "relationships": { "table": { "id": "crm_table_01J8Y6K2…" }, "sheet": { "id": "table_sheet_01J8Y6…" }, "owner": { "id": "user_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.rows.read", "x-nexo-crm-permission": "crm_tables.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "crm_table.row_updated" }, "post": { "operationId": "crm-table-rows-create", "tags": [ "Riadky" ], "summary": "Pridať riadok", "description": "Vytvorí jeden riadok podľa aktuálnej publikovanej schema_version. Povinný Idempotency-Key chráni formuláre a integrácie pred duplicitou.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sheet_id": { "type": "string", "description": "Viditeľný hárok cieľovej tabuľky." }, "values": { "type": "object", "additionalProperties": true, "description": "Hodnoty podľa verejných column_key z publikovanej schémy; systémové, skryté a read-only stĺpce server odmietne." }, "owner_id": { "type": "string", "description": "Voliteľný viditeľný vlastník." }, "visibility": { "type": "string", "description": "Viditeľnosť nesmie rozšíriť prístup mimo oprávnení volajúceho." } }, "required": [ "values" ] }, "example": { "sheet_id": "table_sheet_01J8Y6…", "values": { "municipality": "Ukážková obec", "street": "Hlavná", "street_number": "12", "status": "not_visited" }, "owner_id": "user_01J8Y6…", "visibility": "private" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "table_row_01J8Y6K2…", "type": "crm_table_row", "attributes": { "row_number": 42, "status": "not_visited", "values": { "municipality": "Ukážková obec", "street": "Hlavná", "street_number": "12" }, "visibility": "private", "updated_at": "2026-08-25T17:25:00Z", "revision": "rev_18" }, "relationships": { "table": { "id": "crm_table_01J8Y6K2…" }, "sheet": { "id": "table_sheet_01J8Y6…" }, "owner": { "id": "user_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.rows.write", "x-nexo-crm-permission": "crm_tables.rows.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "crm_table.row_created" } }, "/v1/crm-tables/{table_id}/rows/{row_id}": { "get": { "operationId": "crm-table-rows-detail", "tags": [ "Riadky" ], "summary": "Detail riadku", "description": "Vracajú sa iba publikované hodnoty, bezpečné linky na viditeľné CRM entity a revision pre optimistický zámok.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "row_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "table_row_01J8Y6K2…", "type": "crm_table_row", "attributes": { "row_number": 42, "status": "not_visited", "values": { "municipality": "Ukážková obec", "street": "Hlavná", "street_number": "12" }, "visibility": "private", "updated_at": "2026-08-25T17:25:00Z", "revision": "rev_18" }, "relationships": { "table": { "id": "crm_table_01J8Y6K2…" }, "sheet": { "id": "table_sheet_01J8Y6…" }, "owner": { "id": "user_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.rows.read", "x-nexo-crm-permission": "crm_tables.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "crm-table-rows-update", "tags": [ "Riadky" ], "summary": "Upraviť riadok", "description": "Upraví iba zapisovateľné column_key a overí row visibility, vlastníka, schema_version aj If-Match. Pri súbežnej zmene vráti 412 namiesto tichého prepísania.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "row_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sheet_id": { "type": "string", "description": "Viditeľný hárok cieľovej tabuľky." }, "values": { "type": "object", "additionalProperties": true, "description": "Hodnoty podľa verejných column_key z publikovanej schémy; systémové, skryté a read-only stĺpce server odmietne." }, "owner_id": { "type": "string", "description": "Voliteľný viditeľný vlastník." }, "visibility": { "type": "string", "description": "Viditeľnosť nesmie rozšíriť prístup mimo oprávnení volajúceho." } } }, "example": { "values": { "status": "contact_obtained", "note": "Kontakt bol získaný v teréne." } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "table_row_01J8Y6K2…", "type": "crm_table_row", "attributes": { "row_number": 42, "status": "not_visited", "values": { "municipality": "Ukážková obec", "street": "Hlavná", "street_number": "12" }, "visibility": "private", "updated_at": "2026-08-25T17:25:00Z", "revision": "rev_18" }, "relationships": { "table": { "id": "crm_table_01J8Y6K2…" }, "sheet": { "id": "table_sheet_01J8Y6…" }, "owner": { "id": "user_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.rows.write", "x-nexo-crm-permission": "crm_tables.rows.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.row_updated" } }, "/v1/crm-tables/{table_id}/rows/{row_id}/archive": { "post": { "operationId": "crm-table-rows-archive", "tags": [ "Riadky" ], "summary": "Archivovať riadok", "description": "Bezpečný verejný lifecycle cez If-Match nad pozorovaným soft-delete správaním. Riadok, audit ani prepojené CRM entity sa fyzicky nemažú.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "row_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.rows.write", "x-nexo-crm-permission": "crm_tables.rows.archive", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.row_archived" } }, "/v1/crm-tables/{table_id}/row-jobs": { "post": { "operationId": "crm-table-row-jobs-create", "tags": [ "Riadky" ], "summary": "Hromadná úprava riadkov", "description": "Asynchrónny job s dry_run, limitom, publikovaným view_id a explicitným allowlistom zmien. Nevystavuje neobmedzený bulk paste ani databázový filter.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "operation": { "type": "string", "format": "date", "description": "Povolená hromadná operácia." }, "view_id": { "type": "string", "description": "Publikovaný uložený pohľad určujúci cieľové riadky." }, "changes": { "type": "object", "additionalProperties": true, "description": "Povolené hodnoty alebo cieľový sheet_id." }, "dry_run": { "type": "boolean", "description": "Predvolene true; vráti počty a konflikty bez zápisu." } }, "required": [ "operation", "view_id" ] }, "example": { "operation": "update", "view_id": "table_view_01J8Y6…", "changes": { "owner_id": "user_01J8Y6…" }, "dry_run": true } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.rows.bulk", "x-nexo-crm-permission": "crm_tables.rows.bulk_edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "crm_table.row_job_completed" } }, "/v1/crm-tables/{table_id}/changes": { "get": { "operationId": "crm-table-changes-list", "tags": [ "Synchronizácia" ], "summary": "Zmeny riadkov", "description": "Kurzorová náhrada pozorovaného sync(since). Vracia bezpečné zmeny a server_time bez pevne zakódovaného limitu 3000 alebo interpretácie interného timestampu klientom.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný sync kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximálny počet zmien.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.rows.read", "x-nexo-crm-permission": "crm_tables.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/crm-tables/{table_id}/rows/{row_id}/links/{entity_type}/{entity_id}": { "put": { "operationId": "crm-table-row-link-assign", "tags": [ "Prepojenia na CRM" ], "summary": "Prepojiť riadok so záznamom", "description": "Idempotentne prepojí riadok s viditeľným klientom, leadom alebo obchodom. Pozorovaný CRM table model nepodporuje týmto linkom kontaktnú osobu a väzba nikdy nerozšíri row ani entity visibility.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "row_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.links.write", "x-nexo-crm-permission": "crm_tables.rows.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.row_linked" } }, "/v1/crm-tables/{table_id}/rows/{row_id}/links/{entity_type}/{entity_id}/remove": { "post": { "operationId": "crm-table-row-link-remove", "tags": [ "Prepojenia na CRM" ], "summary": "Odpojiť riadok od záznamu", "description": "Idempotentný auditovaný príkaz odstráni iba link, nie riadok ani CRM záznam.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "row_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.links.write", "x-nexo-crm-permission": "crm_tables.rows.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.row_unlinked" } }, "/v1/crm-tables/{table_id}/imports": { "post": { "operationId": "crm-table-imports-create", "tags": [ "Import a export" ], "summary": "Importovať riadky", "description": "Asynchrónny import najprv skontroluje súbor, kódovanie, publikovanú schema_version, mapovanie, duplicity a row visibility. Prijatie fronty oznámi crm_table.import_queued; po dokončení worker odošle crm_table.import_completed. Zápis sa spustí až po potvrdenom dry-run výsledku.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "file_id": { "type": "string", "description": "Súbor po antivírusovej a typovej kontrole." }, "sheet_id": { "type": "string", "description": "Cieľový hárok." }, "mapping": { "type": "object", "additionalProperties": true, "description": "Mapovanie vstupných hlavičiek na publikované column_key." }, "dry_run": { "type": "boolean", "description": "Prvý request musí byť true." } }, "required": [ "file_id", "sheet_id", "mapping" ] }, "example": { "file_id": "file_01J8Y6…", "sheet_id": "table_sheet_01J8Y6…", "mapping": { "Obec": "municipality", "Ulica": "street", "Cislo": "street_number" }, "dry_run": true } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.import", "x-nexo-crm-permission": "crm_tables.import", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "crm_table.import_queued" } }, "/v1/crm-tables/{table_id}/exports": { "post": { "operationId": "crm-table-exports-create", "tags": [ "Import a export" ], "summary": "Exportovať tabuľku", "description": "Asynchrónny export použije publikovaný view_id, explicitné stĺpce a aktuálnu row visibility. Prijatie fronty oznámi crm_table.export_queued; pripravený výstup worker oznámi crm_table.export_ready. Výsledok je krátko platný autorizovaný download, nikdy token v trvalej URL.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "view_id": { "type": "string" }, "format": { "type": "string" }, "column_keys": { "type": "array", "items": { "type": "string" } } }, "required": [ "view_id", "format", "column_keys" ], "additionalProperties": false }, "example": { "view_id": "table_view_01J8Y6…", "format": "xlsx", "column_keys": [ "municipality", "street", "street_number", "status" ] } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.export", "x-nexo-crm-permission": "crm_tables.export", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "crm_table.export_queued" } }, "/v1/crm-tables/{table_id}/views": { "get": { "operationId": "crm-table-views-list", "tags": [ "Uložené pohľady" ], "summary": "Zoznam uložených pohľadov", "description": "Verejná projekcia pozorovaných saved filters vráti iba vlastné alebo API-publikované pohľady.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.read", "x-nexo-crm-permission": "crm_tables.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "crm-table-views-create", "tags": [ "Uložené pohľady" ], "summary": "Vytvoriť uložený pohľad", "description": "Uloží typované filtre, zoradenie a allowlist stĺpcov. Publikovanie pre integrácie vyžaduje samostatné oprávnenie.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "filters": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string" } } }, "required": [ "status" ], "additionalProperties": false }, "sort": { "type": "array", "items": { "type": "object", "properties": { "column_key": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "column_key", "direction" ], "additionalProperties": false } }, "column_keys": { "type": "array", "items": { "type": "string" } }, "api_access": { "type": "string" } }, "required": [ "name", "filters", "sort", "column_keys", "api_access" ], "additionalProperties": false }, "example": { "name": "Neobídené adresy", "filters": { "status": [ "not_visited" ] }, "sort": [ { "column_key": "municipality", "direction": "asc" } ], "column_keys": [ "municipality", "street", "street_number", "status" ], "api_access": "private" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.views.write", "x-nexo-crm-permission": "crm_tables.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.view_created" } }, "/v1/crm-tables/{table_id}/views/{view_id}": { "patch": { "operationId": "crm-table-views-update", "tags": [ "Uložené pohľady" ], "summary": "Upraviť uložený pohľad", "description": "Upraví vlastný pohľad cez If-Match; cudzí alebo systémový pohľad zostáva read-only.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "view_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "api_access": { "type": "string" } }, "required": [ "name", "api_access" ], "additionalProperties": false }, "example": { "name": "Neobídené adresy · západ", "api_access": "published" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.views.write", "x-nexo-crm-permission": "crm_tables.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.view_updated" } }, "/v1/crm-tables/{table_id}/views/{view_id}/archive": { "post": { "operationId": "crm-table-views-archive", "tags": [ "Uložené pohľady" ], "summary": "Archivovať uložený pohľad", "description": "Verejný lifecycle cez If-Match nahrádza hard delete uloženého filtra a zachová audit.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "view_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.views.write", "x-nexo-crm-permission": "crm_tables.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.view_archived" } }, "/v1/crm-tables/{table_id}/shares": { "get": { "operationId": "crm-table-shares-list", "tags": [ "Zdieľanie" ], "summary": "Zoznam zdieľaní", "description": "Správca vidí iba bezpečné identifikátory principalov a effective permission; prístup zdedený z role sa cez tento endpoint nemení.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.share", "x-nexo-crm-permission": "crm_tables.share", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/crm-tables/{table_id}/shares/{principal_id}": { "put": { "operationId": "crm-table-share-upsert", "tags": [ "Zdieľanie" ], "summary": "Nastaviť zdieľanie", "description": "Idempotentne nastaví view alebo edit v medziach oprávnení volajúceho. Nikdy neudelí manage_schema, bulk alebo export implicitne.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "principal_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "permission": { "type": "string" } }, "required": [ "permission" ], "additionalProperties": false }, "example": { "permission": "view" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.share", "x-nexo-crm-permission": "crm_tables.share", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.share_changed" } }, "/v1/crm-tables/{table_id}/shares/{principal_id}/revoke": { "post": { "operationId": "crm-table-share-revoke", "tags": [ "Zdieľanie" ], "summary": "Odobrať zdieľanie", "description": "Idempotentný auditovaný príkaz cez If-Match odoberie explicitné zdieľanie; nemení rolu ani hierarchické oprávnenia principalu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "principal_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "crm_tables.share", "x-nexo-crm-permission": "crm_tables.share", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "crm_table.share_revoked" } }, "/v1/field-campaigns": { "get": { "operationId": "field-campaigns-list", "tags": [ "Terénne kampane" ], "summary": "Zoznam terénnych kampaní", "description": "Terénne/D2D kampane nad CRM tabuľkami sú samostatná doména od e-mailového marketingu. Zoznam rešpektuje prístup k zdrojovej tabuľke aj assigned-user scope.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "table_id", "in": "query", "required": false, "description": "Kampane nad viditeľnou CRM tabuľkou.", "schema": { "type": "string" } }, { "name": "assigned_user_id", "in": "query", "required": false, "description": "Priradený používateľ.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Lifecycle kampane.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "field_campaign_01J8Y6K2…", "type": "field_campaign", "attributes": { "name": "D2D západ · september", "status": "active", "selection": { "type": "published_view", "view_id": "table_view_01J8Y6…" }, "linked_rows_count": 185, "updated_at": "2026-08-25T17:30:00Z", "revision": "rev_9" }, "relationships": { "table": { "id": "crm_table_01J8Y6K2…" }, "assigned_user": { "id": "user_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "field_campaigns.read", "x-nexo-crm-permission": "campaigns.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "field_campaign.updated" }, "post": { "operationId": "field-campaigns-create", "tags": [ "Terénne kampane" ], "summary": "Vytvoriť terénnu kampaň", "description": "Vytvorí kampaň nad publikovanou tabuľkou a bezpečným selection kontraktom. Raw filter_json z interného modelu sa neprijíma.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Názov terénnej kampane." }, "table_id": { "type": "string", "description": "Publikovaná CRM tabuľka, z ktorej kampaň vyberá riadky." }, "assigned_user_id": { "type": "string", "description": "Viditeľný aktívny vlastník kampane." }, "selection": { "type": "object", "additionalProperties": true, "description": "Typovaný výber all, range alebo published_view; raw filter_json sa vo verejnom API neprijíma." }, "note": { "type": "string", "description": "Voliteľná auditná poznámka." } }, "required": [ "name", "table_id", "selection" ] }, "example": { "name": "D2D západ · september", "table_id": "crm_table_01J8Y6K2…", "assigned_user_id": "user_01J8Y6…", "selection": { "type": "published_view", "view_id": "table_view_01J8Y6…" }, "note": "Terénna kampaň pre overené adresy." } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "field_campaign_01J8Y6K2…", "type": "field_campaign", "attributes": { "name": "D2D západ · september", "status": "active", "selection": { "type": "published_view", "view_id": "table_view_01J8Y6…" }, "linked_rows_count": 185, "updated_at": "2026-08-25T17:30:00Z", "revision": "rev_9" }, "relationships": { "table": { "id": "crm_table_01J8Y6K2…" }, "assigned_user": { "id": "user_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "field_campaigns.write", "x-nexo-crm-permission": "campaigns.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "field_campaign.created" } }, "/v1/field-campaigns/{campaign_id}": { "get": { "operationId": "field-campaigns-detail", "tags": [ "Terénne kampane" ], "summary": "Detail terénnej kampane", "description": "Vráti bezpečný výber, počet prepojených riadkov, vlastníka a revision bez nekontrolovaného vnútorného filtra.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "field_campaign_01J8Y6K2…", "type": "field_campaign", "attributes": { "name": "D2D západ · september", "status": "active", "selection": { "type": "published_view", "view_id": "table_view_01J8Y6…" }, "linked_rows_count": 185, "updated_at": "2026-08-25T17:30:00Z", "revision": "rev_9" }, "relationships": { "table": { "id": "crm_table_01J8Y6K2…" }, "assigned_user": { "id": "user_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "field_campaigns.read", "x-nexo-crm-permission": "campaigns.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "field-campaigns-update", "tags": [ "Terénne kampane" ], "summary": "Upraviť terénnu kampaň", "description": "Upraví názov, priradenie, bezpečný selection kontrakt alebo poznámku cez If-Match a následne prepočíta linky.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Názov terénnej kampane." }, "table_id": { "type": "string", "description": "Publikovaná CRM tabuľka, z ktorej kampaň vyberá riadky." }, "assigned_user_id": { "type": "string", "description": "Viditeľný aktívny vlastník kampane." }, "selection": { "type": "object", "additionalProperties": true, "description": "Typovaný výber all, range alebo published_view; raw filter_json sa vo verejnom API neprijíma." }, "note": { "type": "string", "description": "Voliteľná auditná poznámka." } } }, "example": { "assigned_user_id": "user_01J8Y6…", "selection": { "type": "published_view", "view_id": "table_view_01J8Y7…" } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "field_campaign_01J8Y6K2…", "type": "field_campaign", "attributes": { "name": "D2D západ · september", "status": "active", "selection": { "type": "published_view", "view_id": "table_view_01J8Y6…" }, "linked_rows_count": 185, "updated_at": "2026-08-25T17:30:00Z", "revision": "rev_9" }, "relationships": { "table": { "id": "crm_table_01J8Y6K2…" }, "assigned_user": { "id": "user_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "field_campaigns.write", "x-nexo-crm-permission": "campaigns.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "field_campaign.updated" } }, "/v1/field-campaigns/{campaign_id}/archive": { "post": { "operationId": "field-campaigns-archive", "tags": [ "Terénne kampane" ], "summary": "Archivovať terénnu kampaň", "description": "Idempotentný príkaz cez If-Match nastaví pozorovaný archived stav; zdrojovú tabuľku ani riadky nemaže.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "field_campaigns.write", "x-nexo-crm-permission": "campaigns.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "field_campaign.archived" } }, "/v1/field-campaigns/{campaign_id}/rows/attach": { "post": { "operationId": "field-campaigns-rows-attach", "tags": [ "Terénne kampane" ], "summary": "Pripojiť riadky ku kampani", "description": "Idempotentne pripojí najviac 250 viditeľných riadkov z rovnakej tabuľky. Cudzie a neviditeľné riadky sa neprezradia v detailnej chybe.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "row_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "row_ids" ], "additionalProperties": false }, "example": { "row_ids": [ "table_row_01J8Y6A…", "table_row_01J8Y6B…" ] } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "field_campaigns.write", "x-nexo-crm-permission": "campaigns.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "field_campaign.rows_attached" } }, "/v1/field-campaigns/{campaign_id}/stats": { "get": { "operationId": "field-campaigns-stats", "tags": [ "Terénne kampane" ], "summary": "Štatistiky terénnej kampane", "description": "Agregované pozorované metriky návštev, kontaktov, objednávok, pripojení, vylúčených adries, penetrácie a konverzie. Malé skupiny sa kvôli súkromiu potlačia.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "period_start", "in": "query", "required": false, "description": "Začiatok porovnávaného obdobia.", "schema": { "type": "string", "format": "date" } }, { "name": "period_end", "in": "query", "required": false, "description": "Koniec porovnávaného obdobia.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "field_campaign_01J8Y6K2…", "type": "field_campaign_stats", "attributes": { "total": 185, "visited": 92, "orders": 11, "acquired_contacts": 38, "penetration_percent": 49.7, "conversion_percent": 28.9, "privacy_threshold_applied": false } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "field_campaigns.stats.read", "x-nexo-crm-permission": "campaigns.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/field-campaigns/stats/compare": { "post": { "operationId": "field-campaigns-stats-compare", "tags": [ "Terénne kampane" ], "summary": "Porovnať terénne kampane", "description": "Porovná najviac 20 viditeľných kampaní a dve obdobia. Vracia iba agregáty, nie osobné alebo riadkové dáta.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_ids": { "type": "array", "items": { "type": "string" } }, "period_start": { "type": "string" }, "period_end": { "type": "string" } }, "required": [ "campaign_ids", "period_start", "period_end" ], "additionalProperties": false }, "example": { "campaign_ids": [ "field_campaign_01J8Y6A…", "field_campaign_01J8Y6B…" ], "period_start": "2026-08-01", "period_end": "2026-08-31" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "field_campaigns.stats.read", "x-nexo-crm-permission": "campaigns.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/marketing-campaigns": { "get": { "operationId": "marketing-campaigns-list", "tags": [ "E-mailové kampane" ], "summary": "Zoznam e-mailových kampaní", "description": "Samostatná doména newsletterov; nejde o terénne kampane nad CRM tabuľkami. Výsledky obsahujú agregované počty doručení, otvorení, kliknutí, odhlásení a bounce udalostí.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Vyhľadávanie v názve, predmete a popise.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Stav e-mailovej kampane.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Kampane v povolenom owner scope.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Povolené radenie; prefix - znamená DESC.", "schema": { "type": "string", "format": "date" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet kampaní; predvolené 25.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "marketing_campaign_01J8Y6K2…", "type": "marketing_campaign", "attributes": { "name": "Septembrové novinky", "subject": "Novinky zo sveta NEXO", "preview_text": "Prehľad nových funkcií", "status": "draft", "sender_mode": "user", "language": "sk", "timezone": "Europe/Bratislava", "recipient_count": 0, "content_schema": { "version": 1, "blocks": [] }, "updated_at": "2026-08-25T17:35:00Z", "revision": "rev_6" }, "relationships": { "owner": { "id": "user_01J8Y6…" }, "template": { "id": "marketing_template_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_campaign.updated" }, "post": { "operationId": "marketing-campaigns-create", "tags": [ "E-mailové kampane" ], "summary": "Vytvoriť draft kampane", "description": "Vytvorí bezpečný draft z viditeľnej šablóny. Odoslanie nie je vedľajší efekt create operácie.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Interný názov kampane." }, "template_id": { "type": "string", "description": "Viditeľná aktívna šablóna použitá pri vytvorení draftu." }, "subject": { "type": "string", "description": "Predmet e-mailu; povinný pred preflight kontrolou." }, "preview_text": { "type": "string", "description": "Krátky náhľadový text." }, "sender_mode": { "type": "string", "description": "Iba nakonfigurovaný a povolený odosielateľ." }, "content_schema": { "type": "object", "additionalProperties": true, "description": "Validovaná verzovaná schéma editora; raw HTML nie je bežný zapisovateľný payload." } }, "required": [ "name" ] }, "example": { "name": "Septembrové novinky", "template_id": "marketing_template_01J8Y6…", "subject": "Novinky zo sveta NEXO", "preview_text": "Prehľad nových funkcií", "sender_mode": "user" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "marketing_campaign_01J8Y6K2…", "type": "marketing_campaign", "attributes": { "name": "Septembrové novinky", "subject": "Novinky zo sveta NEXO", "preview_text": "Prehľad nových funkcií", "status": "draft", "sender_mode": "user", "language": "sk", "timezone": "Europe/Bratislava", "recipient_count": 0, "content_schema": { "version": 1, "blocks": [] }, "updated_at": "2026-08-25T17:35:00Z", "revision": "rev_6" }, "relationships": { "owner": { "id": "user_01J8Y6…" }, "template": { "id": "marketing_template_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.write", "x-nexo-crm-permission": "marketing.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_campaign.created" } }, "/v1/marketing-campaigns/{campaign_id}": { "get": { "operationId": "marketing-campaigns-detail", "tags": [ "E-mailové kampane" ], "summary": "Detail e-mailovej kampane", "description": "Vráti draft alebo odosielací stav, bezpečnú obsahovú schému, publikum, preflight, agregované štatistiky a revision. Jednotliví príjemcovia sú oddelený, vždy redigovaný zoznam.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "marketing_campaign_01J8Y6K2…", "type": "marketing_campaign", "attributes": { "name": "Septembrové novinky", "subject": "Novinky zo sveta NEXO", "preview_text": "Prehľad nových funkcií", "status": "draft", "sender_mode": "user", "language": "sk", "timezone": "Europe/Bratislava", "recipient_count": 0, "content_schema": { "version": 1, "blocks": [] }, "updated_at": "2026-08-25T17:35:00Z", "revision": "rev_6" }, "relationships": { "owner": { "id": "user_01J8Y6…" }, "template": { "id": "marketing_template_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "marketing-campaigns-update", "tags": [ "E-mailové kampane" ], "summary": "Upraviť draft kampane", "description": "Upraví iba draft, paused alebo failed kampaň cez If-Match. Sending a completed obsah je nemenný; raw HTML nie je bežný integračný payload.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Interný názov kampane." }, "template_id": { "type": "string", "description": "Viditeľná aktívna šablóna použitá pri vytvorení draftu." }, "subject": { "type": "string", "description": "Predmet e-mailu; povinný pred preflight kontrolou." }, "preview_text": { "type": "string", "description": "Krátky náhľadový text." }, "sender_mode": { "type": "string", "description": "Iba nakonfigurovaný a povolený odosielateľ." }, "content_schema": { "type": "object", "additionalProperties": true, "description": "Validovaná verzovaná schéma editora; raw HTML nie je bežný zapisovateľný payload." } } }, "example": { "subject": "Septembrové novinky NEXO", "preview_text": "Nové funkcie CRM a ERP" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "marketing_campaign_01J8Y6K2…", "type": "marketing_campaign", "attributes": { "name": "Septembrové novinky", "subject": "Novinky zo sveta NEXO", "preview_text": "Prehľad nových funkcií", "status": "draft", "sender_mode": "user", "language": "sk", "timezone": "Europe/Bratislava", "recipient_count": 0, "content_schema": { "version": 1, "blocks": [] }, "updated_at": "2026-08-25T17:35:00Z", "revision": "rev_6" }, "relationships": { "owner": { "id": "user_01J8Y6…" }, "template": { "id": "marketing_template_01J8Y6…" } } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.write", "x-nexo-crm-permission": "marketing.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "marketing_campaign.updated" } }, "/v1/marketing-campaigns/{campaign_id}/duplicate": { "post": { "operationId": "marketing-campaigns-duplicate", "tags": [ "E-mailové kampane" ], "summary": "Duplikovať e-mailovú kampaň", "description": "Vytvorí nový draft so snapshotom obsahu a publika; odosielací stav, recipients, udalosti ani provider ID nekopíruje.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Septembrové novinky · kópia" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.write", "x-nexo-crm-permission": "marketing.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_campaign.duplicated" } }, "/v1/marketing-campaigns/{campaign_id}/archive": { "post": { "operationId": "marketing-campaigns-archive", "tags": [ "E-mailové kampane" ], "summary": "Archivovať e-mailovú kampaň", "description": "Archivácia cez If-Match je povolená iba pre draft, paused, failed, completed alebo cancelled a zachová audit aj agregované výsledky.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.write", "x-nexo-crm-permission": "marketing.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "marketing_campaign.archived" } }, "/v1/marketing-campaigns/{campaign_id}/preflight": { "post": { "operationId": "marketing-campaigns-preflight", "tags": [ "Odoslanie" ], "summary": "Skontrolovať kampaň", "description": "Overí predmet, povinné odhlásenie, validný obsah, pripojeného odosielateľa, nenulové publikum, supresie a súhlasy bez odoslania správy.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "preflight_01J8Y6…", "type": "marketing_preflight", "attributes": { "ok": true, "checks": { "content": "passed", "subject": "passed", "sender": "passed", "audience": "passed", "consents": "passed" }, "checked_at": "2026-08-25T17:40:00Z" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.write", "x-nexo-crm-permission": "marketing.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "marketing_campaign.preflighted" } }, "/v1/marketing-campaigns/{campaign_id}/audience/preview": { "post": { "operationId": "marketing-campaigns-audience-preview", "tags": [ "Publikum" ], "summary": "Náhľad publika", "description": "Vypočíta zahrnutých, vylúčených, duplicitných, bez e-mailu, bez prístupu a potlačených príjemcov. Ukážka je redigovaná bez PII scope.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "list_ids": { "type": "array", "items": { "type": "string" }, "description": "Viditeľné aktívne zoznamy príjemcov." }, "excluded_list_ids": { "type": "array", "items": { "type": "string" }, "description": "Zoznamy, ktoré sa z publika vždy odčítajú." }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Dynamické segmenty prepočítané v čase odoslania." }, "manual_emails": { "type": "string", "format": "email", "description": "Voliteľné normalizované adresy; server ich deduplikuje a uplatní supresie aj súhlasy." } } }, "example": { "list_ids": [ "marketing_list_01J8Y6…" ], "excluded_list_ids": [ "marketing_list_01J8Y7…" ], "segment_ids": [ "marketing_segment_01J8Y6…" ], "manual_emails": [] } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.write", "x-nexo-crm-permission": "marketing.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/marketing-campaigns/{campaign_id}/audience": { "put": { "operationId": "marketing-campaigns-audience-update", "tags": [ "Publikum" ], "summary": "Nastaviť publikum", "description": "Idempotentne uloží iba viditeľné zoznamy a segmenty na draft, paused alebo failed kampani. Zmena zneplatní preflight a neprenáša row visibility.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "list_ids": { "type": "array", "items": { "type": "string" }, "description": "Viditeľné aktívne zoznamy príjemcov." }, "excluded_list_ids": { "type": "array", "items": { "type": "string" }, "description": "Zoznamy, ktoré sa z publika vždy odčítajú." }, "segment_ids": { "type": "array", "items": { "type": "string" }, "description": "Dynamické segmenty prepočítané v čase odoslania." }, "manual_emails": { "type": "string", "format": "email", "description": "Voliteľné normalizované adresy; server ich deduplikuje a uplatní supresie aj súhlasy." } } }, "example": { "list_ids": [ "marketing_list_01J8Y6…" ], "excluded_list_ids": [ "marketing_list_01J8Y7…" ], "segment_ids": [ "marketing_segment_01J8Y6…" ], "manual_emails": [] } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.write", "x-nexo-crm-permission": "marketing.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "marketing_campaign.audience_updated" } }, "/v1/marketing-campaigns/{campaign_id}/queue": { "post": { "operationId": "marketing-campaigns-queue", "tags": [ "Odoslanie" ], "summary": "Zaradiť kampaň na odoslanie", "description": "Doménový príkaz vyžaduje čerstvý úspešný preflight, approve oprávnenie, Idempotency-Key a voliteľný budúci scheduled_at. Publikom vzniká nemenný snapshot.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string" } }, "required": [ "scheduled_at" ], "additionalProperties": false }, "example": { "scheduled_at": "2026-09-02T08:00:00Z" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.send", "x-nexo-crm-permission": "marketing.approve", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "marketing_campaign.queued" } }, "/v1/marketing-campaigns/{campaign_id}/test-send": { "post": { "operationId": "marketing-campaigns-test-send", "tags": [ "Odoslanie" ], "summary": "Odoslať test kampane", "description": "Test je povolený iba na overené adresy aktuálneho tenantu, nesmie meniť štatistiky kampane a zapisuje samostatný audit.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "verified_recipient_id": { "type": "string" }, "personalization": { "type": "object", "properties": { "first_name": { "type": "string" } }, "required": [ "first_name" ], "additionalProperties": false } }, "required": [ "verified_recipient_id", "personalization" ], "additionalProperties": false }, "example": { "verified_recipient_id": "verified_recipient_01J8Y6…", "personalization": { "first_name": "Ukážkové meno" } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.test_send", "x-nexo-crm-permission": "marketing.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "marketing_campaign.test_sent" } }, "/v1/marketing-campaigns/{campaign_id}/recipients": { "get": { "operationId": "marketing-campaign-recipients-list", "tags": [ "Výsledky kampane" ], "summary": "Zoznam príjemcov", "description": "Vráti stav selected, excluded, queued, processing, retry, sent, delivered, failed, bounced alebo unsubscribed. E-mail zostáva vždy maskovaný a provider chyby sa redigujú.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Povolený odosielací stav.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.recipients.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/marketing-campaigns/{campaign_id}/events": { "get": { "operationId": "marketing-campaign-events-list", "tags": [ "Výsledky kampane" ], "summary": "Udalosti doručenia", "description": "Normalizované sent, delivered, open, click, bounce, complaint a unsubscribe udalosti. Raw provider metadata, tracking tokeny a plné URL parametre sa nezverejňujú.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "required": false, "description": "Normalizovaný typ udalosti.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_campaigns.events.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/marketing/templates": { "get": { "operationId": "marketing-templates-list", "tags": [ "Šablóny a obsah" ], "summary": "Zoznam marketingových šablón", "description": "Vráti systémové a vlastné aktívne šablóny, kompatibilnú schema_version a bezpečný náhľad.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Vyhľadávanie v názve a popise.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet šablón; predvolené 50.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_templates.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "marketing-templates-create", "tags": [ "Šablóny a obsah" ], "summary": "Uložiť kampaň ako šablónu", "description": "Vytvorí šablónu zo snapshotu viditeľnej draft kampane. Provider tokeny, publikum a osobné dáta sa nekopírujú.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "campaign_id", "name", "description" ], "additionalProperties": false }, "example": { "campaign_id": "marketing_campaign_01J8Y6…", "name": "Mesačné novinky", "description": "Schválená firemná šablóna." } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_templates.write", "x-nexo-crm-permission": "marketing.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_template.created" } }, "/v1/marketing/lists": { "get": { "operationId": "marketing-lists-list", "tags": [ "Zoznamy a segmenty" ], "summary": "Zoznamy príjemcov", "description": "Vráti vlastné a viditeľné static alebo excluded zoznamy s agregovaným počtom aktívnych členov.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Typ zoznamu.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_lists.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "marketing-lists-create", "tags": [ "Zoznamy a segmenty" ], "summary": "Vytvoriť zoznam príjemcov", "description": "Vytvorí zoznam s nemenným verejným ID. E-maily sa normalizujú, deduplikujú a pri použití v kampani znovu preveria proti supresiám.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "description", "type" ], "additionalProperties": false }, "example": { "name": "Klienti · novinky", "description": "Schválené publikum pre mesačné novinky.", "type": "static" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_lists.write", "x-nexo-crm-permission": "marketing.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_list.created" } }, "/v1/marketing/lists/{list_id}/members/assign": { "post": { "operationId": "marketing-list-members-assign", "tags": [ "Zoznamy a segmenty" ], "summary": "Pridať CRM záznamy do zoznamu", "description": "Pridá viditeľných klientov, kontakty, leady, obchody alebo projekty; použije ich povolený e-mailový kontakt a vráti agregáty added, duplicates, without_email a inaccessible.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "list_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string" }, "entity_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "entity_type", "entity_ids" ], "additionalProperties": false }, "example": { "entity_type": "contacts", "entity_ids": [ "contact_01J8Y6A…", "contact_01J8Y6B…" ] } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_lists.write", "x-nexo-crm-permission": "marketing.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_list.members_assigned" } }, "/v1/marketing/segments": { "get": { "operationId": "marketing-segments-list", "tags": [ "Zoznamy a segmenty" ], "summary": "Zoznam dynamických segmentov", "description": "Vracajú sa iba aktívne segmenty v owner scope a bezpečné normalizované pravidlá; interné SQL sa nikdy nepublikuje.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_segments.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "marketing-segments-create", "tags": [ "Zoznamy a segmenty" ], "summary": "Vytvoriť dynamický segment", "description": "Vytvorí typovaný segment klientov alebo leadov. Povolené pravidlá sú explicitné a membership sa prepočíta v čase odoslania.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "entity_type": { "type": "string" }, "rules": { "type": "object", "properties": { "territory_id": { "type": "string" }, "created_within_days": { "type": "integer" } }, "required": [ "territory_id", "created_within_days" ], "additionalProperties": false }, "description": { "type": "string" } }, "required": [ "name", "entity_type", "rules", "description" ], "additionalProperties": false }, "example": { "name": "Noví klienti · západ", "entity_type": "clients", "rules": { "territory_id": "territory_west", "created_within_days": 90 }, "description": "Dynamické publikum nových klientov." } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_segments.write", "x-nexo-crm-permission": "marketing.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_segment.created" } }, "/v1/marketing/suppressions": { "get": { "operationId": "marketing-suppressions-list", "tags": [ "Súhlasy a supresie" ], "summary": "Zoznam supresií", "description": "Citlivý zoznam je dostupný iba manage principalu; adresy sú predvolene maskované a export nie je implicitne povolený.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "reason", "in": "query", "required": false, "description": "Normalizovaný dôvod supresie.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_suppressions.read", "x-nexo-crm-permission": "marketing.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "marketing-suppressions-create", "tags": [ "Súhlasy a supresie" ], "summary": "Pridať globálnu supresiu", "description": "Idempotentne potlačí normalizovanú adresu pre marketing, uloží dôvod a audit. Nenahrádza immutable consent ledger ani zákonný titul.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "reason": { "type": "string" }, "note": { "type": "string" } }, "required": [ "email", "reason", "note" ], "additionalProperties": false }, "example": { "email": "kontakt@example.sk", "reason": "manual", "note": "Požiadavka prijatá cez podporu." } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_suppressions.write", "x-nexo-crm-permission": "marketing.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_suppression.created" } }, "/v1/marketing/assets": { "get": { "operationId": "marketing-assets-list", "tags": [ "Šablóny a obsah" ], "summary": "Zoznam marketingových assetov", "description": "Vráti iba bezpečné metadáta obrázkov a súborov vlastného tenantu; binárny obsah používa autorizovaný krátkodobý download.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_assets.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "marketing-assets-create", "tags": [ "Šablóny a obsah" ], "summary": "Nahrať marketingový asset", "description": "Upload prejde limitom, detekciou MIME, dekódovaním obrázka, odstránením nebezpečných metadát a antivírusovou kontrolou.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": { "type": "string" }, "alt_text": { "type": "string" } }, "required": [ "file_id", "alt_text" ], "additionalProperties": false }, "example": { "file_id": "file_01J8Y6…", "alt_text": "Ilustračný obrázok noviniek" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_assets.write", "x-nexo-crm-permission": "marketing.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_asset.ready" } }, "/v1/marketing/content-blocks": { "get": { "operationId": "marketing-content-blocks-list", "tags": [ "Šablóny a obsah" ], "summary": "Zoznam obsahových blokov", "description": "Vráti verziované znovupoužiteľné bloky kompatibilné s publikovanou schémou editora.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_templates.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "marketing-content-blocks-create", "tags": [ "Šablóny a obsah" ], "summary": "Uložiť obsahový blok", "description": "Uloží validovaný blok bez publika, tracking tokenov alebo osobných dát.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "block_schema": { "type": "object", "properties": { "type": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "object", "properties": { "company_name": { "type": "string" } }, "required": [ "company_name" ], "additionalProperties": false } }, "required": [ "type", "version", "content" ], "additionalProperties": false } }, "required": [ "name", "block_schema" ], "additionalProperties": false }, "example": { "name": "Päta s kontaktom", "block_schema": { "type": "footer", "version": 1, "content": { "company_name": "NEXO CRM" } } } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_templates.write", "x-nexo-crm-permission": "marketing.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "marketing_content_block.created" } }, "/v1/marketing/brand-kit": { "get": { "operationId": "marketing-brand-kit-detail", "tags": [ "Značka" ], "summary": "Detail brand kitu", "description": "Vráti povolené farby, fonty, logo asset a odosielateľské metadáta bez provider tajomstiev.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_brand.read", "x-nexo-crm-permission": "marketing.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "marketing-brand-kit-update", "tags": [ "Značka" ], "summary": "Upraviť brand kit", "description": "Manage-only operácia validuje farby, font allowlist a vlastníctvo logo assetu cez If-Match.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "primary_color": { "type": "string", "description": "Primárna farba." }, "secondary_color": { "type": "string", "description": "Sekundárna farba." }, "accent_color": { "type": "string", "description": "Akcentová farba." }, "button_color": { "type": "string", "description": "Farba CTA tlačidiel." }, "font_family": { "type": "string", "description": "Podporovaný font značky." }, "logo_asset_id": { "type": "string", "description": "Viditeľný marketingový asset alebo null." }, "company_name": { "type": "string", "description": "Názov odosielateľa." }, "company_address": { "type": "string", "description": "Poštová adresa." }, "company_phone": { "type": "string", "description": "Kontaktný telefón." }, "company_email": { "type": "string", "format": "email", "description": "Kontaktný e-mail." }, "company_web": { "type": "string", "description": "Web odosielateľa." }, "legal_text": { "type": "string", "description": "Právny text päty." }, "unsubscribe_text": { "type": "string", "description": "Text odhlásenia." } } }, "example": { "primary_color": "#087FA2", "secondary_color": "#075E75", "font_family": "Inter", "logo_asset_id": "marketing_asset_01J8Y6…" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "marketing_brand.write", "x-nexo-crm-permission": "marketing.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "marketing_brand.updated" } }, "/v1/import-definitions": { "get": { "operationId": "import-definitions-list", "tags": [ "Import Center" ], "summary": "Podporované typy importu", "description": "Vráti tenantovo dostupné definície pre clients, contacts, leads, products, inventory, deals, activities, projects a tags. Každá definícia publikuje polia, typy, povinnosť, číselníky a permission requirements.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.read", "x-nexo-crm-permission": "imports.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/import-definitions/{definition_id}": { "get": { "operationId": "import-definitions-detail", "tags": [ "Import Center" ], "summary": "Detail definície importu", "description": "Vráti verziované mapovanie cieľovej entity a kompatibilnú schema_version; interné stĺpce ani fallback SQL sa nezverejňujú.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "definition_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.read", "x-nexo-crm-permission": "imports.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/import-definitions/{definition_id}/template": { "get": { "operationId": "import-definitions-template", "tags": [ "Import Center" ], "summary": "Stiahnuť importnú šablónu", "description": "Autorizovaný krátkodobý download vygeneruje CSV/XLSX šablónu podľa aktuálnej definície a publikovanej schémy.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "definition_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.read", "x-nexo-crm-permission": "imports.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/import-jobs": { "get": { "operationId": "imports-list", "tags": [ "Import Center" ], "summary": "Zoznam importov", "description": "Vráti iba vlastné alebo adminom viditeľné joby, ich bezpečný stav, počty a capability ďalšieho kroku.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "definition_id", "in": "query", "required": false, "description": "Typ importu.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Pozorovaný lifecycle jobu.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.read", "x-nexo-crm-permission": "imports.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "imports-create", "tags": [ "Import Center" ], "summary": "Nahrať a analyzovať import", "description": "Bezpečne a synchrónne vytvorí dry-run náhľad: validuje súbor, definíciu, tenantovú schému, kódovanie, mapovanie a duplicity, ale ešte nezapisuje cieľové CRM záznamy. Až potvrdenie zaradí samotný zápis do worker queue.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "definition_id": { "type": "string", "description": "Dostupná importná definícia." }, "file_id": { "type": "string", "description": "Bezpečne nahraný a skontrolovaný CSV/XLSX súbor." } }, "required": [ "definition_id", "file_id" ] }, "example": { "definition_id": "leads", "file_id": "file_01J8Y6…" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.run", "x-nexo-crm-permission": "imports.run", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "import.dry_run_ready" } }, "/v1/import-jobs/{job_id}": { "get": { "operationId": "imports-detail", "tags": [ "Import Center" ], "summary": "Stav importu", "description": "Vráti stav, verziu definície, počty validných/chybných/duplicitných riadkov, progress a povolený ďalší krok bez celého citlivého súboru.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.read", "x-nexo-crm-permission": "imports.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/import-jobs/{job_id}/rows": { "get": { "operationId": "import-rows-list", "tags": [ "Import Center" ], "summary": "Riadky a chyby importu", "description": "Stránkovaný preview ukáže normalizované hodnoty, field errors a duplicate candidates iba v rozsahu cieľovej module/row visibility.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Stav preview riadku.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.read", "x-nexo-crm-permission": "imports.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/import-jobs/{job_id}/mapping": { "patch": { "operationId": "import-mapping-update", "tags": [ "Import Center" ], "summary": "Upraviť mapovanie", "description": "Upraví mapovanie zdrojových hlavičiek na povolené field_key z definície importu a znovu spustí dry-run analýzu. Zdroj možno určiť presným názvom hlavičky alebo jej nulovým indexom; neznáme, duplicitné a interné polia sa odmietnu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "mapping": { "type": "object", "properties": { "Meno": { "type": "string" }, "E-mail": { "type": "string" }, "Telefón": { "type": "string" }, "Zdroj": { "type": "string" } }, "required": [ "Meno", "E-mail", "Telefón", "Zdroj" ], "additionalProperties": false } }, "required": [ "mapping" ], "additionalProperties": false }, "example": { "mapping": { "Meno": "meno", "E-mail": "email", "Telefón": "telefon", "Zdroj": "zdroj_kontaktu" } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.run", "x-nexo-crm-permission": "imports.run", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "import.dry_run_ready" } }, "/v1/import-jobs/{job_id}/selection": { "patch": { "operationId": "import-selection-update", "tags": [ "Import Center" ], "summary": "Vybrať riadky na import", "description": "Uloží explicitný výber validných preview riadkov a stratégiu povolených duplicít cez If-Match.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "include": { "type": "string" }, "excluded_row_ids": { "type": "array", "items": { "type": "string" } }, "duplicate_strategy": { "type": "string" } }, "required": [ "include", "excluded_row_ids", "duplicate_strategy" ], "additionalProperties": false }, "example": { "include": "valid", "excluded_row_ids": [ "importrow_01J8Y6…" ], "duplicate_strategy": "skip" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.run", "x-nexo-crm-permission": "imports.run", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "import.selection_updated" } }, "/v1/import-jobs/{job_id}/confirm": { "post": { "operationId": "imports-confirm", "tags": [ "Import Center" ], "summary": "Potvrdiť import", "description": "Povinný Idempotency-Key a If-Match s čerstvou dry-run revision zaradia zápis do worker queue. processBatch zostáva interný detail; klient sleduje job alebo webhook.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_valid_rows": { "type": "integer" } }, "required": [ "confirm_valid_rows" ], "additionalProperties": false }, "example": { "confirm_valid_rows": 428 } } } }, "responses": { "202": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.approve", "x-nexo-crm-permission": "imports.run", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "import.queued" } }, "/v1/import-jobs/{job_id}/rollback": { "post": { "operationId": "imports-rollback", "tags": [ "Import Center" ], "summary": "Vrátiť import", "description": "Privilegovaný auditovaný rollback vyžaduje If-Match a synchrónne vráti iba bezpečne nezmenené záznamy podporovanej definície. Cudzie alebo medzičasom zmenené záznamy označí ako konflikty a genericky ich nemaže.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "Nesprávne mapovanie zdroja." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.rollback", "x-nexo-crm-permission": "imports.rollback", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "import.rolled_back" } }, "/v1/import-jobs/{job_id}/corrections": { "get": { "operationId": "import-corrections-list", "tags": [ "Import Center" ], "summary": "Korekcie po importe", "description": "Vráti bezpečné korekcie, preskočené konflikty a odkazy na viditeľné cieľové záznamy.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "imports.read", "x-nexo-crm-permission": "imports.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/users": { "get": { "operationId": "users-list", "tags": [ "Používatelia a tímy" ], "summary": "Zoznam používateľov", "description": "Vracia iba bezpečný verejný profil; nikdy prihlasovacie ani bezpečnostné údaje.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "users.read", "x-nexo-crm-permission": "users.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/teams": { "get": { "operationId": "teams-list", "tags": [ "Používatelia a tímy" ], "summary": "Zoznam tímov", "description": "Zoznam tímov. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "teams.read", "x-nexo-crm-permission": "teams.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/me": { "get": { "operationId": "principal-detail", "tags": [ "Aktuálny principal" ], "summary": "Identita integrácie", "description": "Vráti tenant, bezpečný principal, typ kľúča, prefix, expiráciu a efektívny owner scope. Nikdy nevráti secret, hash ani prihlasovacie údaje.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "profile.read", "x-nexo-crm-permission": "profile.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/me/capabilities": { "get": { "operationId": "principal-capabilities", "tags": [ "Aktuálny principal" ], "summary": "Efektívne capability", "description": "Vysvetlí prienik API scopes, aktuálnych CRM module actions, tenant capability, owner-tree visibility a field allowlistu. Je to diagnostika oprávnení, nie spôsob ich rozšírenia.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "profile.read", "x-nexo-crm-permission": "profile.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/scopes": { "get": { "operationId": "scope-catalog", "tags": [ "Aktuálny principal" ], "summary": "Katalóg API scopes", "description": "Strojovo čitateľný katalóg účinných serverových scopes a modulových závislostí pre administráciu najviac troch aktívnych live kľúčov firmy.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "profile.read", "x-nexo-crm-permission": "profile.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/notifications": { "get": { "operationId": "notifications-list", "tags": [ "Notifikácie" ], "summary": "Moje notifikácie", "description": "Pozorovaný current-user feed vráti iba notifikácie principalu prepojeného s používateľom. Admin broadcast ani cudzie notifikácie nie sú súčasťou v1.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Predvolene unread.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Záznamy zmenené od zadaného UTC času; používa sa s deterministickým kurzorom.", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "required": false, "description": "Voliteľný výber polí; explicitný allowlist API gateway má vždy prednosť.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "notifications.read", "x-nexo-crm-permission": "notifications.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/notifications/unread-count": { "get": { "operationId": "notifications-unread-count", "tags": [ "Notifikácie" ], "summary": "Počet neprečítaných", "description": "Vráti iba agregovaný počet neprečítaných notifikácií aktuálneho principalu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "notifications.read", "x-nexo-crm-permission": "notifications.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/notifications/{notification_id}/read": { "post": { "operationId": "notifications-read", "tags": [ "Notifikácie" ], "summary": "Označiť notifikáciu ako prečítanú", "description": "Idempotentne označí iba vlastnú notifikáciu ako prečítanú.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "notification_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "notifications.write", "x-nexo-crm-permission": "notifications.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "notification.read" } }, "/v1/notifications/read-all": { "post": { "operationId": "notifications-read-all", "tags": [ "Notifikácie" ], "summary": "Označiť všetky ako prečítané", "description": "Idempotentný current-user príkaz; neovplyvní notifikácie iných používateľov.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "notifications.write", "x-nexo-crm-permission": "notifications.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "notifications.read" } }, "/v1/tags": { "get": { "operationId": "tags-list", "tags": [ "Štítky" ], "summary": "Zoznam štítkov", "description": "Vyhľadá aktívne aj archivované štítky podľa verejného opaque id, názvu, skupiny a podporovanej entity. Verejné id gateway interne mapuje na serverový stable_key; interné numerické ID ani stable_key sa v kontrakte nevracajú.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Vyhľadanie podľa verejného opaque id alebo názvu štítka; interný stable_key ani numerické ID sa nezverejňujú.", "schema": { "type": "string" } }, { "name": "entity_type", "in": "query", "required": false, "description": "Capability-obmedzený typ: clients, contacts, leads, deals, projects, products, price-lists, warehouses, inventory-items, finance-documents, calendar-events alebo processes.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Predvolene sa vracajú iba aktívne štítky.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "tag_01J8Y6K2…", "type": "tag", "attributes": { "name": "Webový formulár", "description": "Lead alebo kontakt prijatý cez webový formulár.", "color": "#087FA2", "icon": "globe", "group": { "id": "tag_group_acquisition", "name": "Akvizícia" }, "scopes": [ "leads", "clients", "contacts" ], "status": "active" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "tags.read", "x-nexo-crm-permission": "tags.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "tags-create", "tags": [ "Štítky" ], "summary": "Vytvoriť štítok", "description": "Vytvorí riadený štítok pre povolené entity. Volajúci posiela name, nie vlastné id ani slug. Odpoveď vráti nemenné verejné opaque id; gateway ho mapuje na serverom generovaný stable_key a interné numerické ID nikdy nevystaví. API automaticky nevytvára štítky z neznámeho textu vo formulári.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Používateľský názov štítka; jediný povinný identifikačný údaj od volajúceho." }, "description": { "type": "string", "description": "Voliteľný účel alebo vysvetlenie štítka." }, "color": { "type": "string", "description": "Voliteľná farba z povolenej palety." }, "icon": { "type": "string", "description": "Voliteľný kľúč ikony z verejného allowlistu." }, "group_id": { "type": "string", "description": "Voliteľná existujúca skupina štítkov v rovnakom tenantovi." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Povolené typy z centrálnej TagService capability matice. Priradenie navyše vyžaduje oprávnenie cieľového modulu a row visibility." } }, "required": [ "name" ] }, "example": { "name": "Webový formulár", "description": "Lead alebo kontakt prijatý cez webový formulár.", "color": "#087FA2", "icon": "globe", "group_id": "tag_group_acquisition", "scopes": [ "leads", "clients", "contacts" ] } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "tag_01J8Y6K2…", "type": "tag", "attributes": { "name": "Webový formulár", "description": "Lead alebo kontakt prijatý cez webový formulár.", "color": "#087FA2", "icon": "globe", "group": { "id": "tag_group_acquisition", "name": "Akvizícia" }, "scopes": [ "leads", "clients", "contacts" ], "status": "active" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "tags.write", "x-nexo-crm-permission": "tags.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "tag.created" } }, "/v1/tags/{tag_id}": { "get": { "operationId": "tags-detail", "tags": [ "Štítky" ], "summary": "Detail štítka", "description": "Parameter tag_id je nemenné verejné opaque id vrátené z GET /v1/tags. Gateway ho interne mapuje na serverový stable_key a vráti názov do 160 znakov, popis, farbu, ikonu, skupinu, stav a povolené scopes; interné numerické ID sa neprijíma ani nezverejňuje.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tag_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "tag_01J8Y6K2…", "type": "tag", "attributes": { "name": "Webový formulár", "description": "Lead alebo kontakt prijatý cez webový formulár.", "color": "#087FA2", "icon": "globe", "group": { "id": "tag_group_acquisition", "name": "Akvizícia" }, "scopes": [ "leads", "clients", "contacts" ], "status": "active" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "tags.read", "x-nexo-crm-permission": "tags.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "tags-update", "tags": [ "Štítky" ], "summary": "Upraviť alebo archivovať štítok", "description": "Upraví názov, popis, farbu, ikonu, skupinu, scopes alebo stav cez If-Match. Verejné tag_id zostáva nemenné a gateway ho interne mapuje na serverový stable_key; archivácia zachová audit aj existujúce väzby.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tag_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Nový používateľský názov." }, "description": { "type": "string", "description": "Vysvetlenie účelu štítka." }, "color": { "type": "string", "description": "Farba z povolenej palety." }, "icon": { "type": "string", "description": "Kľúč ikony z verejného allowlistu." }, "group_id": { "type": "string", "description": "Existujúca skupina v rovnakom tenantovi alebo null." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Capability-obmedzené typy entít." }, "status": { "type": "string", "description": "Archivácia je auditovateľná a neodstraňuje históriu." } } }, "example": { "name": "Webový formulár", "description": "Lead alebo kontakt prijatý cez webový formulár.", "color": "#087FA2", "icon": "globe", "group_id": "tag_group_acquisition", "scopes": [ "leads", "clients", "contacts" ], "status": "active" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "tag_01J8Y6K2…", "type": "tag", "attributes": { "name": "Webový formulár", "description": "Lead alebo kontakt prijatý cez webový formulár.", "color": "#087FA2", "icon": "globe", "group": { "id": "tag_group_acquisition", "name": "Akvizícia" }, "scopes": [ "leads", "clients", "contacts" ], "status": "active" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "tags.write", "x-nexo-crm-permission": "tags.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "tag.updated" } }, "/v1/{entity_type}/{entity_id}/tags": { "get": { "operationId": "entity-tags-list", "tags": [ "Štítky" ], "summary": "Štítky priradené k záznamu", "description": "Vráti verejné opaque id a bezpečné atribúty štítkov na type potvrdenom TagService capability maticou: klient, kontakt, lead, obchod, projekt, produkt, cenník, sklad, skladová položka, finančný dokument, kalendárna udalosť alebo proces. Každý modul navyše musí mať vlastné mapovanie permissions a row visibility.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "tag_01J8Y6K2…", "type": "tag", "attributes": { "name": "Webový formulár", "description": "Lead alebo kontakt prijatý cez webový formulár.", "color": "#087FA2", "icon": "globe", "group": { "id": "tag_group_acquisition", "name": "Akvizícia" }, "scopes": [ "leads", "clients", "contacts" ], "status": "active" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "tags.read", "x-nexo-crm-permission": "tags.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/{entity_type}/{entity_id}/tags/{tag_id}": { "put": { "operationId": "entity-tag-assign", "tags": [ "Štítky" ], "summary": "Pridať štítok k záznamu", "description": "Parameter tag_id je verejné opaque id z GET /v1/tags, nie interné numerické ID. Operácia existujúci štítok priradí idempotentne; opakovaný request nevytvorí duplicitu a scope nikdy nerozšíri viditeľnosť záznamu.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "tag_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "tag_assignment_01J8Y6…", "type": "tag_assignment", "relationships": { "entity": { "type": "lead", "id": "lead_01J8Y6…" }, "tag": { "id": "tag_01J8Y6K2…" } }, "attributes": { "assigned_at": "2026-08-25T12:00:01Z", "already_assigned": false } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "tags.assign", "x-nexo-crm-permission": "tags.assign", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "tag.assigned" } }, "/v1/{entity_type}/{entity_id}/tags/{tag_id}/remove": { "post": { "operationId": "entity-tag-remove", "tags": [ "Štítky" ], "summary": "Odobrať štítok zo záznamu", "description": "Parameter tag_id je verejné opaque id z GET /v1/tags. Auditovateľný a idempotentný doménový príkaz odstráni iba väzbu; štítok ani CRM záznam nemaže a interné numerické ID neprijíma.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "tag_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "tag_assignment_01J8Y6…", "type": "tag_assignment", "relationships": { "entity": { "type": "lead", "id": "lead_01J8Y6…" }, "tag": { "id": "tag_01J8Y6K2…" } }, "attributes": { "removed": true, "removed_at": "2026-08-25T12:05:00Z" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "tags.assign", "x-nexo-crm-permission": "tags.assign", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "tag.removed" } }, "/v1/notes": { "post": { "operationId": "notes-create", "tags": [ "Obsah a metadáta" ], "summary": "Pridať poznámku", "description": "Vytvorí auditovanú plain-text poznámku iba na podporenom a viditeľnom zázname. Poznámka neprijíma HTML, tajomstvá ani skryté interné polia.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "subject": { "type": "object", "additionalProperties": true, "description": "Uzavretý type a opaque id cieľového záznamu." }, "text": { "type": "string", "description": "Plain-text obsah poznámky." }, "visibility": { "type": "string", "description": "Poznámka nikdy nerozšíri prístup nad cieľový záznam." } }, "required": [ "subject", "text" ] }, "example": { "subject": { "type": "lead", "id": "lead_01J8Y6…" }, "text": "Klient potvrdil termín prezentácie.", "visibility": "inherit" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "notes.write", "x-nexo-crm-permission": "notes.create", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "note.created" } }, "/v1/file-upload-sessions": { "post": { "operationId": "file-upload-sessions-create", "tags": [ "Prílohy" ], "summary": "Nahrať súbor do bezpečnej session", "description": "Prijme Base64 obsah spolu s názvom, MIME, presnou veľkosťou a SHA-256. CRM overí integritu, skutočný typ, povolenú príponu a bezpečný formát; storage path nikdy nezverejní.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "file_name": { "type": "string", "description": "Bezpečný názov s povolenou príponou." }, "content_type": { "type": "string", "description": "Deklarovaný MIME typ." }, "size_bytes": { "type": "integer", "format": "int32", "description": "Presná veľkosť dekódovaného obsahu." }, "sha256": { "type": "string", "description": "SHA-256 dekódovaného obsahu." }, "content_base64": { "type": "string", "description": "Base64 obsah súboru; binárny limit je 7 MiB a celá JSON požiadavka má limit 10 MiB." } }, "required": [ "file_name", "content_type", "size_bytes", "sha256", "content_base64" ] }, "example": { "file_name": "ponuka.pdf", "content_type": "application/pdf", "size_bytes": 17, "sha256": "64-znakový-sha256-hex", "content_base64": "JVBERi0xLjcKLi4u" } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "files.write", "x-nexo-crm-permission": "files.upload", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "file.uploaded" } }, "/v1/file-upload-sessions/{session_id}/complete": { "post": { "operationId": "file-upload-sessions-complete", "tags": [ "Prílohy" ], "summary": "Dokončiť bezpečný upload", "description": "Znovu overí checksum, skutočný MIME, veľkosť a bezpečnostné kontroly. file.ready vznikne až po úspechu; upload sám nič nepripája k CRM záznamu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sha256": { "type": "string" } }, "required": [ "sha256" ], "additionalProperties": false }, "example": { "sha256": "64-znakový-sha256-hex" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "files.write", "x-nexo-crm-permission": "files.upload", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "file.ready" } }, "/v1/{entity_type}/{entity_id}/attachments": { "get": { "operationId": "entity-attachments-list", "tags": [ "Prílohy" ], "summary": "Prílohy záznamu", "description": "Podmienený adapter nad oddelenými client, lead a deal prílohami. Aktivuje sa až po zjednotení private storage, opaque ID a autorizácie; nikdy nevráti file_path ani storage key.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "files.read", "x-nexo-crm-permission": "files.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/{entity_type}/{entity_id}/attachments/{file_id}": { "put": { "operationId": "entity-attachment-assign", "tags": [ "Prílohy" ], "summary": "Pripojiť súbor k záznamu", "description": "Idempotentne pripojí iba ready súbor rovnakého tenantu k viditeľnému podporovanému záznamu. Link nikdy neudelí prístup k súboru iným principalom.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "files.write", "x-nexo-crm-permission": "files.attach", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "file.attached" } }, "/v1/{entity_type}/{entity_id}/attachments/{file_id}/remove": { "post": { "operationId": "entity-attachment-remove", "tags": [ "Prílohy" ], "summary": "Odpojiť súbor od záznamu", "description": "Odstráni iba konkrétnu väzbu a zachová audit. Fyzické čistenie nepoužívaného objektu rieši interná retenčná fronta.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": null } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "files.write", "x-nexo-crm-permission": "files.attach", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "file.detached" } }, "/v1/attachments/{attachment_id}/content": { "get": { "operationId": "attachments-content", "tags": [ "Prílohy" ], "summary": "Stiahnuť obsah prílohy", "description": "Každé stiahnutie znovu overí viditeľnosť prílohy aj cieľovej entity. Odpoveď vráti názov, MIME, veľkosť, SHA-256 a Base64 obsah v autorizovanej JSON obálke; storage path ani bearer token sa nezverejnia.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "attachment_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "files.read", "x-nexo-crm-permission": "files.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/{entity_type}/{entity_id}/profile-media": { "get": { "operationId": "record-profile-media-detail", "tags": [ "Profilové médiá" ], "summary": "Profilová fotografia leadu alebo klienta", "description": "R69.40 candidate má silnejší private-media kontrakt pre lead a client: autorizované serving, JPEG/PNG/WebP, 5 MB, 24 MP, audit a cleanup queue. Iné entity_type sa odmietnu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "profile_media.read", "x-nexo-crm-permission": "profile_media.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "put": { "operationId": "record-profile-media-update", "tags": [ "Profilové médiá" ], "summary": "Nastaviť profilovú fotografiu", "description": "Pripojí už skontrolovaný JPEG, PNG alebo WebP z file_id, znovu overí veľkosť, rozmery a MIME, aktualizuje audit a starú verziu odošle do cleanup queue.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": { "type": "string" } }, "required": [ "file_id" ], "additionalProperties": false }, "example": { "file_id": "file_01J8Y6…" } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "profile_media.write", "x-nexo-crm-permission": "profile_media.edit", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "profile_media.updated" } }, "/v1/schemas/{entity_type}": { "get": { "operationId": "custom-fields-schema", "tags": [ "Schémy a číselníky" ], "summary": "Schéma vlastných polí", "description": "V1 projekcia publikovanej Record Designer schémy pre client, contact, lead alebo deal. Vracia typ, povinnosť, read-only, viditeľnosť, options, list/export/filter/fulltext vlastnosti; zapisovateľnosť navyše vždy zúži explicitný gateway allowlist. Knižnica netvrdí, že dnes existuje všeobecné natívne per-role field ACL.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "schema_leads_v14", "type": "entity_schema", "attributes": { "entity_type": "leads", "version": 14, "supported_types": [ "text", "textarea", "number", "decimal", "currency", "percent", "select", "multiselect", "radio", "binary_choice", "checkbox", "switch", "rating", "date", "datetime", "time", "email", "phone", "url", "user", "relation", "table_link", "tags" ], "fields": [ { "key": "service_interest", "label": "Záujem o službu", "type": "select", "required": false, "readonly": false, "visible": true, "filterable": true, "fulltext": false, "options": [ "internet", "voice", "tv" ], "gateway_writable": true } ] } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "schemas.read", "x-nexo-crm-permission": "schemas.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/dictionaries/{dictionary}": { "get": { "operationId": "dictionaries-list", "tags": [ "Schémy a číselníky" ], "summary": "Hodnoty číselníka", "description": "Vráti stabilné verejné ID mapované na aktuálne tenantové textové hodnoty pre zdroje, kategórie, stavy, vzťahy, teritóriá, typy a pipeline. Je to v1 adapter, nie dôkaz natívnych *_id stĺpcov. Priorita leadu a deal source/category/close-reasons ostávajú podmienené; vlastníci sa čítajú cez /v1/users.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dictionary", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "description": "Vyhľadanie podľa stabilného kľúča alebo názvu.", "schema": { "type": "string" } }, { "name": "include_inactive", "in": "query", "required": false, "description": "Vráti aj archivované hodnoty pre migráciu a historické mapovanie.", "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "lead_status_new", "type": "dictionary_value", "attributes": { "key": "new", "label": "Nový", "active": true, "order": 10, "contract_origin": "v1_adapter_over_tenant_text_value" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "dictionaries.read", "x-nexo-crm-permission": "dictionaries.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/{entity_type}/{entity_id}/history": { "get": { "operationId": "entity-history-list", "tags": [ "Audit a história" ], "summary": "História zmien záznamu", "description": "Navrhovaná v1 projekcia nad existujúcimi entity históriami vráti iba bezpečne redigované udalosti viditeľného klienta, kontaktu, leadu, obchodu alebo projektu. Rozsah udalostí sa líši podľa entity; endpoint nesľubuje neexistujúcu natívnu revíziu každého poľa.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entity_type", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet udalostí na stránke.", "schema": { "type": "integer", "format": "int32" } }, { "name": "event_type", "in": "query", "required": false, "description": "Voliteľný typ auditnej udalosti.", "schema": { "type": "string" } }, { "name": "created_since", "in": "query", "required": false, "description": "Udalosti od UTC času.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "data": { "id": "change_01J8Y6…", "type": "record_change", "attributes": { "event_type": "field.updated", "changed_fields": [ "owner_id", "category_id" ], "created_at": "2026-08-25T16:50:00Z" }, "actor": { "type": "integration", "id": "api_key_prefix_nexo_7H2" } }, "meta": { "request_id": "req_01J8Y6…" } } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "history.read", "x-nexo-crm-permission": "history.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/webhook-event-types": { "get": { "operationId": "webhook-event-types-list", "tags": [ "Katalóg udalostí" ], "summary": "Typy webhook udalostí", "description": "Vráti verziovaný katalóg dostupných udalostí podľa tenant capabilities a scope. Zahŕňa entity lifecycle, tagy, joby, CRM table row batch zmeny, field campaigns a marketing bez PII v základnom payloade.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "webhooks.read", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/webhook-subscriptions": { "get": { "operationId": "webhooks-list", "tags": [ "Odbery" ], "summary": "Zoznam odberov", "description": "Zoznam aktívnych a vypnutých odberov s redigovanou URL, event filtrami, technickým kontaktom, stavom secret rotácie a health metrikami.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "webhooks.read", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "post": { "operationId": "webhooks-create", "tags": [ "Odbery" ], "summary": "Nový webhook", "description": "Zaregistruje pomenovaný HTTPS cieľ po SSRF kontrole, povolené udalosti a technický kontakt. Podpisový secret sa zobrazí iba raz a v Core zostáva šifrovaný pre doručovací worker.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Názov integrácie alebo účelu webhooku." }, "url": { "type": "string", "format": "uri", "description": "Verejný HTTPS cieľ bez credentials, localhostu, private IP a zakázaných redirectov." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Verziované typy z /v1/webhook-event-types." }, "technical_contact": { "type": "object", "additionalProperties": true, "description": "Meno a platný e-mail zodpovednej osoby." }, "description": { "type": "string", "description": "Účel odberu." } }, "required": [ "name", "url", "events", "technical_contact" ] }, "example": { "name": "Synchronizácia leadov", "url": "https://integracia.example.sk/webhooks/nexo", "events": [ "lead.created.v1", "crm_table.row_updated.v1", "marketing_campaign.queued.v1" ], "technical_contact": { "name": "API prevádzka", "email": "api@example.sk" }, "description": "Synchronizácia interného systému." } } } }, "responses": { "201": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "webhooks.write", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "webhook_subscription.created" } }, "/v1/webhook-subscriptions/{subscription_id}": { "get": { "operationId": "webhooks-detail", "tags": [ "Odbery" ], "summary": "Detail webhooku", "description": "Vráti redigovanú konfiguráciu, event set, stav, technický kontakt, revíziu a verziu secretu bez samotného secretu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "webhooks.read", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false }, "patch": { "operationId": "webhooks-update", "tags": [ "Odbery" ], "summary": "Upraviť webhook", "description": "Upraví URL, event set, technický kontakt alebo popis cez If-Match a znovu vykoná SSRF kontrolu.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" } }, "technical_contact": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "email" ], "additionalProperties": false } }, "required": [ "events", "technical_contact" ], "additionalProperties": false }, "example": { "events": [ "lead.created.v1", "lead.updated.v1", "crm_table.row_updated.v1" ], "technical_contact": { "name": "API prevádzka", "email": "api@example.sk" } } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "webhooks.write", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "webhook_subscription.updated" } }, "/v1/webhook-subscriptions/{subscription_id}/rotate-secret": { "post": { "operationId": "webhooks-rotate-secret", "tags": [ "Odbery" ], "summary": "Rotovať podpisový secret", "description": "Okamžite vytvorí nový secret zobrazený iba raz. Povinné If-Match a Idempotency-Key chránia pred rotáciou nad zastaranou konfiguráciou a nechceným opakovaním.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "webhooks.write", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "webhook_subscription.secret_rotated" } }, "/v1/webhook-subscriptions/{subscription_id}/disable": { "post": { "operationId": "webhooks-disable", "tags": [ "Odbery" ], "summary": "Vypnúť webhook", "description": "Idempotentne zastaví nové doručenia nad aktuálnou If-Match revíziou a zachová históriu aj dead-letter frontu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "webhooks.write", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "webhook_subscription.disabled" } }, "/v1/webhook-subscriptions/{subscription_id}/enable": { "post": { "operationId": "webhooks-enable", "tags": [ "Odbery" ], "summary": "Znovu zapnúť webhook", "description": "Zapne odber nad aktuálnou If-Match revíziou po opakovanej SSRF, event a kontaktnej kontrole. Dostupnosť cieľa sa overuje samostatným testom; staré dead-letter udalosti sa neprehrajú automaticky.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "webhooks.write", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "webhook_subscription.enabled" } }, "/v1/webhook-deliveries": { "get": { "operationId": "webhooks-deliveries-list", "tags": [ "Doručenia" ], "summary": "História doručení", "description": "Stránkovaná prevádzková história s event_id, počtom pokusov, stavom, HTTP kódom, trvaním a next_attempt_at; request/response telá zostávajú mimo odpovede.\n\nBezpečnostný režim: štandardné verejné API v1. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "query", "required": false, "description": "Konkrétny odber.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Stav doručenia.", "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "required": false, "description": "Verziovaný typ udalosti.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Nepriehľadný kurzor z predchádzajúcej odpovede.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Počet výsledkov na stránke. Predvolené: 50.", "schema": { "type": "integer", "format": "int32" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Doručenia zmenené od zadaného UTC času.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "candidate", "x-nexo-scope": "webhooks.read", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/webhook-deliveries/{delivery_id}": { "get": { "operationId": "webhook-delivery-detail", "tags": [ "Doručenia" ], "summary": "Detail doručenia", "description": "Vráti bezpečné prevádzkové metadáta, počet pokusov a diagnostiku bez payloadu, secretu, Authorization hlavičiek alebo tela odpovede cieľa.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "webhooks.read", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/webhook-deliveries/{delivery_id}/replay": { "post": { "operationId": "webhook-delivery-replay", "tags": [ "Doručenia" ], "summary": "Znovu odoslať doručenie", "description": "Manuálny replay vytvorí nové delivery_id s väzbou na pôvodné doručenie a zachová pôvodné event_id; príjemca deduplikuje podľa event_id.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "202": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "webhooks.replay", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "webhook_delivery.replayed" } }, "/v1/webhook-subscriptions/{subscription_id}/test": { "post": { "operationId": "webhooks-test", "tags": [ "Doručenia" ], "summary": "Odoslať test", "description": "Zaradí podpísaný webhook.test.v1 fixture nad aktuálnou If-Match revíziou bez produkčných dát a uloží jeho delivery históriu.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": true, "description": "Revízia z posledného bezpečného čítania.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "202": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "If-Match revízia je zastaraná.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "428": { "description": "Povinná If-Match revízia chýba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "webhooks.test", "x-nexo-crm-permission": "webhooks.manage", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": true, "x-nexo-event": "webhook_delivery.tested" } }, "/v1/jobs": { "get": { "operationId": "jobs-list", "tags": [ "Asynchrónne joby" ], "summary": "Zoznam jobov", "description": "Zjednotený pohľad na vlastné import, export, bulk a odosielacie joby s typom, stavom, progressom a povolenými akciami.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "jobs.read", "x-nexo-crm-permission": "jobs.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/jobs/{job_id}": { "get": { "operationId": "jobs-detail", "tags": [ "Asynchrónne joby" ], "summary": "Detail jobu", "description": "Detail jobu. Operácia rešpektuje tenant, rolu používateľa, viditeľnosť riadkov aj povolené polia v NEXO CRM.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "jobs.read", "x-nexo-crm-permission": "jobs.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/jobs/{job_id}/result": { "get": { "operationId": "jobs-result", "tags": [ "Asynchrónne joby" ], "summary": "Výsledok jobu", "description": "Vráti agregovaný výsledok a bezpečné odkazy na viditeľné zdroje. Export môže obsahovať iba krátko platný autorizovaný download.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "jobs.read", "x-nexo-crm-permission": "jobs.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/jobs/{job_id}/errors": { "get": { "operationId": "jobs-errors-list", "tags": [ "Asynchrónne joby" ], "summary": "Chyby jobu", "description": "Stránkované normalizované chyby s row reference a field errors bez stack trace, filesystem path alebo provider tajomstiev.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "jobs.read", "x-nexo-crm-permission": "jobs.view", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false } }, "/v1/jobs/{job_id}/cancel": { "post": { "operationId": "jobs-cancel", "tags": [ "Asynchrónne joby" ], "summary": "Zrušiť job", "description": "Idempotentný príkaz iba pre cancellable stav. Finančný alebo už potvrdený side effect sa zrušením jobu automaticky nevracia.\n\nBezpečnostný režim: podmienené rozšírenými pravidlami. Runtime: aktívny v API v1.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Nepriehľadný verejný identifikátor alebo povolený typ zdroja v aktuálnom tenantovi.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Jedinečný kľúč bezpečného opakovania každej zápisovej operácie.", "schema": { "type": "string", "minLength": 16, "maxLength": 160 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "Import bol nahradený novším súborom." } } } }, "responses": { "200": { "description": "Úspešná odpoveď v jednotnom NEXO envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "400": { "description": "Neplatná požiadavka alebo validačná chyba.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Chýbajúci, neplatný, expirovaný alebo zrušený API kľúč.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope, CRM oprávnenie, row visibility alebo gateway allowlist operáciu nepovolili.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Zdroj alebo operácia nie sú v aktuálnom tenantovi dostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Konflikt alebo porušenie idempotencie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Telo požiadavky prekročilo bezpečný limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Telo požiadavky nemá podporovaný typ application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validácia vstupu zlyhala alebo obsahuje nepovolené pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit bol prekročený.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Neočakávaná interná chyba bez zverejnenia detailov.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Gateway, tenant alebo závislá služba sú dočasne nedostupné.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-nexo-contract-status": "conditional", "x-nexo-scope": "jobs.cancel", "x-nexo-crm-permission": "jobs.cancel", "x-nexo-runtime-status": "active", "x-nexo-if-match-required": false, "x-nexo-event": "job.cancelled" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "nexo_live_…", "description": "Produkčný tenant-bound API kľúč vytvorený v Nastaveniach NEXO CRM. Tajomstvo sa zobrazí iba raz." } }, "schemas": { "SuccessEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "pagination": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "required": [ "request_id" ], "properties": { "request_id": { "type": "string" }, "revision": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": false }, "ErrorEnvelope": { "type": "object", "required": [ "error", "request_id" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field_errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "request_id": { "type": "string" } }, "additionalProperties": false } } }, "security": [ { "bearerAuth": [] } ], "x-nexo-runtime-status": "active", "x-nexo-operation-count": 216, "x-nexo-active-operation-count": 216, "x-nexo-scopes": [ "activities.read", "calendar.read", "calendar.status", "calendar.write", "clients.read", "clients.write", "contacts.addresses.write", "contacts.anonymize", "contacts.channels.write", "contacts.notes.write", "contacts.read", "contacts.relationships.write", "contacts.status", "contacts.write", "crm_tables.export", "crm_tables.import", "crm_tables.links.write", "crm_tables.manage", "crm_tables.read", "crm_tables.rows.bulk", "crm_tables.rows.read", "crm_tables.rows.write", "crm_tables.schema.write", "crm_tables.share", "crm_tables.views.write", "crm_tables.write", "deals.items.write", "deals.read", "deals.stage", "deals.status", "deals.write", "dictionaries.read", "email_offers.preview", "email_offers.read", "field_campaigns.read", "field_campaigns.stats.read", "field_campaigns.write", "files.read", "files.write", "history.read", "imports.approve", "imports.read", "imports.rollback", "imports.run", "invoices.issue", "invoices.read", "jobs.cancel", "jobs.read", "leads.convert", "leads.read", "leads.status", "leads.write", "marketing_assets.read", "marketing_assets.write", "marketing_brand.read", "marketing_brand.write", "marketing_campaigns.events.read", "marketing_campaigns.read", "marketing_campaigns.recipients.read", "marketing_campaigns.send", "marketing_campaigns.test_send", "marketing_campaigns.write", "marketing_lists.read", "marketing_lists.write", "marketing_segments.read", "marketing_segments.write", "marketing_suppressions.read", "marketing_suppressions.write", "marketing_templates.read", "marketing_templates.write", "notes.write", "notifications.read", "notifications.write", "orders.read", "orders.status", "orders.write", "payments.read", "price_lists.read", "price_lists.write", "processes.read", "products.read", "products.write", "profile.read", "profile_media.read", "profile_media.write", "projects.read", "projects.status", "projects.tasks.read", "projects.tasks.write", "projects.write", "schemas.read", "stock.move", "stock.read", "stock.reserve", "tags.assign", "tags.read", "tags.write", "tasks.complete", "tasks.read", "tasks.write", "teams.read", "users.read", "warehouses.read", "webhooks.read", "webhooks.replay", "webhooks.test", "webhooks.write" ] }