Επισκόπηση API

Κάθε REST endpoint του RolChat ακολουθεί ένα ενιαίο συμβόλαιο: το ίδιο βασικό URL, τον ίδιο φάκελο απόκρισης, την ίδια σελιδοποίηση, την ίδια μορφή σφαλμάτων. Μάθετέ το μία φορά και κάθε οικογένεια endpoints στην αναφορά endpoints διαβάζεται με τον ίδιο τρόπο.

Βασικό URL και εκδόσεις

https://api.rolchat.com/api/v1/

Η έκδοση βρίσκεται στη διαδρομή. Η προσθήκη προαιρετικών πεδίων, νέων endpoints ή νέων παραμέτρων query με προεπιλεγμένες τιμές δεν αποτελεί αλλαγή που σπάει τη συμβατότητα και δεν αυξάνει την έκδοση. Οι αλλαγές που σπάνε τη συμβατότητα κυκλοφορούν ως v2 και τα καταργημένα endpoints του v1 συνεχίζουν να λειτουργούν για τουλάχιστον έξι μήνες μετά την ανακοίνωσή τους (δείτε Κατάργηση).

Έλεγχος ταυτότητας

Μέθοδος	Κεφαλίδα	Χρήση
JWT bearer	`Authorization: Bearer <access_token>`	Διαδραστικές συνεδρίες (η web εφαρμογή, οι εφαρμογές για κινητά)
Κλειδί API	`Authorization: Bearer rcp_<secret>`	Κλήσεις μεταξύ συστημάτων, κλειδιά API plugins
Υπογραφή HMAC	`X-RolChat-Signature: sha256=…`	Εισερχόμενα webhooks από τα συστήματά σας, δείτε Webhooks
Κανένας	-	Δημόσια endpoints του widget (`/widget/…`, `/forms/…`), με εμβέλεια ανά ιστότοπο και origin

Για ενσωματώσεις χρησιμοποιήστε κλειδί API (προσωπικό token πρόσβασης). Τα κλειδιά δημιουργούνται στις Ρυθμίσεις → Plugins → Κλειδιά API του RolChat, εμφανίζονται μία φορά και αποθηκεύονται μόνο ως hash. Ένα κλειδί δεν μπορεί ποτέ να κάνει περισσότερα από το μέλος που το δημιούργησε: τα scopes του ελέγχονται σε κάθε κλήση έναντι των τρεχόντων δικαιωμάτων αυτού του μέλους. Δείτε Έλεγχος ταυτότητας για τη διάρκεια ζωής των JWT, την κεφαλίδα X-Account-Id και τις συνεδρίες πολλών εταιρειών.

Φάκελος απόκρισης

Ένας μεμονωμένος πόρος:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

Μια λίστα:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

Οι αποκρίσεις χωρίς σώμα (204 No Content μετά από διαγραφή) εξακολουθούν να φέρουν την κεφαλίδα X-Request-Id.

Ένα σφάλμα:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

Το code είναι αναγνώσιμο από μηχανή σε snake_case και είναι η τιμή βάσει της οποίας διακλαδώνετε τη λογική σας· το message είναι στα αγγλικά και προορίζεται για τα logs. Τα field και details υπάρχουν όταν βοηθούν και δεν περιέχουν ποτέ προσωπικά δεδομένα. Το API δεν απαντά ποτέ 200 με πίνακα errors: αν υπάρχουν σφάλματα, η κατάσταση είναι 400 ή μεγαλύτερη. Η πλήρης λίστα κωδικών βρίσκεται στη σελίδα Σφάλματα.

Σελιδοποίηση

Τα endpoints λιστών που μπορούν να μεγαλώσουν χρησιμοποιούν σελιδοποίηση με cursor. Ζητήστε την πρώτη σελίδα χωρίς cursor και έπειτα επιστρέψτε αυτούσιο το next_cursor που λάβατε:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

