Ügyek — cases

Művelet	Mit tesz	Jog
GET /cases/list	lista	cases:read
GET /cases/get	egy ügy a feladataival, id vagy code szerint	cases:read
GET /cases/schema	a mezők leírása	cases:read
GET /cases/history	az ügy állapotváltásai és kommentjei	cases:read
POST /cases/new	új ügy	cases:write
POST /cases/update	módosítás — csak a küldött mező, updateMask-kal a felsorolt változik	cases:write
POST /cases/set_status	az ügy állapotának váltása	cases:write
POST /cases/add_comment	komment az ügyön	cases:write
POST /cases/new_task	új feladat az ügyön	cases:write
POST /cases/update_task	a feladat módosítása — csak a küldött mező	cases:write
POST /cases/set_task_status	a feladat állapotának váltása	cases:write

Ügy az API-n nem törölhető: a cancelled állapot zárja le. Minden ügy olvasható; írni az aktív ügyfélszolgálati projekt és a projekt nélküli ügyét lehet — a többi ügy írása 422 (OUT_OF_REACH).

A mezők

Mező	Régi	Típus		Listában	Leírás
id	ticket_id	integer	csak olvasható	✓	belső azonosító
code		string(40)		✓	külső azonosító (id és code); az új és az átírt kódot másik ügy nem használhatja
status	state	string	csak olvasható	✓	az állapot: new (Új) · in_progress (Folyamatban) · suspended (Felfüggesztve) · closed (Lezárt) · cancelled (Sztornó); a set_status váltja
processId	process_id	integer	kötelező	✓	a folyamat: az ügy feladatai a lépéseiből épülnek
processName	—	string		✓	a folyamat neve; a kérésben a folyamat a nevével is megadható, ha a processId is jön, az az erősebb
channel	source	string	kötelező	✓	a bejelentés módja: phone (Telefon) · email (E-mail) · sms (SMS) · chat (Chat) · post (Posta) · personal (Személyes) · system (Rendszer)
priority	prior	string		✓	normal vagy high; alapból normal
userId	userid	integer		✓	a felelős felhasználó: a projekt aktív tagja; ha nincs, a válaszban üres, a kérésben 0
userCode	user_code	string		✓	a felelős külső azonosítója; a kérésben a felelős ezzel is megadható
userName	—	string	csak olvasható	✓	a felelős neve
userExtCode	—	string	csak olvasható	✓	a felelős egyéb kódja
folderId	—	integer		✓	a felelős csoport. A felelős egy felhasználó vagy egy csoport: az egyik megadása a másikat üríti.
folderName	—	string		✓	a csoport neve; a kérésben a csoport ezzel is megadható
projectId	prid	integer		✓	a projekt, aktív ügyfélszolgálati projekt; ha nincs, projekt nélküli ügy
projectCode	prcode	string		✓	a projekt külső azonosítója; a kérésben a projekt ezzel is megadható
projectName	—	string	csak olvasható	✓	a projekt neve
listId	lsid	integer		✓	az ügyfél listája, a tételé; a kérésben csak a listItemCode mellett
listCode	lscode	string		✓	a lista külső azonosítója; a kérésben csak a listItemCode mellett
listName	—	string	csak olvasható	✓	a lista neve
listItemId	listitem_num	integer		✓	az ügyfél: a projekt telefonkönyvének tétele, projekt nélküli ügynél bármely aktív ügyfélszolgálati projekté
listItemCode	extcode	string		✓	a tétel külső azonosítója a listában; a kérésben a listId vagy a listCode mellett
listItemName	—	string	csak olvasható	✓	az ügyfél neve a listán
contactNo	contact_num	integer		✓	a tétel kontaktjának sorszáma; a nem létező kontakt nem kerül az ügyre
customerName	client	string(250)		✓	az ügyfél neve az ügyön
contactName	contact_name	string(250)		✓	a kontakt neve
phoneNumber	phone_num	string(20)		✓	telefonszám
email	email_address	string(80)		✓	e-mail cím
description	details	string		✓	a bejelentés leírása
note	notes	string		✓	belső megjegyzés
startedAt	start_time	string		✓	a kezdet, eltolással; felvételkor alapból a mostani idő
closedAt	end_time	string	csak olvasható	✓	a lezárás ideje; a nem lezárt ügynél üres
updatedAt	—	string	csak olvasható	✓	az utolsó módosítás ideje
tasks	tasks	array	csak olvasható		a feladatok, a get adja

Lezárt és sztornózott ügy nem módosítható, a feladatai sem; komment rájuk is írható.

A feladat

