Tovább a tartalomhoz
ADERTISADERTISConnect

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
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 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.

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:

Kérésapplication/json
{ "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.

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 contactNo nélküli kontakt új, a számát a rendszer adja;
  • a contactNo-val és delete: 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 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.

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
Válasz 200application/json
{
"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
Terminál
curl "$BASE/listitems/list?listCode=KAMP-2026-10&updatedSince=2026-10-19T00:00:00" -H "X-API-Key: $API_KEY"

A tétel a lista mezőivel.

Terminál
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
Válasz 200application/json
{
"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"
}
]
}
Terminál
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.

Terminál
curl "$BASE/listitems/schema" -H "X-API-Key: $API_KEY"

Ú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.

Kérésapplication/json
{
"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
Válasz 201application/json
{ "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
Terminá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
Terminá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.

Kérésapplication/json
{
"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.

Válasz 200application/json
{
"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
Terminál
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.

Kérésapplication/json
{
"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)
Terminál
curl "$BASE/listitems/update" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
-d '{"id": 884512, "handlers": []}'

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).

Terminál
curl "$BASE/listitems/disable" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d '{"id": 884512}'

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.

Terminál
curl "$BASE/listitems/enable" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d '{"id": 884512}'
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