Chei API și domenii de acces

API-ul REST Ringhum permite propriilor dumneavoastră sisteme să interacționeze cu spațiul de lucru: să listeze apeluri și transcrieri, să creeze asistenți, să facă programări, să gestioneze contacte, să efectueze apeluri de ieșire și multe altele. Fiecare solicitare este autentificată cu o cheie API care aparține unui singur spațiu de lucru. Acest articol acoperă crearea cheilor și convențiile comune tuturor punctelor finale (endpoints). Referința completă a punctelor finale se află la /docs.

Cine poate gestiona cheile

API-ul este disponibil pe fiecare plan. Ce poate face o cheie rămâne totuși limitat de planul dumneavoastră: de exemplu, crearea unui asistent peste limita planului dumneavoastră returnează o eroare.

Creați o cheie API

1. Deschideți Dezvoltatori din bara laterală.
2. În cardul Chei API, faceți clic pe Creează cheie.
3. Introduceți un Numele cheii care indică unde este folosită cheia, de exemplu „Server de producție”.
4. La Domenii de acces, bifați read, write sau ambele.
5. Faceți clic pe Creează cheie.
6. Copiați cheia din caseta verde și păstrați-o într-un loc sigur, cum ar fi spațiul de stocare a secretelor de pe serverul dumneavoastră. Faceți clic pe Gata.

Important: Cheia este afișată o singură dată. Ringhum stochează doar o amprentă a acesteia, așa că nu mai poate fi afișată din nou. Dacă o pierdeți, creați o cheie nouă și revocați-o pe cea veche.

Cheile încep cu ck_live_. Tabelul Chei API afișează numele fiecărei chei, primele caractere ale cheii, domeniile sale de acces, ultima utilizare și dacă este Activ sau Revocat.

Domenii de acces

Orice cheie poate apela punctele finale care doar citesc date. Punctele finale care creează, modifică sau șterg ceva necesită domeniul write. Exemple sunt efectuarea unui apel, trimiterea unui mesaj, realizarea unei programări sau actualizarea unui asistent. Referința de la /docs marchează aceste puncte finale. O cheie fără write primește o eroare 403 la aceste apeluri.

Oferiți fiecărui sistem cel mai mic acces de care are nevoie. Un tablou de bord pentru rapoarte are nevoie doar de read.

Revocați o cheie

1. În Dezvoltatori, găsiți cheia în tabelul Chei API.
2. Faceți clic pe Revocă și confirmați.

Solicitările care folosesc cheia eșuează imediat cu 401. Cheile revocate rămân în listă, marcate Revocat, astfel încât să le puteți vedea istoricul. O cheie nu poate fi editată: pentru a-i schimba domeniile de acces, creați o cheie nouă și revocați-o pe cea veche.

Efectuarea solicitărilor

• URL de bază: https://ringhum.com/api/v1
• Autentificare: trimiteți cheia ca token Bearer: Authorization: Bearer ck_live_…
• Format: JSON la intrare și la ieșire. Trimiteți Content-Type: application/json cu un corp de cerere.
• Orele sunt în format ISO 8601, UTC. Numerele de telefon sunt în format E.164, de exemplu +14155550132. ID-urile sunt numere întregi.
• Actualizările folosesc PATCH doar cu câmpurile pe care doriți să le modificați.
• Fiecare răspuns conține un antet X-Request-Id. Includeți-l atunci când contactați asistența.

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

Pentru a verifica cărui spațiu de lucru îi aparține o cheie, apelați GET /me.

Răspunsuri și paginare

Un singur obiect este returnat ca {"data": {…}}. Listele paginate sunt returnate cu un obiect 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
  }
}

Folosiți page și per_page pentru a parcurge rezultatele. per_page are valoarea implicită 25 și poate fi cel mult 100.

Erori

Fiecare eroare are aceeași structură, cu un type stabil pe care îl puteți verifica în codul dumneavoastră:

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

Limite de rată

Puteți face 120 de solicitări pe minut. Răspunsurile includ anteturile X-RateLimit-Limit și X-RateLimit-Remaining. Când depășiți limita, primiți 429 cu un antet Retry-After care indică numărul de secunde de așteptare.

Sfat: Nu interogați repetat rezultatele apelurilor. Adăugați un webhook pentru call.ended, iar Ringhum vă trimite rezumatul și transcrierea imediat ce apelul s-a încheiat. Consultați Webhooks.

Întrebări frecvente

Există o specificație citibilă automat? Da. Descrierea OpenAPI 3.1 se află la /api/v1/openapi.json și nu necesită nicio cheie. Puteți genera un client pornind de la ea.

O cheie încetează să mai funcționeze dacă persoana care a creat-o pleacă? Nu. Cheile aparțin spațiului de lucru și continuă să funcționeze până sunt revocate. Revocați cheile în care nu mai aveți încredere, mai ales când cineva care avea acces pleacă.

Pot folosi API-ul dintr-o pagină web? Nu. Oricine deschide pagina ar putea citi cheia. Apelați API-ul de pe serverul dumneavoastră.