Listatételek — listitems
| Művelet | Mit tesz | Jog |
|---|---|---|
GET /listitems/list |
egy lista tételei | listitems:read |
GET /listitems/get |
egy tétel | listitems:read |
GET /listitems/history |
a tétel hívásai, levelei, SMS-ei és ügyei | listitems:read |
GET /listitems/schema |
a mezők leírása | listitems:read |
POST /listitems/new |
új tétel | listitems:write |
POST /listitems/upsert |
felvétel vagy módosítás a külső azonosító szerint | listitems:write |
POST /listitems/bulk |
sok tétel felvétele vagy módosítása egy kérésben | listitems:write |
POST /listitems/update |
tétel módosítása | listitems:write |
POST /listitems/disable |
tiltás | listitems:delete |
POST /listitems/enable |
feloldás | listitems:delete |
A mezők
Szekció neve “A mezők”| Mező | Régi | Típus | Listában | Leírás | |
|---|---|---|---|---|---|
id |
listitem_num |
integer |
csak olvasható | ✓ | belső azonosító |
code |
extcode |
string |
✓ | külső azonosító: a tétel értéke a lista kód-oszlopában (a lista codeColumn-ja). Kód-oszlopos listán felvételkor kötelező és a listában egyedi, utána nem változtatható; üres, ha a listának nincs kód-oszlopa |
|
listId |
lsid |
integer |
✓ | a lista belső azonosítója — felvételkor a listId vagy a listCode kötelező |
|
listCode |
lscode |
string |
✓ | a lista külső azonosítója | |
listName |
— | string |
csak olvasható | ✓ | a lista neve |
status |
disabled |
string |
csak olvasható | ✓ | az állapot — lent; a tiltás és a feloldás a disable és az enable |
values |
columns |
array |
✓ | a tétel adatai, a lista oszlopainak sorrendjében — Az oszlopok | |
extraValues |
plusinfo |
array |
✓ | az egyéb adatok, a lista extraColumns-ának sorrendjében — Az oszlopok |
|
note |
notes |
string |
✓ | megjegyzés | |
expiresAt |
expiration_time |
string |
✓ | a tétel lejárata; üres szöveggel törölhető. A felvételkor a hívás sorrendjét is adja: a lejárattal felvett tételek közül a korábban lejáró kerül előbb sorra — abban a projektben, amelyhez a lista a felvételkor már hozzá van rendelve (a hozzárendelés) | |
updatedAt |
date |
string |
csak olvasható | ✓ | az utolsó módosítás ideje |
contacts |
contacts |
array |
✓ | a kontaktok — A kontaktok | |
handlers |
— | array |
✓ | az ügyfélfelelősök, sorrendben — Az ügyfélfelelősök | |
handlersOnly |
— | boolean |
✓ | csak az ügyfélfelelősök kaphatják a hívást — Az ügyfélfelelősök |
Az állapot: active · disabled (tiltott) · duplicate (duplikáció) · quota (sorkvóta) · expired (lejárt) ·
excluded (kizárt) · anonymized (anonimizált: nem írható, nem tiltható és nem oldható fel; a code-ja megmarad, így
a kód szerinti felvétel nem hozza létre újra — a new ITEM_CODE_TAKEN_NEW-t, az upsert ITEM_ANONYMIZED-et ad). A tételnek disabled
mezője nincs, és a tiltott tétel is módosítható — a tiltás általános szabálya itt csak a
disable-re és az enable-re áll.
A tétel keresése
Szekció neve “A tétel keresése”A get, a history, az update, a disable és az enable ugyanígy keresi a tételt: a get és a history a
query-stringben, a többi a kérés törzsében.
| Paraméter | Régi | Típus | Leírás |
|---|---|---|---|
id |
listitem_num |
integer |
a tétel belső azonosítója — magában elég |
listId |
lsid |
integer |
a lista belső azonosítója, a code-dal |
listCode |
lscode |
string |
a lista külső azonosítója, a listId helyett |
code |
extcode |
string |
a tétel külső azonosítója |
Ha az id is jön, az dönt. A code a lista kód-oszlopában keres; kód-oszlop nélküli listán nem használható, és ha az érték
több tételen áll, a válasz 422 (AMBIGUOUS). A code csak keresés: a tétel kódja nem írható át.
Az oszlopok
Szekció neve “Az oszlopok”A values a tétel adatai a lista oszlopainak sorrendjében (Az oszlopok): az első elem az első
oszlopé. Legfeljebb annyi elem lehet, ahány oszlopa a listának van, egy érték legfeljebb 250 karakter; a szám
szövegként tárolódik. Módosításnál a null elem nem változtat — csak a küldött értékek íródnak:
{ "id": 884512, "values": [null, "Debrecen"] }A kód-oszlop értéke a code is: felvételkor elég az egyik, és ha mindkettő jön, egyezniük kell.
Az extraValues mindig a teljes lista: a küldött tömb a tárolt helyére lép, legfeljebb annyi elemmel, ahány egyéb
oszlopa a listának van.
A kontaktok
Szekció neve “A kontaktok”| Mező | Régi | Típus | Leírás |
|---|---|---|---|
contactNo |
contact_num |
integer |
a kontakt sorszáma a tételen belül — a rendszer adja |
code |
code |
string(40) |
a kontakt külső azonosítója; felvételkor adható, utána nem változik |
name |
name |
string(250) |
név |
position |
jpos |
string(250) |
beosztás |
phone |
phone |
string |
telefonszám, országhívóval (36301234567, +36…, 0036…) — a tárolt alakjában jön vissza: csak számjegy, a 00 előtag nélkül, a 06 helyén 36; országhívó nélkül úgy marad, ahogy jött |
email |
email |
string(80) |
e-mail cím |
note |
notes |
string(250) |
megjegyzés |
disabled |
disabled |
boolean |
tiltott-e a kontakt |
delete |
boolean |
csak a kérésben: a true törli a contactNo-val megadott kontaktot |
A contacts csak a küldött kontaktokat írja, a többi változatlan marad:
- a
contactNo-val küldött kontakt a meglévőt módosítja — a hiányzó mezője változatlan marad; - a
contactNonélküli kontakt új, a számát a rendszer adja; - a
contactNo-val ésdelete: true-val küldött kontakt törlődik; mellette más mező nem állhat.
Egy kontaktban legalább egy mező kitöltött; a 36-tal kezdődő szám legalább tíz jegyű. Egy tételnek legfeljebb 99
kontaktja lehet. A visszahívással lekötött kontakt nem törölhető, csak tiltható (disabled).
Az ügyfélfelelősök
Szekció neve “Az ügyfélfelelősök”Az ügyfélfelelősök sorrendje számít: az első az elsődleges. Ha a projekt a hívásokat az ügyfélfelelősöknek osztja, a tétel ügyfelének
bejövő hívását elsőként az ügyfélfelelősei kapják, ebben a sorrendben; ha a handlersOnly true, csak ők.
| Mező | Típus | Leírás |
|---|---|---|
userId |
integer |
a felhasználó belső azonosítója |
userCode |
string |
a felhasználó kódja |
userName |
string |
a felhasználó neve — csak a válaszban |
userExtCode |
string |
a felhasználó egyéb kódja — csak a válaszban |
A handlers a teljes ügyfélfelelős-lista: aki nincs benne, az kikerül, az üres tömb ([]) mindet kiveszi. Egy tételnek
legfeljebb öt ügyfélfelelőse lehet, egy felhasználó egyszer. Az ügyfélfelelős a userId-jével vagy a userCode-jával jön; ha
mindkettő, a userId dönt. Új ügyfélfelelős csak aktív felhasználó lehet. A tiltott és a törölt felhasználó az ügyfélfelelősök között
marad — a get is visszaadja —, amíg ki nem veszed.
GET /listitems/list Tételek
Szekció neve “GET /listitems/list Tételek”Egy lista tételei, lapozva (A lapozás), a kontaktjaikkal és az ügyfélfelelőseikkel.
| Paraméter | Régi | Típus | Leírás | |
|---|---|---|---|---|
listId · listCode |
lsid · lscode |
kötelező | a lista | |
status |
allow_disabled |
string |
egy állapot; elhagyva mind | |
updatedSince |
from_date |
string |
az ennél nem korábban módosult tételek |
{ "listitems": [ { "id": 884512, "code": "100231", "listId": 12, "listCode": "KAMP-2026-10", "listName": "Októberi kampány", "status": "active", "values": ["Szabó Péter", "Budapest", "100231"], "extraValues": ["Előző vásárlás: 2026. szeptember"], "note": null, "expiresAt": null, "updatedAt": "2026-10-19T09:12:05+02:00", "contacts": [ { "contactNo": 1, "code": null, "name": "Szabó Péter", "position": null, "phone": "3610000001", "email": "peter.szabo@example.com", "note": null, "disabled": false } ], "handlers": [{ "userId": 42, "userCode": "HR-1042", "userName": "Kovács Anna", "userExtCode": null }], "handlersOnly": false } ], "hasMore": false}| HTTP | code |
Mikor |
|---|---|---|
400 |
INVALID_ARGUMENT |
se listId, se listCode · ismeretlen status |
404 |
NOT_FOUND |
ismeretlen lista |
curl "$BASE/listitems/list?listCode=KAMP-2026-10&updatedSince=2026-10-19T00:00:00" -H "X-API-Key: $API_KEY"GET /listitems/get Egy tétel
Szekció neve “GET /listitems/get Egy tétel”A tétel a lista mezőivel.
curl "$BASE/listitems/get?listCode=KAMP-2026-10&code=100231" -H "X-API-Key: $API_KEY"| HTTP | code |
Mikor |
|---|---|---|
400 |
INVALID_ARGUMENT |
se id, se lista és code (Parameter 'id', or 'listId' / 'listCode' with 'code' is required) · a listának nincs kód-oszlopa |
404 |
NOT_FOUND |
ismeretlen lista vagy tétel |
422 |
VALIDATION_FAILED |
a code a listában több tételen áll, vagy a listCode több listán (AMBIGUOUS) |
GET /listitems/history A tétel előzménye
Szekció neve “GET /listitems/history A tétel előzménye”A tétel hívásai, levelei, SMS-ei és ügyei, a legutóbbi száz, a legújabb elöl. A részletet a hivatkozott rekord adja: a
hívásét a calls/get, a levélét az emails/get.
| Mező | Régi | Típus | Leírás |
|---|---|---|---|
type |
channel |
string |
call · email · sms · ticket (ügy, cases) |
startedAt |
start_time |
string |
az esemény kezdete |
endedAt |
end_time |
string |
a hívás vége; a többinél üres |
direction |
direction |
string |
in vagy out; az ügynél üres |
projectId |
— | integer |
a projekt belső azonosítója |
projectCode |
prcode |
string |
a projekt külső azonosítója |
projectName |
— | string |
a projekt neve |
title |
event |
string |
a hívás lezárása, az ügy folyamata; a többinél üres |
text |
notes |
string |
a hívás megjegyzése, a levél tárgya, az SMS szövege, az ügy leírása |
userId |
— | integer |
a felhasználó belső azonosítója; üres, ha nincs |
userCode |
— | string |
a felhasználó külső azonosítója |
userName |
— | string |
a felhasználó neve |
userExtCode |
— | string |
a felhasználó egyéb kódja |
contactName |
contact |
string |
a kontakt neve |
contactAddress |
— | string |
a kontakt száma vagy e-mail címe |
callId · emailId · smsId · caseId |
— | integer |
a hívás, a levél, az SMS, illetve az ügy belső azonosítója — a típusáé, a többi üres |
ticketId |
— | integer |
elavult: a caseId régi neve, ugyanazt adja |
recording |
— | string |
a hívás felvétele, mint a hívásnaplóban; a többinél üres |
callbackAt |
— | string |
a hívás lezárásával kért visszahívás ideje |
{ "events": [ { "type": "call", "startedAt": "2026-10-19T09:12:04+02:00", "endedAt": "2026-10-19T09:15:03+02:00", "direction": "out", "projectId": 12, "projectCode": "SALES", "projectName": "Őszi kampány", "title": "Visszahívást kért", "text": "Délután ráér", "userId": 42, "userCode": "HR-1042", "userName": "Kovács Anna", "userExtCode": null, "contactName": "Szabó Péter", "contactAddress": "3610000001", "callId": 8812345, "emailId": null, "smsId": null, "caseId": null, "ticketId": null, "recording": "available", "callbackAt": "2026-10-19T15:00:00+02:00" } ]}curl "$BASE/listitems/history?id=884512" -H "X-API-Key: $API_KEY"GET /listitems/schema A mezők leírása
Szekció neve “GET /listitems/schema A mezők leírása”Az oszlopok, az egyéb adatok, a kontaktok és az ügyfélfelelősök leírása a mezők mellett áll. A válasz alakja: A mezők leírása.
curl "$BASE/listitems/schema" -H "X-API-Key: $API_KEY"POST /listitems/new Új tétel
Szekció neve “POST /listitems/new Új tétel”Új tétel a listában, a lista projektjeibe is. Kód-oszlopos listán a code kötelező és a listában egyedi; a létező
kódú tételt az upsert módosítja.
{ "listCode": "KAMP-2026-10", "code": "100232", "values": ["Kovács Anna", "Szeged"], "contacts": [{ "name": "Kovács Anna", "phone": "3610000002", "email": "anna.kovacs@example.com" }], "handlers": [{ "userCode": "HR-1042" }]}| Mező | Típus | Leírás | |
|---|---|---|---|
listId · listCode |
kötelező | a lista | |
code |
string |
kód-oszlopos listán kötelező | a tétel külső azonosítója |
values · extraValues · note · expiresAt · contacts · handlers · handlersOnly |
A mezők szerint |
{ "id": 884513 }| HTTP | code |
Mikor |
|---|---|---|
400 |
INVALID_ARGUMENT |
se listId, se listCode · a listának nincs kód-oszlopa, de jön code · a code és a values kód-oszlopa eltér · a values nem tömb, vagy több eleme van, mint a lista oszlopainak száma · hibás kontakt vagy ügyfélfelelős, mint az update-nél |
422 |
VALIDATION_FAILED |
mezőhiba (fields): ismeretlen listId vagy listCode (INVALID_VALUE) · túl hosszú érték (TOO_LONG) · több egyéb adat, mint a lista egyéb oszlopa (TOO_HIGH) |
422 |
VALIDATION_FAILED |
hiányzó kód (ITEM_CODE_REQUIRED) · foglalt kód (ITEM_CODE_TAKEN_NEW) · a kontakt és az ügyfélfelelős hibái, mint az update-nél |
curl "$BASE/listitems/new" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \ -d '{"listCode": "KAMP-2026-10", "code": "100232", "values": ["Kovács Anna", "Szeged"]}'POST /listitems/upsert Felvétel vagy módosítás a kód szerint
Szekció neve “POST /listitems/upsert Felvétel vagy módosítás a kód szerint”A kód-oszlopos lista tételét a code szerint keresi: ha nincs, felveszi, mint a new (201); ha van,
módosítja, mint az update (200). A válasz mindkét esetben { "id": … }.
| HTTP | code |
Mikor |
|---|---|---|
400 |
INVALID_ARGUMENT |
a listának nincs kód-oszlopa · hiányzik a code · a new és az update hibái |
422 |
VALIDATION_FAILED |
a code a listában több tételen áll (AMBIGUOUS) · mint a new-nál és az update-nél |
curl "$BASE/listitems/upsert" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \ -d '{"listCode": "KAMP-2026-10", "code": "100232", "values": [null, "Pécs"]}'POST /listitems/bulk Sok tétel egy kérésben
Szekció neve “POST /listitems/bulk Sok tétel egy kérésben”Egy kód-oszlopos lista legfeljebb 1000 tételét veszi fel vagy módosítja egy kérésben. Minden tételre az
upsert szabálya áll: a code szerint keresi, ha nincs, felveszi, ha van, módosítja. Ha egy code a
kérésben kétszer szerepel, az első felveszi a tételt, a második módosítja.
{ "listCode": "KAMP-2026-10", "items": [ { "code": "100232", "values": ["Kovács Anna", "Szeged"], "contacts": [{ "name": "Kovács Anna", "phone": "3610000002" }] }, { "code": "100233", "values": ["Szabó Péter", "Pécs"] }, { "code": "100234", "note": "VIP" } ]}| Mező | Típus | Leírás | |
|---|---|---|---|
listId · listCode |
kötelező | a lista — a kérés minden tétele ebbe a listába kerül | |
items |
array |
kötelező | a tételek: legalább 1, legfeljebb 1000 |
items[].code |
string |
kötelező | a tétel külső azonosítója |
items[].values · extraValues · note · expiresAt · contacts · handlers · handlersOnly |
A mezők szerint, mint az upsert-nél. A tételben listId és listCode nem állhat |
A válasz akkor is 200, ha egy tétel hibás: a hibás tétel a többit nem állítja meg. A results tételenként egy
eredmény, a kérés sorrendjében.
{ "results": [ { "id": 884513, "result": "created" }, { "id": 884514, "result": "updated" }, { "result": "failed", "error": { "code": "VALIDATION_FAILED", "reason": "ITEM_ANONYMIZED", "message": "An anonymized item is final — it can only be deleted" } } ], "createdCount": 1, "updatedCount": 1, "failedCount": 1}| Mező | Típus | Leírás |
|---|---|---|
results[].result |
string |
created (felvett) · updated (módosított) · failed (hibás) |
results[].id |
integer |
a tétel belső azonosítója; a hibás tételnél nincs |
results[].error |
object |
csak a hibás tételnél: a hiba, mint a hibaválasz error objektuma — az, amit az upsert adna a tételre |
createdCount · updatedCount · failedCount |
integer |
a felvett, a módosított és a hibás tételek száma |
A tömeges kéréseket egymás után küldd: amíg a kulccsal fut egy, a következő 429. Ha a válasz nem érkezik meg
(időtúllépés, 500), küldd újra ugyanazt a kérést: a már felvett tételt a code szerint módosítja, nem veszi fel
újra.
| HTTP | code |
Mikor |
|---|---|---|
400 |
INVALID_ARGUMENT |
se listId, se listCode · a listának nincs kód-oszlopa · az items hiányzik, nem tömb, üres, vagy 1000-nél több eleme van |
413 |
a törzs túl nagy — küldj kevesebb tételt egy kérésben | |
422 |
VALIDATION_FAILED |
mezőhiba (fields): ismeretlen listId vagy listCode (INVALID_VALUE) · a listCode több listán áll (AMBIGUOUS) |
429 |
RATE_LIMITED |
a kulccsal már fut egy tömeges kérés — a Retry-After megmondja, mennyit várj |
curl "$BASE/listitems/bulk" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \ -d '{"listCode": "KAMP-2026-10", "items": [{"code": "100232", "values": ["Kovács Anna", "Szeged"]}, {"code": "100233", "values": ["Szabó Péter", "Pécs"]}]}'POST /listitems/update Tétel módosítása
Szekció neve “POST /listitems/update Tétel módosítása”Csak a küldött mező változik (A módosítás), a values null
eleme sem; a contacts kontaktonként ír (A kontaktok), a handlers mindig a teljes lista. A kérésben a tétel keresése
(A tétel keresése) és a mezők állhatnak. A kód-oszlop értéke a values-ban csak a
tárolttal egyezhet.
Az updateMask-kal a values a teljes sor: a hiányzó és a null elem ürül, a
kód-oszlopba ilyenkor is a tárolt kód kell. A contacts akkor is kontaktonként ír: a maszkban hiányzó nem töröl.
{ "listCode": "KAMP-2026-10", "code": "100231", "values": [null, "Debrecen"], "contacts": [ { "contactNo": 1, "phone": "3610000003" }, { "contactNo": 2, "delete": true }, { "name": "Szabó Éva", "position": "pénzügy" } ], "handlersOnly": true}| HTTP | code |
Mikor |
|---|---|---|
400 |
INVALID_ARGUMENT |
mint a get-nél · a values, a contacts, az extraValues vagy a handlers nem tömb · kétszer szereplő kontakt-contactNo · a delete contactNo nélkül, vagy mellette más mező · ismeretlen mező a kontaktban vagy az ügyfélfelelősben · a handlersOnly nem true / false |
404 |
NOT_FOUND |
mint a get-nél |
422 |
VALIDATION_FAILED |
a kód nem változtatható (ITEM_CODE_IMMUTABLE) · az anonimizált tétel (ITEM_ANONYMIZED) · túl hosszú érték vagy túl sok egyéb adat, mint a new-nál |
422 |
VALIDATION_FAILED |
üres kontakt (CONTACT_EMPTY) · hibás vagy túl hosszú e-mail cím (CONTACT_EMAIL_INVALID, CONTACT_EMAIL_TOO_LONG) · számjegy nélküli vagy rövid 36-os szám (CONTACT_PHONE_NO_DIGITS, CONTACT_PHONE_SHORT) · túl hosszú szöveg vagy kód (CONTACT_TEXT_TOO_LONG, CONTACT_CODE_TOO_LONG) · 99 fölött (CONTACTS_MAX) · visszahívással lekötött kontakt törlése (CONTACT_HAS_CALLBACK) |
422 |
VALIDATION_FAILED |
mezőhiba (fields): ismeretlen kontakt-contactNo (contacts.contactNo, INVALID_VALUE) · a handlers.userCode nem aktív felhasználóé (INVALID_VALUE), vagy több aktív felhasználón áll (AMBIGUOUS) |
422 |
VALIDATION_FAILED |
az új ügyfélfelelős ismeretlen vagy nem aktív (HANDLER_NOT_ALLOWED) · egy felhasználó kétszer (HANDLER_TWICE) · ötnél több ügyfélfelelős (HANDLERS_MAX) |
curl "$BASE/listitems/update" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \ -d '{"id": 884512, "handlers": []}'POST /listitems/disable Tiltás
Szekció neve “POST /listitems/disable Tiltás”A tétel tiltott lesz (disabled), a tétel keresése szerint (A tétel keresése). A már tiltott
tételen nem változik semmi; az anonimizált tétel 422 (ITEM_ANONYMIZED).
curl "$BASE/listitems/disable" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d '{"id": 884512}'POST /listitems/enable Feloldás
Szekció neve “POST /listitems/enable Feloldás”A tétel aktív lesz (active), bármelyik állapotból — az anonimizáltat kivéve (422, ITEM_ANONYMIZED). Az aktív
tételen nem változik semmi.
curl "$BASE/listitems/enable" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d '{"id": 884512}'A régi API-ból
Szekció neve “A régi API-ból”| Cím | Kérés | Válasz | Működés |
|---|---|---|---|
listitem/list → GET /listitems/list |
az allow_disabled helyett a status, a from_date · to_date helyett az updatedSince |
a columns helyett a values, a plusinfo helyett az extraValues, a disabled helyett a status; mellette az ügyfélfelelősök. A kontakt disabled-je a rendszer által kizárt kontaktra is true |
— |
listitem/get → GET /listitems/get |
— | mint a listában | — |
listitem/new → POST /listitems/new · POST /listitems/upsert |
a columns helyett a values; a robinson nincs; az új kontakt szám (contactNo) nélkül jön |
listitem_num → id |
a régi new a kód szerint létező tételt módosította: ez az upsert, a new a foglalt kódra hibát ad. A lejárat nélkül felvett tétel a felvétel sorrendjében kerül sorra, nem véletlen sorrendben — ha a lista a felvételkor már hozzá van rendelve a projekthez. A kontakt számát a rendszer adja |
listitem/update → POST /listitems/update |
az ismeretlen kontakt-szám (contactNo) 422 a mezőnél: új kontakt csak contactNo nélkül jön |
— | a kód nem írható át; a tiltás a disable és az enable |
listitem/history → GET /listitems/history |
— | a típus és az irány szóval, a hivatkozott rekord azonosítójával; a user_name helyett a userId |
— |
listitem/bulknew → POST /listitems/bulk |
a listitems helyett az items; a lista (listId · listCode) a kérés szintjén áll, nem tételenként: egy kérés egy listába ír; legfeljebb 1000 tétel; a robinson nincs |
a listitem_nums helyett a results: tételenként az eredmény és a hiba |
a hibás tétel nem állítja meg a kérést, akárhány hibás; kód-oszlop nélküli listára nem hívható — oda a new vesz fel |
| — | — | — | csak az újban: listitems/schema, listitems/disable, listitems/enable, az ügyfélfelelősök |