Mező	Régi	Típus		Leírás
taskId	task_id	integer	csak olvasható	a feladat belső azonosítója
parentTaskId	parent_id	integer		a szülő feladat ugyanabban az ügyben; ha nincs, a válaszban üres, a kérésben 0
orderNo	order_num	integer	csak olvasható	a sorszáma a testvérei közt
name		string(180)	kötelező	a feladat megnevezése
status	state	string	csak olvasható	new (Új) · in_progress (Folyamatban) · suspended (Felfüggesztve) · done (Elkészült) · skipped (Kihagyott); a set_task_status váltja
userId	userid	integer		a felelős felhasználó: az ügy projektjének aktív tagja
userCode	user_code	string		a felelős külső azonosítója; a kérésben ezzel is
userName · userExtCode	—	string	csak olvasható	a felelős neve és egyéb kódja
folderId	folder_id	integer		a felelős csoport; a felelős egy felhasználó vagy egy csoport
folderName	folder_name	string		a csoport neve; a kérésben ezzel is
startedAt	start_time	string		a kezdet
closedAt	end_time	string	csak olvasható	az elkészülés vagy a kihagyás ideje
note	notes	string		eredmény, megjegyzés
stepDescription	—	string	csak olvasható	a folyamat-lépés leírása, amiből a feladat épült
updatedAt	—	string	csak olvasható	az utolsó módosítás ideje

GET /cases/list Lista

Az ügyek, lapozva (A lapozás), a feladataik nélkül.

Paraméter	Régi	Típus	Mit szűr
projectId · projectCode	prid · prcode		egy projekt ügyei
processId · processName	—		egy folyamat ügyei
status	—	string	egy állapot ügyei
userId · userCode	—		a felelős felhasználó ügyei
folderId · folderName	—		a felelős csoport ügyei
listItemId	—	integer	egy ügyfél ügyei
code	—	string	a külső azonosító
startedSince · startedUntil	start_date · end_date	string	a kezdet: ettől (benne van) eddig (nincs benne)
updatedSince	—	string	az ettől módosultak

Válasz 200application/json

{
  "cases": [
    {
      "id": 5120,
      "code": "UGY-2026-0142",
      "status": "in_progress",
      "processId": 3,
      "processName": "Reklamáció",
      "channel": "phone",
      "priority": "high",
      "userId": 42,
      "userCode": "HR-1042",
      "userName": "Kovács Anna",
      "userExtCode": null,
      "folderId": null,
      "folderName": null,
      "projectId": 9,
      "projectCode": "UGYSZOLG",
      "projectName": "Ügyfélszolgálat",
      "listId": 4,
      "listCode": "TELKONYV",
      "listName": "Telefonkönyv",
      "listItemId": 884512,
      "listItemCode": "C-1001",
      "listItemName": "Szabó Péter",
      "contactNo": 1,
      "customerName": "Szabó Péter",
      "contactName": "Szabó Péter",
      "phoneNumber": "3610000001",
      "email": "peter.szabo@example.com",
      "description": "A számlán kétszer szerepel a havidíj.",
      "note": null,
      "startedAt": "2026-10-28T10:05:00+01:00",
      "closedAt": null,
      "updatedAt": "2026-10-29T14:20:11+01:00"
    }
  ],
  "hasMore": false
}

curl "$BASE/cases/list?projectCode=UGYSZOLG&status=in_progress" -H "X-API-Key: $API_KEY"

GET /cases/get Egy ügy

Ugyanazok a mezők, mint a list-ben, és a feladatok (tasks), a fa sorrendjében: a szülőt a parentTaskId adja.

HTTP	code	Mikor
422	VALIDATION_FAILED	a code több ügyön áll (AMBIGUOUS) — az id keresi

curl "$BASE/cases/get?code=UGY-2026-0142" -H "X-API-Key: $API_KEY"

Válasz 200application/json

{
  "id": 5120,
  "code": "UGY-2026-0142",
  "status": "in_progress",
  "processId": 3,
  "processName": "Reklamáció",
  "channel": "phone",
  "priority": "high",
  "description": "A számlán kétszer szerepel a havidíj.",
  "startedAt": "2026-10-28T10:05:00+01:00",
  "tasks": [
    {
      "taskId": 20311,
      "parentTaskId": null,
      "orderNo": 1,
      "name": "Számla ellenőrzése",
      "status": "done",
      "userId": 42,
      "userCode": "HR-1042",
      "userName": "Kovács Anna",
      "userExtCode": null,
      "folderId": null,
      "folderName": null,
      "startedAt": "2026-10-28T10:10:00+01:00",
      "closedAt": "2026-10-28T11:02:00+01:00",
      "note": "Valóban kétszer terheltük.",
      "stepDescription": "Nézd meg a számlát a számlázó rendszerben.",
      "updatedAt": "2026-10-28T11:02:00+01:00"
    }
  ]
}

A példa az ügy mezőinek egy részét mutatja: a válasz mindet adja, mint a list.

GET /cases/schema A mezők leírása

