API klíče a oprávnění

REST API Ringhum umožňuje vašim vlastním systémům pracovat s vaším pracovním prostorem: vypisovat hovory a přepisy, vytvářet asistenty, rezervovat termíny, spravovat kontakty, uskutečňovat odchozí hovory a další. Každý požadavek je ověřen API klíčem, který patří jednomu pracovnímu prostoru. Tento článek popisuje vytváření klíčů a zvyklosti společné každému koncovému bodu. Úplná dokumentace koncových bodů je na /docs.

Kdo může spravovat klíče

API je dostupné v každém tarifu. To, co klíč umí, je stále omezeno vaším tarifem: například vytvoření asistenta nad rámec limitu tarifu vrátí chybu.

Vytvoření API klíče

1. V postranním panelu otevřete Vývojáři.
2. Na kartě API klíče klikněte na Vytvořit klíč.
3. Zadejte Název klíče, který vypovídá o tom, kde se klíč používá, například „Produkční server“.
4. V sekci Oprávnění zaškrtněte read, write, nebo obojí.
5. Klikněte na Vytvořit klíč.
6. Zkopírujte klíč ze zeleného boxu a uložte jej na bezpečném místě, například v tajném úložišti svého serveru. Klikněte na Hotovo.

Důležité: Klíč se zobrazí jen jednou. Ringhum ukládá pouze jeho otisk, takže jej nelze znovu zobrazit. Pokud jej ztratíte, vytvořte nový klíč a starý odvolejte.

Klíče začínají na ck_live_. Tabulka API klíče zobrazuje u každého klíče jeho název, první znaky klíče, jeho oprávnění, kdy byl naposledy použit a zda je Aktivní, nebo Odvoláno.

Oprávnění

Každý klíč umí volat koncové body, které jen čtou. Koncové body, které něco vytvářejí, mění nebo mažou, vyžadují oprávnění write. Příkladem je uskutečnění hovoru, odeslání zprávy, rezervace termínu nebo úprava asistenta. Dokumentace na /docs tyto koncové body označuje. Klíč bez write na nich dostane chybu 403.

Každému systému dejte jen nejmenší přístup, který potřebuje. Reportovací přehled potřebuje jen read.

Odvolání klíče

1. Na stránce Vývojáři najděte klíč v tabulce API klíče.
2. Klikněte na Odvolat a potvrďte.

Požadavky s tímto klíčem okamžitě selžou s 401. Odvolané klíče zůstávají v seznamu, označené jako Odvoláno, takže vidíte jejich historii. Klíč nelze upravovat: chcete-li změnit jeho oprávnění, vytvořte nový klíč a starý odvolejte.

Odesílání požadavků

• Základní URL: https://ringhum.com/api/v1
• Ověřování: odešlete klíč jako Bearer token: Authorization: Bearer ck_live_…
• Formát: JSON na vstupu i výstupu. S tělem odešlete Content-Type: application/json.
• Časy jsou ve formátu ISO 8601 v UTC. Telefonní čísla jsou ve formátu E.164, například +14155550132. Id jsou celá čísla.
• Aktualizace používají PATCH jen s poli, která chcete změnit.
• Každá odpověď nese hlavičku X-Request-Id. Uveďte ji, když kontaktujete podporu.

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

Chcete-li zjistit, kterému pracovnímu prostoru klíč patří, zavolejte GET /me.

Odpovědi a stránkování

Jeden objekt se vrací jako {"data": {…}}. Stránkované seznamy se vrací s objektem meta:

{
  "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
  }
}

K procházení výsledků použijte page a per_page. per_page má výchozí hodnotu 25 a maximálně 100.

Chyby

Každé selhání má stejný tvar se stálým type, který můžete ve svém kódu ověřit:

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

Limity počtu požadavků

Můžete uskutečnit 120 požadavků za minutu. Odpovědi obsahují hlavičky X-RateLimit-Limit a X-RateLimit-Remaining. Při překročení limitu dostanete 429 s hlavičkou Retry-After, která udává počet sekund čekání.

Tip: Nedotazujte se opakovaně na výsledky hovoru. Přidejte webhook pro call.ended a Ringhum vám po skončení hovoru odešle shrnutí a přepis. Viz Webhooky.

Časté dotazy

Existuje strojově čitelná specifikace? Ano. Popis OpenAPI 3.1 je na /api/v1/openapi.json a nevyžaduje klíč. Můžete z něj vygenerovat klienta.

Přestane klíč fungovat, pokud osoba, která jej vytvořila, odejde? Ne. Klíče patří pracovnímu prostoru a fungují dál, dokud nejsou odvolány. Odvolejte klíče, kterým už nedůvěřujete, zejména když někdo s přístupem odejde.

Mohu použít API z webové stránky? Ne. Kdokoli, kdo stránku otevře, by mohl klíč přečíst. Volejte API ze svého serveru.