Αναφορά API / Σφάλματα

Κάθε κωδικός σφάλματος, σε ένα σημείο

Κάθε απάντηση του API του HyperCRM, επιτυχής ή αποτυχημένη, ακολουθεί μία από δύο μορφές φακέλου. Αυτή η σελίδα παραθέτει και τις δύο μορφές, πώς λειτουργούν τα request id, και τον πλήρη πίνακα κωδικών σφάλματος και καταστάσεων HTTP που μπορεί να επιστρέψει ένα endpoint.

Οι δύο φάκελοι

Οι επιτυχείς απαντήσεις (2xx) μοιάζουν πάντα έτσι, με το data να κρατά τον πόρο και το requestId για συσχέτιση:

{
  "data": { "...": "resource-specific shape" },
  "requestId": "req_5f2c1e40-..."
}

Τα endpoints POST που δημιουργούν πόρο επιστρέφουν 201 με την ίδια μορφή. Οι απαντήσεις σφάλματος (4xx/5xx) μοιράζονται το αντίστροφο σχήμα, με σταθερό code, ένα ασφαλές προς εμφάνιση message, το ίδιο requestId, και προαιρετικό πίνακα details που υπάρχει μόνο όταν υπάρχουν ζητήματα σε επίπεδο πεδίου (π.χ. καταχωρίσεις επικύρωσης πεδίων με path/message):

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "requestId": "req_5f2c1e40-...",
    "details": [ { "path": ["firstName"], "message": "firstName is required" } ]
  }
}

Request id

Κάθε απάντηση φέρει κεφαλίδα x-request-id, και η ίδια τιμή εμφανίζεται ως requestId στο σώμα. Αν το εισερχόμενο αίτημα προμηθεύει τη δική του κεφαλίδα x-request-id (ή x-correlation-id) που ταιριάζει σε ασφαλές μοτίβο, αυτή η τιμή επιστρέφεται αυτούσια για συσχέτιση αρχείων καταγραφής από την πλευρά του πελάτη· διαφορετικά ο διακομιστής παράγει μία της μορφής req_<uuid>.

Πίσω στον κόμβο αναφοράς API για τις υπόλοιπες σελίδες πόρων.

Όλοι οι κωδικοί σφάλματος

Η κατάσταση είναι σταθερή ανά κωδικό. Ορισμένα endpoints αντικαθιστούν το μήνυμα με κάτι πιο συγκεκριμένο κρατώντας τον ίδιο κωδικό και κατάσταση, οπότε ελέγχετε τον κωδικό — ποτέ το κείμενο του μηνύματος.

