Κλειδιά API και εμβέλειες

Το REST API του Ringhum επιτρέπει στα δικά σας συστήματα να συνεργάζονται με τον χώρο εργασίας σας: να καταγράφετε κλήσεις και απομαγνητοφωνήσεις, να δημιουργείτε βοηθούς, να κλείνετε ραντεβού, να διαχειρίζεστε επαφές, να πραγματοποιείτε εξερχόμενες κλήσεις και άλλα. Κάθε αίτημα αυθεντικοποιείται με ένα κλειδί API που ανήκει σε έναν χώρο εργασίας. Αυτό το άρθρο καλύπτει τη δημιουργία κλειδιών και τις συμβάσεις που μοιράζονται όλα τα endpoints. Η πλήρης αναφορά endpoints βρίσκεται στο /docs.

Ποιος μπορεί να διαχειρίζεται κλειδιά

Το API είναι διαθέσιμο σε κάθε πλάνο. Τι μπορεί να κάνει ένα κλειδί εξακολουθεί να περιορίζεται από το πλάνο σας: για παράδειγμα, η δημιουργία βοηθού πέρα από το όριο του πλάνου σας επιστρέφει σφάλμα.

Δημιουργία κλειδιού API

1. Ανοίξτε Προγραμματιστές στην πλαϊνή μπάρα.
2. Στην κάρτα Κλειδιά API, κάντε κλικ στο Δημιουργία κλειδιού.
3. Εισαγάγετε ένα Όνομα κλειδιού που δηλώνει πού χρησιμοποιείται το κλειδί, για παράδειγμα «Διακομιστής παραγωγής».
4. Στις Εμβέλειες, επιλέξτε read, write ή και τα δύο.
5. Κάντε κλικ στο Δημιουργία κλειδιού.
6. Αντιγράψτε το κλειδί από το πράσινο πλαίσιο και αποθηκεύστε το κάπου ασφαλές, όπως στο secret store του διακομιστή σας. Κάντε κλικ στο Ολοκληρώθηκε.

Σημαντικό: Το κλειδί εμφανίζεται μόνο μία φορά. Το Ringhum αποθηκεύει μόνο ένα αποτύπωμα του, γι' αυτό δεν μπορεί να εμφανιστεί ξανά. Αν το χάσετε, δημιουργήστε νέο κλειδί και ανακαλέστε το παλιό.

Τα κλειδιά ξεκινούν με ck_live_. Ο πίνακας Κλειδιά API δείχνει το όνομα κάθε κλειδιού, τους πρώτους χαρακτήρες του, τις εμβέλειές του, πότε χρησιμοποιήθηκε τελευταία φορά και αν είναι Ενεργό ή Ανακλήθηκε.

Εμβέλειες

Κάθε κλειδί μπορεί να καλεί τα endpoints που μόνο διαβάζουν. Τα endpoints που δημιουργούν, αλλάζουν ή διαγράφουν κάτι χρειάζονται την εμβέλεια write. Παραδείγματα είναι η πραγματοποίηση κλήσης, η αποστολή μηνύματος, το κλείσιμο ραντεβού ή η ενημέρωση βοηθού. Η αναφορά στο /docs επισημαίνει αυτά τα endpoints. Ένα κλειδί χωρίς write λαμβάνει σφάλμα 403 σε αυτά.

Δώστε σε κάθε σύστημα τη μικρότερη δυνατή πρόσβαση που χρειάζεται. Ένας πίνακας αναφορών χρειάζεται μόνο read.

Ανάκληση κλειδιού

1. Στη σελίδα Προγραμματιστές, βρείτε το κλειδί στον πίνακα Κλειδιά API.
2. Κάντε κλικ στο Ανάκληση και επιβεβαιώστε.

Τα αιτήματα που χρησιμοποιούν το κλειδί αποτυγχάνουν αμέσως με 401. Τα ανακληθέντα κλειδιά παραμένουν στη λίστα, σημειωμένα ως Ανακλήθηκε, ώστε να βλέπετε το ιστορικό τους. Ένα κλειδί δεν μπορεί να επεξεργαστεί: για να αλλάξετε τις εμβέλειές του, δημιουργήστε νέο κλειδί και ανακαλέστε το παλιό.

Πραγματοποίηση αιτημάτων

• Βασικό URL: https://ringhum.com/api/v1
• Αυθεντικοποίηση: στείλτε το κλειδί ως Bearer token: Authorization: Bearer ck_live_…
• Μορφή: JSON στην είσοδο και στην έξοδο. Στείλτε Content-Type: application/json με το σώμα του αιτήματος.
• Οι Ώρες είναι σε ISO 8601 σε UTC. Οι Αριθμοί τηλεφώνου είναι σε μορφή E.164, για παράδειγμα +14155550132. Τα Ids είναι ακέραιοι αριθμοί.
• Οι Ενημερώσεις χρησιμοποιούν PATCH μόνο με τα πεδία που θέλετε να αλλάξετε.
• Κάθε απόκριση φέρει μια κεφαλίδα X-Request-Id. Συμπεριλάβετέ τη όταν επικοινωνείτε με την υποστήριξη.

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

Για να ελέγξετε σε ποιον χώρο εργασίας ανήκει ένα κλειδί, καλέστε GET /me.

Αποκρίσεις και σελιδοποίηση

Ένα μεμονωμένο αντικείμενο επιστρέφει ως {"data": {…}}. Οι λίστες με σελιδοποίηση επιστρέφουν με ένα αντικείμενο 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
  }
}

Χρησιμοποιήστε page και per_page για να μετακινηθείτε στα αποτελέσματα. Το per_page έχει προεπιλογή 25 και μπορεί να φτάσει έως 100.

Σφάλματα

Κάθε αποτυχία έχει την ίδια μορφή, με σταθερό type που μπορείτε να ελέγξετε στον κώδικά σας:

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

Όρια ρυθμού

Μπορείτε να κάνετε 120 αιτήματα ανά λεπτό. Οι αποκρίσεις περιλαμβάνουν κεφαλίδες X-RateLimit-Limit και X-RateLimit-Remaining. Όταν υπερβείτε το όριο λαμβάνετε 429 με κεφαλίδα Retry-After που δίνει τα δευτερόλεπτα αναμονής.

Συμβουλή: Μην κάνετε polling για αποτελέσματα κλήσεων. Προσθέστε ένα webhook για το call.ended και το Ringhum σάς στέλνει τη σύνοψη και την απομαγνητοφώνηση όταν η κλήση ολοκληρωθεί. Δείτε Webhooks.

Συχνές ερωτήσεις

Υπάρχει προδιαγραφή αναγνώσιμη από μηχανή; Ναι. Η περιγραφή OpenAPI 3.1 βρίσκεται στο /api/v1/openapi.json και δεν χρειάζεται κλειδί. Μπορείτε να δημιουργήσετε client από αυτήν.

Σταματά να λειτουργεί ένα κλειδί αν το άτομο που το δημιούργησε φύγει; Όχι. Τα κλειδιά ανήκουν στον χώρο εργασίας και συνεχίζουν να λειτουργούν έως ότου ανακληθούν. Ανακαλέστε κλειδιά που δεν εμπιστεύεστε πλέον, ειδικά όταν κάποιος με πρόσβαση αποχωρεί.

Μπορώ να χρησιμοποιήσω το API από μια ιστοσελίδα; Όχι. Οποιοσδήποτε ανοίξει τη σελίδα θα μπορούσε να διαβάσει το κλειδί. Καλέστε το API από τον διακομιστή σας.