Integrációs példa

Ez az oldal egy gyakori integrációs forgatókönyvet mutat be végig: egy külső rendszer (például diszpécser, ügyfélszolgálati vagy CRM szoftver) a saját felületéről indít munkalapot egy ügyfélhez. A cél, hogy a kezelő egyetlen gombnyomással munkalapot hozzon létre az OkosMunkalapban, akkor is, ha az ügyfél ott még nem létezik, és visszakapja a munkalapszámot a saját eseménynaplójába.

A példa minden eleme az API referenciára épül; itt a végpontok együttműködését mutatjuk be.

A forgatókönyv

A külső rendszerben minden ügyfélhez tárolva van egy saját azonosító (a külső rendszer ügyfél azonosítója). A kezelő az ügyfélkártyáról vagy egy eseményből indít munkalapot. Az integrációnak ilyenkor:

1. meg kell találnia a hozzá tartozó ügyfelet az OkosMunkalapban a saját azonosító alapján,
2. ha nincs ilyen ügyfél, létre kell hoznia,
3. létre kell hoznia a munkalapot,
4. vissza kell írnia a munkalapszámot a saját eseménynaplójába,
5. később követnie kell a munkalap státuszának változását.

Ezt az OkosMunkalap egyetlen hívással támogatja (match-or-create), így a fenti 1, 2 és 3 lépés egyetlen kérés lehet.

1. A kulcs előkészítése

Hozz létre egy API kulcsot (Beállítások → Integrációk → Kulcsok) a következő beállításokkal:

• Külső rendszer azonosító (névtér): adj a kulcsnak egy rövid gépi azonosítót (pl. diszecser). Ez nyitja meg a saját névteret, amelybe a külső ügyfél azonosítók kerülnek. Lásd: Hitelesítés.
• Adat hatókör: external_system, hogy a kulcs csak a saját integrációja által kezelt ügyfeleket és munkalapokat lássa.
• Jogosultságok: customers:read, customers:create, worksheets:create. Ha a státuszt is vissza akarod írni az OkosMunkalapba, worksheets:write is. Ha a munkalapot rögtön kollégához is rendelnéd, team:read is (a felületen ez a Csapat sor).

2. Az ügyfél azonosítása saját azonosítóval

Az ügyfél azonosságának kulcsa kizárólag a külső azonosító. A külső rendszer ügyfél azonosítója az OkosMunkalapban az externalId mezőbe kerül, a kulcs névterébe.

Ha külön szeretnéd ellenőrizni, létezik-e már az ügyfél, lekérdezheted:

curl "https://api.okosmunkalap.hu/v1/customers?externalId=CUST-9001" \
  -H "Authorization: Bearer omk_live_a1b2c3d..."

A legtöbb esetben azonban erre nincs külön szükség: a munkalap indításakor a match-or-create egy lépésben elvégzi a keresést és szükség esetén a létrehozást.

3. Munkalap indítása egy lépésben (match-or-create)

A munkalap létrehozásakor a customer mezőben add meg a külső azonosítót lookupExternalId-ként, és a createIfMissing objektumban azokat az ügyféladatokat, amelyekből új ügyfél jöjjön létre, ha még nincs ilyen:

curl -X POST https://api.okosmunkalap.hu/v1/worksheets \
  -H "Authorization: Bearer omk_live_a1b2c3d..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2a9f4b1c-7e3d-4a10-9c8b-1f2e3d4c5b6a" \
  -d '{
    "customer": {
      "lookupExternalId": "CUST-9001",
      "createIfMissing": {
        "name": "Példa Kft.",
        "phone": "+36 30 123 4567",
        "address": { "fullText": "1051 Budapest, Fő utca 1." }
      }
    },
    "title": "Hibajavítás",
    "category": "Hibaelhárítás",
    "notes": "A bejelentő szerint nem működik a berendezés.",
    "siteContactName": "Kovács Anna",
    "siteContactPhone": "+36 70 222 3344",
    "customFields": { "fld_y2": "GYS-2026-114" }
  }'

Mi történik:

• Ha a CUST-9001 külső azonosítóhoz már tartozik ügyfél a kulcs névterében, a munkalap arra az ügyfélre jön létre. A válasz customerCreated: false.
• Ha nincs ilyen ügyfél, az OkosMunkalap létrehozza a createIfMissing adataiból, hozzárendeli a CUST-9001 külső azonosítót, és arra hozza létre a munkalapot. A válasz customerCreated: true.

Mindkét esetben ugyanaz a hívás, és az eredmény ugyanúgy néz ki.

Ha a külső azonosító több élő ügyfélre illeszkedik (duplikált). Ha ugyanaz az azonosító egyszerre több élő ügyfélhez tartozik (például amikor egy azonosítót felmondás után új ügyfél kap meg), a hívás 409 (EXTERNAL_ID_AMBIGUOUS) hibát ad, és nem hoz létre sem munkalapot, sem új ügyfelet (nem választ önkényesen). Ilyenkor jelezd a diszpécsernek, hogy az adott azonosító nem egyértelmű, és nem hozható létre munkalap. Amint az azonosító a forrásnál egyértelművé válik (egy azonosító egy ügyfél), a következő ugyanilyen hívás automatikusan a megfelelő ügyfélre dolgozik, külön beavatkozás nélkül.