A feladat mezői a tasks leírásában. A válasz alakja: A mezők leírása.

curl "$BASE/cases/schema" -H "X-API-Key: $API_KEY"

GET /cases/history Az ügy előzménye

Az ügy állapotváltásai (statusChanges) és kommentjei (comments), a legújabb elöl. Az ügyet az id vagy a code adja. Az API-n írt váltás és komment szereplője API.

Mező	Típus	Leírás
statusChanges[].changedAt	string	a váltás ideje
statusChanges[].status	string	az új állapot
statusChanges[].userId · userName		aki váltott
statusChanges[].note	string	megjegyzés
comments[].id	integer	a komment belső azonosítója
comments[].createdAt	string	a komment ideje
comments[].text	string	a komment
comments[].userName	string	a szerzője

Válasz 200application/json

{
  "statusChanges": [
    { "changedAt": "2026-10-28T10:10:00+01:00", "status": "in_progress", "userId": 42, "userName": "Kovács Anna", "note": null },
    { "changedAt": "2026-10-28T10:05:00+01:00", "status": "new", "userId": null, "userName": "API", "note": null }
  ],
  "comments": [
    { "id": 77, "createdAt": "2026-10-28T12:30:00+01:00", "text": "Az ügyfél visszahívást kér.", "userName": "API" }
  ]
}

curl "$BASE/cases/history?id=5120" -H "X-API-Key: $API_KEY"

POST /cases/new Új ügy

Kötelező a folyamat (processId vagy processName) és a channel. Az új ügy new állapotban indul, a feladatai a folyamat lépéseiből épülnek. A válasz 201, az új ügy azonosítójával.

Kérésapplication/json

{
  "code": "UGY-2026-0143",
  "processName": "Reklamáció",
  "channel": "email",
  "projectCode": "UGYSZOLG",
  "listCode": "TELKONYV",
  "listItemCode": "C-1001",
  "contactNo": 1,
  "description": "Nem érkezett meg a megrendelt csomag."
}

HTTP	code	Mikor
422	VALIDATION_FAILED	mezőhiba (fields): hiányzó vagy ismeretlen channel (REQUIRED, INVALID_VALUE), nem létező hivatkozás a kódjával vagy a nevével (INVALID_VALUE), a kód egy másik ügyé (CODE_TAKEN_BY)
422	VALIDATION_FAILED	a folyamat nem választható (PROCESS_NOT_ALLOWED) · a projekt nem aktív ügyfélszolgálati projekt (PROJECT_NOT_ALLOWED) · a felelős nem dolgozik a projekten (OWNER_NOT_MEMBER) · felhasználó és csoport együtt (OWNER_BOTH) · ismeretlen csoport (UNKNOWN_FOLDER) · a tétel nem választható (CUSTOMER_NOT_AVAILABLE)

curl "$BASE/cases/new" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"processName": "Reklamáció", "channel": "email", "projectCode": "UGYSZOLG", "description": "Nem érkezett meg a csomag."}'

POST /cases/update Módosítás

Csak nyitott ügy módosítható. A folyamat cseréje az ügy feladatait a folyamat lépéseiből újraépíti: a régi feladatok törlődnek. Az állapotot a set_status váltja. Ha az ügyet a code keresi, a kód nem változik.

Kérésapplication/json

{ "id": 5120, "priority": "normal", "folderName": "Számlázás" }

HTTP	code	Mikor
422	VALIDATION_FAILED	mezőhiba és hivatkozás-hiba, mint a new-nál · lezárt vagy sztornózott ügy (CLOSED) · az ügy projektje nem aktív ügyfélszolgálati projekt (OUT_OF_REACH)

curl "$BASE/cases/update" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"id": 5120, "priority": "normal"}'

POST /cases/set_status Állapotváltás

Az ügyet az id vagy a code, a célállapotot a status adja. Ha az ügy már ebben az állapotban van, nem történik semmi. A felelős nem változik.

Célállapot	Ahonnan
in_progress	new, suspended, closed, cancelled
suspended	new, in_progress
closed	new, in_progress, suspended — ha nincs nyitott feladata
cancelled	new, in_progress, suspended

Kérésapplication/json

{ "code": "UGY-2026-0142", "status": "closed" }

HTTP	code	Mikor
422	VALIDATION_FAILED	ismeretlen status (INVALID_VALUE) · a mostani állapotból nem vihető ide (STATUS_NOT_ALLOWED) · lezárás nyitott feladattal (OPEN_TASKS) · az ügy projektje nem aktív ügyfélszolgálati projekt (OUT_OF_REACH)

curl "$BASE/cases/set_status" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"code": "UGY-2026-0142", "status": "closed"}'

POST /cases/add_comment Komment

