{ "openapi": "3.0.3", "info": { "title": "Signingo API", "version": "1.1.0", "description": "A Signingo API-val a saját programod (ügyviteli rendszer, CRM, webáruház, belső eszköz) gépi úton\néri el ugyanazokat az adatokat és műveleteket, amelyeket a Signingo felületén látsz: profilok,\nszerződéssablonok, szerződések, aláírók, mellékletek, megjegyzések és webhookok.\n\n## Alapok\n\n- **Cím:** minden végpont a `https://api.signingo.hu` alatt érhető el, HTTPS-en.\n- **Formátum:** a kérés és a válasz JSON (`Content-Type: application/json`, `Accept: application/json`).\n A fájlfeltöltések (mellékletek, aláírásképek, aláírt PDF, Excel) `multipart/form-data` kéréssel mennek,\n az exportok `.xlsx` fájlt adnak vissza.\n- **Nincs burok:** a válasz maga az objektum vagy a lista, nincs `data` kulcs körülötte.\n- **Időpontok:** az időbélyegek (`created_at`, `signed_at` …) Unix-időbélyegek másodpercben (egész szám);\n a naptári dátumok (például a születési dátum) `ÉÉÉÉ-HH-NN` alakú szövegek.\n- **Fájlok:** a válaszban a fájlmezők (aláíráskép, melléklet, logó) letölthető URL-t tartalmaznak, vagy `null`-t.\n A szerződés PDF-jét a `generate-preview-url` / `generate-signed-file-url` végpont adja: ez egy aláírt,\n 60 percig érvényes letöltési linket ad vissza, amely hitelesítés nélkül megnyitható.\n- **Nyelv:** a hibaüzenetek a felhasználó beállított nyelvén (magyar vagy angol) jönnek; bejelentkezés\n nélkül az `Accept-Language` fejléc dönt (`hu` / `en`).\n- **Azonosítók:** a szerződések, sablonok és szerződésmeghívások azonosítója egy 16 karakteres `token`;\n a többi rekordé (profil, aláíró, mező, megjegyzés …) egész szám (`id`).\n\n## Alapfogalmak\n\n- **Profil:** az a cég vagy magánszemély, akinek a nevében a szerződést kötöd. Egy felhasználó több\n profilhoz is tartozhat (sajáthoz és meghívottként másokéhoz); a szerződés és a sablon mindig egy profilé.\n- **Aláíró (aláírói hely):** a szerződés egy fele. A küldő fél a profilod, a többi fél a partnered, akit\n e-mailben hívunk meg; ő regisztráció nélkül, a levél linkjével ír alá (lásd *Vendég aláíró*).\n- **Aláírási mód:** elfogadással (aláírásképpel), vagy saját minősített / AVDH-s elektronikus aláírással\n (a letöltött PDF-et aláírva visszatöltik). Amikor minden fél aláírt, a Signingo lezárja a szerződést,\n elektronikus bélyegzőt és időbélyeget tesz rá, és az aláírt PDF-et minden félnek elküldi.\n\n## Hitelesítés\n\nA végpontok (a konfiguráció, a belépés, a regisztráció, a jelszó-visszaállítás, a blog, a szerződésminták és\na vendég aláíró végpontjai kivételével) hitelesítést kérnek: a kérés `Authorization` fejlécében egy\n**Bearer token** megy.\n\n```\nAuthorization: Bearer 12|AbCdEf…\n```\n\nKétféle token van, a hitelesített végpontok mindkettőt elfogadják:\n\n1. **API-kulcs (ajánlott gépi kapcsolathoz).** A Signingóban a **Felhasználóm › API kulcsok** oldalon hozod\n létre ([közvetlen link](https://signingo.hu/profile/api-keys)). A kulcs csak a létrehozáskor látszik,\n ezért azonnal tárold el biztonságos helyen. Addig érvényes, amíg nem törlöd. Az API-kulcs csak olyan\n előfizetési csomaggal működik, amelyben benne van az **API hozzáférés** funkció; enélkül minden kérés\n `402` választ kap.\n2. **Belépési token.** A `POST /login` e-mail-címmel és jelszóval egy belépési tokent (`access_token`,\n 3 napig érvényes) és egy frissítő tokent (`refresh_token`, 60 napig érvényes) ad. Lejárat előtt a\n `POST /refresh-token` a frissítő tokennel új belépési tokent ad. Ha a felhasználónál be van kapcsolva a\n kétlépcsős azonosítás, a belépéshez a hitelesítő alkalmazás kódja is kell (`two_factor_code`).\n\nA token a **létrehozó felhasználó nevében** működik: ugyanazokat a profilokat és szerződéseket látja, és\nugyanazok a jogosultsági és előfizetési korlátok vonatkoznak rá, mint a felhasználóra a felületen.\n\nA Swagger UI-ban a jobb felső **Authorize** gombbal adhatod meg a kulcsot; a „Try it out\" ezután valódi\nkéréseket küld a fiókodba.\n\n## Listák, keresés, lapozás\n\n- A `GET /…` listák (például `GET /profiles`, `GET /webhooks`) **minden** elérhető rekordot visszaadnak,\n lapozás nélkül.\n- A `POST /…/search` végpontok szűrnek és lapoznak. A kérésben: `search` (szabad szöveg; szavanként keres,\n minden szónak szerepelnie kell valamelyik kereshető mezőben), `limit` (1–200, alapból 200), `page`\n (1-től), `order_column` és `order_direction` (`asc` / `desc`), plusz a végpont saját szűrői. A válasz:\n `records` (a találatok), `count` (az összes találat száma), `page`, `max_page`, `order_column`,\n `order_direction`.\n- A `POST /…/export` végpontok ugyanazokkal a szűrőkkel Excel-fájlt (`.xlsx`) adnak vissza, lapozás nélkül.\n\n## Webhookok\n\nA **Webhookok** végpontokkal megadott címekre a Signingo `POST` kérést küld, amikor egy szerződésed vagy\nannak része (aláíró, mező, melléklet, megjegyzés) változik — így nem kell a változásokat lekérdezéssel\nfigyelned. A kérés tartalmát a *Webhookok* témakör írja le.\n\n## Hibák\n\n| Kód | Jelentés | Válasz |\n|---|---|---|\n| `401` | Hiányzó, lejárt vagy érvénytelen token | `{\"message\": \"Unauthenticated.\"}` |\n| `402` | Az előfizetési csomag nem tartalmazza a funkciót (például az API hozzáférést) | `{\"message\": \"…\"}` |\n| `403` | A felhasználónak nincs joga a művelethez (például nem tagja a profilnak) | `{\"message\": \"…\"}` |\n| `404` | A rekord nem létezik, vagy a felhasználó nem éri el | `{\"message\": \"…\"}` |\n| `422` | Hibás adat, vagy a művelet a rekord mostani állapotában nem végezhető el | `{\"message\": \"…\", \"errors\": {\"mezo\": [\"…\"]}}` |\n| `500` | Váratlan hiba | `{\"message\": \"Server Error\"}` |\n\n## Változásnapló\n\n- **1.1.0 (2026-10-27):** a leírás a signingo.hu/api-docs oldalra költözött, és minden végpontja a működés\n szerint pontosítva (mezők, kötelezőség, válaszok, jogosultságok, csomagkorlátok). Javítva a\n `GET /packages/customer-portal` útvonal (a régi leírásban elírva szerepelt). Újonnan leírt végpontok:\n belépés, token-megújítás, kilépés, regisztráció és jelszó-visszaállítás; API-kulcsok; kétlépcsős\n azonosítás; jelszó- és telefonszámcsere; értesítési beállítások; profil-arculat (`/profiles/{id}/branding`);\n szerződés megosztási linkje (`/contracts/{token}/share`); emlékeztető küldése\n (`/contract-signatures/{id}/send-reminder`); korábbi partnerek adatai (`/contract-signatures/known-parties`);\n szerződésminták; blog; és a vendég aláíró végpontjai (`/guest/{guestSignatureToken}/…`).\n- **1.0 (SwaggerHub):** az első nyilvános leírás.\n", "contact": { "name": "Signingo ügyfélszolgálat", "email": "ugyfelszolgalat@signingo.hu", "url": "https://signingo.hu" } }, "servers": [ { "url": "https://api.signingo.hu", "description": "Éles API" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Konfiguráció", "description": "Bejelentkezés nélkül lekérhető beállítások: csomagok és funkcióik, oktatóvideók, a regisztrációs CAPTCHA kulcsa." }, { "name": "Belépés és tokenek", "description": "Belépés e-mail-címmel és jelszóval, a belépési token megújítása és a kilépés." }, { "name": "Regisztráció", "description": "Új felhasználó regisztrációja lépésenként: adatok, e-mail- és telefonszám-ellenőrzés." }, { "name": "Jelszó-visszaállítás", "description": "Elfelejtett jelszó: visszaállító levél kérése és az új jelszó beállítása." }, { "name": "Felhasználó", "description": "A bejelentkezett felhasználó adatai, jelszava, telefonszáma és értesítési beállításai." }, { "name": "Kétlépcsős azonosítás", "description": "A belépés kétlépcsős azonosításának (hitelesítő alkalmazás) be- és kikapcsolása." }, { "name": "API-kulcsok", "description": "A felhasználó saját API-kulcsai a gépi kapcsolathoz." }, { "name": "Webhookok", "description": "Címek, amelyekre a Signingo értesítést küld, amikor a szerződéseid változnak." }, { "name": "Előfizetés", "description": "Előfizetési csomag, számlázási adatok és a szerződéskötési egyenleg." }, { "name": "Számlák", "description": "A Signingo-előfizetés számlái." }, { "name": "Irányítópult", "description": "Az irányítópult összesítő számai." }, { "name": "Jogosultsági figyelmeztetések", "description": "Előzetes ellenőrzés: elérhető-e egy funkció a felhasználó előfizetésében." }, { "name": "Profilok", "description": "A profil az a cég vagy magánszemély, akinek a nevében a szerződéseket kötöd. Egy felhasználó több profilhoz is tartozhat." }, { "name": "Profiltagok és meghívások", "description": "Társfelhasználók meghívása egy profilba, a meghívások és a tagok kezelése." }, { "name": "Partnerek", "description": "A partnereid: akikkel korábban szerződést kötöttél." }, { "name": "Szerződéssablonok", "description": "Újrahasznosítható szerződések: szöveg, aláírók, kitöltendő mezők, mellékletek." }, { "name": "Tömeges szerződéskészítés", "description": "Sok szerződés egyszerre egy sablonból, Excel-táblázat alapján." }, { "name": "Szerződések", "description": "Szerződések létrehozása, kiküldése, kitöltése, archiválása, megosztása és az aláírt PDF letöltése." }, { "name": "Szerződésmeghívások", "description": "Mások által neked küldött szerződések, amelyeket egy saját profilodba fogadhatsz be." }, { "name": "Aláírások", "description": "Az aláírói helyek: az aláíró adatainak kitöltése, aláírás elfogadással vagy saját elektronikus aláírással, emlékeztető." }, { "name": "Megjegyzések", "description": "Megjegyzések egy szerződéshez." }, { "name": "Szerződésminták", "description": "A Signingo kész szerződésmintái, amelyeket a saját profilodba másolhatsz sablonként." }, { "name": "Blog", "description": "A signingo.hu blogcikkei." }, { "name": "Tevékenységnapló", "description": "A felhasználó tevékenységeinek naplója (belépés, módosítások)." }, { "name": "Kiküldött levelek", "description": "A szerződéseidhez kiküldött e-mailek és a kézbesítésük állapota." }, { "name": "Vendég aláíró", "description": "A regisztráció nélküli aláíró végpontjai: a meghívó levél linkjében lévő tokennel azonosít. Ezeket a signingo.hu vendégoldala használja." } ], "paths": { "/configs": { "get": { "tags": [ "Konfiguráció" ], "summary": "Nyilvános konfiguráció lekérdezése", "description": "Visszaadja az előfizetési csomagokat (név, leírás, funkciók, díjak), az útmutató videók listáját és a regisztrációs CAPTCHA nyilvános kulcsát. Bejelentkezés nélkül hívható. A szöveges mezők nyelvét az `Accept-Language` fejléc (hu|en) adja.", "operationId": "getConfigs", "security": [], "responses": { "200": { "description": "A konfiguráció.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Config" } } } } } } }, "/login": { "post": { "tags": [ "Belépés és tokenek" ], "summary": "Belépés email címmel és jelszóval", "description": "Email címmel és jelszóval belép, és visszaadja a felhasználót, egy belépési tokent (3 napig érvényes) és egy frissítő tokent (60 napig érvényes). Bejelentkezés nélkül hívható. Ha a fiókban be van kapcsolva a kétlépcsős azonosítás, a `two_factor_code` mezőben a hitelesítő alkalmazás aktuális 6 jegyű kódja is kell: nélküle, vagy hibás kóddal 422 jön (`errors.two_factor_code`), és felhasználónként 15 percen belül 5 hibás kód után átmenetileg letiltódik a kódellenőrzés. Egy már elfogadott kód ugyanabban az időablakban nem használható újra. A sikeres belépés bekerül a tevékenységnaplóba.", "operationId": "login", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "description": "A fiók email címe.", "format": "email", "example": "minta.peter@example.com" }, "password": { "type": "string", "format": "password", "description": "A fiók jelszava.", "example": "titkos-jelszo" }, "two_factor_code": { "type": "string", "description": "Csak bekapcsolt kétlépcsős azonosításnál kötelező: a hitelesítő alkalmazás 6 jegyű kódja (a nem számjegy karakterek, pl. szóköz, nem számítanak).", "example": "123456" } } } } } }, "responses": { "200": { "description": "Sikeres belépés.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ] }, { "$ref": "#/components/schemas/AuthTokens" } ] } } } }, "401": { "description": "Hibás email cím vagy jelszó.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Hibaüzenet.", "example": "Helytelen email-jelszó páros." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/refresh-token": { "post": { "tags": [ "Belépés és tokenek" ], "summary": "Új tokenpár kérése frissítő tokennel", "description": "Új belépési és új frissítő tokent ad. CSAK a frissítő tokennel hívható (`Authorization: Bearer `); belépési tokennel vagy API-kulccsal 403. Hívd, mielőtt a belépési token lejár, és ezután az új tokenpárt használd.", "operationId": "refreshToken", "responses": { "200": { "description": "Az új tokenpár.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokens" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/logout": { "post": { "tags": [ "Belépés és tokenek" ], "summary": "Kilépés", "description": "Érvényteleníti azt a belépési tokent, amellyel a hívás történt, és naplózza a kilépést. CSAK belépési tokennel hívható; API-kulccsal vagy frissítő tokennel 403. A frissítő token ettől nem válik érvénytelenné.", "operationId": "logout", "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/registrations": { "post": { "tags": [ "Regisztráció" ], "summary": "Regisztráció indítása", "description": "Elindít egy regisztrációt, és emailben megerősítő kódot küld a megadott címre. A válasz `token` mezőjével folytatod: email-megerősítés → telefonszám-megerősítés (SMS-kód) → a fiók létrejön. Bejelentkezés nélkül hívható.\n\n- A `captcha_token` a regisztrációs űrlap CAPTCHA-tokenje; a widget nyilvános kulcsa a `GET /configs` válaszában van (`turnstile.site_key`). A tokent a rendszer minden más mező előtt ellenőrzi, egyszer használható és kb. 5 percig érvényes.\n- Ha a `fill_details` nem igaz, a profiladatok helyére egy mintaprofil kerül (később módosítható); profilmeghívóval érkezőnél ilyenkor nem jön létre saját profil, csak a meghívó profil tagja lesz.\n- A `referral_code` egy másik felhasználó ajánlókódja (`User.token`); ismeretlen kód nem hiba, csak nincs hatása.", "operationId": "createRegistration", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "captcha_token", "name", "email", "phone", "language", "password" ], "properties": { "captcha_token": { "type": "string", "description": "A regisztrációs űrlap CAPTCHA-tokenje (a site key a `GET /configs` válaszában).", "maxLength": 2048 }, "name": { "type": "string", "description": "Teljes név.", "maxLength": 255, "example": "Minta Péter" }, "email": { "type": "string", "description": "Email cím; nem tartozhat hozzá már létező fiók, és a domainjének léteznie kell.", "format": "email", "maxLength": 255, "example": "minta.peter@example.com" }, "phone": { "type": "string", "description": "Telefonszám (erre jön az SMS-kód).", "example": "+36301234567" }, "language": { "type": "string", "description": "Nyelv.", "enum": [ "hu", "en" ], "example": "hu" }, "password": { "type": "string", "format": "password", "minLength": 6, "description": "Jelszó, legalább 6 karakter.", "example": "titkos-jelszo" }, "referral_code": { "type": "string", "description": "Ajánlókód (egy meglévő felhasználó `token`-je).", "nullable": true, "example": "k3f9x0aq2mzr7c1b" }, "fill_details": { "type": "boolean", "description": "Igaz, ha a saját profil adatait most megadod (ekkor a `profile_*` mezők a típusnak megfelelően kötelezők).", "nullable": true, "default": false }, "profile_type": { "type": "string", "description": "A saját profil típusa: cég (`company`) vagy magánszemély (`private_person`). Kötelező, ha `fill_details` igaz.", "enum": [ "company", "private_person" ], "nullable": true }, "profile_name": { "type": "string", "description": "A profil neve (cégnév vagy a magánszemély neve). Kötelező, ha `fill_details` igaz.", "maxLength": 255, "nullable": true, "example": "Minta Kft." }, "profile_tax_number": { "type": "string", "description": "Adószám. Kötelező, ha `profile_type` = `company`.", "maxLength": 255, "nullable": true, "example": "12345678-1-23" }, "profile_mother_name": { "type": "string", "description": "Anyja neve. Kötelező, ha `profile_type` = `private_person`.", "maxLength": 255, "nullable": true }, "profile_birth_date": { "type": "string", "description": "Születési dátum ÉÉÉÉ-HH-NN alakban. Kötelező, ha `profile_type` = `private_person`.", "format": "date", "nullable": true }, "profile_birth_place": { "type": "string", "description": "Születési hely. Kötelező, ha `profile_type` = `private_person`.", "maxLength": 255, "nullable": true }, "profile_address": { "type": "string", "description": "Cím / székhely. Kötelező, ha `fill_details` igaz.", "maxLength": 255, "nullable": true, "example": "1111 Budapest, Minta utca 1." } } } } } }, "responses": { "200": { "description": "A létrejött regisztráció.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registration" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/registrations/{registrationToken}": { "get": { "tags": [ "Regisztráció" ], "summary": "Regisztráció lekérdezése", "description": "A folyamatban lévő regisztráció adatai (pl. a megerősítő linkről visszatérve). Bejelentkezés nélkül hívható: a regisztrációt az útvonalban lévő token azonosítja.", "operationId": "getRegistration", "security": [], "parameters": [ { "name": "registrationToken", "in": "path", "required": true, "description": "A regisztráció tokenje (a `POST /registrations` válaszának `token` mezője). Érvénytelen vagy már befejezett regisztrációnál 404.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A regisztráció.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registration" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Regisztráció" ], "summary": "Regisztráció adatainak módosítása", "description": "Felülírja a regisztráció adatait. Bejelentkezés nélkül hívható: a regisztrációt az útvonalban lévő token azonosítja. Teljes cserét végez: a `profile_*` mezők közül, amit nem küldesz el, az üresre áll, ezért mindig küldd el az összeset. Ha az email cím változik, a megerősítés elvész, és új kód megy az új címre. Ha a telefonszám változik és az email már meg van erősítve, új SMS-kód megy az új számra (ha nem küldhető, 422 `errors.phone`).", "operationId": "updateRegistration", "security": [], "parameters": [ { "name": "registrationToken", "in": "path", "required": true, "description": "A regisztráció tokenje (a `POST /registrations` válaszának `token` mezője). Érvénytelen vagy már befejezett regisztrációnál 404.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "phone", "language" ], "properties": { "name": { "type": "string", "description": "Teljes név.", "maxLength": 255, "example": "Minta Péter" }, "email": { "type": "string", "description": "Email cím; nem tartozhat hozzá már létező fiók, és a domainjének léteznie kell.", "format": "email", "maxLength": 255, "example": "minta.peter@example.com" }, "phone": { "type": "string", "description": "Telefonszám (erre jön az SMS-kód).", "example": "+36301234567" }, "language": { "type": "string", "description": "Nyelv.", "enum": [ "hu", "en" ], "example": "hu" }, "password": { "type": "string", "format": "password", "minLength": 6, "nullable": true, "description": "Új jelszó, legalább 6 karakter; ha üres vagy hiányzik, a régi marad." }, "profile_type": { "type": "string", "description": "A saját profil típusa: cég (`company`) vagy magánszemély (`private_person`).", "enum": [ "company", "private_person" ], "nullable": true }, "profile_name": { "type": "string", "description": "A profil neve (cégnév vagy a magánszemély neve).", "maxLength": 255, "nullable": true, "example": "Minta Kft." }, "profile_tax_number": { "type": "string", "description": "Adószám. Kötelező, ha `profile_type` = `company`.", "maxLength": 255, "nullable": true, "example": "12345678-1-23" }, "profile_mother_name": { "type": "string", "description": "Anyja neve. Kötelező, ha `profile_type` = `private_person`.", "maxLength": 255, "nullable": true }, "profile_birth_date": { "type": "string", "description": "Születési dátum ÉÉÉÉ-HH-NN alakban. Kötelező, ha `profile_type` = `private_person`.", "format": "date", "nullable": true }, "profile_birth_place": { "type": "string", "description": "Születési hely. Kötelező, ha `profile_type` = `private_person`.", "maxLength": 255, "nullable": true }, "profile_address": { "type": "string", "description": "Cím / székhely.", "maxLength": 255, "nullable": true, "example": "1111 Budapest, Minta utca 1." } } } } } }, "responses": { "200": { "description": "A módosított regisztráció.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registration" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/registrations/{registrationToken}/email-verification/send": { "post": { "tags": [ "Regisztráció" ], "summary": "Email-megerősítő kód újraküldése", "description": "Új 6 jegyű megerősítő kódot küld emailben a regisztráció címére; a korábbi kód érvényét veszti. Bejelentkezés nélkül hívható: a regisztrációt az útvonalban lévő token azonosítja. Ha az email cím már meg van erősítve, 403.", "operationId": "sendRegistrationEmailVerification", "security": [], "parameters": [ { "name": "registrationToken", "in": "path", "required": true, "description": "A regisztráció tokenje (a `POST /registrations` válaszának `token` mezője). Érvénytelen vagy már befejezett regisztrációnál 404.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/registrations/{registrationToken}/email-verification/verify": { "post": { "tags": [ "Regisztráció" ], "summary": "Email cím megerősítése kóddal", "description": "Megerősíti az email címet az emailben kapott 6 jegyű kóddal (24 óráig érvényes, egyszer használható). Siker esetén automatikusan SMS-ben elküldi a telefonszám megerősítő kódját. Bejelentkezés nélkül hívható: a regisztrációt az útvonalban lévő token azonosítja. Hibás kódnál 422 (`errors.code`); ha az email már meg van erősítve, 403.", "operationId": "verifyRegistrationEmail", "security": [], "parameters": [ { "name": "registrationToken", "in": "path", "required": true, "description": "A regisztráció tokenje (a `POST /registrations` válaszának `token` mezője). Érvénytelen vagy már befejezett regisztrációnál 404.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer", "description": "Az emailben kapott 6 jegyű kód.", "example": 482913 } } } } } }, "responses": { "200": { "description": "A regisztráció (`email_verified: true`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registration" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/registrations/{registrationToken}/phone-verification/send": { "post": { "tags": [ "Regisztráció" ], "summary": "Telefonszám-megerősítő SMS újraküldése", "description": "Új 6 jegyű kódot küld SMS-ben a regisztráció telefonszámára; a korábbi kód érvényét veszti. Bejelentkezés nélkül hívható: a regisztrációt az útvonalban lévő token azonosítja. Előbb az email címet kell megerősíteni (különben 403), és két kérés között legalább 60 másodpercnek el kell telnie (különben 403). Ha a telefonszámra nem küldhető SMS, 422 (`errors.phone`).", "operationId": "sendRegistrationPhoneVerification", "security": [], "parameters": [ { "name": "registrationToken", "in": "path", "required": true, "description": "A regisztráció tokenje (a `POST /registrations` válaszának `token` mezője). Érvénytelen vagy már befejezett regisztrációnál 404.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/registrations/{registrationToken}/phone-verification/verify": { "post": { "tags": [ "Regisztráció" ], "summary": "Telefonszám megerősítése és a fiók létrehozása", "description": "Megerősíti a telefonszámot az SMS-ben kapott kóddal, és létrehozza a fiókot: a felhasználót, a saját profilt (a regisztráció profiladataival), a profilmeghívók elfogadását (a meghívó profil tulajdonosa emailt kap), és a címedre korábban küldött, még nyitott szerződések hozzád kötését. Ajánlókódos regisztrációnál az ajánló emailt kap. Belépési és frissítő tokent ad vissza, mint a `POST /login`; a regisztráció tokenje ezután megszűnik. Bejelentkezés nélkül hívható: a regisztrációt az útvonalban lévő token azonosítja. Előbb az email címet kell megerősíteni (különben 403); hibás kódnál 422 (`errors.code`).", "operationId": "verifyRegistrationPhone", "security": [], "parameters": [ { "name": "registrationToken", "in": "path", "required": true, "description": "A regisztráció tokenje (a `POST /registrations` válaszának `token` mezője). Érvénytelen vagy már befejezett regisztrációnál 404.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer", "description": "Az SMS-ben kapott 6 jegyű kód.", "example": 731205 } } } } } }, "responses": { "200": { "description": "A fiók létrejött; a felhasználó és a tokenpár.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ] }, { "$ref": "#/components/schemas/AuthTokens" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/password/email": { "post": { "tags": [ "Jelszó-visszaállítás" ], "summary": "Jelszó-visszaállító link kérése", "description": "Emailt küld a megadott címre egy jelszó-visszaállító linkkel. A link 60 percig érvényes, és egy új kérés a korábbi linket érvényteleníti. Bejelentkezés nélkül hívható. Ha a címhez nem tartozik fiók, 422 jön.", "operationId": "sendPasswordResetLink", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "A fiók email címe.", "format": "email", "example": "minta.peter@example.com" } } } } } }, "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/password/reset": { "post": { "tags": [ "Jelszó-visszaállítás" ], "summary": "Új jelszó beállítása", "description": "Beállítja az új jelszót a visszaállító linkben kapott token alapján. A token egyszer használható és 60 percig érvényes; érvénytelen, már felhasznált vagy lejárt tokennél 422 jön (`errors.token`). Bejelentkezés nélkül hívható. A visszaállítás bekerül a tevékenységnaplóba, és a webes felület „maradjak bejelentkezve\" állapota megszűnik.", "operationId": "resetPassword", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "password" ], "properties": { "token": { "type": "string", "description": "A visszaállító link tokenje.", "example": "p0q9w8e7r6t5y4u3" }, "password": { "type": "string", "format": "password", "minLength": 6, "description": "Az új jelszó, legalább 6 karakter.", "example": "uj-titkos-jelszo" } } } } } }, "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/user": { "get": { "tags": [ "Felhasználó" ], "summary": "Saját felhasználói adatok lekérése", "description": "Visszaadja a bejelentkezett felhasználó adatait: név, elérhetőségek, nyelv, számlázási adatok, alapértelmezett profilok, értesítési beállítások, az aktuális előfizetési csomag és funkciói, valamint hogy be van-e kapcsolva a kétlépcsős azonosítás. Belépési tokennel és API-kulccsal is hívható.", "operationId": "getCurrentUser", "responses": { "200": { "description": "A bejelentkezett felhasználó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } }, "put": { "tags": [ "Felhasználó" ], "summary": "Név és nyelv módosítása", "description": "Módosítja a bejelentkezett felhasználó nevét és nyelvét. Mindkét mezőt meg kell adnod. A nyelv határozza meg a válaszok, a hibaüzenetek és a neked küldött levelek nyelvét. A módosítás bekerül a tevékenységnaplódba.", "operationId": "updateCurrentUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "language" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Minta Péter", "description": "A teljes neved." }, "language": { "type": "string", "enum": [ "hu", "en" ], "example": "hu", "description": "A felület és a levelek nyelve." } } } } } }, "responses": { "200": { "description": "A módosított felhasználó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/user/change-password": { "post": { "tags": [ "Felhasználó" ], "summary": "Jelszó megváltoztatása", "description": "Megváltoztatja a bejelentkezett felhasználó jelszavát; ehhez a jelenlegi jelszót is meg kell adnod. A módosítás bekerül a tevékenységnaplódba. A már kiadott belépési tokenek és API-kulcsok érvényesek maradnak — ha a jelszócsere oka egy kiszivárgott hozzáférés, töröld az API-kulcsaidat is.", "operationId": "changePassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "current_password", "new_password" ], "properties": { "current_password": { "type": "string", "format": "password", "description": "A jelenlegi jelszavad (ellenőrizzük)." }, "new_password": { "type": "string", "format": "password", "minLength": 6, "description": "Az új jelszó, legalább 6 karakter." } } } } } }, "responses": { "200": { "description": "A jelszó megváltozott, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/user/notification-settings": { "put": { "tags": [ "Felhasználó" ], "summary": "Értesítési beállítások mentése", "description": "Be- vagy kikapcsolja a kikapcsolható levélcsoportokat. Mindhárom csoportot meg kell adnod. A kötelező levelek (meghívók, emlékeztetők, a megkötött szerződés, jelszó- és megerősítő levelek) egyik csoportba sem tartoznak, ezeket mindig megkapod. Alapértelmezésben minden csoport be van kapcsolva.", "operationId": "updateNotificationSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "partner_activity", "comments", "news" ], "properties": { "partner_activity": { "type": "boolean", "example": true, "description": "Levél a partnereid tevékenységéről a közös szerződéseken (pl. elfogadta, kitöltötte, aláírta)." }, "comments": { "type": "boolean", "example": true, "description": "Levél a szerződésekhez írt új megjegyzésekről." }, "news": { "type": "boolean", "example": false, "description": "Hírek, újdonságok és tájékoztató levelek a Signingótól." } } } } } }, "responses": { "200": { "description": "A felhasználó a mentett `notification_settings` mezővel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/user/send-phone-change-request": { "post": { "tags": [ "Felhasználó" ], "summary": "Telefonszám-csere indítása (SMS-kód küldése)", "description": "A telefonszám cseréjének első lépése: az új számra SMS-ben 6 jegyű ellenőrző kódot küld, amely 24 óráig érvényes. A cserét a `POST /user/verify-phone-change-request` végponttal fejezed be. Új kódot legkorábban 60 másodperc múlva kérhetsz; egy új kód az előzőt érvényteleníti. Ha a megadott szám megegyezik a jelenlegivel, vagy az SMS nem küldhető ki, 422-t kapsz.", "operationId": "sendPhoneChangeRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "pattern": "^\\+\\d{7,14}$", "example": "+36301234567", "description": "Az új telefonszám nemzetközi formában: `+` jel, utána 7–14 számjegy, szóköz nélkül." } } } } } }, "responses": { "200": { "description": "A kódot elküldtük, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/user/verify-phone-change-request": { "post": { "tags": [ "Felhasználó" ], "summary": "Telefonszám-csere megerősítése", "description": "A telefonszám cseréjének második lépése: a kapott SMS-kóddal megerősítve a fiókod telefonszáma az új számra változik. A kód egyszer használható fel. A csere bekerül a tevékenységnaplódba.", "operationId": "verifyPhoneChangeRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "integer", "example": 482913, "description": "Az SMS-ben kapott 6 jegyű ellenőrző kód." } } } } } }, "responses": { "200": { "description": "A telefonszám megváltozott, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/user/two-factor/enable": { "post": { "tags": [ "Kétlépcsős azonosítás" ], "summary": "Kétlépcsős azonosítás bekapcsolásának indítása", "description": "Új titkos kulcsot hoz létre a hitelesítő alkalmazásodhoz (pl. Google Authenticator), és visszaadja a beolvasandó QR-kódot. A kétlépcsős azonosítás ekkor még NEM él: a `POST /user/two-factor/confirm` végponttal, az alkalmazás első kódjával kapcsolod be. Ismételt hívás új kulcsot ad (az előző, meg nem erősített kulcs elvész). Ha már be van kapcsolva, 422-t kapsz. Helyreállító kódok nincsenek: ha elveszíted a telefonodat, az ügyfélszolgálat tudja kikapcsolni.", "operationId": "enableTwoFactor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string", "format": "password", "description": "A jelenlegi jelszavad (ellenőrizzük)." } } } } } }, "responses": { "200": { "description": "A hitelesítő alkalmazás beállításához szükséges adatok.", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "example": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP", "description": "A titkos kulcs (Base32), ha kézzel írnád be az alkalmazásba." }, "url": { "type": "string", "example": "otpauth://totp/Signingo:minta%40example.com?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Signingo", "description": "Az `otpauth://` cím, ugyanaz, amit a QR-kód tartalmaz." }, "qr_svg": { "type": "string", "description": "A QR-kód SVG-képként (192×192), közvetlenül megjeleníthető." } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/user/two-factor/confirm": { "post": { "tags": [ "Kétlépcsős azonosítás" ], "summary": "Kétlépcsős azonosítás megerősítése", "description": "A hitelesítő alkalmazás aktuális kódjával bekapcsolja a kétlépcsős azonosítást. Ezután a `POST /login` a jelszó mellett a `two_factor_code` mezőt is kéri. Előbb a `POST /user/two-factor/enable` végpontot kell hívnod. 5 hibás kód után 15 percig minden kódot elutasítunk. A bekapcsolás bekerül a tevékenységnaplódba.", "operationId": "confirmTwoFactor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "maxLength": 10, "example": "123456", "description": "A hitelesítő alkalmazás aktuális 6 jegyű kódja (a szóköz és más nem számjegy karakterek nem számítanak)." } } } } } }, "responses": { "200": { "description": "A felhasználó, `two_factor_enabled: true` értékkel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/user/two-factor/disable": { "post": { "tags": [ "Kétlépcsős azonosítás" ], "summary": "Kétlépcsős azonosítás kikapcsolása", "description": "Kikapcsolja a kétlépcsős azonosítást és törli a titkos kulcsot. A jelszavad ÉS a hitelesítő alkalmazás egy érvényes kódja is kell hozzá. 5 hibás kód után 15 percig minden kódot elutasítunk. A kikapcsolás bekerül a tevékenységnaplódba.", "operationId": "disableTwoFactor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password", "code" ], "properties": { "password": { "type": "string", "format": "password", "description": "A jelenlegi jelszavad (ellenőrizzük)." }, "code": { "type": "string", "maxLength": 10, "example": "123456", "description": "A hitelesítő alkalmazás aktuális 6 jegyű kódja (a szóköz és más nem számjegy karakterek nem számítanak)." } } } } } }, "responses": { "200": { "description": "Kikapcsolva, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api-keys": { "get": { "tags": [ "API-kulcsok" ], "summary": "API-kulcsaim listája", "description": "Az API-kulcs (`developer-api` képességű token) a saját rendszered és a Signingo összekötésére való: ugyanúgy `Authorization: Bearer ` fejlécben küldöd, mint a belépési tokent, de nem jár le, és nem kell frissíteni. Ez a végpont a bejelentkezett felhasználó API-kulcsait listázza a legújabbal kezdve; a kulcsok titkos értékét nem adja vissza (az csak létrehozáskor látható).", "operationId": "listApiKeys", "responses": { "200": { "description": "Az API-kulcsok.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } }, "post": { "tags": [ "API-kulcsok" ], "summary": "API-kulcs létrehozása", "description": "Az API-kulcs (`developer-api` képességű token) a saját rendszered és a Signingo összekötésére való: ugyanúgy `Authorization: Bearer ` fejlécben küldöd, mint a belépési tokent, de nem jár le, és nem kell frissíteni. A válaszban kapott `token` értéket CSAK most látod, utána nem kérhető le újra — tárold biztonságosan. A kulcs csak akkor használható, ha az előfizetési csomagodban benne van az `api` funkció; ha nincs (vagy később kikerül), minden vele indított kérés 402-t kap. A kulcs a fiókod teljes jogkörével dolgozik, ezért ne add ki harmadik félnek.", "operationId": "createApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Ügyviteli rendszer", "description": "A kulcs neve, hogy később felismerd (pl. melyik rendszer használja)." } } } } } }, "responses": { "200": { "description": "Az új API-kulcs titkos értéke.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "17|f3Kq9ZsXbV0mT2aLpR8yW4nE6cU1hJ5dG7oI3kM9", "description": "A kulcs teljes értéke (`|` alakban); ezt küldd a `Bearer` fejlécben." } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api-keys/{id}": { "get": { "tags": [ "API-kulcsok" ], "summary": "Egy API-kulcs adatai", "description": "Egy saját API-kulcs neve, létrehozásának és utolsó használatának ideje (a titkos értéke nem). Más kulcsára 404-et kapsz.", "operationId": "getApiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az API-kulcs azonosítója (`id`; ez a kulcs `|` előtti része is).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Az API-kulcs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "API-kulcsok" ], "summary": "API-kulcs törlése (visszavonása)", "description": "Véglegesen visszavonja az API-kulcsot: a vele indított kérések ettől kezdve 401-et kapnak. Csak saját kulcs törölhető.", "operationId": "deleteApiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az API-kulcs azonosítója (`id`).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Sikeres törlés, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhooks": { "get": { "tags": [ "Webhookok" ], "summary": "Webhookjaim listája", "description": "A bejelentkezett felhasználó webhook-címei a legújabbal kezdve. Csomagkorlát nélkül hívható, de értesítést csak akkor küldünk a címekre, ha a csomagodban benne van az `api` funkció.", "operationId": "listWebhooks", "responses": { "200": { "description": "A webhookok.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } }, "post": { "tags": [ "Webhookok" ], "summary": "Webhook létrehozása", "description": "Felvesz egy URL-t, amelyre a Signingo a szerződéseid változásairól értesítést küld. Az `api` funkció kell hozzá a csomagodban: ha nincs benne, csomagkorlát miatt 403-at kapsz (a hibaüzenet csomagváltást javasol).\n\n**Mikor hívunk?** Amikor egy szerződés vagy hozzá tartozó adat (aláírók, kitöltendő mezők, csatolmányok, megjegyzések) létrejön vagy megváltozik — bármelyik fél tette, a felületen, az API-n vagy vendégként a meghívó linkjén. Egy műveletben történt több változásról szerződésenként EGY hívás megy. Törlésről nem küldünk értesítést.\n\n**Kinek?** A szerződést létrehozó profil és az aláíró felek profiljainak minden olyan tagjának, akinek az előfizetési csomagjában benne van az `api` funkció — a tag összes webhook-címére. A saját változtatásaidról is kapsz hívást.\n\n**Hogyan?** `POST` kérés a megadott URL-re, `Content-Type: application/json` törzzsel (lásd a `WebhookPayload` sémát): `model` (mindig `\"contract\"`), `data` (a szerződés a címzett jogosultságaival, ahogy a `GET /contracts/{id}` is mutatná) és `time` (a változás Unix-időbélyege másodpercben). Hitelesítő fejlécet vagy aláírást a hívás nem tartalmaz: kezeld a webhook-URL-t titokként (pl. tegyél bele egy hosszú, véletlen részt), és a `data.token` alapján kérd le a szerződést az API-ról, ha biztosra akarsz menni. Bármely 2xx válasz sikeresnek számít; sikertelen hívást nem ismétlünk meg.", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 255, "example": "https://erp.example.com/hooks/signingo/9f2c7e1a", "description": "A hívandó cím. Érvényes URL legyen, amelynek a host-neve a mentéskor feloldható a DNS-ben." } } } } } }, "responses": { "200": { "description": "A létrehozott webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "callbacks": { "contractChanged": { "{$request.body#/url}": { "post": { "summary": "Értesítés egy szerződés változásáról", "description": "**Mikor hívunk?** Amikor egy szerződés vagy hozzá tartozó adat (aláírók, kitöltendő mezők, csatolmányok, megjegyzések) létrejön vagy megváltozik — bármelyik fél tette, a felületen, az API-n vagy vendégként a meghívó linkjén. Egy műveletben történt több változásról szerződésenként EGY hívás megy. Törlésről nem küldünk értesítést.\n\n**Kinek?** A szerződést létrehozó profil és az aláíró felek profiljainak minden olyan tagjának, akinek az előfizetési csomagjában benne van az `api` funkció — a tag összes webhook-címére. A saját változtatásaidról is kapsz hívást.\n\n**Hogyan?** `POST` kérés a megadott URL-re, `Content-Type: application/json` törzzsel (lásd a `WebhookPayload` sémát): `model` (mindig `\"contract\"`), `data` (a szerződés a címzett jogosultságaival, ahogy a `GET /contracts/{id}` is mutatná) és `time` (a változás Unix-időbélyege másodpercben). Hitelesítő fejlécet vagy aláírást a hívás nem tartalmaz: kezeld a webhook-URL-t titokként (pl. tegyél bele egy hosszú, véletlen részt), és a `data.token` alapján kérd le a szerződést az API-ról, ha biztosra akarsz menni. Bármely 2xx válasz sikeresnek számít; sikertelen hívást nem ismétlünk meg.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "2XX": { "description": "A hívást sikeresnek tekintjük." } } } } } } } }, "/webhooks/{id}": { "get": { "tags": [ "Webhookok" ], "summary": "Egy webhook lekérése", "description": "Egy saját webhook adatai. Más felhasználó webhookjára 404-et kapsz.", "operationId": "getWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A webhook azonosítója (`id`).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "A webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Webhookok" ], "summary": "Webhook címének módosítása", "description": "Lecseréli egy saját webhook URL-jét; a következő értesítések már az új címre mennek. Az `api` funkció kell hozzá a csomagodban: ha nincs benne, csomagkorlát miatt 403-at kapsz (a hibaüzenet csomagváltást javasol). A hívások formáját a `POST /webhooks` leírása és a `WebhookPayload` séma mutatja.", "operationId": "updateWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A webhook azonosítója (`id`).", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 255, "example": "https://erp.example.com/hooks/signingo/4b8d0c3e", "description": "Az új hívandó cím. Érvényes URL legyen, amelynek a host-neve a mentéskor feloldható a DNS-ben." } } } } } }, "responses": { "200": { "description": "A módosított webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Webhookok" ], "summary": "Webhook törlése", "description": "Törli a webhookot; erre a címre ezután nem küldünk értesítést. Csomagkorlát nélkül hívható.", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A webhook azonosítója (`id`).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Sikeres törlés, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/packages/billing-details": { "post": { "tags": [ "Előfizetés" ], "summary": "Számlázási adatok mentése", "description": "Elmenti a bejelentkezett felhasználó számlázási adatait; a számláidon ezek szerepelnek. Előfizetni (`POST /packages/subscribe`) csak kitöltött számlázási adatokkal lehet. A módosítás bekerül a tevékenységnaplódba.", "operationId": "updateBillingDetails", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "billing_name", "billing_city", "billing_zip", "billing_address" ], "properties": { "billing_name": { "type": "string", "maxLength": 255, "example": "Minta Kft.", "description": "A számlán szereplő név (cégnév vagy magánszemély neve)." }, "billing_city": { "type": "string", "maxLength": 255, "example": "Budapest", "description": "Település." }, "billing_zip": { "type": "integer", "minimum": 1000, "maximum": 9999, "example": 1111, "description": "Négyjegyű magyar irányítószám." }, "billing_address": { "type": "string", "maxLength": 255, "example": "Minta utca 1.", "description": "Utca, házszám." }, "billing_tax_number": { "type": "string", "nullable": true, "example": "12345676-2-42", "description": "Magyar adószám (`12345678-1-23` formában, kötőjelek nélkül is elfogadjuk; az ellenőrző számjegyet is vizsgáljuk). Magánszemélynek hagyd üresen." } } } } } }, "responses": { "200": { "description": "A felhasználó a mentett számlázási adatokkal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/packages/subscribe": { "post": { "tags": [ "Előfizetés" ], "summary": "Előfizetés vagy csomagváltás", "description": "Előfizetést indít vagy csomagot vált, és visszaad egy URL-t, ahová a felhasználót át kell irányítanod:\n- **nincs aktív előfizetésed**: a fizetési szolgáltató fizetési oldalának URL-je (ott adod meg a kártyát; kuponkód is beváltható);\n- **van aktív előfizetésed, és ugyanezt a csomagot és időszakot kéred, vagy az ingyenes csomagot**: az ügyfélportál URL-je, ahol az előfizetésedet kezelheted vagy lemondhatod;\n- **van aktív előfizetésed, és másik csomagot vagy időszakot kérsz**: a váltás AZONNAL megtörténik, a különbözetről számla készül, és a weboldal előfizetés-oldalának URL-je jön vissza.\n\nKitöltött számlázási adatok kellenek hozzá (különben 403). Az ingyenes csomagra előfizetés nélkül nem lehet „váltani\" (már azt használod), próbaidőszak alatt sem (422).", "operationId": "subscribe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "package", "period" ], "properties": { "package": { "type": "string", "enum": [ "free", "basic", "standard", "premium" ], "example": "premium", "description": "A választott csomag azonosítója." }, "period": { "type": "string", "enum": [ "monthly", "yearly" ], "example": "yearly", "description": "Számlázási időszak: havi vagy éves." } } } } } }, "responses": { "200": { "description": "Az URL, ahová a felhasználót át kell irányítani.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://checkout.example.com/c/pay/cs_test_a1B2c3", "description": "A fizetési oldal, az ügyfélportál vagy a weboldal előfizetés-oldalának URL-je (lásd a leírást)." } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/packages/customer-portal": { "get": { "tags": [ "Előfizetés" ], "summary": "Ügyfélportál URL-je", "description": "Visszaadja a fizetési szolgáltató ügyfélportáljának URL-jét, ahol a felhasználó a fizetési módját, az előfizetését és a korábbi fizetéseit kezeli, vagy lemondja az előfizetést. A portálról a weboldal előfizetés-oldalára tér vissza. Csak aktív előfizetéssel hívható (különben 403).", "operationId": "getCustomerPortalUrl", "responses": { "200": { "description": "Az ügyfélportál URL-je.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://billing.example.com/p/session/test_YWNjdF8x", "description": "Az ügyfélportál egyszer használható URL-je." } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/packages/contract-signing-balance": { "get": { "tags": [ "Előfizetés" ], "summary": "Szerződéskötési egyenleg", "description": "Megmutatja, hány szerződéskötés van még ingyenesen, illetve hányat használtál fel az aktuális számlázási időszakban. Negatív érték: ennyi ingyenes szerződéskötésed van még hátra (pl. `-2`). Pozitív érték: az aktuális előfizetési időszakban ennyi díjköteles szerződéskötést használtál fel. `0`: nincs ingyenes kereted és nincs felhasználás (vagy nincs aktív előfizetésed).", "operationId": "getContractSigningBalance", "responses": { "200": { "description": "Az egyenleg.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSigningBalance" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/invoices": { "get": { "tags": [ "Számlák" ], "summary": "Számláim listája", "description": "A bejelentkezett felhasználónak kiállított összes számla, a legújabbal kezdve (lapozás nélkül). A számla a felhasználóhoz tartozik, nem a profilhoz: a profiltagok egymás számláit nem látják.", "operationId": "listInvoices", "responses": { "200": { "description": "A számlák.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/invoices/{id}": { "get": { "tags": [ "Számlák" ], "summary": "Egy számla lekérése", "description": "Egy saját számla adatai és a megtekintési/letöltési linkje. Más felhasználó számlájára 404-et kapsz.", "operationId": "getInvoice", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A számla azonosítója (`id`).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "A számla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/invoices/export": { "post": { "tags": [ "Számlák" ], "summary": "Számlák exportálása Excelbe", "description": "Az összes saját számlát Excel-fájlban (`invoice.xlsx`) adja vissza, a legújabbal kezdve. Oszlopok: számlaszám, ár, URL (kattintható link), kiállítás ideje; a fejléc a felhasználó nyelvén. Kérés törzs nem kell (rendezést és szűrést nem fogad).", "operationId": "exportInvoices", "responses": { "200": { "description": "Az Excel-fájl (`invoice.xlsx`).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/dashboard": { "get": { "tags": [ "Irányítópult" ], "summary": "Irányítópult adatai", "description": "Az irányítópult összesítője: a szerződéseid száma állapot szerint (minden profilod szerződései, amelynek tagja vagy, valamint azok, amelyekben a tulajdonolt profiloddal félként szerepelsz), a függő meghívásaid száma, és a legutóbbi 10 tevékenységnapló-bejegyzésed. Belépési tokennel vagy API-kulccsal hívható.", "operationId": "getDashboard", "responses": { "200": { "description": "Az irányítópult adatai.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/permission-warnings": { "post": { "tags": [ "Jogosultsági figyelmeztetések" ], "summary": "Funkciók elérhetőségének lekérdezése", "description": "Megmondja, hogy a felsorolt műveleteket most elvégezheted-e, és ha nem, miért (pl. csomagváltás kell: `upgrade_required`, 402). Arra való, hogy a felületen előre letiltsd / megmagyarázd a gombokat. Belépési tokennel vagy API-kulccsal hívható. Ha az `actions` hiányzik, mind a nyolc művelet szerepel a válaszban.", "operationId": "getPermissionWarnings", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "nullable": true, "uniqueItems": true, "description": "A lekérdezendő műveletek (ismétlés nélkül). Hiányzik vagy `null` = mind. Üres tömbre üres választ kapsz.", "items": { "type": "string", "enum": [ "user_subscribe", "user_get_customer_portal_url", "profile_create", "contract_template_create", "contract_create", "api_key_create", "webhook_create", "use_bulk_contract_creation" ] } } } } } } }, "responses": { "200": { "description": "Műveletenként a figyelmeztetés vagy `null`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionWarningsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/profiles": { "get": { "tags": [ "Profilok" ], "summary": "Profiljaid listája", "operationId": "listProfiles", "description": "Visszaadja az összes profilt, amelynek tagja vagy (sajátjaidat és azokat is, ahová meghívtak), azonosító szerint növekvő sorrendben, a tagokkal és a függő meghívásokkal együtt. A lista üres is lehet: meghívott társfelhasználónak nem kötelező saját profil.", "responses": { "200": { "description": "A profilok listája.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } }, "post": { "tags": [ "Profilok" ], "summary": "Profil létrehozása", "operationId": "createProfile", "description": "Új profilt hoz létre, és te leszel a tulajdonosa. A saját profilok száma a csomagod `max_own_profiles` korlátjáig nőhet; a korlát elérésekor 403-at kapsz (a `permission_warnings`-ban ez `upgrade_required` típusú figyelmeztetés). A cégtípusnál a magánszemély-mezők, magánszemélynél az adószám mentéskor törlődik.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "name", "address" ], "properties": { "type": { "type": "string", "enum": [ "company", "private_person" ], "description": "A profil típusa: `company` = cég / egyéni vállalkozó, `private_person` = magánszemély." }, "name": { "type": "string", "maxLength": 255, "description": "Cégnév vagy a magánszemély neve." }, "tax_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Adószám. `company` típusnál kötelező; `private_person` típusnál mentéskor törlődik." }, "mother_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Anyja neve. `private_person` típusnál kötelező; `company` típusnál mentéskor törlődik." }, "birth_date": { "type": "string", "format": "date", "nullable": true, "example": "1985-04-12", "description": "Születési dátum `ÉÉÉÉ-HH-NN` alakban. `private_person` típusnál kötelező; `company` típusnál mentéskor törlődik." }, "birth_place": { "type": "string", "maxLength": 255, "nullable": true, "description": "Születési hely. `private_person` típusnál kötelező; `company` típusnál mentéskor törlődik." }, "address": { "type": "string", "maxLength": 255, "description": "Cím / székhely." } }, "example": { "type": "company", "name": "Példa Bt.", "tax_number": "12345678-1-42", "address": "1111 Budapest, Kitalált utca 3." } } } } }, "responses": { "200": { "description": "A létrehozott profil.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/profiles/own": { "get": { "tags": [ "Profilok" ], "summary": "Saját (tulajdonolt) profiljaid", "operationId": "listOwnProfiles", "description": "Csak azokat a profilokat adja vissza, amelyeknek te vagy a tulajdonosa. Szerződést aláírni és bejövő szerződést elfogadni csak saját profillal lehet, ezért ez a lista a választható „elfogadó\" profilok forrása. Üres is lehet (pl. ha az utolsó saját profilodat törölted).", "responses": { "200": { "description": "A profilok listája.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/profiles/{id}": { "get": { "tags": [ "Profilok" ], "summary": "Profil lekérése", "operationId": "getProfile", "description": "Egy profil adatai a tagokkal, a függő meghívásokkal és a jogosultsági figyelmeztetésekkel. Bármely tag lekérheti; ha nem vagy tagja a profilnak, 404-et kapsz.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." } ], "responses": { "200": { "description": "A profil.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Profilok" ], "summary": "Profil módosítása", "operationId": "updateProfile", "description": "A profil adatainak teljes cseréje (minden kötelező mezőt újra meg kell adnod). Csak a profil tulajdonosa hívhatja, másnak 403. A módosítás a már aláírt szerződéseket nem érinti.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "name", "address" ], "properties": { "type": { "type": "string", "enum": [ "company", "private_person" ], "description": "A profil típusa: `company` = cég / egyéni vállalkozó, `private_person` = magánszemély." }, "name": { "type": "string", "maxLength": 255, "description": "Cégnév vagy a magánszemély neve." }, "tax_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Adószám. `company` típusnál kötelező; `private_person` típusnál mentéskor törlődik." }, "mother_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Anyja neve. `private_person` típusnál kötelező; `company` típusnál mentéskor törlődik." }, "birth_date": { "type": "string", "format": "date", "nullable": true, "example": "1985-04-12", "description": "Születési dátum `ÉÉÉÉ-HH-NN` alakban. `private_person` típusnál kötelező; `company` típusnál mentéskor törlődik." }, "birth_place": { "type": "string", "maxLength": 255, "nullable": true, "description": "Születési hely. `private_person` típusnál kötelező; `company` típusnál mentéskor törlődik." }, "address": { "type": "string", "maxLength": 255, "description": "Cím / székhely." } }, "example": { "type": "company", "name": "Példa Bt.", "tax_number": "12345678-1-42", "address": "1111 Budapest, Kitalált utca 3." } } } } }, "responses": { "200": { "description": "A módosított profil.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Profilok" ], "summary": "Profil törlése", "operationId": "deleteProfile", "description": "Törli a profilt; csak a tulajdonos hívhatja (az utolsó saját profilod is törölhető — utána profil nélkül maradsz, és bejövő szerződést elfogadni csak új profil létrehozása után tudsz). Mellékhatások:\n\n- a profil minden tag számára eltűnik, a függő meghívásai törlődnek;\n- a profil még **nem aláírt** szerződései törlődnek; az aláírtak megmaradnak és a tagok továbbra is elérik;\n- más profilok még nem aláírt szerződéseiben, ahol ez a profil fogadta el a meghívást, az aláíró-hely visszaáll alaphelyzetbe (az email cím, az adatok és az esetleges aláírás törlődik).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." } ], "responses": { "200": { "description": "Sikeres törlés, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/profiles/{id}/upload-signature": { "post": { "tags": [ "Profilok" ], "summary": "Aláíráskép feltöltése", "operationId": "uploadProfileSignature", "description": "Feltölti (vagy lecseréli) a profil újrahasználható aláírásképét, amelyet aláíráskor használhatsz. Csak a profil tulajdonosa hívhatja. A kép 500 px szélesre méreteződik.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "signature" ], "properties": { "signature": { "type": "string", "format": "binary", "description": "Aláíráskép: JPEG vagy PNG, legfeljebb 4500×4500 px és 30 MB; nem lehet teljesen üres (átlátszó) kép." } } } } } }, "responses": { "200": { "description": "A profil az új aláírásképpel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/profiles/{id}/delete-signature": { "post": { "tags": [ "Profilok" ], "summary": "Aláíráskép törlése", "operationId": "deleteProfileSignature", "description": "Törli a profil aláírásképét. Csak a tulajdonos hívhatja; ha nincs feltöltött aláírás, 403-at kapsz. A már aláírt szerződéseken lévő aláírást nem érinti.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." } ], "responses": { "200": { "description": "A profil aláíráskép nélkül.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/profiles/{id}/branding": { "post": { "tags": [ "Profilok" ], "summary": "Arculat (logó, kiemelő szín) beállítása", "operationId": "updateProfileBranding", "description": "Beállítja a profil arculatát, amely a szerződés PDF-jén, a szerződés nézetében, a vendég aláíró oldalán és a kiküldött leveleken jelenik meg. Prémium funkció: csak a tulajdonos hívhatja, és csak ha a tulajdonos csomagjában van `branding` funkció — különben 403 (a `permission_warnings.update_branding` ilyenkor `upgrade_required`). Figyelj: a `brand_color` minden hívásnál felülíródik, ha kihagyod, a szín törlődik; a logó csak akkor változik, ha új fájlt küldesz vagy `remove_logo=true`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "logo": { "type": "string", "format": "binary", "description": "Új logó (nem kötelező): JPEG vagy PNG, legfeljebb 2000×2000 px és 2 MB. Átméretezés nélkül tárolódik (a PNG átlátszósága megmarad)." }, "remove_logo": { "type": "boolean", "nullable": true, "description": "Ha `true` és nem küldesz új logót, a meglévő logó törlődik." }, "brand_color": { "type": "string", "nullable": true, "pattern": "^#[0-9a-fA-F]{6}$", "example": "#1F6FEB", "description": "Kiemelő szín `#RRGGBB` alakban; kisbetűsítve tárolódik. Üres / kihagyott érték = nincs szín." } } } } } }, "responses": { "200": { "description": "A profil az új arculattal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/profiles/{id}/invite": { "post": { "tags": [ "Profiltagok és meghívások" ], "summary": "Felhasználó meghívása a profilba", "operationId": "inviteProfileUser", "description": "Csak a profil tulajdonosa hívhatja. Ha az email címhez már tartozik Signingo-fiók, a felhasználó **azonnal** a profil tagja lesz, és emailben értesítést kap. Ha nincs fiókja, függő meghívás jön létre, és meghívó emailt küld; regisztráláskor automatikusan taggá válik (saját profil nélkül is regisztrálhat). A tagok száma a tulajdonos csomagjának `max_profile_users` korlátjáig nőhet; elérésekor 403 (`upgrade_required` figyelmeztetés).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "example": "kollega@pelda.hu", "description": "A meghívott email címe (érvényes, létező domainnel). Hiba, ha már tag vagy már meg van hívva." } } } } } }, "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/profiles/{id}/resend-invitation/{invitationId}": { "post": { "tags": [ "Profiltagok és meghívások" ], "summary": "Meghívó újraküldése", "operationId": "resendProfileInvitation", "description": "Újra elküldi a meghívó emailt egy függő meghívás címére. Csak a profil tulajdonosa hívhatja.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A függő profilmeghívás azonosítója (a profil `invitations[].id` mezője). Más profil meghívása 404." } ], "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/profiles/{id}/delete-user/{userId}": { "delete": { "tags": [ "Profiltagok és meghívások" ], "summary": "Tag eltávolítása a profilból", "operationId": "removeProfileUser", "description": "Eltávolít egy tagot a profilból. Csak a tulajdonos hívhatja, és a tulajdonos magát nem távolíthatja el (403). Az eltávolított tag elveszíti a hozzáférést a profil szerződéseihez és sablonjaihoz; ha ez volt az alapértelmezett profilja, az alapértelmezés törlődik. Az eltávolított tag nem kap értesítést.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az eltávolítandó tag felhasználói azonosítója (a profil `users[].id` mezője). Ha nem tagja a profilnak, 404." } ], "responses": { "200": { "description": "Sikeres törlés, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/profiles/{id}/delete-invitation/{invitationId}": { "delete": { "tags": [ "Profiltagok és meghívások" ], "summary": "Függő meghívás visszavonása", "operationId": "deleteProfileInvitation", "description": "Visszavon egy még el nem fogadott meghívást; a címzett regisztráláskor már nem lesz a profil tagja. Csak a tulajdonos hívhatja. Értesítést nem küld.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A függő profilmeghívás azonosítója (a profil `invitations[].id` mezője). Más profil meghívása 404." } ], "responses": { "200": { "description": "Sikeres törlés, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/profiles/{id}/leave": { "post": { "tags": [ "Profiltagok és meghívások" ], "summary": "Kilépés a profilból", "operationId": "leaveProfile", "description": "Kilépsz egy olyan profilból, amelynek tagja (de nem tulajdonosa) vagy; a tulajdonos nem léphet ki (403 — ő a profilt törölheti). Utána nem éred el a profil szerződéseit és sablonjait; ha ez volt az alapértelmezett profilod, az alapértelmezés törlődik. Profil nélkül is maradhatsz.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "A profil azonosítója (`id`). Csak olyan profil érhető el, amelynek tagja vagy, különben 404." } ], "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/partners/{id}": { "get": { "tags": [ "Partnerek" ], "summary": "Egy partner lekérése", "description": "Egy partnerprofil adatai. Partner az a profil, amelynek NEM vagy tagja, de van veled közös (általad elérhető) szerződése, amelyben aláíró félként szerepel. A válaszban a profil tulajdonosának nyilvános adatai is benne vannak. Ha a profil nem a partnered (pl. a saját profilod, vagy nincs közös szerződésetek), 404-et kapsz.", "operationId": "getPartner", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A partnerprofil azonosítója (a profil `id`-ja).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "A partnerprofil.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Partner" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/partners/search": { "post": { "tags": [ "Partnerek" ], "summary": "Partnerek keresése", "description": "A partnereid (a veled közös szerződésekben aláíró, de nem saját profilok) lapozva, alapból név szerint ABC-sorrendben. A `search` szavakra bontva keres; minden szónak szerepelnie kell a profil nevében, adószámában vagy címében, illetve a tulajdonos nevében, email-címében vagy telefonszámában.", "operationId": "searchPartners", "requestBody": { "required": false, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchRequest" }, { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ "name" ], "default": "name", "description": "A rendezés oszlopa. Alapértelmezés: `name`, `asc` iránnyal." } } } ] } } } }, "responses": { "200": { "description": "A partnerek egy oldala.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchMeta" }, { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Partner" }, "description": "Az aktuális oldal találatai." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-templates": { "get": { "tags": [ "Szerződéssablonok" ], "summary": "Sablonok listája", "operationId": "listContractTemplates", "description": "Az összes profilod (saját és tagsági) összes szerződéssablonja, létrehozási sorrendben, teljes tartalommal (aláírók, mezők, mellékletek, profil). Sok sablonnál használd inkább a lapozható `POST /contract-templates/search` végpontot.", "responses": { "200": { "description": "A sablonok listája.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContractTemplate" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } }, "post": { "tags": [ "Szerződéssablonok" ], "summary": "Sablon létrehozása", "operationId": "createContractTemplate", "description": "Üres sablont hoz létre a megadott profilban, egy „Küldő\" (`sender`) és egy „Címzett\" (`receiver`) aláíróval, elfogadásos (`acceptance`) aláírási móddal és a felhasználói nyelveddel; a tartalmat utána a `PUT` végponttal töltöd fel. A profil bármely tagja létrehozhat sablont, de a profil **tulajdonosának** csomagjában szerepelnie kell a `contract_templates` funkciónak, különben 402. A megadott profil lesz az alapértelmezett, szerződés-létrehozó profilod.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_id", "name" ], "properties": { "profile_id": { "type": "integer", "example": 42, "description": "A profil azonosítója, amelyben a sablon készül; olyan profil kell, amelynek tagja vagy." }, "name": { "type": "string", "maxLength": 255, "example": "Megbízási szerződés", "description": "A sablon neve." } } } } } }, "responses": { "200": { "description": "A létrehozott sablon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractTemplate" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-templates/{id}": { "get": { "tags": [ "Szerződéssablonok" ], "summary": "Sablon lekérése", "operationId": "getContractTemplate", "description": "Egy sablon minden adata. A sablon profiljának bármely tagja lekérheti.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A szerződéssablon **tokenje** (`token`, 16 karakteres kisbetűs azonosító) — az útvonal neve `id`, de az értéke a token. Csak a saját profiljaid sablonjai érhetők el, különben 404." } ], "responses": { "200": { "description": "A sablon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractTemplate" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Szerződéssablonok" ], "summary": "Sablon módosítása", "operationId": "updateContractTemplate", "description": "A sablon teljes mentése: név, aláírási mód, nyelv, szöveg, megjegyzés, valamint az aláírók, a mezők és a mellékletek **teljes listája**. A listák szinkronizálódnak: a meglévő elemet `id`-val tartod meg, `id` nélkül új jön létre, ami kimarad, az törlődik — **ha a `fields` vagy az `attachments` mezőt kihagyod, az összes mező, ill. melléklet törlődik**. A sorrend a tömb sorrendje. Új mellékletet előbb a `POST /contract-templates/{token}/attachments` végponttal tölts fel. A profil bármely tagja hívhatja. A már elkészült szerződéseket nem érinti.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A szerződéssablon **tokenje** (`token`, 16 karakteres kisbetűs azonosító) — az útvonal neve `id`, de az értéke a token. Csak a saját profiljaid sablonjai érhetők el, különben 404." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "security", "language", "signatures" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "A sablon neve." }, "security": { "type": "string", "enum": [ "acceptance", "digital_signature" ], "description": "Aláírási mód: `acceptance` = elfogadással, `digital_signature` = elektronikus aláírással." }, "language": { "type": "string", "enum": [ "hu", "en" ], "description": "A sablonból készülő szerződés nyelve." }, "content": { "type": "string", "nullable": true, "maxLength": 16777215, "description": "A szerződés szövege (HTML)." }, "note": { "type": "string", "nullable": true, "maxLength": 16777215, "description": "Belső megjegyzés." }, "signatures": { "type": "array", "minItems": 1, "description": "Az aláírók teljes listája sorrendben; legalább 1, legfeljebb egy `sender`, és legfeljebb annyi, amennyit a csomagod `max_contract_signatures` korlátja enged (korlátlan csomagnál 255).", "items": { "type": "object", "required": [ "reference", "signer" ], "properties": { "id": { "type": "integer", "nullable": true, "minimum": 1, "description": "Meglévő aláíró-hely azonosítója (megtartáshoz); üresen új jön létre." }, "reference": { "type": "string", "maxLength": 255, "example": "Megbízó", "description": "A fél megnevezése." }, "signer": { "type": "string", "enum": [ "sender", "receiver" ], "description": "`sender` = küldő, `receiver` = címzett." } } } }, "fields": { "type": "array", "nullable": true, "maxItems": 255, "description": "A kitöltendő mezők teljes listája sorrendben. Kihagyva / null = minden mező törlődik.", "items": { "type": "object", "required": [ "name", "filler" ], "properties": { "id": { "type": "integer", "nullable": true, "minimum": 1, "description": "Meglévő mező azonosítója (megtartáshoz); üresen új jön létre." }, "name": { "type": "string", "maxLength": 255, "description": "A mező neve." }, "filler": { "type": "string", "enum": [ "sender", "receiver" ], "description": "Ki tölti ki." } } } }, "attachments": { "type": "array", "nullable": true, "maxItems": 255, "description": "A megtartandó mellékletek sorrendben (a feltöltött mellékletek `id`-jával). Kihagyva / null = minden melléklet törlődik. Ismeretlen `id` csendben kimarad.", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "minimum": 1, "description": "A melléklet azonosítója." }, "name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Megjelenő név. Ha a kulcs szerepel és üres, az eredeti fájlnév látszik; ha a kulcs hiányzik, a név nem változik." } } } } }, "example": { "name": "Megbízási szerződés", "security": "acceptance", "language": "hu", "content": "

A felek megállapodnak…

", "note": null, "signatures": [ { "id": 101, "reference": "Megbízó", "signer": "sender" }, { "id": 102, "reference": "Megbízott", "signer": "receiver" } ], "fields": [ { "name": "Megbízási díj", "filler": "sender" } ], "attachments": [ { "id": 9, "name": "Árjegyzék" } ] } } } } }, "responses": { "200": { "description": "A mentett sablon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractTemplate" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Szerződéssablonok" ], "summary": "Sablon törlése", "operationId": "deleteContractTemplate", "description": "Véglegesen törli a sablont az aláíróival, mezőivel és mellékleteivel. A belőle már elkészült szerződések megmaradnak (a sablonhoz kötésük megszűnik). A profil bármely tagja hívhatja.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A szerződéssablon **tokenje** (`token`, 16 karakteres kisbetűs azonosító) — az útvonal neve `id`, de az értéke a token. Csak a saját profiljaid sablonjai érhetők el, különben 404." } ], "responses": { "200": { "description": "Sikeres törlés, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contract-templates/search": { "post": { "tags": [ "Szerződéssablonok" ], "summary": "Sablonok keresése", "operationId": "searchContractTemplates", "description": "Lapozható, rendezhető keresés a profiljaid sablonjai között. A `search` szavanként keres (minden szónak illeszkednie kell) a sablon nevében, szövegében, megjegyzésében, a profil nevében, az aláírók megnevezésében és a mezők nevében. Alapértelmezett rendezés: `created_at` csökkenő.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchRequest" }, { "type": "object", "properties": { "order_column": { "type": "string", "enum": [ "name", "created_at", "updated_at" ], "default": "created_at", "description": "Rendezési oszlop." }, "profile_id": { "type": "integer", "nullable": true, "description": "Szűrés egy profilra (olyan profil, amelynek tagja vagy)." } } } ] } } } }, "responses": { "200": { "description": "A találatok és a lapozási adatok.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchMeta" }, { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/ContractTemplate" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-templates/export": { "post": { "tags": [ "Szerződéssablonok" ], "summary": "Sablonok exportálása Excelbe", "operationId": "exportContractTemplates", "description": "A keresés feltételeivel (lapozás nélkül, az összes találat) Excel-táblát ad a sablonokról: név, nyelv, aláírók száma, létrehozás és módosítás ideje. A `search` szöveg is szűr, ugyanúgy, mint a keresésnél.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string", "nullable": true, "description": "Szabad szavas szűrés (mint a keresésnél)." }, "order_column": { "type": "string", "enum": [ "name", "created_at", "updated_at" ], "default": "created_at", "description": "Rendezési oszlop." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Rendezési irány." }, "profile_id": { "type": "integer", "nullable": true, "description": "Szűrés egy profilra (olyan profil, amelynek tagja vagy)." } } } } } }, "responses": { "200": { "description": "Az Excel-fájl (`contract_template.xlsx`).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-templates/{token}/attachments": { "post": { "tags": [ "Szerződéssablonok" ], "summary": "Melléklet feltöltése a sablonhoz", "operationId": "uploadContractTemplateAttachment", "description": "Feltölt egy mellékletet a sablon végére. A profil bármely tagja hívhatja. Figyelj: ha utána a sablont `PUT`-tal mented, az `attachments` listába ennek az `id`-ját is bele kell tenned, különben a melléklet törlődik.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A szerződéssablon tokenje (`token`). Csak a saját profiljaid sablonjai érhetők el, különben 404." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "A melléklet: JPEG, PNG vagy PDF, legfeljebb 30 MB; a PDF-nek olvashatónak (nem sérültnek) kell lennie." } } } } } }, "responses": { "200": { "description": "A feltöltött melléklet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractTemplateAttachment" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-templates/{token}/bulk-contract-creation/download-excel": { "get": { "tags": [ "Tömeges szerződéskészítés" ], "summary": "Kitöltendő Excel-minta letöltési linkje", "operationId": "getBulkContractCreationExcelUrl", "description": "Nem magát a fájlt adja, hanem egy **aláírt, 60 percig érvényes letöltési URL-t**, amely bejelentkezés nélkül letölti a sablonhoz illő `.xlsx` mintát: a fejlécsorban a várt oszlopokkal (a címzettek és mezők nevével) és két kitöltött példasorral. Csak akkor hívható, ha a sablon profiljának **tulajdonosa** olyan csomaggal rendelkezik, amelyben szerepel a `bulk_contract_creation` funkció; különben 403 (`upgrade_required` figyelmeztetés).", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A szerződéssablon tokenje (`token`). Csak a saját profiljaid sablonjai érhetők el, különben 404." } ], "responses": { "200": { "description": "A letöltési link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Aláírt letöltési URL (60 percig érvényes, lejárat után 403). Az API domainjén szolgálja ki az `.xlsx` fájlt.", "example": "https://api.signingo.hu/file-download/contract-templates/k3x9q2m7v1b8n4zt/download-bulk-contract-creation-excel?expires=1761559200&signature=0f1e2d…" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contract-templates/{token}/bulk-contract-creation/test-excel": { "post": { "tags": [ "Tömeges szerződéskészítés" ], "summary": "Kitöltött Excel ellenőrzése", "operationId": "testBulkContractCreationExcel", "description": "Ellenőrzi a kitöltött Excelt, és cellánként visszaadja az értéket és a hibákat — **semmit nem hoz létre, emailt nem küld**. Az importálás előtt érdemes meghívni; ha a válasz `success` mezője `true`, az import ugyanezzel a fájllal sikerülni fog. Csak akkor hívható, ha a sablon profiljának **tulajdonosa** olyan csomaggal rendelkezik, amelyben szerepel a `bulk_contract_creation` funkció; különben 403 (`upgrade_required` figyelmeztetés).\n\nAz Excel oszlopai **sorrendben** (az első sor a fejléc, ezt kihagyja; az oszlopokat a helyük alapján olvassa, nem a fejléc szövege alapján):\n\n1. a szerződés neve (kötelező, max. 255 karakter);\n2. címzettenként (`receiver` aláírónként) egy email-oszlop (üresen hagyható: akkor a címzett később adható meg);\n3. a sablon mezőnként egy érték-oszlop (max. 255 karakter, üresen hagyható);\n4. címzettenként kilenc adat-oszlop: típus (`cég` / `magánszemély`), név / cégnév, aláíró neve, adószám, anyja neve, születési hely, születési dátum (pl. `1985.04.12.`), cím / székhely, telefon (`+36…`). Ha egy címzett bármely adatát kitöltöd, a kötelezőket (típus, név, aláíró neve, cím, cégnél adószám, magánszemélynél anyja neve, születési hely és dátum) is ki kell tölteni.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A szerződéssablon tokenje (`token`). Csak a saját profiljaid sablonjai érhetők el, különben 404." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "A kitöltött táblázat: `.xlsx`, `.xls` vagy `.csv` (az első munkalapot olvassa)." } } } } } }, "responses": { "200": { "description": "Az ellenőrzés eredménye.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkContractCreationTestResult" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-templates/{token}/bulk-contract-creation/import-excel": { "post": { "tags": [ "Tömeges szerződéskészítés" ], "summary": "Szerződések tömeges létrehozása Excelből", "operationId": "importBulkContractCreationExcel", "description": "A kitöltött Excel minden sorából egy új szerződést készít a sablon alapján (szöveg, aláírási mód, nyelv, megjegyzés, aláírók, mezők a sorban megadott értékekkel, a mellékletek másolata), a sablon profiljában. Csak akkor hívható, ha a sablon profiljának **tulajdonosa** olyan csomaggal rendelkezik, amelyben szerepel a `bulk_contract_creation` funkció; különben 403 (`upgrade_required` figyelmeztetés).\n\n**Mellékhatások:** a szerződések azonnal kimennek — minden kitöltött címzett-email címre a partner emailt kap: a regisztrált felhasználó szerződésmeghívót, a többi a vendég aláíró linkjét. Ha webhookot állítottál be, szerződésenként webhook-esemény is érkezik. A küldő (te) aláírása nem történik meg automatikusan.\n\nA fájl egészét egyben dolgozza fel: ha bármely sor hibás, 422-t kapsz, és egyetlen szerződés sem jön létre. A hibaüzenet nem jelöli a sort, ezért előbb a `test-excel` végponttal ellenőrizz. A válasz sikeres esetben üres; a létrejött szerződéseket a `POST /contracts/search` végponttal éred el.\n\nAz Excel oszlopai **sorrendben** (az első sor a fejléc, ezt kihagyja; az oszlopokat a helyük alapján olvassa, nem a fejléc szövege alapján):\n\n1. a szerződés neve (kötelező, max. 255 karakter);\n2. címzettenként (`receiver` aláírónként) egy email-oszlop (üresen hagyható: akkor a címzett később adható meg);\n3. a sablon mezőnként egy érték-oszlop (max. 255 karakter, üresen hagyható);\n4. címzettenként kilenc adat-oszlop: típus (`cég` / `magánszemély`), név / cégnév, aláíró neve, adószám, anyja neve, születési hely, születési dátum (pl. `1985.04.12.`), cím / székhely, telefon (`+36…`). Ha egy címzett bármely adatát kitöltöd, a kötelezőket (típus, név, aláíró neve, cím, cégnél adószám, magánszemélynél anyja neve, születési hely és dátum) is ki kell tölteni.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A szerződéssablon tokenje (`token`). Csak a saját profiljaid sablonjai érhetők el, különben 404." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "A kitöltött táblázat: `.xlsx`, `.xls` vagy `.csv` (az első munkalapot olvassa)." } } } } } }, "responses": { "200": { "description": "A szerződések létrejöttek, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contracts/{id}": { "get": { "tags": [ "Szerződések" ], "summary": "Szerződés lekérése", "operationId": "readContract", "description": "Egy szerződés teljes adatai az összes kapcsolattal (aláírók, mezők, mellékletek, profil, megjegyzések, napló). Azokat a szerződéseket éred el, amelyeket egy olyan profil készített, amelynek tagja vagy, vagy amelyben egy általad tulajdonolt profil aláíró. Egy még el nem fogadott meghívást itt 404 jelez — azt a `GET /contracts/invitations/{token}` adja vissza.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító, pl. `k3j9x0qa7bmz2wfe`) — a paraméter neve `id`, de az értéke NEM a numerikus azonosító.", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres kérés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Szerződések" ], "summary": "Szerződés módosítása", "operationId": "updateContract", "description": "A szerződés adatainak, aláíróinak, mezőinek és mellékleteinek mentése EGYBEN (teljes csere: a `signatures`, `fields`, `attachments` listából kimaradó elemek törlődnek). Hívhatja a szerződést készítő profil bármely tagja, amíg a szerződés nincs lezárva (`signed` → 403).\n\n**Kiküldés a partnernek:** nincs külön „küldés” lépés — amikor egy `receiver` helyen az `email`-t először megadod vagy megváltoztatod, a partner azonnal levelet kap: ha az email-címmel van Signingo-fiók, szerződésmeghívót (a hely `invited` lesz, a partner a `/contracts/invitations` végpontokon fogadja el), különben a vendég aláíró linkjét tartalmazó levelet (a hely `published`).\n\n**Aláírások törlése:** ha az aláírt tartalom bármely része változik (név, nyelv, aláírási mód, szöveg, aláírók adatai, mezők, mellékletek — a `note` kivétel), a már leadott aláírások törlődnek, és akinek az aláírása törlődött, levelet kap, hogy írja alá újra. A változás webhook-eseményt vált ki.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító, pl. `k3j9x0qa7bmz2wfe`) — a paraméter neve `id`, de az értéke NEM a numerikus azonosító.", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "security", "language", "signatures" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "A szerződés neve.", "example": "Bérleti szerződés – Fő utca 12." }, "security": { "type": "string", "enum": [ "acceptance", "digital_signature" ], "description": "Aláírás módja (lásd `Contract.security`)." }, "language": { "type": "string", "enum": [ "hu", "en" ], "description": "A szerződés nyelve." }, "content": { "type": "string", "nullable": true, "maxLength": 16777215, "description": "A szerződés szövege HTML-ben, helyőrzőkkel (lásd `Contract.processed_content`).", "example": "

A bérleti díj havi [berleti_dij].

" }, "note": { "type": "string", "nullable": true, "maxLength": 16777215, "description": "Megjegyzés (nem része az aláírt tartalomnak, a módosítása nem törli az aláírásokat)." }, "signatures": { "type": "array", "minItems": 1, "maxItems": 255, "items": { "type": "object", "required": [ "reference", "signer" ], "properties": { "id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Meglévő aláírói hely azonosítója (`signatures[].id`). Hiányában új hely jön létre. Ha a meglévő helyen az email-cím megváltozik, a régi hely TÖRLŐDIK és újat kap (új azonosító, a régi vendéglink érvénytelen)." }, "reference": { "type": "string", "maxLength": 255, "description": "A fél szerepe a szerződésben (pl. „Bérbeadó”, „Megbízott”); a szövegben a `[_…]` helyőrzők ebből képződnek.", "example": "Bérlő" }, "signer": { "type": "string", "enum": [ "sender", "receiver" ], "description": "`sender` = a szerződést készítő profil (legfeljebb egy lehet; az email-címe mindig a profiltulajdonosé, a küldött érték figyelmen kívül marad), `receiver` = partner." }, "email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true, "description": "A partner email-címe (a listán belül egyedi). Megadásakor / módosításakor a partner levelet kap — lásd a végpont leírását. `null` = még nincs kiküldve.", "example": "partner@example.com" }, "fill_details": { "type": "boolean", "nullable": true, "default": false, "description": "Ha `true`, a fél adatait te töltöd ki ebben a kérésben (a lenti adatmezők; a hiányzók `null`-ra állnak). Ha `false`/hiányzik, a meglévő adatok nem változnak, és a partner adja meg őket." }, "signer_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Az aláíró személy neve. Kötelező, ha `fill_details` igaz.", "example": "Nagy Péter" }, "phone": { "type": "string", "nullable": true, "pattern": "^\\+\\d{7,14}$", "description": "Telefonszám nemzetközi formában (`+` és 7–14 számjegy).", "example": "+36301234567" }, "type": { "type": "string", "enum": [ "company", "private_person" ], "nullable": true, "description": "A fél típusa: cég vagy magánszemély. Kötelező, ha `fill_details` igaz." }, "name": { "type": "string", "maxLength": 255, "nullable": true, "description": "A fél neve (cégnév vagy a magánszemély neve). Kötelező, ha `fill_details` igaz.", "example": "Példa Bt." }, "tax_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Adószám. Kötelező, ha `fill_details` igaz és `type` = `company`; magánszemélynél mentéskor törlődik.", "example": "12345678-1-41" }, "mother_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Anyja neve. Kötelező, ha `fill_details` igaz és `type` = `private_person`; cégnél mentéskor törlődik." }, "birth_date": { "type": "string", "format": "date", "nullable": true, "description": "Születési dátum `ÉÉÉÉ-HH-NN` alakban. Kötelező, ha `fill_details` igaz és `type` = `private_person`.", "example": "1985-04-12" }, "birth_place": { "type": "string", "maxLength": 255, "nullable": true, "description": "Születési hely. Kötelező, ha `fill_details` igaz és `type` = `private_person`." }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "Cím / székhely. Kötelező, ha `fill_details` igaz.", "example": "1051 Budapest, Példa utca 1." } } }, "description": "Az aláírói helyek TELJES listája, a kívánt sorrendben. Ami a listából kimarad, törlődik. A maximális darabszámot a csomagod `max_contract_signatures` korlátja adja (422, ha túlléped); legfeljebb egy `sender`." }, "fields": { "type": "array", "nullable": true, "maxItems": 255, "items": { "type": "object", "required": [ "name", "filler" ], "properties": { "id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Meglévő mező azonosítója; hiányában új mező jön létre." }, "name": { "type": "string", "maxLength": 255, "description": "A mező neve.", "example": "Bérleti díj" }, "filler": { "type": "string", "enum": [ "sender", "receiver" ], "description": "Ki tölti ki a mezőt." }, "value": { "type": "string", "maxLength": 255, "nullable": true, "description": "Elfogadja (validálja), de ez a végpont NEM menti — az értéket a `POST /contracts/{token}/fill-fields` végponttal add meg." } } }, "description": "A mezők TELJES listája sorrendben. Ami kimarad, törlődik — ha a kulcsot elhagyod vagy `null`, MINDEN mező törlődik." }, "attachments": { "type": "array", "nullable": true, "maxItems": 255, "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "minimum": 1, "description": "Egy már feltöltött melléklet azonosítója (`POST /contracts/{token}/attachments` válaszából). Más szerződés melléklete csendben kimarad." }, "name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Megjelenő név; üres / `null` = az eredeti fájlnév. Ha a kulcs hiányzik, a név nem változik." } } }, "description": "A megtartandó mellékletek TELJES listája sorrendben. Ami kimarad, törlődik — ha a kulcsot elhagyod vagy `null`, MINDEN melléklet törlődik." }, "sign_after_save": { "type": "boolean", "nullable": true, "default": false, "description": "Ha `true` és van a te email-címedre szóló aláírói hely, mentés előtt ellenőrzi, hogy aláírhatod-e; ha nem, 403-mal az egész mentés elmarad. Magát az aláírást NEM végzi el (azt az aláírás-végpontokkal teheted meg)." } } }, "example": { "name": "Bérleti szerződés – Fő utca 12.", "security": "acceptance", "language": "hu", "content": "

A bérleti díj havi [berleti_dij]. Bérlő: [berlo_name], [berlo_address].

", "note": "Kulcsátadás a hónap első napján.", "signatures": [ { "id": 30101, "reference": "Bérbeadó", "signer": "sender" }, { "id": 30102, "reference": "Bérlő", "signer": "receiver", "email": "partner@example.com", "fill_details": true, "signer_name": "Nagy Péter", "type": "private_person", "name": "Nagy Péter", "mother_name": "Szabó Mária", "birth_date": "1985-04-12", "birth_place": "Debrecen", "address": "4026 Debrecen, Példa utca 3.", "phone": "+36301234567" } ], "fields": [ { "id": 5821, "name": "Bérleti díj", "filler": "sender" } ], "attachments": [ { "id": 912, "name": "Alaprajz" } ] } } } }, "responses": { "200": { "description": "A mentett szerződés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Szerződések" ], "summary": "Szerződés törlése", "operationId": "deleteContract", "description": "A szerződés végleges törlése a mellékleteivel, aláíróival, mezőivel, megjegyzéseivel és naplójával együtt. A szerződést készítő profil bármely tagja hívhatja, amíg a szerződés nincs lezárva (`signed` → 403). A partnerek a törlés után nem érik el a szerződést (a vendéglink is megszűnik).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító, pl. `k3j9x0qa7bmz2wfe`) — a paraméter neve `id`, de az értéke NEM a numerikus azonosító.", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres törlés, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts": { "post": { "tags": [ "Szerződések" ], "summary": "Szerződés létrehozása", "operationId": "createContract", "description": "Új szerződés (piszkozat) létrehozása egy profil nevében, amelynek tagja vagy. Sablon nélkül egy üres szerződés jön létre a te nyelveden, `acceptance` aláírási móddal és két aláírói hellyel (a készítő `sender` — a profiltulajdonos adataival — és egy üres `receiver`). Sablonból (`contract_template_token`) a sablon aláírási módja, nyelve, szövege, megjegyzése, aláírói helyei, mezői és mellékletei másolódnak át; ehhez a profil tulajdonosának csomagjában sablon funkció kell (különben 402).\n\nLétrehozáskor még senki nem kap levelet: a tartalmat, a partnereket és az email-címeket a `PUT /contracts/{id}` végponttal adod meg. A megadott profil lesz a következő szerződéseid alapértelmezett profilja. Webhook-eseményt vált ki.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_id", "name" ], "properties": { "profile_id": { "type": "integer", "description": "A profil azonosítója, amelynek a nevében a szerződés készül; olyan profil, amelynek tagja vagy (nem kell tulajdonosnak lenned).", "example": 1204 }, "name": { "type": "string", "maxLength": 255, "description": "A szerződés neve.", "example": "Bérleti szerződés – Fő utca 12." }, "contract_template_token": { "type": "string", "nullable": true, "description": "Sablon `token`-je, ha sablonból készül. A sablonnak a megadott `profile_id` profiljáé kell lennie (különben 422), és a profil tulajdonosának csomagjában kell lennie sablon funkciónak (különben 402).", "example": "tmpl0a1b2c3d4e5f" } } }, "example": { "profile_id": 1204, "name": "Bérleti szerződés – Fő utca 12." } } } }, "responses": { "200": { "description": "A létrehozott szerződés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contracts/search": { "post": { "tags": [ "Szerződések" ], "summary": "Szerződések keresése", "operationId": "searchContracts", "description": "Lapozható, rendezhető lista a hozzáférhető szerződéseidről. Azokat a szerződéseket éred el, amelyeket egy olyan profil készített, amelynek tagja vagy, vagy amelyben egy általad tulajdonolt profil aláíró. A `search` kulcsszó (szavanként, mind teljesüljön) a névben, a szövegben, a megjegyzésben, a felek szerepében és email-címében, valamint a mezők nevében és értékében keres. Minden találat a teljes `Contract` (minden kapcsolattal); alapértelmezett rendezés: `created_at` csökkenő.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchRequest" }, { "type": "object", "properties": { "order_column": { "type": "string", "enum": [ "name", "created_at", "updated_at" ], "default": "created_at", "description": "Rendezési oszlop (alapértelmezett irány: `desc`)." }, "profile_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak azok a szerződések, amelyeket ez a profil készített, vagy amelyben ez a profil aláíró (a választható profilok: `GET /contracts/available-profiles`)." }, "status": { "type": "string", "enum": [ "opened", "signable", "signed" ], "nullable": true, "description": "Állapot szerinti szűrés (lásd `Contract.status`)." }, "contract_template_token": { "type": "string", "nullable": true, "description": "Csak az ebből a sablonból készült szerződések (a sablonnak a te profiljaid egyikéé kell lennie)." }, "archived": { "type": "boolean", "nullable": true, "description": "`true` = csak az általad archiváltak, `false` = csak a nem archiváltak, hiányzik = mind." } } } ] } } } }, "responses": { "200": { "description": "Sikeres kérés.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchMeta" }, { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contracts/export": { "post": { "tags": [ "Szerződések" ], "summary": "Szerződések exportálása Excelbe", "operationId": "exportContracts", "description": "A keresés szűrőinek megfelelő ÖSSZES szerződés (lapozás nélkül) letöltése `contract.xlsx` fájlként. Oszlopok: név, profil, sablon, nyelv, állapot, aláírók száma, létrehozva, módosítva. Azokat a szerződéseket éred el, amelyeket egy olyan profil készített, amelynek tagja vagy, vagy amelyben egy általad tulajdonolt profil aláíró.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string", "nullable": true, "description": "Kulcsszavas szűrés, ugyanúgy, mint a keresésnél." }, "order_column": { "type": "string", "enum": [ "name", "created_at", "updated_at" ], "default": "created_at", "description": "Rendezési oszlop." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Rendezési irány." }, "profile_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak azok a szerződések, amelyeket ez a profil készített, vagy amelyben ez a profil aláíró (a választható profilok: `GET /contracts/available-profiles`)." }, "status": { "type": "string", "enum": [ "opened", "signable", "signed" ], "nullable": true, "description": "Állapot szerinti szűrés (lásd `Contract.status`)." }, "contract_template_token": { "type": "string", "nullable": true, "description": "Csak az ebből a sablonból készült szerződések (a sablonnak a te profiljaid egyikéé kell lennie)." }, "archived": { "type": "boolean", "nullable": true, "description": "`true` = csak az általad archiváltak, `false` = csak a nem archiváltak, hiányzik = mind." } } } } } }, "responses": { "200": { "description": "Az Excel-fájl.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contracts/available-profiles": { "get": { "tags": [ "Szerződések" ], "summary": "Szűréshez választható profilok", "operationId": "listContractAvailableProfiles", "description": "A profilok, amelyek szerint a szerződéseidet szűrheted (`POST /contracts/search` → `profile_id`): a saját profiljaid (amelyeknek tagja vagy) és azok a partnerprofilok, amelyek aláíróként szerepelnek valamelyik hozzáférhető szerződésedben. Név szerint rendezve. Egy partnerprofil tagjai és meghívásai nem szerepelnek a válaszban.", "responses": { "200": { "description": "Sikeres kérés.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/contracts/{token}/attachments": { "post": { "tags": [ "Szerződések" ], "summary": "Melléklet feltöltése", "operationId": "uploadContractAttachment", "description": "Egy melléklet (JPEG, PNG vagy PDF, legfeljebb 30 MB; a PDF-nek olvashatónak kell lennie) feltöltése a szerződéshez; a melléklet AZONNAL a lista végére kerül. A szerződést készítő profil tagja hívhatja, lezárt szerződésnél 403. A következő `PUT /contracts/{id}` hívásban az `attachments` listában szerepeltetned kell az azonosítóját, különben az a mentés törli. A feltöltés módosítja az aláírt tartalmat: a már leadott aláírások törlődnek (az érintettek levelet kapnak), és webhook-eseményt vált ki.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "A fájl (jpeg, png vagy pdf, max. 30 MB). Az eredeti fájlnév megmarad." } } } } } }, "responses": { "200": { "description": "A feltöltött melléklet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractAttachment" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contracts/{token}/leave": { "post": { "tags": [ "Szerződések" ], "summary": "Kilépés a szerződésből", "operationId": "leaveContract", "description": "Partnerként kilépsz egy szerződésből, amelybe korábban beléptél (elfogadtad a meghívást). Az aláírói helyed üres lesz (az email-cím, a profil törlődik), a már leadott aláírások is törlődnek (mivel az aláírt tartalom változik), és a szerződés a továbbiakban nem látszik nálad. A szerződést készítő profil tulajdonosa nem léphet ki, lezárt szerződésből sem lehet (403). A többi résztvevő levelet kap.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts/{token}/archive": { "post": { "tags": [ "Szerződések" ], "summary": "Szerződés archiválása", "operationId": "archiveContract", "description": "Egy lezárt (`signed`) szerződés archiválása a te profiljaidban (a szerződéshez kapcsolódó összes profilodban, így a profil többi tagja is archiváltnak látja). Csak lezárt, még nem archivált szerződésen (különben 403). A partnereknél nem változik semmi. Keresésben az `archived` szűrővel választhatod szét.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts/{token}/unarchive": { "post": { "tags": [ "Szerződések" ], "summary": "Archiválás visszavonása", "operationId": "unarchiveContract", "description": "Egy archivált, lezárt szerződés visszaállítása a profiljaidban. Csak lezárt és archivált szerződésen hívható (különben 403).", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts/{token}/sign-manually": { "post": { "tags": [ "Szerződések" ], "summary": "Szerződés lezárása (kézi)", "operationId": "signContractManually", "description": "Ha minden fél aláírt, de a szerződés még nincs lezárva, ezzel zárod le: elkészül az aláírt fájl (`acceptance` módnál a Signingo hitelesített időbélyeget és elektronikus bélyegzőt tesz rá; jogvita esetén a bíróságon bizonyítékként felhasználható), és minden résztvevő levelet kap. Csak a szerződést készítő profil **tulajdonosa** hívhatja, kitöltött számlázási adatokkal (különben 403).\n\n- Ha van ingyenes aláírási kereted, vagy a csomagod szerződésenként számol el: a lezárás azonnal megtörténik (a keretből fogy / elszámolódik), az `url` a szerződés oldala a webes felületen.\n- Különben az `url` a fizetési szolgáltató oldala egyetlen szerződés díjának kifizetéséhez; sikeres fizetés után a szerződés magától lezárul.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres kérés.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "A szerződés oldala (azonnali lezárásnál) vagy a fizetési oldal URL-je.", "example": "https://signingo.hu/contracts/k3j9x0qa7bmz2wfe" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts/{token}/fill-fields": { "post": { "tags": [ "Szerződések" ], "summary": "Mezők kitöltése", "operationId": "fillContractFields", "description": "Mezőértékek megadása. A szerződést készítő profil tagja minden mezőt kitölthet; partnerként (az aláíró profil tulajdonosaként) csak a `receiver` mezőket. Lezárt szerződésnél 403; ha egy felsorolt mezőt nem tölthetsz ki, 403 és semmi nem mentődik. Egy érték megváltozása módosítja az aláírt tartalmat: a már leadott aláírások törlődnek (az érintettek levelet kapnak). Amikor ezzel a hívással az összes `receiver` mező kitöltötté válik, a többi résztvevő levelet kap. Webhook-eseményt vált ki.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "array", "description": "A kitöltendő mezők (csak a felsoroltak változnak).", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "A szerződés egyik mezőjének azonosítója (`fields[].id`).", "example": 5821 }, "value": { "type": "string", "maxLength": 255, "nullable": true, "description": "Az új érték; `null` / hiányzó = a mező kiürítése.", "example": "250 000 Ft / hó" } } } } } }, "example": { "fields": [ { "id": 5821, "value": "250 000 Ft / hó" } ] } } } }, "responses": { "200": { "description": "A szerződés a kitöltés után.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contracts/{token}/generate-preview-url": { "get": { "tags": [ "Szerződések" ], "summary": "Előnézeti PDF linkje", "operationId": "generateContractPreviewUrl", "description": "Lejáró (60 percig érvényes) letöltési linket ad a szerződés **aktuális állapotának előnézeti PDF-jéhez** (még aláírás és bélyegző nélkül, a mellékletekkel). A link a böngészőben megjelenítve (inline) adja a PDF-et. A hozzáférhető szerződéseiden kívül egy még el nem fogadott meghívás szerződésén is hívható. Lezárt szerződésnél 403 — akkor az aláírt fájl linkjét kérd.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres kérés.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Aláírt, lejáró letöltési link az API-domainen (`/file-download/contracts/{token}/…?expires=…&signature=…`). A kiállítástól számított **60 percig** érvényes, bejelentkezés nélkül megnyitható (a link maga a jogosultság, ne oszd meg); lejárat vagy módosított paraméter esetén 403-at ad.", "example": "https://api.signingo.hu/file-download/contracts/k3j9x0qa7bmz2wfe/preview?expires=1793102400&signature=3f9c0e…" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts/{token}/generate-signed-file-url": { "get": { "tags": [ "Szerződések" ], "summary": "Aláírt fájl linkje", "operationId": "generateContractSignedFileUrl", "description": "Lejáró (60 percig érvényes) letöltési linket ad a lezárt szerződés **végleges, aláírt fájljához** (PDF; régi, AVDH-val aláírt szerződésnél `.asice`), a szerződés nevéből képzett fájlnévvel, böngészőben megjelenítve (inline). Csak lezárt (`signed`) szerződésen hívható (különben 403).", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres kérés.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Aláírt, lejáró letöltési link az API-domainen (`/file-download/contracts/{token}/…?expires=…&signature=…`). A kiállítástól számított **60 percig** érvényes, bejelentkezés nélkül megnyitható (a link maga a jogosultság, ne oszd meg); lejárat vagy módosított paraméter esetén 403-at ad.", "example": "https://api.signingo.hu/file-download/contracts/k3j9x0qa7bmz2wfe/preview?expires=1793102400&signature=3f9c0e…" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts/{token}/analyze-signed-file": { "get": { "tags": [ "Szerződések" ], "summary": "Aláírt fájl elemzése", "operationId": "analyzeContractSignedFile", "description": "Az aláírt fájl elektronikus aláírásainak és bélyegzőjének ellenőrzése: ki írta alá, érvényes-e, a tanúsítvány adatai. Lezárt szerződésnél a végleges fájlt elemzi; `digital_signature` módú, még nem lezárt szerződésnél a legutóbb feltöltött aláírt változatot. Ha még nincs aláírt fájl, 403.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres kérés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedFileAnalysis" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts/{token}/share": { "post": { "tags": [ "Szerződések" ], "summary": "Megosztási link létrehozása", "operationId": "shareContract", "description": "Csak olvasható megosztási linket készít: aki ismeri, bejelentkezés nélkül megnézheti a szerződést (a felek adatai, a mezők, a szöveg, a mellékletek, az aláírások — napló, megjegyzések és levelek nélkül), de aláírni nem tudja. Ha már volt link, újat készít, és a régi azonnal érvénytelen. A szerződést készítő profil tagja hívhatja (különben 403). A naplóba bekerül.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Az új megosztási link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractShare" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Szerződések" ], "summary": "Megosztási link visszavonása", "operationId": "unshareContract", "description": "A megosztási link azonnal érvénytelenné válik. A szerződést készítő profil tagja hívhatja (különben 403). A naplóba bekerül. A válaszban `url: null`.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A szerződés `token`-je (16 karakteres, kisbetűs azonosító).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "A link visszavonva (`url: null`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractShare" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts/invitations": { "get": { "tags": [ "Szerződésmeghívások" ], "summary": "Szerződésmeghívásaim", "operationId": "listContractInvitations", "description": "Azok a szerződések, amelyekbe a te email-címeddel hívtak meg aláírónak, és még nem fogadtad el vagy utasítottad el őket (legújabb elöl). Elfogadás előtt ezek a szerződések nem szerepelnek a keresésben és a `GET /contracts/{id}` végponton.", "responses": { "200": { "description": "Sikeres kérés.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContractInvitation" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" } } } }, "/contracts/invitations/{token}": { "get": { "tags": [ "Szerződésmeghívások" ], "summary": "Szerződésmeghívás lekérése", "operationId": "readContractInvitation", "description": "Egy, a te email-címedre szóló, még függő szerződésmeghívás szerződése. Ha nincs ilyen függő meghívásod, 404. Előnézeti PDF: `GET /contracts/{token}/generate-preview-url`.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A meghívást tartalmazó szerződés `token`-je (a meghívólistában a szerződés `token` mezője).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres kérés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractInvitation" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contracts/invitations/{token}/accept": { "post": { "tags": [ "Szerződésmeghívások" ], "summary": "Szerződésmeghívás elfogadása", "operationId": "acceptContractInvitation", "description": "Elfogadod a meghívást, és kiválasztod, melyik **saját** (általad tulajdonolt) profilod nevében írod alá. Az aláírói hely a profilhoz kapcsolódik, üres adatai a profil adataival töltődnek ki, és a szerződés ezután a hozzáférhető szerződéseid között szerepel. Saját profil nélkül (pl. ha egy profilba meghívott társfelhasználóként regisztráltál) 422 a `profile_id` mezőre: előbb hozz létre egy profilt. Lezárt szerződésnél 403. A szerződést készítő profil tagjai levelet kapnak. A választott profil lesz a következő elfogadások alapértelmezése.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A meghívást tartalmazó szerződés `token`-je (a meghívólistában a szerződés `token` mezője).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_id" ], "properties": { "profile_id": { "type": "integer", "description": "Egy általad tulajdonolt profil azonosítója (`GET /profiles/own`).", "example": 1307 } } } } } }, "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contracts/invitations/{token}/reject": { "post": { "tags": [ "Szerződésmeghívások" ], "summary": "Szerződésmeghívás elutasítása", "operationId": "rejectContractInvitation", "description": "Elutasítod a meghívást: az aláírói hely üres lesz (az email-címed törlődik róla), a szerződés nem látszik nálad. Lezárt szerződésnél 403. A szerződést készítő profil tagjai levelet kapnak, és új partnert adhatnak meg.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "A meghívást tartalmazó szerződés `token`-je (a meghívólistában a szerződés `token` mezője).", "schema": { "type": "string", "example": "k3j9x0qa7bmz2wfe" } } ], "responses": { "200": { "description": "Sikeres művelet, üres válasz." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contract-signatures/known-parties": { "get": { "tags": [ "Aláírások" ], "summary": "Korábbi partnerek keresése", "description": "Gépelés közbeni javaslat a címzett-mezőhöz: a szerződéseidben (amelyeket amúgy is látsz) korábban szereplő címzetteket keresi email-cím eleje, a fél neve vagy az aláíró neve alapján, a legutóbb megadott adataikkal. Legfeljebb 8 találat, email-címenként a legfrissebb; a saját email-címed és az adatok nélküli címzettek kimaradnak. Új adatot nem tárol, mellékhatása nincs.", "operationId": "getKnownParties", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Keresett szöveg (2–255 karakter): az email-cím eleje, vagy a fél / aláíró nevének bármely része.", "schema": { "type": "string", "minLength": 2, "maxLength": 255, "example": "minta" } } ], "responses": { "200": { "description": "A találatok (lehet üres lista).", "content": { "application/json": { "schema": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/KnownParty" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-signatures/{id}/fill-details": { "post": { "tags": [ "Aláírások" ], "summary": "Aláíró adatainak és email-címének megadása", "description": "Egy aláírói hely email-címét és szerződői adatait (személy / cég adatai) állítja be. Hívhatja a szerződést készítő profil bármely tagja (bármelyik helyre), illetve a címzett a saját, már elfogadott (`accepted`) helyére. Lezárt szerződésnél 403.\n\n**Két mód:** ha az `email`-en és a `type`-on kívül bármelyik adatmezőt kitöltöd, az összes adatmező validálódik (a `signer_name`, `type`, `name`, `address` kötelező; céghez `tax_number`, magánszemélyhez `mother_name`, `birth_date`, `birth_place`). Ha csak `email`-t küldesz, a hely adatai TÖRLŐDNEK (a címzett maga tölti ki őket).\n\n**Mellékhatások:** email-cím változásakor meghívó emailt küld a címzettnek; az adatok változásáról a többi fél emailt kap; ha a szerződést valaki már aláírta, az adatok módosítása minden aláírást töröl (ők emailt kapnak, hogy írják alá újra); a szerződéshez beállított webhookok értesítést kapnak.", "operationId": "fillSignatureDetails", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az aláírói hely (ContractSignature) numerikus azonosítója (`signatures[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 4821 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "nullable": true, "maxLength": 255, "description": "Az aláírói hely email-címe. MINDIG küldd el (a jelenlegi értékkel is): ha kimarad vagy `null`, a hely meghívása törlődik (állapota `pending` lesz). Nem egyezhet a szerződés másik aláírói helyének címével. Ha MEGVÁLTOZIK, a hely új meghívót kap: regisztrált felhasználó meghívást (állapot `invited`), más vendéglinket emailben (állapot `published`); a korábbi profil-kapcsolat és aláírás törlődik. A küldő (`signer=sender`) helyénél figyelmen kívül marad: ott mindig a profiltulajdonos címe áll.", "example": "partner@example.com" }, "signer_name": { "type": "string", "maxLength": 255, "description": "Az aláíró (cégnél a képviselő) teljes neve.", "example": "Kovács Anna", "nullable": true }, "phone": { "type": "string", "nullable": true, "pattern": "^\\+\\d{7,14}$", "description": "Telefonszám nemzetközi formátumban, szóköz nélkül (`+` és 7–14 számjegy). Nem kötelező.", "example": "+36301234567" }, "type": { "type": "string", "enum": [ "company", "private_person" ], "description": "A szerződő fél típusa: `company` = cég / egyéni vállalkozó, `private_person` = magánszemély.", "example": "company", "nullable": true }, "name": { "type": "string", "maxLength": 255, "description": "A szerződő fél neve (cégnév, vagy magánszemélynél a teljes név).", "example": "Minta Kereskedelmi Kft.", "nullable": true }, "tax_number": { "type": "string", "nullable": true, "maxLength": 255, "description": "Adószám. `type=company` esetén KÖTELEZŐ; magánszemélynél a mentéskor törlődik. Formátumot nem ellenőriz.", "example": "12345678-2-42" }, "mother_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Anyja születési neve. `type=private_person` esetén KÖTELEZŐ; cégnél a mentéskor törlődik.", "example": "Szabó Mária" }, "birth_date": { "type": "string", "format": "date", "nullable": true, "description": "Születési dátum `ÉÉÉÉ-HH-NN` alakban. `type=private_person` esetén KÖTELEZŐ; cégnél a mentéskor törlődik.", "example": "1985-04-12" }, "birth_place": { "type": "string", "nullable": true, "maxLength": 255, "description": "Születési hely. `type=private_person` esetén KÖTELEZŐ; cégnél a mentéskor törlődik.", "example": "Debrecen" }, "address": { "type": "string", "maxLength": 255, "description": "Székhely (cégnél) vagy lakcím (magánszemélynél).", "example": "1111 Budapest, Minta utca 1.", "nullable": true } } } } } }, "responses": { "200": { "description": "A frissített aláírói hely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSignature" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-signatures/{id}/sign-with-acceptance": { "post": { "tags": [ "Aláírások" ], "summary": "Aláírás elfogadással (aláírásképpel)", "description": "A szerződés `security` mezője dönti el, melyik aláírási mód érvényes:\n- **Elfogadással** (`acceptance`): az aláíró egy aláírásképet ad (feltölti, vagy a profil mentett aláírását használja). Az aláírás időpontja, IP-címe és eszköze rögzül.\n- **Digitális aláírással** (`digital_signature`): az aláíró letölti a szerződés aláírandó PDF-jét, a saját minősített vagy AVDH-s (DÁP) e-aláírásával aláírja, és visszatölti. A következő fél már ezt az aláírt változatot tölti le.\n\nEz a végpont az **elfogadásos** módé. Csak az aláírói hely profiljának tulajdonosa hívhatja (más helyére 404). Feltétel: minden fél adatai és a szerződés összes mezője ki van töltve, a hely még nincs aláírva, és a szerződés `security` értéke `acceptance` — különben 403 a pontos okkal (ezt előre a `permission_warnings.sign_with_acceptance` mutatja).\n\nA többi fél emailt kap az aláírásról, a webhookok értesítést kapnak. Ha ezzel az utolsó fél is aláírt, és a szerződés tulajdonosának van aláírási kerete, a rendszer lezárja a szerződést: elfogadásos módnál elkészíti az aláírt PDF-et, hitelesített időbélyeget és elektronikus bélyegzőt tesz rá (jogvita esetén a bíróságon bizonyítékként felhasználható), digitálisnál az utolsó feltöltött PDF lesz a végleges fájl; a lezárás egyet fogyaszt a tulajdonos aláírási keretéből, és minden fél emailt kap a kész szerződésről. Ha nincs keret, a szerződés aláírva, de lezáratlanul vár: a tulajdonos a `POST /contracts/{token}/sign-manually` hívással zárhatja le.", "operationId": "signWithAcceptance", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az aláírói hely (ContractSignature) numerikus azonosítója (`signatures[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 4821 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "signature": { "type": "string", "format": "binary", "description": "Az aláírás képe (JPEG vagy PNG, legfeljebb 30 MB és 4500×4500 px; nem lehet teljesen üres / átlátszó). KÖTELEZŐ, ha az aláíró profiljának nincs mentett aláírásképe; ha van és nem küldesz képet, a profil mentett aláírása kerül a szerződésre." }, "save_signature": { "type": "boolean", "nullable": true, "description": "Ha `true` és küldtél `signature` képet, a kép a profil mentett aláírásaként is eltárolódik (felülírja a korábbit).", "example": true } } } } } }, "responses": { "200": { "description": "Az aláírt hely (`status=signed`, `signature` = az aláíráskép URL-je).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSignature" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-signatures/{id}/download-signable-file-to-sign-with-digital-signature": { "get": { "tags": [ "Aláírások" ], "summary": "Aláírandó PDF letöltési linkje (digitális aláíráshoz)", "description": "A **digitális aláírásos** mód első lépése: visszaadja az aláírandó PDF 60 percig érvényes letöltési linkjét. Az első aláíró a Signingo elektronikus bélyegzőjével ellátott PDF-et kapja, a későbbiek az előző fél által aláírt változatot. Ezt a fájlt írd alá a saját minősített vagy AVDH-s (DÁP) e-aláírásoddal (a tartalmán ne módosíts), majd töltsd vissza a `…/sign-with-digital-signature` végponton.\n\nCsak az aláírói hely profiljának tulajdonosa hívhatja (más helyére 404), és csak akkor, ha a hely most aláírható (adatok és mezők kitöltve, `security=digital_signature`) — különben 403. Mellékhatása nincs.", "operationId": "getSignableFileUrlForDigitalSignature", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az aláírói hely (ContractSignature) numerikus azonosítója (`signatures[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 4821 } } ], "responses": { "200": { "description": "A letöltési link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Aláírt, 60 percig érvényes letöltési link (az API domainjén). Bejelentkezés nélkül megnyitható, ezért ne oszd meg.", "example": "https://api.signingo.hu/file-download/contracts/abcd1234efgh5678/preview?expires=1767225600&signature=0f1e2d…" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contract-signatures/{id}/sign-with-digital-signature": { "post": { "tags": [ "Aláírások" ], "summary": "Aláírás digitálisan aláírt PDF feltöltésével", "description": "A szerződés `security` mezője dönti el, melyik aláírási mód érvényes:\n- **Elfogadással** (`acceptance`): az aláíró egy aláírásképet ad (feltölti, vagy a profil mentett aláírását használja). Az aláírás időpontja, IP-címe és eszköze rögzül.\n- **Digitális aláírással** (`digital_signature`): az aláíró letölti a szerződés aláírandó PDF-jét, a saját minősített vagy AVDH-s (DÁP) e-aláírásával aláírja, és visszatölti. A következő fél már ezt az aláírt változatot tölti le.\n\nEz a végpont a **digitális** mód második lépése: feltöltöd a letöltött és saját e-aláírásoddal aláírt PDF-et. Csak az aláírói hely profiljának tulajdonosa hívhatja (más helyére 404), a feltételek ugyanazok, mint a letöltésnél (különben 403). A rendszer ellenőrzi, hogy a fájl ugyanezt a szerződést tartalmazza változatlanul, minden aláírása érvényes, a korábbi aláírások mind megvannak, és legalább egy új aláírás került rá — ha nem, 422 a `signed_file` mezőre.\n\nA többi fél emailt kap az aláírásról, a webhookok értesítést kapnak; az első digitális aláírásnál a szerződés hatályának kezdete (`validity_start`) a letöltött PDF bélyegzőjének ideje lesz. Ha ezzel az utolsó fél is aláírt, és a szerződés tulajdonosának van aláírási kerete, a rendszer lezárja a szerződést: elfogadásos módnál elkészíti az aláírt PDF-et, hitelesített időbélyeget és elektronikus bélyegzőt tesz rá (jogvita esetén a bíróságon bizonyítékként felhasználható), digitálisnál az utolsó feltöltött PDF lesz a végleges fájl; a lezárás egyet fogyaszt a tulajdonos aláírási keretéből, és minden fél emailt kap a kész szerződésről. Ha nincs keret, a szerződés aláírva, de lezáratlanul vár: a tulajdonos a `POST /contracts/{token}/sign-manually` hívással zárhatja le.", "operationId": "signWithDigitalSignature", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az aláírói hely (ContractSignature) numerikus azonosítója (`signatures[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 4821 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "signed_file" ], "properties": { "signed_file": { "type": "string", "format": "binary", "description": "A `…/download-signable-file-to-sign-with-digital-signature` linkjéről letöltött PDF, a saját minősített vagy AVDH-s (DÁP) elektronikus aláírásoddal aláírva. Csak PDF." } } } } } }, "responses": { "200": { "description": "Sikeres aláírás.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedFileAnalysis" }, { "type": "object", "required": [ "signature" ], "properties": { "signature": { "allOf": [ { "$ref": "#/components/schemas/ContractSignature" } ], "description": "Az aláírói hely a mentés után (`status=signed`)." } } } ], "description": "A frissített aláírói hely, és a feltöltött PDF aláírásainak elemzése (`signers`, `hierarchy` — ugyanaz a forma, mint a `…/analyze-signed-file` válasza)." } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-signatures/{id}/remove-signature": { "post": { "tags": [ "Aláírások" ], "summary": "Aláírás visszavonása", "description": "Visszavonja a hely aláírását, amíg a szerződés nincs lezárva. Csak az aláírói hely profiljának tulajdonosa hívhatja (más helyére 404); ha a hely nincs aláírva vagy a szerződés lezárt, 403.\n\n**Mellékhatások:** digitális aláírásos szerződésnél a később aláírt felek aláírása is törlődik (az ő fájljuk erre épült). Ha így egy aláírás sem marad, a `validity_start` törlődik. A többi fél emailt kap, a webhookok értesítést kapnak.", "operationId": "removeSignature", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az aláírói hely (ContractSignature) numerikus azonosítója (`signatures[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 4821 } } ], "responses": { "200": { "description": "A hely aláírás nélkül (`status` = `accepted`, vagy vendégnél `published`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSignature" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contract-signatures/{id}/send-reminder": { "post": { "tags": [ "Aláírások" ], "summary": "Emlékeztető küldése a címzettnek", "description": "Kézi emlékeztető emailt küld egy címzettnek a hátralévő teendőjéről (meghívás elfogadása, adatok megadása, mezők kitöltése vagy aláírás — ami épp esedékes; ha egyik sem, egy általános „még nem írtad alá\" levelet). A szerződést készítő profil tagja hívhatja, csak `receiver` helyre, amelynek van email-címe, még nem írt alá, és nem a saját profilodé.\n\nUgyanannak a címzettnek az utolsó meghívó / emlékeztető után 60 percig nem küldhető újra: ilyenkor 403 (a `permission_warnings.send_reminder.code` értéke `reminder_too_soon`, nem elérhető esetben `reminder_not_available`). Lezárt szerződésnél 403.", "operationId": "sendSignatureReminder", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az aláírói hely (ContractSignature) numerikus azonosítója (`signatures[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 4821 } } ], "responses": { "200": { "description": "Az aláírói hely (változatlan adatokkal).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSignature" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contract-comments": { "post": { "tags": [ "Megjegyzések" ], "summary": "Megjegyzés írása a szerződéshez", "description": "Megjegyzést fűz egy szerződéshez, amelyet látsz (a küldő profil tagjaként vagy egy címzett profil tulajdonosaként). A megjegyzés a saját neveddel és email-címeddel jelenik meg minden félnek.\n\nFeltétel: a szerződés tulajdonosának csomagjában legyen elérhető a megjegyzés funkció (`contract_commenting`), különben 403 (előre: a szerződés `permission_warnings.create_comment` mezője; a tulajdonosnál ott `upgrade_required`). Mellékhatás: a szerződés többi fele emailt kap, a webhookok értesítést kapnak.", "operationId": "createContractComment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contract_token", "content" ], "properties": { "contract_token": { "type": "string", "description": "A szerződés tokenje (`token`). Csak olyan szerződésé lehet, amelyet látsz.", "example": "abcd1234efgh5678" }, "content": { "type": "string", "maxLength": 65535, "description": "A megjegyzés szövege (sima szöveg).", "example": "A 3. pontban a fizetési határidő 15 nap legyen." } } } } } }, "responses": { "200": { "description": "A létrehozott megjegyzés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractComment" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contract-comments/{id}": { "put": { "tags": [ "Megjegyzések" ], "summary": "Saját megjegyzés módosítása", "description": "A saját megjegyzésed szövegét cseréli; más megjegyzésénél és törölt megjegyzésnél 403. Csak a látható szerződéseid megjegyzései érhetők el (más: 404). A módosított megjegyzés `edited=true` jelölést kap. A webhookok értesítést kapnak; emailt nem küld.", "operationId": "updateContractComment", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A megjegyzés numerikus azonosítója (`comments[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 912 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 65535, "description": "A megjegyzés szövege (sima szöveg).", "example": "A 3. pontban a fizetési határidő 15 nap legyen." } } } } } }, "responses": { "200": { "description": "A módosított megjegyzés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractComment" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Megjegyzések" ], "summary": "Saját megjegyzés törlése", "description": "Törli a saját megjegyzésedet; más megjegyzésénél és már törölt megjegyzésnél 403. A megjegyzés helye megmarad a szerződésben (`deleted=true`, a `content` `null` lesz), a szövege nem állítható vissza. A webhookok értesítést kapnak.", "operationId": "deleteContractComment", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A megjegyzés numerikus azonosítója (`comments[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 912 } } ], "responses": { "200": { "description": "A törölt megjegyzés (`deleted=true`, `content=null`). Nem üres válasz, mint a többi törlésnél.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractComment" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contract-samples": { "get": { "tags": [ "Szerződésminták" ], "summary": "Szerződésminták listája", "description": "Az összes szerződésminta a Signingo által meghatározott sorrendben, az aláírói helyekkel, mezőkkel és mellékletekkel együtt. Bejelentkezés nélkül is hívható (token nélkül a minták nyilvánosan böngészhetők). Saját sablonként a `POST /contract-samples/{id}/copy-to-profile` hívással másolhatod a profilodba.", "operationId": "listContractSamples", "security": [], "responses": { "200": { "description": "A minták listája (nincs lapozás).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContractSample" } } } } } } } }, "/contract-samples/{id}": { "get": { "tags": [ "Szerződésminták" ], "summary": "Szerződésminta lekérdezése", "description": "Egy szerződésminta az aláírói helyekkel, mezőkkel és mellékletekkel. Bejelentkezés nélkül is hívható.", "operationId": "getContractSample", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A minta numerikus azonosítója (`id`).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A minta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSample" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contract-samples/{id}/copy-to-profile": { "post": { "tags": [ "Szerződésminták" ], "summary": "Szerződésminta másolása sablonként egy profilba", "description": "Új szerződéssablont hoz létre a megadott profilban a minta nevével, nyelvével, szövegével, aláírói helyeivel, mezőivel és mellékleteivel (a mellékletfájlok is lemásolódnak). Belépési tokennel vagy API-kulccsal hívható; a `profile_id` bármely profil lehet, amelynek tag vagy (nem csak a tulajdonolt). A profil tulajdonosának csomagjában kell a `contract_templates` funkció, különben 403. A sablon biztonsági szintje az alapértelmezett (`acceptance`).", "operationId": "copyContractSampleToProfile", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A minta numerikus azonosítója (`id`).", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_id" ], "properties": { "profile_id": { "type": "integer", "description": "A célprofil azonosítója; csak olyan profil, amelynek tagja vagy.", "example": 512 } } } } } }, "responses": { "200": { "description": "A létrejött sablon. Ebben a válaszban a kapcsolatok közül csak a `signatures` szerepel, a `fields`, `attachments` és `profile` nincs betöltve (a teljes sablont a `GET /contract-templates/{id}` adja).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractTemplate" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/posts/search": { "post": { "tags": [ "Blog" ], "summary": "Blogbejegyzések listázása", "description": "Lapozva listázza a blogbejegyzéseket, alapból a legújabbal kezdve (`published_at` szerint csökkenő). Bejelentkezés nélkül hívható. Szöveges keresést (`search`) ez a végpont NEM fogad: ha elküldöd, figyelmen kívül marad. A szöveges mezők nyelvét az `Accept-Language` fejléc (hu|en) adja.", "operationId": "searchPosts", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchRequest" }, { "type": "object", "properties": { "order_column": { "type": "string", "description": "A rendezés oszlopa. Alapértelmezés: `published_at`.", "enum": [ "published_at" ], "nullable": true, "default": "published_at" }, "order_direction": { "type": "string", "description": "Rendezési irány. Alapértelmezés: `desc`.", "enum": [ "asc", "desc" ], "nullable": true, "default": "desc" } } } ] } } } }, "responses": { "200": { "description": "A találatok egy oldala.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchMeta" }, { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } }, "required": [ "records" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/posts/{id}": { "get": { "tags": [ "Blog" ], "summary": "Blogbejegyzés lekérdezése", "description": "Egy blogbejegyzés az azonosítója alapján. Bejelentkezés nélkül hívható. A szöveges mezők nyelvét az `Accept-Language` fejléc (hu|en) adja.", "operationId": "getPost", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A bejegyzés numerikus azonosítója (`id`).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A bejegyzés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/user-logs/{id}": { "get": { "tags": [ "Tevékenységnapló" ], "summary": "Egy naplóbejegyzés lekérése", "description": "A bejelentkezett felhasználó tevékenységnaplójának egy bejegyzése (pl. bejelentkezés, jelszócsere, profil módosítása). Más felhasználó bejegyzésére 404-et kapsz.", "operationId": "getUserLog", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A naplóbejegyzés azonosítója (`id`).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "A naplóbejegyzés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserLog" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/user-logs/search": { "post": { "tags": [ "Tevékenységnapló" ], "summary": "Tevékenységnapló lapozása", "description": "A bejelentkezett felhasználó tevékenységnaplója lapozva, alapból a legújabbal kezdve. Csak időrendben rendezhető; szöveges keresést (`search`) ez a végpont nem fogad, a mezőt figyelmen kívül hagyja.", "operationId": "searchUserLogs", "requestBody": { "required": false, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchRequest" }, { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ "created_at" ], "default": "created_at", "description": "A rendezés oszlopa. Alapértelmezés: `created_at`, `desc` iránnyal." } } } ] } } } }, "responses": { "200": { "description": "A naplóbejegyzések egy oldala.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchMeta" }, { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/UserLog" }, "description": "Az aktuális oldal találatai." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/user-logs/export": { "post": { "tags": [ "Tevékenységnapló" ], "summary": "Tevékenységnapló exportálása Excelbe", "description": "A teljes saját tevékenységnaplót Excel-fájlban (`user_log.xlsx`) adja vissza, lapozás nélkül. Oszlopok: esemény, eszköz, IP, időpont; a fejléc és az esemény szövege a felhasználó nyelvén.", "operationId": "exportUserLogs", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ "created_at" ], "default": "created_at", "description": "A rendezés oszlopa." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "desc", "description": "A rendezés iránya." } } } } } }, "responses": { "200": { "description": "Az Excel-fájl (`user_log.xlsx`).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/sent-mails/{id}": { "get": { "tags": [ "Kiküldött levelek" ], "summary": "Egy kiküldött levél lekérése", "description": "Egy, a te email-címedre küldött rendszerlevél adatai és kézbesítési állapota (elküldve / megérkezett / megnyitva / blokkolva). Más címre küldött levélre 404-et kapsz.", "operationId": "getSentMail", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A kiküldött levél azonosítója (`id`).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "A kiküldött levél.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentMail" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sent-mails/search": { "post": { "tags": [ "Kiküldött levelek" ], "summary": "Kiküldött levelek lapozása", "description": "A Signingo által a te email-címedre küldött levelek (meghívók, emlékeztetők, értesítések) lapozva, alapból a legújabbal kezdve, kézbesítési állapottal. Csak időrendben rendezhető; szöveges keresést (`search`) ez a végpont nem fogad, a mezőt figyelmen kívül hagyja.", "operationId": "searchSentMails", "requestBody": { "required": false, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchRequest" }, { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ "created_at" ], "default": "created_at", "description": "A rendezés oszlopa. Alapértelmezés: `created_at`, `desc` iránnyal." } } } ] } } } }, "responses": { "200": { "description": "A levelek egy oldala.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchMeta" }, { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/SentMail" }, "description": "Az aktuális oldal találatai." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/sent-mails/export": { "post": { "tags": [ "Kiküldött levelek" ], "summary": "Kiküldött levelek exportálása Excelbe", "description": "A te email-címedre küldött összes levelet Excel-fájlban (`sent_mail.xlsx`) adja vissza, lapozás nélkül. Oszlopok: email-cím, levél típusa, tárgy, állapot, küldés ideje; a fejléc és a címkék a felhasználó nyelvén.", "operationId": "exportSentMails", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ "created_at" ], "default": "created_at", "description": "A rendezés oszlopa." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "desc", "description": "A rendezés iránya." } } } } } }, "responses": { "200": { "description": "Az Excel-fájl (`sent_mail.xlsx`).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/guest/{guestSignatureToken}/contract": { "get": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "A szerződés lekérése vendégként", "description": "A Signingo vendég aláírói felületét szolgálja ki: a meghívó emailben kapott linkkel, regisztráció nélkül megnyitott szerződést adja vissza. Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. \n\nA válasz ugyanaz a teljes szerződés-erőforrás, amit a hitelesített `GET /contracts/{id}` ad (lásd `GuestContract`): a vendég saját helyét a `signatures[].own=true` jelöli. Mellékhatása nincs.", "operationId": "guestReadContract", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "responses": { "200": { "description": "A szerződés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestContract" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/guest/{guestSignatureToken}/contract/fill-fields": { "post": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Mezők kitöltése vendégként", "description": "A címzettnek (`filler=receiver`) szánt kitöltendő mezők értékét adja meg. Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. A hitelesített párja (`POST /contracts/{token}/fill-fields`) ugyanígy működik, de ott a küldő mezői is kitölthetők; vendégként a küldő mezője 403. Lezárt szerződésnél 403.\n\n**Mellékhatások:** ha a szerződést valaki már aláírta, a mezőérték változása minden aláírást töröl (ők emailt kapnak); amikor az utolsó címzetti mező is kitöltődik, a többi fél emailt kap; a webhookok értesítést kapnak.", "operationId": "guestFillContractFields", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "array", "description": "A kitöltendő mezők. Nem kell mindet egyszerre küldeni; a nem küldött mezők nem változnak.", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "A mező azonosítója (`fields[].id` a szerződés válaszában); csak e szerződés mezője lehet.", "example": 311 }, "value": { "type": "string", "nullable": true, "maxLength": 255, "description": "A mező értéke; `null` vagy hiányzó érték törli a kitöltést.", "example": "2026. november 15." } } } } } } } } }, "responses": { "200": { "description": "A frissített szerződés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestContract" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/guest/{guestSignatureToken}/contract/generate-preview-url": { "get": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Előnézeti PDF linkje vendégként", "description": "A még nem lezárt szerződés előnézeti PDF-jének 60 percig érvényes letöltési linkjét adja (lezárt szerződésnél 403 — akkor az aláírt fájlt kérd). Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. Ugyanaz, mint a hitelesített `GET /contracts/{token}/generate-preview-url`. Mellékhatása nincs.", "operationId": "guestGenerateContractPreviewUrl", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "responses": { "200": { "description": "A letöltési link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Aláírt, 60 percig érvényes letöltési link (az API domainjén). Bejelentkezés nélkül megnyitható, ezért ne oszd meg.", "example": "https://api.signingo.hu/file-download/contracts/abcd1234efgh5678/preview?expires=1767225600&signature=0f1e2d…" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/guest/{guestSignatureToken}/contract/generate-signed-file-url": { "get": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Aláírt szerződés letöltési linkje vendégként", "description": "A lezárt (`status=signed`) szerződés végleges, aláírt PDF-jének 60 percig érvényes letöltési linkjét adja; lezáratlan szerződésnél 403. Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. Ugyanaz, mint a hitelesített `GET /contracts/{token}/generate-signed-file-url`. Mellékhatása nincs.", "operationId": "guestGenerateSignedFileUrl", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "responses": { "200": { "description": "A letöltési link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Aláírt, 60 percig érvényes letöltési link (az API domainjén). Bejelentkezés nélkül megnyitható, ezért ne oszd meg.", "example": "https://api.signingo.hu/file-download/contracts/abcd1234efgh5678/preview?expires=1767225600&signature=0f1e2d…" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/guest/{guestSignatureToken}/contract/analyze-signed-file": { "get": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Aláírt fájl aláírásainak elemzése vendégként", "description": "Kiolvassa és ellenőrzi az aláírt PDF-en lévő elektronikus aláírásokat és bélyegzőket: lezárt szerződésnél a végleges fájlét, lezáratlan digitális aláírásos szerződésnél a legutóbb aláírt változatét. Ha még nincs aláírt fájl, 403. Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. Ugyanaz, mint a hitelesített `GET /contracts/{token}/analyze-signed-file`. Mellékhatása nincs.", "operationId": "guestAnalyzeSignedFile", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "responses": { "200": { "description": "Az elemzés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedFileAnalysis" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/guest/{guestSignatureToken}/signature/fill-details": { "post": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Saját szerződői adatok megadása vendégként", "description": "A vendég a saját aláírói helyének szerződői adatait adja meg (személy vagy cég). Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. A hitelesített `POST /contract-signatures/{id}/fill-details`-től eltérően itt nincs `email` mező (a vendég email-címe nem módosítható), és az adatok mindig teljes körűen validálódnak: a `signer_name`, `type`, `name`, `address` kötelező; céghez a `tax_number`, magánszemélyhez a `mother_name`, `birth_date`, `birth_place` is. Lezárt szerződésnél 403.\n\n**Mellékhatások:** a többi fél emailt kap az adatok változásáról; ha a szerződést valaki már aláírta, minden aláírás törlődik (ők emailt kapnak); a webhookok értesítést kapnak.", "operationId": "guestFillSignatureDetails", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "signer_name", "type", "name", "address" ], "properties": { "signer_name": { "type": "string", "maxLength": 255, "description": "Az aláíró (cégnél a képviselő) teljes neve.", "example": "Kovács Anna" }, "phone": { "type": "string", "nullable": true, "pattern": "^\\+\\d{7,14}$", "description": "Telefonszám nemzetközi formátumban, szóköz nélkül (`+` és 7–14 számjegy). Nem kötelező.", "example": "+36301234567" }, "type": { "type": "string", "enum": [ "company", "private_person" ], "description": "A szerződő fél típusa: `company` = cég / egyéni vállalkozó, `private_person` = magánszemély.", "example": "company" }, "name": { "type": "string", "maxLength": 255, "description": "A szerződő fél neve (cégnév, vagy magánszemélynél a teljes név).", "example": "Minta Kereskedelmi Kft." }, "tax_number": { "type": "string", "nullable": true, "maxLength": 255, "description": "Adószám. `type=company` esetén KÖTELEZŐ; magánszemélynél a mentéskor törlődik. Formátumot nem ellenőriz.", "example": "12345678-2-42" }, "mother_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Anyja születési neve. `type=private_person` esetén KÖTELEZŐ; cégnél a mentéskor törlődik.", "example": "Szabó Mária" }, "birth_date": { "type": "string", "format": "date", "nullable": true, "description": "Születési dátum `ÉÉÉÉ-HH-NN` alakban. `type=private_person` esetén KÖTELEZŐ; cégnél a mentéskor törlődik.", "example": "1985-04-12" }, "birth_place": { "type": "string", "nullable": true, "maxLength": 255, "description": "Születési hely. `type=private_person` esetén KÖTELEZŐ; cégnél a mentéskor törlődik.", "example": "Debrecen" }, "address": { "type": "string", "maxLength": 255, "description": "Székhely (cégnél) vagy lakcím (magánszemélynél).", "example": "1111 Budapest, Minta utca 1." } } } } } }, "responses": { "200": { "description": "A vendég frissített aláírói helye.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSignature" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/guest/{guestSignatureToken}/signature/sign-with-acceptance": { "post": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Aláírás elfogadással vendégként", "description": "A vendég aláírja a szerződést egy aláírásképpel (elfogadásos mód, `security=acceptance`). Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. A hitelesített párjától eltérően itt a `signature` kép mindig kötelező (a vendégnek nincs mentett aláírása), és `save_signature` nincs. Feltétel: minden fél adatai és a szerződés összes mezője ki van töltve, és a vendég még nem írt alá — különben 403 a pontos okkal.\n\nA többi fél emailt kap, a webhookok értesítést kapnak. Ha ezzel az utolsó fél is aláírt, és a szerződés tulajdonosának van aláírási kerete, a rendszer lezárja a szerződést: elfogadásos módnál elkészíti az aláírt PDF-et, hitelesített időbélyeget és elektronikus bélyegzőt tesz rá (jogvita esetén a bíróságon bizonyítékként felhasználható), digitálisnál az utolsó feltöltött PDF lesz a végleges fájl; a lezárás egyet fogyaszt a tulajdonos aláírási keretéből, és minden fél emailt kap a kész szerződésről. Ha nincs keret, a szerződés aláírva, de lezáratlanul vár: a tulajdonos a saját fiókjából zárhatja le.", "operationId": "guestSignWithAcceptance", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "signature" ], "properties": { "signature": { "type": "string", "format": "binary", "description": "Az aláírás képe (JPEG vagy PNG, legfeljebb 30 MB és 4500×4500 px; nem lehet teljesen üres / átlátszó)." } } } } } }, "responses": { "200": { "description": "Az aláírt hely (`status=signed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSignature" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/guest/{guestSignatureToken}/signature/download-signable-file-to-sign-with-digital-signature": { "get": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Aláírandó PDF linkje vendégként (digitális aláíráshoz)", "description": "A digitális aláírásos mód első lépése vendégként: az aláírandó PDF 60 percig érvényes letöltési linkje (az eddigi aláírásokkal együtt). Ezt írd alá a saját minősített vagy AVDH-s (DÁP) e-aláírásoddal, és töltsd vissza a `…/signature/sign-with-digital-signature` végponton. Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. Ha a hely most nem aláírható (hiányzó adatok / mezők, már aláírt, nem digitális mód), 403. Ugyanaz, mint a hitelesített párja, csak a hely a tokenből jön. Mellékhatása nincs.", "operationId": "guestGetSignableFileUrlForDigitalSignature", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "responses": { "200": { "description": "A letöltési link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Aláírt, 60 percig érvényes letöltési link (az API domainjén). Bejelentkezés nélkül megnyitható, ezért ne oszd meg.", "example": "https://api.signingo.hu/file-download/contracts/abcd1234efgh5678/preview?expires=1767225600&signature=0f1e2d…" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/guest/{guestSignatureToken}/signature/sign-with-digital-signature": { "post": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Aláírás digitálisan aláírt PDF feltöltésével vendégként", "description": "A vendég feltölti a letöltött és saját e-aláírásával aláírt PDF-et (digitális mód, `security=digital_signature`). Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. Az ellenőrzés ugyanaz, mint a hitelesített párjánál: a fájl ugyanezt a szerződést tartalmazza változatlanul, minden aláírása érvényes, a korábbiak megvannak, és van rajta új aláírás — különben 422 a `signed_file` mezőre.\n\nA többi fél emailt kap, a webhookok értesítést kapnak. Ha ezzel az utolsó fél is aláírt, és a szerződés tulajdonosának van aláírási kerete, a rendszer lezárja a szerződést: elfogadásos módnál elkészíti az aláírt PDF-et, hitelesített időbélyeget és elektronikus bélyegzőt tesz rá (jogvita esetén a bíróságon bizonyítékként felhasználható), digitálisnál az utolsó feltöltött PDF lesz a végleges fájl; a lezárás egyet fogyaszt a tulajdonos aláírási keretéből, és minden fél emailt kap a kész szerződésről. Ha nincs keret, a szerződés aláírva, de lezáratlanul vár: a tulajdonos a saját fiókjából zárhatja le.", "operationId": "guestSignWithDigitalSignature", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "signed_file" ], "properties": { "signed_file": { "type": "string", "format": "binary", "description": "A `…/download-signable-file-to-sign-with-digital-signature` linkjéről letöltött PDF, a saját minősített vagy AVDH-s (DÁP) elektronikus aláírásoddal aláírva. Csak PDF." } } } } } }, "responses": { "200": { "description": "Sikeres aláírás.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedFileAnalysis" }, { "type": "object", "required": [ "signature" ], "properties": { "signature": { "allOf": [ { "$ref": "#/components/schemas/ContractSignature" } ], "description": "Az aláírói hely a mentés után (`status=signed`)." } } } ], "description": "A frissített aláírói hely, és a feltöltött PDF aláírásainak elemzése (`signers`, `hierarchy` — ugyanaz a forma, mint a `…/analyze-signed-file` válasza)." } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/guest/{guestSignatureToken}/signature/remove-signature": { "post": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Saját aláírás visszavonása vendégként", "description": "A vendég visszavonja a saját aláírását, amíg a szerződés nincs lezárva (lezárt szerződésnél vagy ha nincs aláírva: 403). Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. Digitális aláírásos szerződésnél a később aláírt felek aláírása is törlődik. A többi fél emailt kap, a webhookok értesítést kapnak. Ugyanaz, mint a hitelesített párja, csak a hely a tokenből jön.", "operationId": "guestRemoveSignature", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "responses": { "200": { "description": "A hely aláírás nélkül (`status=published`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSignature" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/guest/{guestSignatureToken}/comments": { "post": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Megjegyzés írása vendégként", "description": "Megjegyzést fűz a szerződéshez a vendég email-címével. Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. A hitelesített `POST /contract-comments`-től eltérően nincs `contract_token`: a szerződés a tokenből jön. Ha a szerződés tulajdonosának csomagjában nincs megjegyzés funkció, 403. A többi fél emailt kap, a webhookok értesítést kapnak.", "operationId": "guestCreateContractComment", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 65535, "description": "A megjegyzés szövege (sima szöveg).", "example": "A 3. pontban a fizetési határidő 15 nap legyen." } } } } } }, "responses": { "200": { "description": "A létrehozott megjegyzés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractComment" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/guest/{guestSignatureToken}/comments/{id}": { "put": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Saját megjegyzés módosítása vendégként", "description": "A vendég a saját (az email-címével írt, vendégként létrehozott) megjegyzésének szövegét cseréli; más megjegyzésénél 403, törölt vagy más szerződéshez tartozó megjegyzésnél 404. Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. A módosított megjegyzés `edited=true` jelölést kap; a webhookok értesítést kapnak.", "operationId": "guestUpdateContractComment", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } }, { "name": "id", "in": "path", "required": true, "description": "A megjegyzés numerikus azonosítója (`comments[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 912 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 65535, "description": "A megjegyzés szövege (sima szöveg).", "example": "A 3. pontban a fizetési határidő 15 nap legyen." } } } } } }, "responses": { "200": { "description": "A módosított megjegyzés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractComment" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Vendég aláíró" ], "security": [], "summary": "Saját megjegyzés törlése vendégként", "description": "A vendég törli a saját megjegyzését; más megjegyzésénél 403, már törölt vagy más szerződéshez tartozó megjegyzésnél 404. Bejelentkezés nélkül hívható: a vendég aláírót az útvonalban lévő `guestSignatureToken` azonosítja (a meghívó email linkjéből). Csak nem regisztrált címzett (`published`) vagy már aláírt vendéghely tokenjével működik; ismeretlen token, vagy ha a címzett közben regisztrált és a hely a profiljához kapcsolódott: 404. A megjegyzés helye megmarad (`deleted=true`, `content=null`); a webhookok értesítést kapnak.", "operationId": "guestDeleteContractComment", "parameters": [ { "name": "guestSignatureToken", "in": "path", "required": true, "description": "A vendég aláíró tokenje: a meghívó email „Szerződés megnyitása\" linkjében szereplő 16 karakteres azonosító. Ez maga a hitelesítés — aki ismeri, a címzett nevében eljárhat, ezért kezeld jelszóként. Ha az aláírói hely email-címét módosítják, új token készül, és a régi link 404-et ad.", "schema": { "type": "string", "minLength": 16, "maxLength": 16, "example": "k3j9x0q2m8w1r7ty" } }, { "name": "id", "in": "path", "required": true, "description": "A megjegyzés numerikus azonosítója (`comments[].id` a szerződés válaszában).", "schema": { "type": "integer", "minimum": 1, "example": 912 } } ], "responses": { "200": { "description": "A törölt megjegyzés (`deleted=true`, `content=null`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractComment" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API-kulcs (Felhasználóm › API kulcsok) vagy a `POST /login` által adott belépési token (`access_token.token`)." } }, "responses": { "Unauthenticated": { "description": "Hiányzó, lejárt vagy érvénytelen token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A hiba szöveges leírása a felhasználó nyelvén." } } }, "example": { "message": "Unauthenticated." } } } }, "PaymentRequired": { "description": "Az előfizetési csomag nem tartalmazza a funkciót (például az API hozzáférést).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A hiba szöveges leírása a felhasználó nyelvén." } } }, "example": { "message": "Jelenlegi csomagod nem támogatja az API hozzáférést. Válts nagyobb csomagra!" } } } }, "Forbidden": { "description": "A felhasználónak nincs joga a művelethez.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A hiba szöveges leírása a felhasználó nyelvén." } } }, "example": { "message": "Ehhez a művelethez nincs jogosultságod." } } } }, "NotFound": { "description": "A rekord nem létezik, vagy a felhasználó nem éri el.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A hiba szöveges leírása a felhasználó nyelvén." } } }, "example": { "message": "No query results for model." } } } }, "TooManyRequests": { "description": "Túl sok kérés rövid idő alatt; várj egy kicsit, és próbáld újra.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A hiba szöveges leírása a felhasználó nyelvén." } } }, "example": { "message": "Too Many Attempts." } } } }, "ValidationError": { "description": "Hibás adat, vagy a művelet a rekord mostani állapotában nem végezhető el.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Az első hiba szövege; több hibánál a végén „(és még N hiba)”." }, "errors": { "type": "object", "description": "Mezőnként a hibaüzenetek listája.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "example": { "message": "A név megadása kötelező.", "errors": { "name": [ "A név megadása kötelező." ] } } } } } }, "schemas": { "SearchRequest": { "type": "object", "description": "A `POST …/search` végpontok közös kérésmezői.", "properties": { "search": { "type": "string", "nullable": true, "description": "Szabad szöveges keresés. Szavanként keres: minden szónak szerepelnie kell valamelyik kereshető mezőben. Csak azoknál a végpontoknál, amelyek leírása kereshető mezőket említ." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200, "nullable": true, "description": "Egy oldalon visszaadott találatok száma." }, "page": { "type": "integer", "minimum": 1, "default": 1, "nullable": true, "description": "Az oldal sorszáma, 1-től." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "nullable": true, "description": "Rendezés iránya: `asc` növekvő, `desc` csökkenő. Alapértéke végpontonként eltér." } } }, "SearchMeta": { "type": "object", "description": "A `POST …/search` válaszok közös mezői (a találatok a `records` listában).", "properties": { "count": { "type": "integer", "description": "Az összes találat száma (minden oldalon együtt).", "example": 42 }, "page": { "type": "integer", "description": "A visszaadott oldal sorszáma.", "example": 1 }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat).", "example": 3 }, "order_column": { "type": "string", "description": "A rendezés oszlopa (a kért vagy az alapértelmezett).", "example": "id" }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A rendezés iránya (a kért vagy az alapértelmezett)." } } }, "PermissionWarnings": { "type": "object", "description": "Műveletenként (a kulcs a művelet neve, például `update`, `delete`, `sign_manually`): elvégezheti-e a bejelentkezett felhasználó. Az érték `null`, ha igen, különben egy figyelmeztetés. A felület ebből tudja előre, mely gombokat mutassa; a tényleges hívás tiltásnál `403`-at ad (csomagkorlátnál is).", "additionalProperties": { "type": "object", "nullable": true, "description": "Miért nem végezhető el a művelet.", "properties": { "message": { "type": "string", "description": "A figyelmeztetés szövege a felhasználó nyelvén (például mire kell váltani)." }, "code": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Az ok kódja: `402` = az előfizetési csomag nem tartalmazza, `403` = nincs jogosultság, `401` = bejelentkezés kell; egyes műveleteknél szöveges kód (például `reminder_too_soon`)." }, "type": { "type": "string", "enum": [ "upgrade_required", "forbidden", "login_required" ], "description": "Az ok típusa: `upgrade_required` (csomagváltás kell), `forbidden` (nincs jog), `login_required` (bejelentkezés kell)." } } }, "example": { "update": null, "delete": { "message": "Ehhez a művelethez nincs jogosultságod.", "code": 403, "type": "forbidden" } } }, "PackageFeatures": { "type": "object", "description": "Egy előfizetési csomag funkciói és korlátai. A számkorlátoknál a `null` korlátlant jelent.", "properties": { "contract_signing_balance": { "type": "boolean", "description": "Szerződéskötési egyenleg használata (a lezárt szerződések a csomag egyenlegéből fogynak, nem egyenként fizetendők)." }, "max_own_profiles": { "type": "integer", "description": "Legfeljebb ennyi saját (tulajdonolt) profil hozható létre; `null` = korlátlan.", "nullable": true, "example": 1 }, "max_profile_users": { "type": "integer", "description": "Egy profilnak legfeljebb ennyi tagja lehet (a tulajdonossal együtt); `null` = korlátlan.", "nullable": true, "example": 2 }, "max_contract_signatures": { "type": "integer", "description": "Egy szerződésen legfeljebb ennyi aláíró lehet; `null` = korlátlan.", "nullable": true, "example": 2 }, "contract_templates": { "type": "boolean", "description": "Szerződéssablonok használata (a szerződésminták profilba másolása is ezt kéri)." }, "contract_commenting": { "type": "boolean", "description": "Megjegyzések írása a szerződéseken." }, "email_tracking": { "type": "boolean", "description": "A kiküldött levelek kézbesítési állapotának követése." }, "bulk_contract_creation": { "type": "boolean", "description": "Tömeges szerződéskészítés Excel-táblából." }, "api": { "type": "boolean", "description": "Fejlesztői API-kulcsok és webhookok használata." }, "branding": { "type": "boolean", "description": "Saját logó és márkaszín a szerződéseken és a leveleken." } }, "required": [ "contract_signing_balance", "max_own_profiles", "max_profile_users", "max_contract_signatures", "contract_templates", "contract_commenting", "email_tracking", "bulk_contract_creation", "api", "branding" ] }, "User": { "type": "object", "description": "Egy felhasználó. A saját fiókodnál (belépés, regisztráció befejezése, `GET /user`) a teljes alakot kapod; más felhasználónál (pl. egy profil tagjainál) csak az alapadatok szerepelnek: `id`, `name`, `email`, `phone`, `avatar`, `language`, `intercom_hmac`. A többi mező csak a saját fiókodnál van jelen.", "properties": { "id": { "type": "integer", "description": "A felhasználó azonosítója.", "example": 1024 }, "name": { "type": "string", "description": "Teljes név.", "maxLength": 255, "example": "Minta Péter" }, "email": { "type": "string", "description": "Email cím (a belépési azonosító).", "format": "email", "maxLength": 255, "example": "minta.peter@example.com" }, "phone": { "type": "string", "description": "Telefonszám nemzetközi formában.", "example": "+36301234567" }, "avatar": { "type": "string", "description": "Profilkép. Jelenleg nem állítható be az API-n, ezért a gyakorlatban mindig `null`.", "nullable": true, "example": null }, "language": { "type": "string", "description": "A felület, a levelek és az API-üzenetek nyelve.", "enum": [ "hu", "en" ], "example": "hu" }, "token": { "type": "string", "description": "Csak a saját fiókodnál. Az ajánlókódod: aki ezzel regisztrál (`referral_code`), azt a rendszer hozzád köti.", "minLength": 16, "maxLength": 16, "example": "k3f9x0aq2mzr7c1b" }, "billing_name": { "type": "string", "description": "Csak a saját fiókodnál. Számlázási név.", "nullable": true, "maxLength": 255, "example": "Minta Kft." }, "billing_city": { "type": "string", "description": "Csak a saját fiókodnál. Számlázási cím: település.", "nullable": true, "maxLength": 255, "example": "Budapest" }, "billing_zip": { "type": "integer", "description": "Csak a saját fiókodnál. Számlázási cím: irányítószám.", "nullable": true, "minimum": 1000, "maximum": 9999, "example": 1111 }, "billing_address": { "type": "string", "description": "Csak a saját fiókodnál. Számlázási cím: utca, házszám.", "nullable": true, "maxLength": 255, "example": "Minta utca 1." }, "billing_tax_number": { "type": "string", "description": "Csak a saját fiókodnál. Számlázási adószám, formázva.", "nullable": true, "example": "12345678-1-23" }, "default_contract_creating_profile_id": { "type": "integer", "description": "Csak a saját fiókodnál. Az alapértelmezett profil, amelyben új szerződést hozol létre.", "nullable": true, "example": 512 }, "default_contract_accepting_profile_id": { "type": "integer", "description": "Csak a saját fiókodnál. Az alapértelmezett profil, amellyel a hozzád érkező szerződéseket elfogadod.", "nullable": true, "example": 512 }, "notification_settings": { "type": "object", "nullable": true, "description": "Csak a saját fiókodnál. A kikapcsolható levélcsoportok; `null` vagy hiányzó kulcs = kéri a leveleket. A kötelező levelek (meghívók, emlékeztetők, a kész szerződés, jelszó, megerősítés) nem kapcsolhatók ki.", "properties": { "partner_activity": { "type": "boolean", "description": "Értesítések a partnerek tevékenységéről (megnyitás, kitöltés, aláírás)." }, "comments": { "type": "boolean", "description": "Értesítések az új megjegyzésekről." }, "news": { "type": "boolean", "description": "Hírek, újdonságok." } } }, "intercom_hmac": { "type": "string", "description": "Az ügyfélszolgálati csevegő azonosításához használt aláírás (hex). Az integrációnak nincs vele teendője.", "example": "3f1c0e…" }, "package": { "type": "object", "description": "Csak a saját fiókodnál. A jelenleg érvényes előfizetési csomag.", "properties": { "name": { "type": "string", "description": "A csomag kulcsa. Előfizetés nélkül `free`, a próbaidőszak alatt a próbacsomag.", "enum": [ "free", "basic", "standard", "premium" ], "example": "standard" }, "period": { "type": "string", "description": "Számlázási időszak; `null`, ha nincs érvényes előfizetés.", "enum": [ "monthly", "yearly" ], "nullable": true, "example": "monthly" }, "trial": { "type": "boolean", "description": "Próbaidőszakban vagy-e (érvényes előfizetés nélkül)." }, "trial_ends_at": { "type": "integer", "description": "A próbaidőszak vége Unix-időbélyegként (másodperc); `null`, ha nem vagy próbaidőszakban.", "nullable": true, "example": 1793000000 }, "features": { "$ref": "#/components/schemas/PackageFeatures" } }, "required": [ "name", "period", "trial", "trial_ends_at", "features" ] }, "two_factor_enabled": { "type": "boolean", "description": "Csak a saját fiókodnál. Be van-e kapcsolva a kétlépcsős azonosítás." } }, "required": [ "id", "name", "email", "phone", "avatar", "language", "intercom_hmac" ] }, "AuthTokens": { "type": "object", "description": "Egy belépési (access) és egy frissítő (refresh) token. A belépési token 3 napig, a frissítő token 60 napig érvényes.", "properties": { "access_token": { "type": "object", "description": "Belépési token: ezzel hívod a hitelesített végpontokat (képessége `access-api`).", "properties": { "token": { "type": "string", "description": "A token, ahogy az `Authorization: Bearer ` fejlécbe kell tenni.", "example": "1234|Xq3vA9mPz…" }, "expires_at": { "type": "integer", "description": "A lejárat Unix-időbélyegként (másodperc).", "example": 1793000000 } }, "required": [ "token", "expires_at" ] }, "refresh_token": { "type": "object", "description": "Frissítő token: CSAK a `POST /refresh-token` hívására jó (képessége `issue-access-token`).", "properties": { "token": { "type": "string", "description": "A token, ahogy az `Authorization: Bearer ` fejlécbe kell tenni.", "example": "1235|Lw8rT2nKd…" }, "expires_at": { "type": "integer", "description": "A lejárat Unix-időbélyegként (másodperc).", "example": 1793000000 } }, "required": [ "token", "expires_at" ] } }, "required": [ "access_token", "refresh_token" ] }, "Registration": { "type": "object", "description": "Egy folyamatban lévő regisztráció. A telefonszám megerősítésekor felhasználóvá alakul, és a regisztráció (a tokenjével együtt) megszűnik.", "properties": { "token": { "type": "string", "description": "A regisztráció azonosító tokenje: a további regisztrációs hívások útvonalába (`{registrationToken}`) kerül. Kezeld titokként: aki ismeri, folytathatja a regisztrációt.", "minLength": 16, "maxLength": 16, "example": "a8d2k4m1q9z0x7c3" }, "name": { "type": "string", "description": "Teljes név.", "example": "Minta Péter" }, "email": { "type": "string", "description": "Email cím.", "format": "email", "example": "minta.peter@example.com" }, "phone": { "type": "string", "description": "Telefonszám.", "example": "+36301234567" }, "language": { "type": "string", "description": "Nyelv.", "enum": [ "hu", "en" ], "example": "hu" }, "profile_type": { "type": "string", "description": "A létrejövő saját profil típusa: cég vagy magánszemély.", "enum": [ "company", "private_person" ], "nullable": true, "example": "company" }, "profile_name": { "type": "string", "description": "A profil neve (cégnév vagy a magánszemély neve).", "nullable": true, "example": "Minta Kft." }, "profile_tax_number": { "type": "string", "description": "Adószám (cégnél).", "nullable": true, "example": "12345678-1-23" }, "profile_mother_name": { "type": "string", "description": "Anyja neve (magánszemélynél).", "nullable": true, "example": null }, "profile_birth_date": { "type": "string", "description": "Születési dátum (magánszemélynél), ÉÉÉÉ-HH-NN.", "format": "date", "nullable": true, "example": null }, "profile_birth_place": { "type": "string", "description": "Születési hely (magánszemélynél).", "nullable": true, "example": null }, "profile_address": { "type": "string", "description": "Cím / székhely.", "nullable": true, "example": "1111 Budapest, Minta utca 1." }, "email_verified": { "type": "boolean", "description": "Megerősítette-e már az email címét." } }, "required": [ "token", "name", "email", "phone", "language", "profile_type", "profile_name", "profile_tax_number", "profile_mother_name", "profile_birth_date", "profile_birth_place", "profile_address", "email_verified" ] }, "Config": { "type": "object", "description": "Nyilvános konfiguráció: csomagok, útmutató videók, a regisztrációs CAPTCHA nyilvános kulcsa.", "properties": { "packages": { "type": "object", "description": "Az előfizetési csomagok a kulcsuk szerint (`free`, `basic`, `standard`, `premium`).", "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "description": "A csomag megjelenő neve a kérés nyelvén.", "example": "Standard csomag" }, "icon": { "type": "string", "description": "A csomag ikonjának neve (Material Icons).", "example": "handshake" }, "description": { "type": "string", "description": "Rövid ajánló szöveg a kérés nyelvén." }, "features": { "$ref": "#/components/schemas/PackageFeatures" }, "pricing": { "type": "object", "description": "Díjak forintban, egész számként.", "properties": { "subscription": { "type": "object", "properties": { "monthly": { "type": "integer", "description": "Havi előfizetési díj." }, "yearly": { "type": "integer", "description": "Éves előfizetési díj." } }, "required": [ "monthly", "yearly" ] }, "contract": { "type": "integer", "description": "Egy lezárt szerződés díja ebben a csomagban." } }, "required": [ "subscription", "contract" ] } }, "required": [ "label", "icon", "description", "features", "pricing" ] } }, "tutorial_videos": { "type": "array", "description": "Útmutató videók.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "A videó címe.", "example": "A rendszer teljes bemutatása" }, "image": { "type": "string", "description": "Előnézeti kép URL-je.", "format": "uri" }, "url": { "type": "string", "description": "A videó oldalának URL-je.", "format": "uri" }, "embed_url": { "type": "string", "description": "Beágyazható lejátszó URL-je.", "format": "uri" } }, "required": [ "name", "image", "url", "embed_url" ] } }, "turnstile": { "type": "object", "description": "A regisztrációs űrlap CAPTCHA-ellenőrzéséhez.", "properties": { "site_key": { "type": "string", "description": "A CAPTCHA widget nyilvános kulcsa (Cloudflare Turnstile). Ezzel kapott tokent küldd a `POST /registrations` `captcha_token` mezőjében.", "nullable": true, "example": "0x4AAAAAAAxxxxxxxxxxxxxx" } }, "required": [ "site_key" ] } }, "required": [ "packages", "tutorial_videos", "turnstile" ] }, "Post": { "type": "object", "description": "Blogbejegyzés. A `title`, `description`, `content` és `slug` a kérés nyelvén (`Accept-Language`, hu|en) jön.", "properties": { "id": { "type": "integer", "description": "A bejegyzés azonosítója.", "example": 42 }, "image": { "type": "string", "description": "A borítókép URL-je, vagy `null`.", "format": "uri", "nullable": true }, "slug": { "type": "string", "description": "A címből képzett URL-barát rövid név.", "example": "hogyan-kossunk-szerzodest-online" }, "title": { "type": "string", "description": "Cím.", "example": "Hogyan kössünk szerződést online?" }, "description": { "type": "string", "description": "Rövid leírás (10–20 szó)." }, "content": { "type": "string", "description": "A bejegyzés szövege HTML-ként." }, "published_at": { "type": "integer", "description": "Megjelenés ideje Unix-időbélyegként (másodperc).", "nullable": true, "example": 1790000000 }, "updated_at": { "type": "integer", "description": "Utolsó módosítás Unix-időbélyegként (másodperc).", "nullable": true, "example": 1790000000 } }, "required": [ "id", "image", "slug", "title", "description", "content", "published_at", "updated_at" ] }, "ContractSample": { "type": "object", "description": "Szerződésminta: a Signingo által összeállított, bárki által megtekinthető szerződésszöveg, amelyet a saját profilodba sablonként átmásolhatsz.", "properties": { "id": { "type": "integer", "description": "A minta azonosítója.", "example": 7 }, "name": { "type": "string", "description": "A minta neve.", "example": "Ingó adásvételi szerződés" }, "language": { "type": "string", "description": "A szerződés nyelve.", "enum": [ "hu", "en" ], "example": "hu" }, "content": { "type": "string", "description": "A szerződés szövege HTML-ként. A kitöltendő mezők és az aláírók hivatkozásai a szövegben szerepelnek." }, "created_at": { "type": "integer", "description": "Létrehozás ideje Unix-időbélyegként (másodperc).", "nullable": true }, "updated_at": { "type": "integer", "description": "Utolsó módosítás Unix-időbélyegként (másodperc).", "nullable": true }, "intro_text": { "type": "string", "description": "A szerződés bevezető mondata a szerződés nyelvén, a felek hivatkozásaival (a nevek helyén „...\")." }, "framework_contract_text": { "type": "string", "description": "A keretszerződési záradék szövege a szerződés nyelvén." }, "signatures": { "type": "array", "description": "Az aláírói helyek, sorrendben.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Az aláírói hely azonosítója." }, "reference": { "type": "string", "description": "A fél hivatkozási neve a szövegben (pl. „Eladó\").", "example": "Eladó" }, "signer": { "type": "string", "description": "Ki tölti be ezt a helyet: a küldő (`sender`) vagy a fogadó fél (`receiver`).", "enum": [ "sender", "receiver" ] } }, "required": [ "id", "reference", "signer" ] } }, "fields": { "type": "array", "description": "A kitöltendő mezők, sorrendben.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "A mező azonosítója." }, "name": { "type": "string", "description": "A mező neve.", "example": "Vételár" }, "filler": { "type": "string", "description": "Ki tölti ki: a küldő (`sender`) vagy a fogadó fél (`receiver`).", "enum": [ "sender", "receiver" ] } }, "required": [ "id", "name", "filler" ] } }, "attachments": { "type": "array", "description": "Mellékletek, sorrendben.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "A melléklet azonosítója." }, "file": { "type": "string", "description": "A melléklet letöltési URL-je.", "format": "uri" }, "name": { "type": "string", "description": "A melléklet megjelenő neve; `null` esetén az eredeti fájlnév látszik.", "nullable": true } }, "required": [ "id", "file", "name" ] } }, "permission_warnings": { "$ref": "#/components/schemas/PermissionWarnings" } }, "required": [ "id", "name", "language", "content", "created_at", "updated_at", "intro_text", "framework_contract_text", "signatures", "fields", "attachments", "permission_warnings" ] }, "Dashboard": { "type": "object", "properties": { "contracts": { "type": "object", "description": "Szerződésszámlálók.", "properties": { "invited": { "type": "integer", "description": "Ennyi szerződésre hívtak meg az email címeden, és még nem fogadtad el / nem utasítottad el.", "example": 1 }, "opened": { "type": "integer", "description": "Nyitott szerződéseid (van még kitöltetlen mező vagy hiányos aláíró adat).", "example": 3 }, "signable": { "type": "integer", "description": "Aláírható szerződéseid (minden adat kész, aláírásra vár).", "example": 2 }, "signed": { "type": "integer", "description": "Lezárt (aláírt) szerződéseid.", "example": 25 } }, "required": [ "invited", "opened", "signable", "signed" ] }, "user_logs": { "type": "array", "description": "A fiókod legutóbbi 10 tevékenységnapló-bejegyzése, a legújabbal kezdve.", "maxItems": 10, "items": { "$ref": "#/components/schemas/UserLog" } } }, "required": [ "contracts", "user_logs" ] }, "PermissionWarningsResponse": { "type": "object", "description": "A kért műveletek kulcsa szerint: `null`, ha a művelet engedélyezett, egyébként a figyelmeztetés. Csak a kért kulcsok szerepelnek (kérés nélkül mind).", "properties": { "user_subscribe": { "type": "object", "nullable": true, "description": "Előfizethetsz-e (ehhez a számlázási adataidnak kitöltve kell lenniük). `null` = engedélyezett.", "properties": { "message": { "type": "string", "description": "A felhasználónak megjeleníthető indoklás a kérés nyelvén.", "example": "Ehhez a művelethez nincs jogosultságod." }, "code": { "type": "integer", "description": "A hívás várható HTTP-hibakódja.", "enum": [ 401, 402, 403 ], "example": 402 }, "type": { "type": "string", "description": "`login_required` (401), `upgrade_required` (402: csomagváltás kell), `forbidden` (minden más).", "enum": [ "login_required", "upgrade_required", "forbidden" ], "example": "upgrade_required" } }, "required": [ "message", "code", "type" ] }, "user_get_customer_portal_url": { "type": "object", "nullable": true, "description": "Elérheted-e az előfizetés-kezelő portált (ehhez érvényes előfizetés kell). `null` = engedélyezett.", "properties": { "message": { "type": "string", "description": "A felhasználónak megjeleníthető indoklás a kérés nyelvén.", "example": "Ehhez a művelethez nincs jogosultságod." }, "code": { "type": "integer", "description": "A hívás várható HTTP-hibakódja.", "enum": [ 401, 402, 403 ], "example": 402 }, "type": { "type": "string", "description": "`login_required` (401), `upgrade_required` (402: csomagváltás kell), `forbidden` (minden más).", "enum": [ "login_required", "upgrade_required", "forbidden" ], "example": "upgrade_required" } }, "required": [ "message", "code", "type" ] }, "profile_create": { "type": "object", "nullable": true, "description": "Létrehozhatsz-e újabb saját profilt (a csomag `max_own_profiles` korlátja; elérésekor 402). `null` = engedélyezett.", "properties": { "message": { "type": "string", "description": "A felhasználónak megjeleníthető indoklás a kérés nyelvén.", "example": "Ehhez a művelethez nincs jogosultságod." }, "code": { "type": "integer", "description": "A hívás várható HTTP-hibakódja.", "enum": [ 401, 402, 403 ], "example": 402 }, "type": { "type": "string", "description": "`login_required` (401), `upgrade_required` (402: csomagváltás kell), `forbidden` (minden más).", "enum": [ "login_required", "upgrade_required", "forbidden" ], "example": "upgrade_required" } }, "required": [ "message", "code", "type" ] }, "contract_template_create": { "type": "object", "nullable": true, "description": "Létrehozhatsz-e szerződéssablont (legalább egy profilod tulajdonosának csomagjában kell a `contract_templates` funkció; különben 402). `null` = engedélyezett.", "properties": { "message": { "type": "string", "description": "A felhasználónak megjeleníthető indoklás a kérés nyelvén.", "example": "Ehhez a művelethez nincs jogosultságod." }, "code": { "type": "integer", "description": "A hívás várható HTTP-hibakódja.", "enum": [ 401, 402, 403 ], "example": 402 }, "type": { "type": "string", "description": "`login_required` (401), `upgrade_required` (402: csomagváltás kell), `forbidden` (minden más).", "enum": [ "login_required", "upgrade_required", "forbidden" ], "example": "upgrade_required" } }, "required": [ "message", "code", "type" ] }, "contract_create": { "type": "object", "nullable": true, "description": "Létrehozhatsz-e szerződést. `null` = engedélyezett.", "properties": { "message": { "type": "string", "description": "A felhasználónak megjeleníthető indoklás a kérés nyelvén.", "example": "Ehhez a művelethez nincs jogosultságod." }, "code": { "type": "integer", "description": "A hívás várható HTTP-hibakódja.", "enum": [ 401, 402, 403 ], "example": 402 }, "type": { "type": "string", "description": "`login_required` (401), `upgrade_required` (402: csomagváltás kell), `forbidden` (minden más).", "enum": [ "login_required", "upgrade_required", "forbidden" ], "example": "upgrade_required" } }, "required": [ "message", "code", "type" ] }, "api_key_create": { "type": "object", "nullable": true, "description": "Létrehozhatsz-e fejlesztői API-kulcsot (a csomag `api` funkciója; különben 402). `null` = engedélyezett.", "properties": { "message": { "type": "string", "description": "A felhasználónak megjeleníthető indoklás a kérés nyelvén.", "example": "Ehhez a művelethez nincs jogosultságod." }, "code": { "type": "integer", "description": "A hívás várható HTTP-hibakódja.", "enum": [ 401, 402, 403 ], "example": 402 }, "type": { "type": "string", "description": "`login_required` (401), `upgrade_required` (402: csomagváltás kell), `forbidden` (minden más).", "enum": [ "login_required", "upgrade_required", "forbidden" ], "example": "upgrade_required" } }, "required": [ "message", "code", "type" ] }, "webhook_create": { "type": "object", "nullable": true, "description": "Létrehozhatsz-e webhookot (a csomag `api` funkciója; különben 402). `null` = engedélyezett.", "properties": { "message": { "type": "string", "description": "A felhasználónak megjeleníthető indoklás a kérés nyelvén.", "example": "Ehhez a művelethez nincs jogosultságod." }, "code": { "type": "integer", "description": "A hívás várható HTTP-hibakódja.", "enum": [ 401, 402, 403 ], "example": 402 }, "type": { "type": "string", "description": "`login_required` (401), `upgrade_required` (402: csomagváltás kell), `forbidden` (minden más).", "enum": [ "login_required", "upgrade_required", "forbidden" ], "example": "upgrade_required" } }, "required": [ "message", "code", "type" ] }, "use_bulk_contract_creation": { "type": "object", "nullable": true, "description": "Használhatod-e a tömeges szerződéskészítést (legalább egy profilod tulajdonosának csomagjában kell a `bulk_contract_creation` funkció; különben 402). `null` = engedélyezett.", "properties": { "message": { "type": "string", "description": "A felhasználónak megjeleníthető indoklás a kérés nyelvén.", "example": "Ehhez a művelethez nincs jogosultságod." }, "code": { "type": "integer", "description": "A hívás várható HTTP-hibakódja.", "enum": [ 401, 402, 403 ], "example": 402 }, "type": { "type": "string", "description": "`login_required` (401), `upgrade_required` (402: csomagváltás kell), `forbidden` (minden más).", "enum": [ "login_required", "upgrade_required", "forbidden" ], "example": "upgrade_required" } }, "required": [ "message", "code", "type" ] } } }, "ApiKey": { "type": "object", "description": "Egy API-kulcs (`developer-api` képességű token) adatai, a titkos érték nélkül.", "properties": { "id": { "type": "integer", "example": 17, "description": "A kulcs azonosítója (a teljes kulcs `|` előtti része)." }, "name": { "type": "string", "example": "Ügyviteli rendszer", "description": "A létrehozáskor megadott név." }, "last_used_at": { "type": "integer", "nullable": true, "example": 1767312000, "description": "Az utolsó használat ideje (Unix-időbélyeg, másodperc), vagy `null`, ha még nem használták." }, "created_at": { "type": "integer", "description": "A létrehozás ideje (Unix-időbélyeg, másodperc).", "example": 1767225600 } } }, "Webhook": { "type": "object", "description": "Egy webhook-cím. A rá küldött hívások formáját a `WebhookPayload` séma írja le.", "properties": { "id": { "type": "integer", "example": 5, "description": "A webhook azonosítója." }, "url": { "type": "string", "format": "uri", "example": "https://erp.example.com/hooks/signingo/9f2c7e1a", "description": "A hívandó cím." }, "created_at": { "type": "integer", "description": "A létrehozás ideje (Unix-időbélyeg, másodperc).", "example": 1767225600 }, "updated_at": { "type": "integer", "description": "Az utolsó módosítás ideje (Unix-időbélyeg, másodperc).", "example": 1767225600 } } }, "WebhookPayload": { "type": "object", "description": "A webhook-címre küldött `POST` kérés JSON-törzse.", "required": [ "model", "data", "time" ], "properties": { "model": { "type": "string", "enum": [ "contract" ], "example": "contract", "description": "A megváltozott erőforrás típusa. Jelenleg mindig `contract`: az aláírók, mezők, csatolmányok és megjegyzések változásáról is a szerződés egészét küldjük." }, "data": { "allOf": [ { "$ref": "#/components/schemas/Contract" } ], "description": "A szerződés a változás utáni állapotában, a címzett felhasználó jogosultságaival (`permission_warnings` is az övé). A kapcsolt listák közül a `signatures` mindig benne van, a `fields` akkor, ha a szerződésnek van szöveges tartalma; a `profile`, `attachments`, `comments` és `logs` nincs benne. A teljes állapotért hívd a `GET /contracts/{id}` végpontot a `data.token` értékkel." }, "time": { "type": "integer", "example": 1767225600, "description": "A változás ideje (Unix-időbélyeg, másodperc). Ha több hívás érkezik ugyanarról a szerződésről, ezzel állapíthatod meg a sorrendet." } } }, "Invoice": { "type": "object", "description": "A felhasználónak kiállított számla (előfizetési díj vagy szerződéskötési díj).", "properties": { "id": { "type": "integer", "example": 311, "description": "A számla azonosítója." }, "invoice_no": { "type": "string", "example": "SGN-2026-000123", "description": "A számla sorszáma." }, "price": { "type": "integer", "example": 12700, "description": "A számla bruttó végösszege forintban." }, "url": { "type": "string", "format": "uri", "example": "https://www.example.com/access/c:Xy7bQ2", "description": "A számla megtekintésére és letöltésére szolgáló link." }, "created_at": { "type": "integer", "description": "A kiállítás ideje (Unix-időbélyeg, másodperc).", "example": 1767225600 }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Jogosultsági figyelmeztetések; ennél az erőforrásnál csak a `read` kulcs szerepel (mindig `null`)." } } }, "UserLog": { "type": "object", "description": "A felhasználó tevékenységnaplójának egy bejegyzése.", "properties": { "id": { "type": "integer", "example": 9021, "description": "A bejegyzés azonosítója." }, "content": { "type": "string", "example": "Felhasználó módosítva: Név: Minta Péter | Nyelv: hu", "description": "Az esemény szövege a felhasználó nyelvén. Lehetséges események: regisztráció, bejelentkezés, kijelentkezés, jelszó-visszaállítás, felhasználó módosítása, jelszócsere, kétlépcsős azonosítás be-/kikapcsolása, telefonszám-csere, számlázási adatok módosítása, profil létrehozása / módosítása / törlése, felhasználó meghívása a profilba és törlése a profilból." }, "device": { "type": "string", "nullable": true, "example": "Macintosh OS X Chrome", "description": "A böngésző fejlécéből felismert eszköz, rendszer és böngésző, ha felismerhető." }, "ip": { "type": "string", "nullable": true, "example": "203.0.113.17", "description": "A kérést indító IP-cím." }, "created_at": { "type": "integer", "description": "Az esemény ideje (Unix-időbélyeg, másodperc).", "example": 1767225600 }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Jogosultsági figyelmeztetések; ennél az erőforrásnál csak a `read` kulcs szerepel (mindig `null`)." } } }, "SentMail": { "type": "object", "description": "Egy, a Signingo által a felhasználó email-címére küldött levél és a kézbesítési állapota.", "properties": { "id": { "type": "integer", "example": 55120, "description": "A levél azonosítója." }, "email": { "type": "string", "format": "email", "example": "minta.peter@example.com", "description": "A címzett email-címe (a te címed)." }, "subject": { "type": "string", "example": "Aláírásra vár: Megbízási szerződés", "description": "A levél tárgya." }, "created_at": { "type": "integer", "description": "A küldés ideje (Unix-időbélyeg, másodperc).", "example": 1767225600 }, "notification": { "type": "string", "example": "contract_signature_signed", "description": "A levél típusa (gépi azonosító). Jelenlegi értékek: `contract_accepted`, `contract_comment_created`, `contract_invitation`, `contract_publishing`, `contract_rejected`, `contract_signature_sign_removed`, `contract_signature_signed`, `contract_signed`, `contract_reminder`, `contract_modified_signature_removed`, `contract_fields_filled`, `contract_signature_details_refreshed`, `contract_left`, `email_verification`, `profile_invitation`, `profile_invitation_accepted`, `user_added_to_profile`, `user_password_reset`, `waiting_to_fill_contract_signature_details`, `waiting_to_accept_contract_invitation`, `waiting_to_fill_contract_fields`, `waiting_to_sign_contract_signature`, `registration_with_referral_code`, `referral_reward_applied`, `join_facebook_group`. Régebbi leveleknél más érték is előfordulhat, és új típusok jöhetnek." }, "notification_label": { "type": "string", "example": "Szerződés aláírva", "description": "A levél típusának olvasható neve a felhasználó nyelvén." }, "status": { "type": "string", "enum": [ "sent", "delivered", "opened", "failed" ], "example": "opened", "description": "Kézbesítési állapot: `sent` elküldve, `delivered` megérkezett, `opened` megnyitva, `failed` a címzett levelezője visszautasította (blokkolva)." }, "status_label": { "type": "string", "example": "Megnyitva", "description": "Az állapot olvasható neve a felhasználó nyelvén." }, "updated_at": { "type": "integer", "description": "Az állapot utolsó változásának ideje (Unix-időbélyeg, másodperc).", "example": 1767225600 }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Jogosultsági figyelmeztetések; ennél az erőforrásnál csak a `read` kulcs szerepel (mindig `null`)." } } }, "Partner": { "type": "object", "description": "Egy partnerprofil: olyan cég vagy magánszemély profilja, amelynek nem vagy tagja, de közös szerződésetek van. A mezők a `Profile` sémáéval egyeznek, de a tagok és a meghívások listája nincs benne.", "properties": { "id": { "type": "integer", "example": 1207, "description": "A profil azonosítója." }, "type": { "type": "string", "enum": [ "company", "private_person" ], "example": "company", "description": "Cég (`company`) vagy magánszemély (`private_person`)." }, "name": { "type": "string", "example": "Példa Bt.", "description": "A cég vagy a magánszemély neve." }, "tax_number": { "type": "string", "nullable": true, "example": "87654321-1-13", "description": "Adószám; csak cégnél." }, "mother_name": { "type": "string", "nullable": true, "example": "Minta Mária", "description": "Anyja neve; csak magánszemélynél." }, "birth_date": { "type": "string", "format": "date", "nullable": true, "example": "1985-04-12", "description": "Születési dátum (ÉÉÉÉ-HH-NN); csak magánszemélynél." }, "birth_place": { "type": "string", "nullable": true, "example": "Debrecen", "description": "Születési hely; csak magánszemélynél." }, "address": { "type": "string", "example": "4025 Debrecen, Példa tér 2.", "description": "Cím (székhely vagy lakcím)." }, "signature": { "type": "string", "format": "uri", "nullable": true, "description": "A profil aláírásképének URL-je, vagy `null`." }, "logo": { "type": "string", "format": "uri", "nullable": true, "description": "A profil logójának URL-je, vagy `null`." }, "brand_color": { "type": "string", "nullable": true, "pattern": "^#[0-9a-fA-F]{6}$", "example": "#1f6feb", "description": "A profil arculati színe, vagy `null`." }, "owner": { "type": "object", "nullable": true, "description": "A profil tulajdonosának nyilvános adatai.", "properties": { "id": { "type": "integer", "example": 880, "description": "A felhasználó azonosítója." }, "name": { "type": "string", "example": "Példa Anna", "description": "Név." }, "email": { "type": "string", "format": "email", "example": "anna@example.com", "description": "Email-cím." }, "phone": { "type": "string", "nullable": true, "example": "+36201234567", "description": "Telefonszám." }, "avatar": { "type": "string", "nullable": true, "description": "Profilkép, vagy `null`." }, "language": { "type": "string", "enum": [ "hu", "en" ], "description": "A felhasználó nyelve." }, "intercom_hmac": { "type": "string", "description": "Belső azonosító az ügyfélszolgálati csevegőhöz; integrációhoz nem kell." } } }, "deleted": { "type": "boolean", "example": false, "description": "Törölt-e a profil (itt mindig `false`)." }, "branding_available": { "type": "boolean", "example": false, "description": "A profil tulajdonosának csomagja engedi-e az arculatot (logó, szín) a szerződéseken." }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Jogosultsági figyelmeztetések a profilon végezhető műveletekre (`read`, `update`, `delete`, `invite_user`, `delete_invitation`, `leave`, `upload_signature`, `update_branding`, `delete_signature`, `create_contract_from_template`). Partnerprofilon a módosító műveletek nem érhetők el, mert nem vagy tagja." } } }, "ContractSigningBalance": { "type": "object", "description": "A szerződéskötési egyenleg.", "properties": { "balance": { "type": "integer", "example": -2, "description": "Negatív: ennyi ingyenes szerződéskötés van még hátra (abszolút értékben). Pozitív: az aktuális előfizetési időszakban ennyi díjköteles szerződéskötést használtál fel. `0`: nincs ingyenes keret és nincs felhasználás." } } }, "Profile": { "type": "object", "description": "Profil (cég vagy magánszemély), amelynek nevében szerződést kötsz. Egy profilnak pontosan egy tulajdonosa és tetszőleges számú tagja lehet (a csomag `max_profile_users` korlátjáig).", "properties": { "id": { "type": "integer", "example": 42, "description": "A profil azonosítója." }, "type": { "type": "string", "enum": [ "company", "private_person" ], "description": "`company` = cég / egyéni vállalkozó, `private_person` = magánszemély." }, "name": { "type": "string", "example": "Példa Bt.", "description": "Cégnév vagy a magánszemély neve." }, "tax_number": { "type": "string", "nullable": true, "example": "12345678-1-42", "description": "Adószám (csak `company`)." }, "mother_name": { "type": "string", "nullable": true, "description": "Anyja neve (csak `private_person`)." }, "birth_date": { "type": "string", "format": "date", "nullable": true, "description": "Születési dátum `ÉÉÉÉ-HH-NN` (csak `private_person`)." }, "birth_place": { "type": "string", "nullable": true, "description": "Születési hely (csak `private_person`)." }, "address": { "type": "string", "example": "1111 Budapest, Kitalált utca 3.", "description": "Cím / székhely." }, "signature": { "type": "string", "format": "uri", "nullable": true, "description": "A profil feltöltött aláírásképének URL-je (500 px szélesre méretezve), vagy null." }, "logo": { "type": "string", "format": "uri", "nullable": true, "description": "A profil logójának URL-je (arculat), vagy null." }, "brand_color": { "type": "string", "nullable": true, "pattern": "^#[0-9a-f]{6}$", "example": "#1f6feb", "description": "Kiemelő szín `#rrggbb` alakban (kisbetűvel tárolva), vagy null." }, "owner": { "allOf": [ { "$ref": "#/components/schemas/ProfileUser" } ], "nullable": true, "description": "A profil tulajdonosa." }, "deleted": { "type": "boolean", "description": "Törölt-e a profil. Ezeken a végpontokon mindig `false` (törölt profil nem érhető el)." }, "branding_available": { "type": "boolean", "description": "Elérhető-e az arculat (logó, szín) — a profil TULAJDONOSÁNAK csomagjától függ (`branding` funkció). Ha `false`, a beállított logó és szín megmarad, de nem jelenik meg a szerződéseken." }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileUser" }, "description": "A profil tagjai (a tulajdonossal együtt). Csak a profil tagjai látják." }, "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileInvitation" }, "description": "Függő meghívások (még nem regisztrált email címek). Csak a profil tagjai látják." }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Műveletenkénti jogosultsági figyelmeztetés a hívó számára (null = megengedett). Kulcsok: `read`, `update`, `delete`, `invite_user`, `delete_invitation`, `leave`, `upload_signature`, `update_branding`, `delete_signature`, `create_contract_from_template`." } } }, "ProfileUser": { "type": "object", "description": "Egy profiltag (felhasználó) a profil szemszögéből. Ha a tag te magad vagy, a teljes saját felhasználói adataid is szerepelnek benne (lásd `User` séma: számlázási adatok, csomag stb.).", "properties": { "id": { "type": "integer", "example": 7, "description": "A felhasználó azonosítója." }, "name": { "type": "string", "example": "Minta Anna", "description": "A felhasználó neve." }, "email": { "type": "string", "format": "email", "example": "anna@pelda.hu", "description": "Email cím." }, "phone": { "type": "string", "nullable": true, "example": "+36301234567", "description": "Telefonszám nemzetközi alakban." }, "avatar": { "type": "string", "nullable": true, "description": "Profilkép, vagy null." }, "language": { "type": "string", "enum": [ "hu", "en" ], "description": "A felhasználó nyelve." }, "intercom_hmac": { "type": "string", "description": "Az ügyfélszolgálati csevegő azonosításához használt ellenőrző kód." } } }, "ProfileInvitation": { "type": "object", "description": "Függő profilmeghívás egy még nem regisztrált email címre. Amikor a címzett regisztrál, automatikusan a profil tagja lesz, és a meghívás megszűnik.", "properties": { "id": { "type": "integer", "example": 15, "description": "A meghívás azonosítója." }, "email": { "type": "string", "format": "email", "example": "kollega@pelda.hu", "description": "A meghívott email cím." }, "created_at": { "type": "integer", "example": 1761555600, "description": "A meghívás ideje (Unix-időbélyeg, másodperc)." } } }, "ContractTemplate": { "type": "object", "description": "Szerződéssablon: újrahasználható szerződésszöveg aláírókkal, kitöltendő mezőkkel és mellékletekkel. A sablon azonosítója a `token` (nincs `id` a válaszban).", "properties": { "token": { "type": "string", "example": "k3x9q2m7v1b8n4zt", "description": "A sablon azonosítója (az útvonalakban ezt add meg)." }, "name": { "type": "string", "example": "Megbízási szerződés", "description": "A sablon neve (ebből lesz a szerződés neve)." }, "language": { "type": "string", "enum": [ "hu", "en" ], "description": "A sablonból készülő szerződés nyelve." }, "content": { "type": "string", "nullable": true, "description": "A szerződés szövege (HTML)." }, "security": { "type": "string", "enum": [ "acceptance", "digital_signature" ], "description": "Aláírási mód: `acceptance` = elfogadással, `digital_signature` = elektronikus aláírással (aláírt PDF feltöltésével)." }, "note": { "type": "string", "nullable": true, "description": "Belső megjegyzés (a profil tagjainak)." }, "created_at": { "type": "integer", "description": "Létrehozás ideje (Unix-időbélyeg, másodperc)." }, "updated_at": { "type": "integer", "description": "Utolsó módosítás ideje (Unix-időbélyeg, másodperc)." }, "intro_text": { "type": "string", "description": "A szerződés bevezető szövege a felekkel (a sablon nyelvén generálva; a sablonban a nevek helyén „...\")." }, "framework_contract_text": { "type": "string", "description": "A keretszerződési szöveg a sablon nyelvén." }, "profile": { "allOf": [ { "$ref": "#/components/schemas/Profile" } ], "description": "A sablon profilja (tagokkal, meghívásokkal)." }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ContractTemplateSignature" }, "description": "Az aláírók sorrendben (legfeljebb egy `sender`)." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ContractTemplateField" }, "description": "A kitöltendő mezők sorrendben." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ContractTemplateAttachment" }, "description": "A mellékletek sorrendben." }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Műveletenkénti jogosultsági figyelmeztetés (null = megengedett). Kulcsok: `read`, `update`, `delete`, `upload_attachment`, `download_bulk_contract_creation_excel`, `test_bulk_contract_creation_excel`, `import_bulk_contract_creation_excel` (az utóbbi három `upgrade_required`, ha a profil tulajdonosának csomagjában nincs tömeges szerződéskészítés)." } } }, "ContractTemplateSignature": { "type": "object", "description": "Aláíró-hely a sablonban.", "properties": { "id": { "type": "integer", "example": 101, "description": "Az aláíró-hely azonosítója (módosításkor ezzel tartod meg)." }, "reference": { "type": "string", "example": "Megbízó", "description": "A fél megnevezése a szerződésben (pl. Megbízó, Bérlő)." }, "signer": { "type": "string", "enum": [ "sender", "receiver" ], "description": "`sender` = a szerződést küldő profil (te), `receiver` = a címzett partner." } } }, "ContractTemplateField": { "type": "object", "description": "Kitöltendő mező a sablonban (a szerződésben a kitöltő fél adja meg az értékét).", "properties": { "id": { "type": "integer", "example": 55, "description": "A mező azonosítója (módosításkor ezzel tartod meg)." }, "name": { "type": "string", "example": "Megbízási díj", "description": "A mező neve." }, "filler": { "type": "string", "enum": [ "sender", "receiver" ], "description": "Ki tölti ki: `sender` = a küldő, `receiver` = a címzett." } } }, "ContractTemplateAttachment": { "type": "object", "description": "A sablon melléklete; a sablonból készülő szerződések másolatot kapnak róla.", "properties": { "id": { "type": "integer", "example": 9, "description": "A melléklet azonosítója (módosításkor ezzel tartod meg / rendezed)." }, "file": { "type": "string", "format": "uri", "description": "A melléklet fájljának URL-je." }, "name": { "type": "string", "nullable": true, "description": "A melléklet megjelenő neve; null esetén az eredeti fájlnév látszik." } } }, "BulkContractCreationTestResult": { "type": "object", "description": "A tömeges szerződéskészítő Excel ellenőrzésének eredménye: cellánként az érték és a hibák. Semmit nem hoz létre.", "properties": { "headings": { "type": "array", "items": { "type": "string" }, "description": "A várt oszlopfejlécek a várt sorrendben (lásd a letölthető Excel-mintát).", "example": [ "Szerződés neve", "Címzett", "Megbízási díj", "Címzett – típus (cég / magánszemély)" ] }, "table": { "type": "array", "description": "Az Excel sorai a fejlécsor nélkül; soronként a `headings` szerinti oszlopok cellái.", "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "A cella értéke, ahogy az Excelből beolvasva (üres cella = null)." }, "success": { "type": "boolean", "description": "Érvényes-e a cella." }, "errors": { "description": "Hiba esetén `{\"value\": [\"üzenet\", …]}` objektum; hibátlan cellánál ÜRES TÖMB (`[]`).", "oneOf": [ { "type": "object", "properties": { "value": { "type": "array", "items": { "type": "string" } } } }, { "type": "array", "maxItems": 0, "items": {} } ] } } } } }, "success": { "type": "boolean", "description": "`true`, ha minden cella érvényes (az import ezzel a fájllal sikerülne)." } } }, "ContractField": { "type": "object", "description": "A szerződés egy kitöltendő mezője. A szövegben `[mezo_kulcs]` alakban hivatkozhatsz rá (a név kisbetűsítve, ékezetek nélkül, a nem `a-z0-9-` karakterek `_`-ra cserélve; pl. „Bérleti díj” → `[berleti_dij]`).", "required": [ "id", "name", "filler", "value", "permission_warnings" ], "properties": { "id": { "type": "integer", "description": "A mező azonosítója (a módosításnál és a kitöltésnél erre hivatkozol).", "example": 5821 }, "name": { "type": "string", "maxLength": 255, "description": "A mező neve.", "example": "Bérleti díj" }, "filler": { "type": "string", "enum": [ "sender", "receiver" ], "description": "Ki tölti ki: `sender` = a szerződést készítő fél (a profil tagjai), `receiver` = a fogadó fél." }, "value": { "type": "string", "nullable": true, "maxLength": 255, "description": "A kitöltött érték, vagy `null`, ha még üres.", "example": "250 000 Ft / hó" }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Kulcs: `fill` — kitöltheted-e most ezt a mezőt." } } }, "ContractAttachment": { "type": "object", "description": "A szerződés melléklete (kép vagy PDF). A lezárt PDF-be bekerül.", "required": [ "id", "file", "name" ], "properties": { "id": { "type": "integer", "description": "A melléklet azonosítója (a szerződés módosításánál az `attachments` listában erre hivatkozol).", "example": 912 }, "file": { "type": "string", "format": "uri", "nullable": true, "description": "A feltöltött fájl URL-je (az eredeti fájlnévvel).", "example": "https://files.signingo.hu/contract_attachments/alaprajz.pdf" }, "name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Megjelenő név; `null` esetén az eredeti fájlnév látszik.", "example": "Alaprajz" } } }, "ContractLog": { "type": "object", "description": "A szerződés tevékenységnaplójának egy bejegyzése (létrehozás, módosítás, meghívás, aláírás, megosztás stb.).", "required": [ "id", "performer_email", "content", "created_at" ], "properties": { "id": { "type": "integer", "example": 77120 }, "performer_email": { "type": "string", "format": "email", "nullable": true, "description": "Aki a műveletet végezte (felhasználó vagy vendég aláíró email-címe); `null`, ha rendszerművelet.", "example": "kovacs.anna@example.com" }, "content": { "type": "string", "description": "A bejegyzés szövege a kérés nyelvén.", "example": "Aláíró meghívva: partner@example.com." }, "created_at": { "type": "integer", "description": "Unix-időbélyeg (másodperc).", "example": 1793016000 } } }, "Contract": { "type": "object", "description": "Egy szerződés teljes adatai. Minden végponton, amely `Contract`-ot ad vissza (lekérés, létrehozás, módosítás, keresés, mezők kitöltése, meghívások), MINDEN kapcsolat betöltődik: `signatures`, `fields`, `attachments`, `profile`, `comments`, `logs`.", "required": [ "name", "language", "content", "created_at", "updated_at", "token", "security", "status", "note", "validity_start", "intro_text", "framework_contract_text", "processed_content", "archived", "signatures", "fields", "attachments", "profile", "comments", "logs", "permission_warnings" ], "properties": { "token": { "type": "string", "description": "A szerződés azonosítója az útvonalakban.", "example": "k3j9x0qa7bmz2wfe" }, "name": { "type": "string", "maxLength": 255, "description": "A szerződés neve.", "example": "Bérleti szerződés – Fő utca 12." }, "language": { "type": "string", "enum": [ "hu", "en" ], "description": "A szerződés nyelve (a PDF, a levelek a partnereknek és a szövegek nyelve)." }, "security": { "type": "string", "enum": [ "acceptance", "digital_signature" ], "description": "Aláírás módja: `acceptance` = elfogadással / rajzolt aláírással, a végén a Signingo hitelesített időbélyeget és elektronikus bélyegzőt tesz a PDF-re; `digital_signature` = minden fél a saját elektronikus aláírásával (pl. DÁP) írja alá a letöltött PDF-et, és visszatölti." }, "status": { "type": "string", "enum": [ "opened", "signable", "signed" ], "description": "`opened` = hiányzik még aláírói adat vagy mezőérték; `signable` = minden adat és mező kitöltve, aláírható; `signed` = lezárva, az aláírt fájl elkészült." }, "content": { "type": "string", "nullable": true, "description": "A szerződés szövege HTML-ben, helyőrzőkkel (`[mezo_kulcs]`, `[_]`)." }, "processed_content": { "type": "string", "nullable": true, "description": "A `content` a helyőrzők helyére írt értékekkel: mezők (`[mezo_kulcs]`) és a felek adatai (`[_reference|name|tax_number|mother_name|birth_date|birth_place|address|signer_name|email|phone]`, pl. `[berbeado_name]`). `null`, ha nincs tartalom." }, "note": { "type": "string", "nullable": true, "description": "Megjegyzés a szerződéshez (nem kerül a PDF-be, nem része az aláírt tartalomnak). Minden résztvevő látja, aki a szerződést megnyitja." }, "intro_text": { "type": "string", "description": "A PDF bevezető mondata a felek nevével (a szerződés nyelvén).", "example": "Amely létrejött egyrészről Példa Kft. (Bérbeadó), másrészről ... (Bérlő) között az alábbi feltételekkel:" }, "framework_contract_text": { "type": "string", "description": "A keretszöveg (a szerződés nyelvén), amely a PDF-ben az aláírások előtt áll." }, "validity_start": { "type": "integer", "nullable": true, "description": "A hatályba lépés ideje Unix-időbélyegként (másodperc): az első elektronikus aláírás vagy a lezárás ideje; `null`, amíg nincs.", "example": 1793102400 }, "archived": { "type": "boolean", "description": "Archiváltad-e (a te profiljaid valamelyikében)." }, "created_at": { "type": "integer", "description": "Létrehozás, Unix-időbélyeg (másodperc).", "example": 1792929600 }, "updated_at": { "type": "integer", "description": "Utolsó módosítás, Unix-időbélyeg (másodperc).", "example": 1793016000 }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ContractSignature" }, "description": "Az aláírói helyek (felek) `position` szerinti sorrendben; mindegyikben a hozzá kapcsolt profil és a neki küldött levelek is." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ContractField" }, "description": "A kitöltendő mezők sorrendben." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ContractAttachment" }, "description": "A mellékletek sorrendben." }, "profile": { "allOf": [ { "$ref": "#/components/schemas/Profile" } ], "description": "A szerződést készítő profil (a tagok és a meghívások csak akkor szerepelnek benne, ha te is tagja vagy)." }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/ContractComment" }, "description": "A megjegyzések időrendben (a törölt megjegyzések is, üres tartalommal, `deleted: true`)." }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/ContractLog" }, "description": "A szerződés tevékenységnaplója." }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Funkciónév → figyelmeztetés (vagy `null`, ha a művelet a hívónak most engedélyezett). Kulcsok: `read`, `update`, `share`, `delete`, `upload_attachment`, `leave`, `archive`, `unarchive`, `preview`, `download_signed_file`, `create_comment`, `show_sign_manually_button`, `sign_manually`, `accept`, `reject`, `fill_fields`, `analyze_signed_file`, `show_sent_mails`. Pl. `create_comment` és `show_sent_mails` `code: 402`, `type: upgrade_required` figyelmeztetést ad a profiltulajdonosnak, ha a csomagjában nincs megjegyzés / levélkövetés funkció (a tényleges hívás ilyenkor HTTP 403-at ad, nem 402-t)." } } }, "ContractInvitation": { "allOf": [ { "$ref": "#/components/schemas/Contract" } ], "description": "Egy szerződés, amelybe aláíróként meghívtak (a te email-címedre szóló, még el nem fogadott aláírói hellyel, `status: invited`). Ugyanaz a szerkezet, mint a `Contract`." }, "ContractShare": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "nullable": true, "description": "A csak olvasható megosztási link (a weboldalon, bejelentkezés nélkül megnyitható); visszavonás után `null`.", "example": "https://signingo.hu/shared/Q2v8sLk0aZ1mN4pR7tY3uW6xB9cE2fH5jK8nP1qS" } } }, "SignedFileAnalysisNode": { "type": "object", "description": "Az elemzés egy címkézett sora. Az érték lehet szöveg, alsorok listája (pl. az aláíró meghatalmazója), vagy listák listája (aláírásonként / beágyazott fájlonként egy-egy sorlista).", "required": [ "label", "value" ], "properties": { "label": { "type": "string", "description": "A sor címkéje a kérés nyelvén.", "example": "Fájlnév" }, "value": { "description": "Szöveg, `SignedFileAnalysisNode`-ok listája, vagy ilyen listák listája.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/SignedFileAnalysisNode" } }, { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/SignedFileAnalysisNode" } } } ], "example": "berleti_szerzodes.pdf" } } }, "SignedFileAnalysis": { "type": "object", "description": "Az aláírt fájl elektronikus aláírásainak elemzése.", "required": [ "signers", "hierarchy" ], "properties": { "signers": { "type": "array", "description": "A fájlban talált aláírások (régi `.asice` fájlnál a beágyazott fájlokéi is). Ha a fájl nem elemezhető, üres lista.", "items": { "type": "object", "required": [ "type", "title", "description", "valid", "details" ], "properties": { "type": { "type": "string", "enum": [ "signingo", "dap", "avdh", "digital_signature" ], "description": "`signingo` = a Signingo elektronikus bélyegzője; `dap` = DÁP (Digitális Állampolgárság) aláírás; `avdh` = AVDH-hitelesítés; `digital_signature` = egyéb elektronikus aláírás." }, "title": { "type": "string", "nullable": true, "description": "Az aláíró neve (vagy a szervezet neve).", "example": "Kovács Anna" }, "description": { "type": "string", "nullable": true, "description": "Rövid azonosító sor (adószám / szervezet / email / sorozatszám, AVDH-nál a születési hely és idő).", "example": "E-mail cím: kovacs.anna@example.com" }, "valid": { "type": "boolean", "description": "Érvényes-e az aláírás (a fájl az aláírás óta nem módosult, a tanúsítvány érvényes)." }, "details": { "type": "array", "description": "A tanúsítvány kitöltött adatai címkézett sorokban.", "items": { "type": "object", "required": [ "label", "value" ], "properties": { "label": { "type": "string", "example": "Név" }, "value": { "type": "string", "example": "Kovács Anna" } } } } } } }, "hierarchy": { "type": "array", "items": { "$ref": "#/components/schemas/SignedFileAnalysisNode" }, "description": "A fájl teljes elemzése fa-szerkezetben: fájlnév, PDF-cím/szerző, aláírásonként a tanúsítvány adatai (érvényesség kezdete/vége `ÉÉÉÉ-HH-NN óó:pp:mm+zz:zz` alakban, érvényes-e), `.asice` esetén a beágyazott fájlok. Hibás fájlnál egy hibasor." } } }, "ContractSignature": { "type": "object", "description": "Egy szerződés egy aláírói helye (szerződő fél). A `profile` és a `sent_mails` csak akkor szerepel, ha a válasz betöltötte: a szerződés lekérésénél (`signatures[]`) mindkettő ott van; az aláírási végpontok válaszában a `profile` csak profilhoz tartozó helynél, a `sent_mails` soha.", "required": [ "id", "reference", "signer", "status", "email", "signer_name", "phone", "phone_verified", "type", "name", "tax_number", "mother_name", "birth_date", "birth_place", "address", "signature", "signed_at", "signed_from_ip", "signed_from_device", "own", "details_modified", "permission_warnings" ], "properties": { "id": { "type": "integer", "description": "Az aláírói hely azonosítója (a `/contract-signatures/{id}/…` végpontokhoz).", "example": 4821 }, "reference": { "type": "string", "maxLength": 255, "description": "A fél megnevezése a szerződésben (pl. „Megbízó\", „Vállalkozó\").", "example": "Megbízott" }, "signer": { "type": "string", "enum": [ "sender", "receiver" ], "description": "`sender` = a szerződést készítő profil helye (legfeljebb egy), `receiver` = címzett." }, "status": { "type": "string", "enum": [ "pending", "invited", "published", "accepted", "signed" ], "description": "A hely állapota:\n- `pending`: még nincs email-cím;\n- `invited`: regisztrált Signingo-felhasználó, a meghívás elfogadására vár;\n- `published`: nem regisztrált címzett, vendéglinket kapott emailben;\n- `accepted`: a hely egy profilhoz tartozik (a küldő, vagy a meghívást elfogadó felhasználó), aláírásra vár;\n- `signed`: aláírta." }, "email": { "type": "string", "nullable": true, "description": "A hely email-címe.", "format": "email", "maxLength": 255, "example": "partner@example.com" }, "signer_name": { "type": "string", "nullable": true, "description": "Az aláíró (cégnél a képviselő) neve.", "maxLength": 255, "example": "Kovács Anna" }, "phone": { "type": "string", "nullable": true, "description": "Telefonszám nemzetközi formátumban.", "example": "+36301234567" }, "phone_verified": { "type": "boolean", "description": "A telefonszám ellenőrzött-e: igaz, ha a hely profilhoz tartozik, és a szám megegyezik a profiltulajdonos ellenőrzött számával." }, "type": { "type": "string", "nullable": true, "enum": [ "company", "private_person", null ], "description": "`company` = cég / egyéni vállalkozó, `private_person` = magánszemély; `null`, ha még nincs megadva." }, "name": { "type": "string", "nullable": true, "description": "A szerződő fél neve (cégnév vagy a magánszemély neve).", "maxLength": 255, "example": "Minta Kereskedelmi Kft." }, "tax_number": { "type": "string", "nullable": true, "description": "Adószám (csak cégnél).", "maxLength": 255, "example": "12345678-2-42" }, "mother_name": { "type": "string", "nullable": true, "description": "Anyja neve (csak magánszemélynél).", "maxLength": 255 }, "birth_date": { "type": "string", "nullable": true, "description": "Születési dátum `ÉÉÉÉ-HH-NN` (csak magánszemélynél).", "format": "date" }, "birth_place": { "type": "string", "nullable": true, "description": "Születési hely (csak magánszemélynél).", "maxLength": 255 }, "address": { "type": "string", "nullable": true, "description": "Székhely vagy lakcím.", "maxLength": 255, "example": "1111 Budapest, Minta utca 1." }, "signature": { "type": "string", "nullable": true, "description": "Elfogadásos aláírásnál az aláíráskép URL-je; egyébként `null`.", "format": "uri" }, "signed_at": { "type": "integer", "nullable": true, "description": "Az aláírás ideje (Unix-időbélyeg, másodperc).", "example": 1767225600 }, "signed_from_ip": { "type": "string", "nullable": true, "description": "Az aláíráskor rögzített IP-cím.", "example": "203.0.113.17" }, "signed_from_device": { "type": "string", "nullable": true, "description": "Az aláíráskor rögzített eszköz / böngésző.", "example": "Chrome, macOS" }, "own": { "type": "boolean", "description": "A hely a hívóé-e: bejelentkezve az email-cím egyezése, vendégként a token helye." }, "details_modified": { "type": "boolean", "description": "Profilhoz tartozó helynél: eltérnek-e az adatok a profil (és tulajdonosa) adataitól. Vendéghelynél: van-e már kitöltött adat." }, "profile": { "allOf": [ { "$ref": "#/components/schemas/Profile" } ], "nullable": true, "description": "A helyhez kapcsolt profil (küldőnél a készítő profil, elfogadott meghívásnál a címzett profilja); csak ha a válasz betöltötte, lásd a séma leírását." }, "sent_mails": { "type": "array", "items": { "$ref": "#/components/schemas/SentMail" }, "description": "A szerződés ennek a félnek küldött levelei (csak a szerződés lekérésénél). A kézbesítési állapot csak a saját leveleidnél, vagy levélkövetési funkcióval látszik." }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Kulcsok: accept, reject, fill_details, sign, sign_with_acceptance, sign_with_digital_signature, send_reminder, remove_signature. A `send_reminder.code` lehet `reminder_too_soon` vagy `reminder_not_available` is (szöveg)." } } }, "ContractComment": { "type": "object", "description": "Egy szerződéshez írt megjegyzés. A `user` csak a szerződés lekérésénél (`comments[]`) szerepel; a megjegyzés-végpontok válaszában nincs.", "required": [ "id", "email", "content", "created_at", "updated_at", "deleted_at", "edited", "deleted", "permission_warnings" ], "properties": { "id": { "type": "integer", "example": 912 }, "email": { "type": "string", "format": "email", "description": "A szerző email-címe (felhasználó vagy vendég aláíró).", "example": "partner@example.com" }, "content": { "type": "string", "nullable": true, "description": "A szöveg; törölt megjegyzésnél `null`.", "example": "A 3. pontban a fizetési határidő 15 nap legyen." }, "created_at": { "type": "integer", "description": "Létrehozás (Unix-időbélyeg, másodperc).", "example": 1767225600 }, "updated_at": { "type": "integer", "description": "Utolsó módosítás (Unix-időbélyeg, másodperc).", "example": 1767229200 }, "deleted_at": { "type": "integer", "nullable": true, "description": "Törlés ideje (Unix-időbélyeg), vagy `null`." }, "edited": { "type": "boolean", "description": "Módosították-e a létrehozás után (törölt megjegyzésnél mindig `false`)." }, "deleted": { "type": "boolean", "description": "Törölt-e." }, "user": { "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "A szerző felhasználó; vendég megjegyzésénél `null`. Csak a szerződés lekérésénél." }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Kulcsok: update, delete." } } }, "KnownParty": { "type": "object", "description": "Egy korábbi szerződésben szereplő címzett, a legutóbb megadott adataival.", "required": [ "email", "signer_name", "phone", "type", "name", "tax_number", "mother_name", "birth_place", "address", "birth_date" ], "properties": { "email": { "type": "string", "format": "email", "example": "partner@example.com" }, "signer_name": { "type": "string", "nullable": true, "description": "Aláíró neve.", "example": "Kovács Anna" }, "phone": { "type": "string", "nullable": true, "description": "Telefonszám.", "example": "+36301234567" }, "type": { "type": "string", "enum": [ "company", "private_person" ], "description": "A fél típusa (mindig ki van töltve)." }, "name": { "type": "string", "nullable": true, "description": "A fél neve.", "example": "Minta Kereskedelmi Kft." }, "tax_number": { "type": "string", "nullable": true, "description": "Adószám (cégnél).", "example": "12345678-2-42" }, "mother_name": { "type": "string", "nullable": true, "description": "Anyja neve (magánszemélynél)." }, "birth_place": { "type": "string", "nullable": true, "description": "Születési hely (magánszemélynél)." }, "address": { "type": "string", "nullable": true, "description": "Székhely vagy lakcím.", "example": "1111 Budapest, Minta utca 1." }, "birth_date": { "type": "string", "nullable": true, "description": "Születési dátum `ÉÉÉÉ-HH-NN` (magánszemélynél).", "format": "date" } } }, "GuestContract": { "type": "object", "description": "A szerződés, ahogy a vendég aláíró megkapja. A kód szerint NEM szűkített: ugyanaz a teljes szerződés-erőforrás, mint a hitelesített lekérésnél — benne minden fél összes adata (adószám, anyja neve, születési adatok, cím, aláírási IP / eszköz), a `note`, a teljes tevékenységnapló és a feleknek küldött levelek listája. Vendégként az `archived` mindig `false`, a `profile`-ban nincs tagnévsor és meghívólista, és a `permission_warnings` csak a vendégnek is értelmes kulcsoknál ad érdemi választ.", "required": [ "name", "language", "content", "created_at", "updated_at", "token", "security", "status", "note", "validity_start", "intro_text", "framework_contract_text", "processed_content", "archived", "signatures", "fields", "attachments", "profile", "comments", "logs", "permission_warnings" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "A szerződés neve.", "example": "Megbízási szerződés" }, "language": { "type": "string", "enum": [ "hu", "en" ], "description": "A szerződés (és a hozzá tartozó levelek) nyelve." }, "content": { "type": "string", "nullable": true, "description": "A szerződés szövege HTML-ben, a `[…]` helyőrzőkkel. Megjelenítés előtt szűrd (sanitize)." }, "created_at": { "type": "integer", "description": "Létrehozás (Unix-időbélyeg, másodperc).", "example": 1767225600 }, "updated_at": { "type": "integer", "description": "Utolsó módosítás (Unix-időbélyeg, másodperc).", "example": 1767229200 }, "token": { "type": "string", "description": "A szerződés tokenje (a hitelesített végpontokhoz; vendégként nem használható).", "example": "abcd1234efgh5678" }, "security": { "type": "string", "enum": [ "acceptance", "digital_signature" ], "description": "Aláírási mód: `acceptance` = elfogadással (aláírásképpel), `digital_signature` = saját minősített / AVDH-s e-aláírással aláírt PDF feltöltésével." }, "status": { "type": "string", "enum": [ "opened", "signable", "signed" ], "description": "`opened` = hiányzó adat vagy mező, `signable` = minden ki van töltve, aláírható, `signed` = lezárva, az aláírt fájl elkészült." }, "note": { "type": "string", "nullable": true, "description": "A szerződéshez fűzött megjegyzés (a készítő profil tölti ki)." }, "validity_start": { "type": "integer", "nullable": true, "description": "A hatály kezdete (Unix-időbélyeg): digitális módnál az első aláírt PDF bélyegzőjének ideje, egyébként a lezárás ideje." }, "intro_text": { "type": "string", "description": "A szerződés bevezető mondata a felek nevével, a szerződés nyelvén." }, "framework_contract_text": { "type": "string", "description": "A keretszerződési záradék szövege a szerződés nyelvén." }, "processed_content": { "type": "string", "nullable": true, "description": "A `content`, a helyőrzők helyére a mezőértékek és a felek adatai behelyettesítve (HTML). Megjelenítés előtt szűrd (sanitize)." }, "archived": { "type": "boolean", "description": "Archivált-e a hívó profiljaiban; vendégként mindig `false`." }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ContractSignature" }, "description": "Az aláírói helyek sorrendben, mindegyikben `profile` és `sent_mails`. A vendég saját helye: `own=true`." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ContractField" }, "description": "A kitöltendő mezők sorrendben." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ContractAttachment" }, "description": "A mellékletek sorrendben." }, "profile": { "allOf": [ { "$ref": "#/components/schemas/Profile" } ], "description": "A szerződést készítő profil (a tulajdonos `owner` adataival; tagnévsor és meghívók nélkül)." }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/ContractComment" }, "description": "A megjegyzések időrendben, a törölteket is beleértve (`deleted=true`, `content=null`), a szerző `user` adataival." }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/ContractLog" }, "description": "A szerződés teljes tevékenységnaplója." }, "permission_warnings": { "allOf": [ { "$ref": "#/components/schemas/PermissionWarnings" } ], "description": "Kulcsok: read, update, share, delete, upload_attachment, leave, archive, unarchive, preview, download_signed_file, create_comment, show_sign_manually_button, sign_manually, accept, reject, fill_fields, analyze_signed_file, show_sent_mails. Vendégként érdemi: preview, download_signed_file, create_comment, fill_fields, analyze_signed_file, show_sent_mails; a többi mindig `forbidden`." } } } } } }