Κωδικός	Κατάσταση	Πότε συμβαίνει
validation_failed	400	Ένα πεδίο απέτυχε στην επικύρωση, στάλθηκε άγνωστο πεδίο, ή το JSON ήταν κακοσχηματισμένο. Συνοδεύεται από details.
bad_request	400	Κακοσχηματισμένο αίτημα που δεν είναι αποτυχία επικύρωσης πεδίου.
unauthorized	401	Απαιτείται ταυτοποίηση. Διαφέρει από τους κωδικούς bearer token παρακάτω, που αφορούν το ίδιο το token.
forbidden	403	Ταυτοποιημένος, αλλά χωρίς δικαίωμα — για παράδειγμα εξαγωγή δεδομένων χωρίς ρόλο ιδιοκτήτη.
not_found	404	Δεν υπάρχει τέτοιος πόρος στο ιατρείο σας. Επιστρέφεται και για κακοσχηματισμένο id διαδρομής, ώστε οι δύο περιπτώσεις να μη διακρίνονται.
conflict	409	Το αίτημα συγκρούεται με την τρέχουσα κατάσταση — π.χ. διπλότυπος τίτλος ετικέτας.
already_submitted	409	Δημόσιος σύνδεσμος φόρμας που έχει ήδη υποβληθεί.
entries_not_billable	409	Έκδοση απόδειξης ή τιμολογίου για επιλεγμένες χρεώσεις, όταν κάποια δεν είναι ανεξόφλητη χρέωση του ίδιου ασθενή.
appointment_already_charged	409	Χρέωση ραντεβού που έχει ήδη χρέωση χωρίς ακύρωση. Ακυρώστε πρώτα εκείνη τη χρέωση.
appointment_not_chargeable	409	Χρέωση ραντεβού που δεν είναι επιβεβαιωμένο ραντεβού ασθενή: αίτημα, απορριφθέν, ακυρωμένο ή ληγμένο ραντεβού, υπενθύμιση ή κλειστό διάστημα.
token_expired	410	Ο δημόσιος σύνδεσμος έχει λήξει.
payload_too_large	413	Το σώμα του αιτήματος ξεπερνά το μέγιστο αποδεκτό μέγεθος.
recipient_tax_id_required	422	Ζητήθηκε τιμολόγιο για ασθενή χωρίς ΑΦΜ. Προσθέστε τον ΑΦΜ ή εκδώστε απόδειξη.
rate_limit_exceeded	429	Συμπληρώθηκε ένα όριο ρυθμού.
internal_error	500	Απρόσμενο σφάλμα διακομιστή. Δεν επιστρέφεται τίποτα για την αιτία· αναφέρετε το requestId.
service_unavailable	503	Μια εξάρτηση δεν είναι προσωρινά διαθέσιμη.
missing_authorization	401	Δεν στάλθηκε κεφαλίδα Authorization.
invalid_authorization_header	401	Η κεφαλίδα υπήρχε αλλά όχι στη μορφή Bearer <token>.
invalid_auth_token	401	Το token δεν είναι έγκυρο.
expired_auth_token	401	Το token έχει λήξει. Ανανεώστε το και δοκιμάστε ξανά.
revoked_auth_token	401	Το token έχει ανακληθεί.
auth_token_verification_failed	401	Το token δεν επαληθεύτηκε για λόγο χωρίς πιο συγκεκριμένο κωδικό.
disabled_auth_token	403	Το token επαληθεύεται, αλλά η ταυτότητα πίσω του είναι απενεργοποιημένη — εξ ου 403 και όχι 401.
unsupported_auth_provider	403	Ο συγκεκριμένος πάροχος σύνδεσης δεν γίνεται δεκτός για πρόσβαση στο API.
auth_provider_email_required	403	Ο πάροχος σύνδεσης δεν έδωσε διεύθυνση email, που απαιτείται για δημιουργία λογαριασμού.
user_disabled	403	Ο ίδιος ο λογαριασμός HyperCRM είναι απενεργοποιημένος.
auth_configuration_missing	503	Η ταυτοποίηση δεν είναι ρυθμισμένη στον διακομιστή.

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

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

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

Χρησιμοποιήστε την τιμή requestId από το σώμα της απάντησης, ή την ταυτόσημη κεφαλίδα απάντησης x-request-id. Αν το δικό σας αίτημα έστειλε ήδη κεφαλίδα x-request-id ή x-correlation-id στην αναμενόμενη μορφή, η ίδια τιμή επιστρέφεται αυτούσια, οπότε μπορείτε να παράγετε το δικό σας id εκ των προτέρων και να το ταιριάζετε από άκρη σε άκρη.

Επειδή το ίδιο το bearer token εξακολουθεί να είναι έγκυρο και επαληθεύεται σωστά — η ταυτότητα πίσω του είναι απενεργοποιημένη, κάτι που το HyperCRM αντιμετωπίζει ως αποτυχία εξουσιοδότησης αντί για αποτυχία αυθεντικοποίησης. Είναι σκόπιμη εξαίρεση από τη συνηθέστερη σύμβαση, τεκμηριωμένη ρητά στη σελίδα αναφοράς αυθεντικοποίησης.