Áttekintés

Az API HTTPS-en, JSON-nal szolgál ki; minden kérés az API-kulccsal lép be. A mezők neve és az értékek szabálya: Mezők és értékek.

A cím

https://connect.adertis.hu/{ügyfélkód}/api/{entitás}/{művelet}

Rész	Mi
{ügyfélkód}	az ADERTIS helpdesktől kapott egyedi ügyfélkód
{entitás}	az adat fajtája: users, projects, lists, listitems, interviews, calls, emails, sms, cases, monitor, stats, activity — a hívásindításé dial
{művelet}	a lenti műveletek közül egy, vagy az entitás saját művelete (calls/last, dial/ivr)

A művelet az URL utolsó tagja, nem a HTTP-metódus.

A példák

A lapok curl-példái két változót használnak:

BASE=https://connect.adertis.hu/acme/api   # az acme helyén az ügyfélkód
API_KEY=adc_…                               # a kiadott kulcs

Az API-kulcs

Minden kérés az X-API-Key fejlécben viszi a kulcsot; a query-stringben nem fogadjuk.

curl "$BASE/users/list" -H "X-API-Key: $API_KEY"

A kulcs csak a kiadásakor megadott IP-címekről használható: az igénylésekor add meg, honnan hívod az API-t.

A kulcs jogai szabják meg, mit hívhat: a művelethez szükségeset az entitás lapja mutatja (Jog oszlop). Egyes mezők írásához a művelet joga mellett külön jog is kell: a mezőtábla a mező leírásában jelzi (jog: …). Jog nélkül a válasz 403, hibás kulcsra 401 — Hibák.

A műveletek

Az entitások ugyanezeket a műveleteket kínálják, ahol értelmük van. A jel színe a művelet hatása: olvas, létrehoz vagy módosít.

Művelet	Mit tesz
GET /{entitás}/list	lista, a szűrők a query-stringben
GET /{entitás}/get	egy elem, ?id= vagy ?code= szerint
GET /{entitás}/schema	a mezők leírása: típus, hossz, kötelező-e, választható értékek
POST /{entitás}/new	új elem
POST /{entitás}/upsert	code szerint felvesz vagy módosít
POST /{entitás}/update	módosítás — csak a küldött mezők, updateMask-kal a felsoroltak változnak
POST /{entitás}/disable	tiltás
POST /{entitás}/enable	feloldás

Hogy egy entitásnál melyik hívható, és milyen saját művelete van, azt az entitás lapja mondja meg — az oldalsávban, témánként csoportosítva.

id és code

Mező	Mi
id	belső azonosító: a rendszer adja, szám
code	külső azonosító: az ügyfél rendszerének kódja, szöveg

A get, az update, a disable és az enable az elemet az egyikkel keresi. Ha mindkettő jön, az id dönt — az update-ben ilyenkor a code már az új érték: így írható át a kód. Ha egyik sem jön, a válasz 400; az ismeretlen id és code 404-et ad. A code nem mindig egyedi: ha több elemen áll, a válasz 422 (AMBIGUOUS) — akkor az id-vel keress. A más elemre mutató kód (például projectCode) ugyanígy; a lista szűrőjében a több elemre illő kód 400.

A kérés

• Olvasás: GET, a paraméterek a query-stringben — users/get?id=42. POST-tal is mehet, a paraméterek akkor a törzsben. Ha a keresés személyes adatot tartalmaz (például ügyfélszámot), így küldd: a cím naplókba kerülhet.
• Írás: POST, a mezők JSON-objektumként a törzsben, Content-Type: application/json fejléccel. A lapos mezők form-alakban is jöhetnek (application/x-www-form-urlencoded); a tömb csak JSON-ban. Query-stringet az írás nem fogad: a válasz 400. Más metódusra a válasz 405, más törzsre 415.
• A szöveg UTF-8.

A válasz

A siker jele a 2xx-es HTTP-státusz: 200, az új elemre 201, az elindított hívásra 202.

Művelet	Válasz
list	{ "users": [ … ], "hasMore": false } — a kulcs az entitás neve; lapozva, A lapozás szerint
get	az elem, a gyökérben
new, upsert	az elem azonosítója: { "id": 57 } — új elemnél 201, és a Location fejléc a get-jére mutat; az upsert módosításánál 200
update és a többi	{}, ha a művelet mást nem ad

A hiba alakja: Hibák.

A lapozás