4. A bejelentő és az ügyféltörzs szétválasztása

A bejelentő vagy értesítendő személy gyakran eltér az ügyféltörzsben tárolt kapcsolattartótól (pl. a helyszínen más személy fogadja a szerelőt). Ezt a munkalap siteContactName és siteContactPhone mezőivel kezeld:

• ezek a munkalaphoz tartoznak, nem az ügyfélhez,
• nem módosítják az ügyfél törzsadatait,
• és nem hoznak létre új ügyfelet.

Az ügyfél azonossága továbbra is kizárólag a külső azonosítón múlik, így ugyanahhoz az ügyfélhez tetszőleges számú, eltérő bejelentőjű munkalap tartozhat, duplikált ügyfél létrehozása nélkül.

5. A válasz feldolgozása

A 201 válasz tartalmazza a külső rendszer eseménynaplójába visszaírható adatokat:

{
  "data": {
    "id": "ws_abc123",
    "worksheetNumber": "ML-2026-0042",
    "status": "draft",
    "customerId": "abc123",
    "customerCreated": true,
    "url": "https://app.okosmunkalap.hu/worksheets/ws_abc123"
  }
}

• worksheetNumber: az emberi olvasásra szánt munkalapszám (pl. ML-2026-0042), amit a kezelőnek megjeleníthetsz.
• url: közvetlen hivatkozás a munkalapra az OkosMunkalap alkalmazásban.
• customerCreated: jelezheted az eseménynaplóban, hogy a hívás új ügyfelet is létrehozott.
• customerId: az OkosMunkalap belső ügyfél azonosítója, ha el akarod tárolni.

6. A munkalapszám stabil kezelése (idempotencia)

Ha a hálózati hívás időtúllépést ad, de nem tudod, létrejött-e a munkalap, ne küldd el vakon újra: ugyanazzal az Idempotency-Key fejléccel ismételd meg. Ha az első kérés sikeres volt, a második ugyanazt a munkalapot adja vissza, új munkalap létrehozása nélkül. Részletek: Idempotencia.

7. Státusz visszacsatolás

A munkalap státuszának változását kétféleképpen követheted:

• Lekérdezéssel (pull): GET /v1/worksheets/{id} vagy a GET /v1/worksheets?status=... listával.
• Webhookkal (push): az OkosMunkalap a munkalap státuszváltozásáról valós időben értesítheti a külső rendszeredet, így nem kell ismételten lekérdezned. Ehhez a kulcson állítsd be a webhook címet és a kívánt eseményeket. Részletek a payload formátumáról és az aláírás ellenőrzéséről: Webhookok.

Ha a saját rendszered státuszt is ír az OkosMunkalapba (pl. a kezelő ott zárja le a munkát), használd a PATCH /v1/worksheets/{id}/status végpontot a worksheets:write jogosultsággal.

8. Kollégához rendelés (opcionális)

Ha a diszpécser a saját rendszerében választja ki, ki menjen ki a munkára, a hozzárendelést az OkosMunkalapba is átadhatod. Így a kolléga értesítést kap, és a munkalap a saját listájában is megjelenik.

Először kérdezd le a csapattagok névsorát (ehhez team:read kell), és párosítsd a saját szerelő-törzsedhez, mert a hozzárendelés azonosítót vár, nem nevet:

curl https://api.okosmunkalap.hu/v1/team-members \
  -H "Authorization: Bearer omk_live_a1b2c3d..."

A kapott userId értékeket érdemes eltárolni a saját rendszeredben (a névsor ritkán változik, de az azonosítót ne találgasd, mindig innen vedd).

Ezután a hozzárendelést vagy már a munkalap létrehozásakor megadod (assignments mező), vagy utólag küldöd:

curl -X POST https://api.okosmunkalap.hu/v1/worksheets/ws_abc123/assign \
  -H "Authorization: Bearer omk_live_a1b2c3d..." \
  -H "Content-Type: application/json" \
  -d '{ "assignments": [ { "userId": "u_9f21ab", "role": "lead" } ] }'

A lista a kívánt végállapot, nem hozzáad: a hívás lecseréli a munkalap addigi hozzárendeléseit, az üres tömb pedig mindet törli. Ezért nyugodtan megismételhető ugyanazzal a tartalommal. A szerepköröket és a hibakezelést lásd: Hozzárendelés kollégákhoz.

Jó gyakorlatok

• Csak a szükséges jogosultságokat add a kulcsnak.
• Mindig használj Idempotency-Key-t a munkalap és ügyfél létrehozó hívásoknál.
• A code mezőre ágazz el a hibakezelésben, ne az üzenet szövegére.
• Tartsd tiszteletben a Retry-After fejlécet a 429 válaszoknál, és építs be exponenciális visszalépést.
• A külső azonosítót (externalId) következetesen használd: ez az ügyfél egyedi kulcsa a te névtéredben, és ez zárja ki a duplikációt.