Το limit έχει προεπιλογή 50 και ανώτατο όριο 200· μεγαλύτερες τιμές απορρίπτονται με 400 validation_failed.
Οι cursors είναι αδιαφανείς και λήγουν μετά από 24 ώρες (400 validation_failed με code: cursor_expired).
Τα αποτελέσματα είναι συνεπή ως προς το στιγμιότυπο που λήφθηκε στην πρώτη σελίδα: οι εγγραφές που διαγράφονται μεταξύ σελίδων εξαφανίζονται, οι νέες εγγραφές εμφανίζονται μόνο όταν ξεκινήσετε ξανά χωρίς cursor.
Αποστέλλεται επίσης κεφαλίδα Link με rel="next" και rel="prev" για πελάτες που την προτιμούν.

Idempotency

Στείλτε κεφαλίδα Idempotency-Key (ένα UUID ή ULID, έως 255 χαρακτήρες) με οποιοδήποτε POST, PATCH ή DELETE:

Το πρώτο αίτημα με ένα κλειδί εκτελείται και η κατάσταση και το σώμα του αποθηκεύονται για 24 ώρες.
Μια επανάληψη με το ίδιο κλειδί και το ίδιο σώμα επιστρέφει την αποθηκευμένη απόκριση χωρίς να εκτελέσει ξανά παρενέργειες.
Μια επανάληψη με το ίδιο κλειδί αλλά διαφορετικό σώμα απορρίπτεται με 409 idempotency_key_conflict.

Χρησιμοποιήστε το σε κάθε κλήση που δημιουργεί κάτι με παρενέργειες: αποστολή μηνύματος, email ή SMS, πραγματοποίηση κλήσης, οτιδήποτε χρεώνεται. Τα αιτήματα GET είναι πάντα idempotent και αγνοούν την κεφαλίδα.

Όρια ρυθμού

Τα όρια μετρώνται ανά λεπτό και αντιστοιχούν στον λογαριασμό, το κλειδί API ή τον χρήστη (ανά διεύθυνση IP στις διαδρομές που δεν απαιτούν σύνδεση). Τα προεπιλεγμένα ανώτατα όρια:

Κάδος	Προεπιλεγμένο όριο	Ανά λεπτό
Αιτήματα χωρίς σύνδεση (ανά IP)	60	ανά IP
Συνδεδεμένος χρήστης (πίνακας ελέγχου)	1 000	ανά χρήστη
Κλειδί API	1 000	ανά κλειδί
Δημόσια endpoints του widget	60 ανά επισκέπτη και 600 ανά διεύθυνση δικτύου	ανά λεπτό
Σύνδεση (`/auth/login`)	5	ανά IP
Εισερχόμενα webhooks	300	ανά λεπτό
Διακομιστής MCP	600	ανά λεπτό
Endpoints OAuth	600	ανά λεπτό

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

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

Όταν ξεπεράσετε ένα όριο, η απόκριση είναι 429 με code: rate_limited στον πίνακα errors και κεφαλίδα Retry-After σε δευτερόλεπτα. Περιμένετε τόσο χρόνο πριν από την επόμενη κλήση. Δέκα αποτυχημένες συνδέσεις κλειδώνουν τον λογαριασμό για 30 λεπτά.

Μεγέθη και χρονικά όρια

Κατηγορία	Μέγιστο σώμα αιτήματος	Χρονικό όριο διακομιστή
Προεπιλογή	1 MB	30 s
Μήνυμα με συνημμένα	25 MB	30 s
Εισαγωγή CSV	50 MB	επιστρέφει `202` και εκτελείται στο παρασκήνιο
Εικόνες βάσης γνώσης	10 MB	30 s
Bulk API	10 MB	30 s
Αναζήτηση	1 MB	10 s
Αιτήματα AI	1 MB	60 s
Endpoints του widget	100 KB	30 s