A list azonosító szerint, lapokban adja az elemeket:

Paraméter	Típus	Leírás
limit	integer	a lap legfeljebb ennyi elemet ad, 1–5000; alapból 1000
after	integer	az előző lap utolsó id-je; elhagyva az első lap jön
updatedSince	string	csak az ennél nem korábban módosult elemek — ahol a mezőtáblában van updatedAt; az időpont alakja: Dátum

A válasz hasMore-ja true, ha van még elem: a következő lapot a mostani utolsó id-jével kérd.

curl "$BASE/users/list?limit=100&after=42" -H "X-API-Key: $API_KEY"

A változások követése: jegyezd meg a kérés idejét, és legközelebb azzal kérdezz (updatedSince). Ugyanazt az elemet megkaphatod kétszer, de egyet sem veszítesz el; a törölt elem nem jön.

A mezők leírása

A schema élőben írja le az entitás mezőit: a választható értékek a rendszer mostani adatai. Paramétere nincs. Részlet a users/schema válaszából:

Válasz 200application/json

{
  "type": "object",
  "required": ["login", "name"],
  "properties": {
    "id": { "type": "integer", "title": "ID", "readOnly": true },
    "login": { "type": "string", "title": "Login name", "minLength": 8, "maxLength": 40, "writeOnly": true },
    "roleId": {
      "type": "integer",
      "title": "Role",
      "options": [
        { "id": 5, "title": "Operátor" },
        { "id": 7, "title": "Felügyelő" }
      ]
    },
    "roleName": { "type": "string", "title": "Role name" },
    "disabled": { "type": "boolean", "title": "Disabled" },
    "status": { "type": "string", "title": "Status", "description": "active · disabled · locked", "readOnly": true }
  }
}

Kulcs	Mi
required	a new kötelező mezői
readOnly	csak a válaszban jön — Az értékek
writeOnly	csak a kérésben küldhető
options	a választható értékek: id — ezt kell küldeni —, title — a felirata

Az entitás lapjának mezőtáblája ugyanezt jelzi (kötelező · csak olvasható · csak írható).

A módosítás: csak a küldött mező

Az update csak a törzsben küldött mezőket írja, a többi nem változik — a teljes elemet nem kell visszaküldeni. A kihagyott, a null és az üres értékű mező szabálya: Az értékek.

Az updateMask

Az update törzsében az updateMask sorolja a módosítandó mezőket: vesszővel elválasztva ("note,expiresAt") vagy tömbként. Vele csak a felsorolt mezők íródnak:

Mező	updateMask-kal
felsorolva, értékkel	íródik
felsorolva, kihagyva vagy null	ürül, mint az üres értékkel — a kötelező mező nem üríthető
nincs felsorolva	nem változik, akkor sem, ha a törzsben jön — a csak olvasható sem hiba, így a get válasza egy mező átírásával visszaküldhető

A tömb-mező egészében íródik; ahol nem, az entitás lapja mondja. A felsorolt ismeretlen vagy csak olvasható mező 400. A new és az upsert nem fogad updateMask-ot.

A listitems tétel megjegyzése „VIP” lesz, a lejárata ürül, a többi mezője nem változik:

Kérésapplication/json

{ "id": 812, "updateMask": "note,expiresAt", "note": "VIP" }

A tiltás

• A disable tilt, az enable felold. A már tiltott, illetve az aktív elemen nem változik semmi.
• A disabled mező ugyanezt teszi: a new-ban a true tiltva veszi fel az elemet, az update-ben a true tilt, a false felold. Az írásához ugyanaz a jog kell, mint a disable-höz.
• Tiltott elemet csak a feloldással együtt lehet módosítani: küldd mellé a disabled: false-t. Nélküle a válasz 409 (DISABLED_EDIT).

Új mezők és értékek

Új entitás, művelet, mező, választható érték és hibakód jöhet; a változásokat a Változások lap sorolja. A kliens:

• a válasz ismeretlen mezőjét és ismeretlen választható értékét figyelmen kívül hagyja;
• az ismeretlen hibakódot a HTTP-státusza szerint kezeli.

Meglévő elem nem változik és nem szűnik meg előzetes jelzés nélkül. Az elavult művelet vagy mező hívására a válasz Deprecation fejlécet kap (RFC 9745), és ha már tudni, meddig él, Sunset-et is (RFC 8594); a helyette valót a Változások lap „Elavul” sora mondja meg.