Komment az ügyön (text, legfeljebb 2000 karakter); lezárt ügyre is. Az ügyet az id vagy a code adja. A válasz 201, a komment azonosítójával.

Kérésapplication/json

{ "id": 5120, "text": "Az ügyfél visszahívást kér." }

HTTP	code	Mikor
422	VALIDATION_FAILED	üres komment (COMMENT_EMPTY) · túl hosszú (COMMENT_TOO_LONG)

curl "$BASE/cases/add_comment" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"id": 5120, "text": "Az ügyfél visszahívást kér."}'

POST /cases/new_task Új feladat

Új feladat a nyitott ügyön: az ügyet a caseId vagy a caseCode adja, mellette a feladat mezői. Kötelező a name. Az új feladat new állapotban a testvérei végére kerül. A válasz 201, az új feladat azonosítójával.

Kérésapplication/json

{ "caseId": 5120, "name": "Jóváírás indítása", "parentTaskId": 20311, "userCode": "HR-1042" }

HTTP	code	Mikor
422	VALIDATION_FAILED	lezárt ügy (TASKS_CLOSED) · a szülő nem az ügy feladata (PARENT_NOT_ALLOWED) · a felelős, mint a new-nál

curl "$BASE/cases/new_task" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"caseId": 5120, "name": "Jóváírás indítása"}'

POST /cases/update_task A feladat módosítása

A feladatot a taskId adja; csak a küldött mező változik, updateMask-kal a felsorolt. Az állapotot a set_task_status váltja. A szülő nem lehet a feladat saját ága.

Kérésapplication/json

{ "taskId": 20312, "note": "A jóváírás elindult." }

HTTP	code	Mikor
422	VALIDATION_FAILED	lezárt ügy (TASKS_CLOSED) · nem választható szülő (PARENT_NOT_ALLOWED) · a felelős, mint a new-nál

curl "$BASE/cases/update_task" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"taskId": 20312, "note": "A jóváírás elindult."}'

POST /cases/set_task_status A feladat állapotváltása

A feladatot a taskId, a célállapotot a status adja; nyitott ügyön. Ha a feladat már ebben az állapotban van, nem történik semmi.

Célállapot	Ahonnan	Ami vele jár
in_progress	bármelyik	a szülő feladatok és az ügy is in_progress; ha a feladat első nyitott részfeladata new, az is indul
new	in_progress	—
suspended	new, in_progress	—
done · skipped	new, in_progress, suspended — ha nincs nyitott részfeladata	a következő new testvér indul; ha a testvérek mind lezárultak, a szülő is lezárul

Kérésapplication/json

{ "taskId": 20312, "status": "done" }

HTTP	code	Mikor
422	VALIDATION_FAILED	ismeretlen status (INVALID_VALUE) · lezárt ügy (TASKS_CLOSED) · a feladat már lezárult (TASK_CLOSED) · felfüggesztés lezárt feladaton (TASK_SUSPEND_STATE) · vissza new-ba nem folyamatban lévő feladatról (TASK_RESET_STATE) · nyitott részfeladat (TASK_OPEN_CHILD)

curl "$BASE/cases/set_task_status" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"taskId": 20312, "status": "done"}'

A régi API-ból

Cím	Kérés	Válasz	Működés
ticket/list → GET /cases/list	a start_date · end_date nap helyett startedSince · startedUntil időpont; az offset helyett after	a tickets helyett cases; az állapot, a bejelentés módja és a prioritás szóval	a régi a nyitott ügyet az időszaktól függetlenül is adta, az új csak a kezdet szerint szűr · a sorrend az azonosítóé
ticket/get → GET /cases/get	ticket_id · ticket_code → id · code	az ügy a válasz gyökerében, a feladatai a tasks-ban	—
ticket/new → POST /cases/new	a state nem adható meg; a felelős csoporttal is megadható	ticket_id → id, 201	az új ügy mindig new · a description nem kötelező · a projekt aktív ügyfélszolgálati projekt, a felelős a projekt aktív tagja, az ügyfél a projekt telefonkönyvének tétele · a kód egyedi
ticket/update → POST /cases/set_status	ticket_id · ticket_code → id · code; a state szám helyett status szó	—	csak az engedett irányba vált, a lezárás nyitott feladattal nem megy · az ügy mezőit az update módosítja
ticket/new_task → POST /cases/new_task	ticket_id · ticket_code → caseId · caseCode	task_id → id, 201	az új feladat new, a testvérei végére kerül
ticket/update_task → POST /cases/update_task · POST /cases/set_task_status	a feladatot a taskId adja, az ügy nem kell; az állapot a set_task_status-ban, szóval	—	a régi bármelyik állapotot beírta; az új az engedett irányba vált, és a szülőket, a testvéreket és az ügyet is viszi
—	—	—	csak az újban: cases/schema, cases/update, cases/history, cases/add_comment