Τα υπερμεγέθη σώματα λαμβάνουν 413 payload_too_large. Μια upstream υπηρεσία που έληξε ο χρόνος της απαντά 504 με code: upstream_timeout και υπόδειξη retry_after όταν μια επανάληψη μπορεί να βοηθήσει.

Τύποι περιεχομένου, ημερομηνίες και αναγνωριστικά

Τα αιτήματα και οι αποκρίσεις είναι application/json; charset=utf-8. Οι μεταφορτώσεις αρχείων χρησιμοποιούν multipart/form-data· οι εξαγωγές CSV επιστρέφουν text/csv. Το μη έγκυρο UTF-8 απορρίπτεται με 400 validation_failed.
Οι χρονοσφραγίδες είναι ISO-8601 σε UTC με ακρίβεια χιλιοστού του δευτερολέπτου: 2026-04-20T14:23:45.123Z. Οποιαδήποτε μετατόπιση ISO-8601 γίνεται δεκτή στην είσοδο και κανονικοποιείται σε UTC.
Τα αναγνωριστικά είναι αδιαφανή ULID ή UUID. Δεν υπάρχουν αριθμητικά αναγνωριστικά και οι διευθύνσεις email ή οι αριθμοί τηλεφώνου δεν εμφανίζονται ποτέ σε URL.

Απομόνωση tenants και δικαιώματα

Κάθε αίτημα με έλεγχο ταυτότητας εκτελείται μέσα σε έναν λογαριασμό. Ένας πόρος που ανήκει σε άλλον λογαριασμό ή σε ιστότοπο που δεν καλύπτει ο ρόλος του καλούντος απαντά 404 not_found αντί για 403, ώστε να μη διαρρέει ποτέ η ύπαρξη εγγραφών. Ένα έγκυρο token χωρίς το απαιτούμενο δικαίωμα (για παράδειγμα contacts.delete) απαντά 403 forbidden. Ορισμένα δικαιώματα φέρουν επίθημα εμβέλειας (conversations.read:own, :team, :all) που περιορίζει τι επιστρέφει μια λίστα.

Το PATCH δέχεται μόνο εγγράψιμα πεδία. Τα id, account_id, created_at, updated_at και πεδία κατάστασης όπως το resolved_at είναι μόνο για ανάγνωση· η αποστολή τους επιστρέφει 400 validation_failed με details.forbidden_fields. Οι αλλαγές κατάστασης γίνονται μέσω ειδικών ενεργειών όπως POST /tickets/:id/resolve.

Κάθε εγγραφή καταγράφεται στο αρχείο ελέγχου του λογαριασμού.

Κεφαλίδες παρατηρησιμότητας

Κάθε απόκριση φέρει:

X-Request-Id: req_01HK…

Καταγράφετε το X-Request-Id. Είναι το πρώτο που ζητά η υποστήριξη.

CORS

Το origin του πίνακα ελέγχου στον browser είναι https://app.rolchat.com. Τα δημόσια endpoints του widget επιτρέπουν οποιοδήποτε origin ή μόνο τα origins που επαληθεύετε για έναν ιστότοπο. Οι κλήσεις μεταξύ διακομιστών με κλειδί API δεν υπόκεινται σε CORS.

Κατάργηση

Η αλλαγή ανακοινώνεται στο αρχείο αλλαγών και το επηρεαζόμενο endpoint αρχίζει να στέλνει Deprecation: true και κεφαλίδα Sunset με την ημερομηνία αφαίρεσης.
Τα δημόσια endpoints συνεχίζουν να λειτουργούν για τουλάχιστον έξι μήνες μετά την ανακοίνωση.
Η αφαίρεση γίνεται μόνο σε νέα κύρια έκδοση. Μέσα στο v1 οι αλλαγές είναι μόνο προσθετικές.

Υγεία

Κάθε υπηρεσία εκθέτει τα /healthz (liveness) και /readyz (readiness).