API-kulcsok és jogkörök

A Ringhum REST API lehetővé teszi, hogy saját rendszerei együttműködjenek a munkaterületével: hívásokat és átiratokat listázhat, asszisztenseket hozhat létre, időpontokat foglalhat, kapcsolatokat kezelhet, kimenő hívásokat indíthat és sok minden mást. Minden kérést egy API-kulcs hitelesít, amely egy munkaterülethez tartozik. Ez a cikk a kulcsok létrehozását és a minden végponton érvényes konvenciókat mutatja be. A teljes végpont-referencia a /docs oldalon található.

Ki kezelheti a kulcsokat

Az API minden csomagban elérhető. Hogy egy kulcs mit tehet, azt továbbra is korlátozza a csomagja: például ha a csomag limitjén felül próbál asszisztenst létrehozni, hibaüzenetet kap.

API-kulcs létrehozása

1. Nyissa meg a Fejlesztők menüpontot az oldalsávon.
2. Az API-kulcsok kártyán kattintson a Kulcs létrehozása gombra.
3. Adjon meg egy Kulcs neve mezőt, amely elárulja, hol használja a kulcsot, például „Éles szerver”.
4. A Jogkörök alatt jelölje be a read, write vagy mindkettő lehetőséget.
5. Kattintson a Kulcs létrehozása gombra.
6. Másolja ki a kulcsot a zöld dobozból, és tárolja biztonságos helyen, például a szerver titkosítótárában. Kattintson a Kész gombra.

Fontos: A kulcs csak egyszer jelenik meg. A Ringhum csak egy ujjlenyomatot tárol róla, így az nem jeleníthető meg újra. Ha elveszíti, hozzon létre egy új kulcsot, és vonja vissza a régit.

A kulcsok ck_live_ előtaggal kezdődnek. Az API-kulcsok táblázat minden kulcsnál mutatja a nevét, a kulcs első karaktereit, a jogköreit, az utolsó használat idejét, valamint hogy Aktív vagy Visszavonva állapotú-e.

Jogkörök

Minden kulcs meghívhatja azokat a végpontokat, amelyek csak olvasnak. Azoknak a végpontoknak, amelyek létrehoznak, módosítanak vagy törölnek valamit, write jogkör kell. Ilyen például hívás indítása, üzenet küldése, időpont foglalása vagy egy asszisztens frissítése. A /docs oldalon található referencia megjelöli ezeket a végpontokat. Egy write jogkör nélküli kulcs ezeken 403 hibát kap.

Minden rendszernek adja meg a lehető legkisebb hozzáférést, amire szüksége van. Egy jelentéskészítő irányítópultnak csak read jogkör kell.

Kulcs visszavonása

1. A Fejlesztők oldalon keresse meg a kulcsot az API-kulcsok táblázatban.
2. Kattintson a Visszavonás gombra, és erősítse meg.

A kulcsot használó kérések azonnal 401 hibával meghiúsulnak. A visszavont kulcsok a listában maradnak, Visszavonva jelöléssel, így láthatja az előzményeiket. Egy kulcs nem szerkeszthető: a jogköreinek módosításához hozzon létre egy új kulcsot, és vonja vissza a régit.

Kérések küldése

• Alap URL: https://ringhum.com/api/v1
• Hitelesítés: küldje a kulcsot Bearer tokenként: Authorization: Bearer ck_live_…
• Formátum: JSON be- és kimenetnél. Küldjön Content-Type: application/json fejlécet a törzzsel.
• Az időpontok ISO 8601 formátumúak, UTC időben. A telefonszámok E.164 formátumúak, például +14155550132. Az azonosítók egész számok.
• A frissítések PATCH metódust használnak, csak a módosítani kívánt mezőkkel.
• Minden válasz tartalmaz egy X-Request-Id fejlécet. Ezt adja meg, amikor kapcsolatba lép az ügyfélszolgálattal.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

Ahhoz, hogy ellenőrizze, melyik munkaterülethez tartozik egy kulcs, hívja meg a GET /me végpontot.

Válaszok és lapozás

Egyetlen objektum {"data": {…}} formában érkezik vissza. A lapozott listák egy meta objektummal térnek vissza:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Használja a page és per_page paramétereket az eredmények közötti mozgáshoz. A per_page alapértelmezett értéke 25, és legfeljebb 100 lehet.

Hibák

Minden hiba ugyanazt a formát követi, egy stabil type mezővel, amelyet a kódjában ellenőrizhet:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Sebességkorlátok

Percenként 120 kérést küldhet. A válaszok tartalmaznak X-RateLimit-Limit és X-RateLimit-Remaining fejléceket. Ha túllépi a korlátot, 429 hibát kap egy Retry-After fejléccel, amely megadja a várakozási időt másodpercben.

Tipp: Ne kérdezze le folyamatosan a hívások eredményét. Adjon hozzá egy webhookot a call.ended eseményhez, és a Ringhum elküldi Önnek az összefoglalót és az átiratot, amikor a hívás véget ért. Lásd: Webhookok.

Gyakori kérdések

Van gépileg olvasható specifikáció? Igen. Az OpenAPI 3.1 leírás a /api/v1/openapi.json címen található, és nem igényel kulcsot. Ebből klienst is generálhat.

Leáll egy kulcs működni, ha az azt létrehozó személy távozik? Nem. A kulcsok a munkaterülethez tartoznak, és addig működnek, amíg vissza nem vonják őket. Vonja vissza azokat a kulcsokat, amelyekben már nem bízik, különösen ha valaki, akinek hozzáférése volt, távozik.

Használhatom az API-t egy weboldalról? Nem. Bárki, aki megnyitja az oldalt, elolvashatná a kulcsot. Az API-t a szerveréről hívja meg.