Klucze API i uprawnienia

REST API Ringhum pozwala Twoim własnym systemom współpracować z Twoją przestrzenią roboczą: wyświetlać listy połączeń i transkrypcji, tworzyć asystentów, umawiać wizyty, zarządzać kontaktami, wykonywać połączenia wychodzące i wiele więcej. Każde żądanie jest uwierzytelniane kluczem API należącym do jednej przestrzeni roboczej. Ten artykuł opisuje tworzenie kluczy oraz konwencje wspólne dla wszystkich punktów końcowych. Pełna dokumentacja punktów końcowych znajduje się pod adresem /docs.

Kto może zarządzać kluczami

API jest dostępne w każdym planie. To, co może zrobić klucz, nadal ogranicza Twój plan: na przykład utworzenie asystenta ponad limit planu zwraca błąd.

Utwórz klucz API

1. Otwórz Deweloperzy w pasku bocznym.
2. W karcie Klucze API kliknij Utwórz klucz.
3. Wpisz Nazwę klucza, która mówi, gdzie klucz jest używany, na przykład „Serwer produkcyjny”.
4. W sekcji Uprawnienia zaznacz read, write lub oba.
5. Kliknij Utwórz klucz.
6. Skopiuj klucz z zielonego pola i zapisz go w bezpiecznym miejscu, na przykład w magazynie sekretów Twojego serwera. Kliknij Gotowe.

Ważne: Klucz jest pokazywany tylko raz. Ringhum przechowuje jedynie jego odcisk, więc nie można go pokazać ponownie. Jeśli go zgubisz, utwórz nowy klucz i unieważnij stary.

Klucze zaczynają się od ck_live_. Tabela Klucze API pokazuje nazwę każdego klucza, pierwsze znaki klucza, jego uprawnienia, datę ostatniego użycia oraz to, czy jest Aktywny, czy Odwołany.

Uprawnienia

Każdy klucz może wywoływać punkty końcowe, które tylko odczytują dane. Punkty końcowe, które tworzą, zmieniają lub usuwają coś, wymagają uprawnienia write. Przykłady to wykonanie połączenia, wysłanie wiadomości, umówienie wizyty czy aktualizacja asystenta. Dokumentacja pod adresem /docs oznacza te punkty końcowe. Klucz bez uprawnienia write otrzyma na nich błąd 403.

Nadaj każdemu systemowi najmniejszy potrzebny dostęp. Panel raportowania potrzebuje jedynie uprawnienia read.

Unieważnij klucz

1. Na stronie Deweloperzy znajdź klucz w tabeli Klucze API.
2. Kliknij Odwołaj i potwierdź.

Żądania korzystające z tego klucza natychmiast kończą się błędem 401. Odwołane klucze pozostają na liście, oznaczone jako Odwołany, dzięki czemu widać ich historię. Klucza nie można edytować: aby zmienić jego uprawnienia, utwórz nowy klucz i unieważnij stary.

Wysyłanie żądań

• Adres bazowy: https://ringhum.com/api/v1
• Uwierzytelnianie: wyślij klucz jako token Bearer: Authorization: Bearer ck_live_…
• Format: JSON na wejściu i wyjściu. Przy wysyłaniu treści dołącz Content-Type: application/json.
• Czas jest w formacie ISO 8601 w UTC. Numery telefonów w formacie E.164, na przykład +14155550132. Identyfikatory są liczbami całkowitymi.
• Aktualizacje używają metody PATCH tylko z polami, które chcesz zmienić.
• Każda odpowiedź zawiera nagłówek X-Request-Id. Podaj go, kontaktując się z pomocą techniczną.

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

Aby sprawdzić, do której przestrzeni roboczej należy klucz, wywołaj GET /me.

Odpowiedzi i paginacja

Pojedynczy obiekt zwracany jest jako {"data": {…}}. Listy z paginacją zwracane są wraz z obiektem 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
  }
}

Użyj page i per_page, aby przechodzić przez wyniki. per_page domyślnie wynosi 25 i może wynosić maksymalnie 100.

Błędy

Każdy błąd ma taką samą strukturę, ze stałym polem type, które możesz sprawdzić w swoim kodzie:

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

Limity zapytań

Możesz wykonać 120 żądań na minutę. Odpowiedzi zawierają nagłówki X-RateLimit-Limit i X-RateLimit-Remaining. Po przekroczeniu limitu otrzymasz błąd 429 z nagłówkiem Retry-After, podającym liczbę sekund do odczekania.

Wskazówka: Nie odpytuj serwera o wyniki połączeń. Dodaj webhook dla call.ended, a Ringhum wyśle Ci podsumowanie i transkrypcję po zakończeniu połączenia. Zobacz Webhooki.

Najczęstsze pytania

Czy istnieje specyfikacja czytelna maszynowo? Tak. Opis OpenAPI 3.1 znajduje się pod adresem /api/v1/openapi.json i nie wymaga klucza. Możesz na jego podstawie wygenerować klienta.

Czy klucz przestaje działać, gdy osoba, która go utworzyła, odejdzie? Nie. Klucze należą do przestrzeni roboczej i działają, dopóki nie zostaną odwołane. Odwołuj klucze, którym już nie ufasz, zwłaszcza gdy osoba mająca dostęp odchodzi.

Czy mogę korzystać z API ze strony internetowej? Nie. Każdy, kto otworzy tę stronę, mógłby odczytać klucz. Wywołuj API z poziomu swojego serwera.