Αναφορά API / Ραντεβού

Κρατήσεις, συγκρούσεις και διαθεσιμότητα

Ο πόρος appointments καλύπτει κρατήσεις, καταχωρίσεις αποκλεισμού έδρας, και ένα παράγωγο endpoint διαθεσιμότητας που υπολογίζει ελεύθερα διαστήματα για μια έδρα σε συγκεκριμένη ημέρα. Αυτή η σελίδα απαριθμεί τη μορφή του αντικειμένου, τον κανόνα ανίχνευσης σύγκρουσης, και τα πεδία και σφάλματα κάθε endpoint.

Ποιος μπορεί να κάνει τι

Κάθε endpoint απαιτεί αυθεντικοποίηση και λειτουργεί εντός του ιατρείου του καλούντος. Σε αντίθεση με τις έδρες και τις ρυθμίσεις ιατρείου, τα ραντεβού δεν είναι μόνο για τον ιδιοκτήτη — κάθε μέλος του ιατρείου, ιδιοκτήτης ή βοηθός, μπορεί να δημιουργεί, ενημερώνει και διαγράφει. Τα τμήματα διαδρομής appointmentId πρέπει να είναι κανονικά UUID· ένα κακοσχηματισμένο επιστρέφει not_found (404) χωρίς να φτάσει στο επίπεδο υπηρεσίας.

Το αντικείμενο ραντεβού και ο τύπος του

Ένα ραντεβού φέρει chairId, patientId, type, title, startAt, endAt, color, serviceRef, notes, createdBy, και metadata, συν id, practiceId, createdAt, updatedAt. Το type είναι ένα από appointment, reminder, ή unavailable. Μια καταχώριση unavailable αποκλείει μια έδρα όπως ένα πραγματικό ραντεβού για σκοπούς σύγκρουσης· μια καταχώριση reminder ποτέ δεν καταλαμβάνει έδρα και εξαιρείται τόσο από τον έλεγχο επικάλυψης όσο και από τον υπολογισμό διαθεσιμότητας, ακόμη κι αν έχει ορισμένο chairId.

Ανίχνευση επικάλυψης (διπλής κράτησης)

Όταν έχει οριστεί chairId και type !== "reminder", η δημιουργία ή ενημέρωση ενός ραντεβού απορρίπτεται με conflict (409) αν επικαλύπτεται με υπάρχον ραντεβού ή αποκλεισμό στην ίδια έδρα. Η επικάλυψη χρησιμοποιεί αυστηρή ανισότητα (existing.startAt < newEnd AND existing.endAt > newStart), οπότε δύο καταχωρίσεις που αγγίζονται ακριβώς σε ένα όριο δεν θεωρούνται επικαλυπτόμενες. Διαφορετικές έδρες ποτέ δεν συγκρούονται μεταξύ τους, και στο PATCH το ίδιο το ραντεβού που ενημερώνεται εξαιρείται από τον δικό του έλεγχο σύγκρουσης.

Υπενθυμίσεις ως παρενέργεια

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

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

Endpoints

GET/api/v1/appointments

Επιστρέφει τα ραντεβού που ξεκινούν εντός ενός χρονικού παραθύρου, ταξινομημένα κατά ώρα έναρξης.

Το παράθυρο είναι ημιανοιχτό: ένα ραντεβού περιλαμβάνεται όταν το startAt ανήκει στο [from, to). Ένα ραντεβού που ξεκίνησε πριν το from και ακόμη διαρκεί δεν επιστρέφεται.

Παράμετροι ερωτήματος

Πεδίο	Τύπος	Προεπιλογή	Περιγραφή
fromΥποχρεωτικό	ISO datetime	—	Αρχή του παραθύρου, συμπεριλαμβανομένη.
toΥποχρεωτικό	ISO datetime	—	Τέλος του παραθύρου, μη συμπεριλαμβανομένο.
chairId	uuid	—	Περιορίζει το αποτέλεσμα σε μία έδρα.

Απόκριση · 200

{
  "data": {
    "appointments": [
      {
        "id": "a7c30e51-....",
        "type": "appointment",
        "startAt": "2026-07-08T10:00:00.000Z",
        "endAt": "2026-07-08T11:00:00.000Z"
      }
    ]
  },
  "requestId": "req_5f2c1e40-...."
}

Σφάλματα

Κωδικός	Κατάσταση	Πότε
validation_failed	400	Λείπει ή είναι άκυρο το from ή το to, ή το chairId είναι κακοσχηματισμένο.
missing_authorization	401	Δεν στάλθηκε κεφαλίδα Authorization.

POST/api/v1/appointments

Δημιουργεί ραντεβού, υπενθύμιση ή εγγραφή δέσμευσης έδρας.

Κάθε μέλος του ιατρείου μπορεί να το κάνει — δεν υπάρχει περιορισμός μόνο για τον ιδιοκτήτη, σε αντίθεση με τις έδρες και τις ρυθμίσεις.

Ένα chairId ή patientId άλλου ιατρείου απορρίπτεται ως validation_failed και δεν εμφανίζεται ως σφάλμα βάσης.

Σώμα αιτήματος

Πεδίο	Τύπος	Περιγραφή
typeΥποχρεωτικό	string	Ένα από appointment, reminder, unavailable.
startAtΥποχρεωτικό	ISO datetime	Πότε ξεκινά.
endAtΥποχρεωτικό	ISO datetime	Πρέπει να είναι αυστηρά μετά το startAt.
chairId	uuid	Πρέπει να ανήκει στο ιατρείο σας. Απαιτείται για να δεσμευτεί έδρα.
patientId	uuid	Πρέπει να ανήκει στο ιατρείο σας. Ενεργοποιεί τον προγραμματισμό υπενθύμισης.
title	string	Χωρίς κενά στα άκρα· δεν επιτρέπεται κενό αν δοθεί.
color	string	Χρώμα εμφάνισης στο ημερολόγιο.
serviceRef	string	Αναφορά στην υπηρεσία που εκτελείται.
notes	string	Ελεύθερο κείμενο.

Παράδειγμα αιτήματος

{
  "type": "appointment",
  "startAt": "2026-07-08T10:00:00.000Z",
  "endAt": "2026-07-08T11:00:00.000Z",
  "chairId": "5c2f9b74-....",
  "title": "Checkup"
}

Απόκριση · 201

{
  "data": {
    "id": "a7c30e51-....",
    "type": "appointment",
    "startAt": "2026-07-08T10:00:00.000Z",
    "endAt": "2026-07-08T11:00:00.000Z"
  },
  "requestId": "req_5f2c1e40-...."
}

Σφάλματα

Κωδικός	Κατάσταση	Πότε
validation_failed	400	Το endAt δεν είναι μετά το startAt, άγνωστο chairId ή patientId, ή στάλθηκε άγνωστο πεδίο.
conflict	409	Η εγγραφή επικαλύπτεται με υπάρχον ραντεβού ή δέσμευση στην ίδια έδρα.

GET/api/v1/appointments/:appointmentId

Επιστρέφει ένα ραντεβού.

Παράμετροι διαδρομής

Πεδίο	Τύπος	Περιγραφή
appointmentIdΥποχρεωτικό	uuid	Κανονικό UUID.

Απόκριση · 200

{
  "data": { "id": "a7c30e51-....", "type": "appointment" },
  "requestId": "req_5f2c1e40-...."
}

Σφάλματα

Κωδικός	Κατάσταση	Πότε
not_found	404	Δεν υπάρχει τέτοιο ραντεβού στο ιατρείο.

PATCH/api/v1/appointments/:appointmentId

Ενημερώνει ραντεβού. Όλα τα πεδία της δημιουργίας, όλα προαιρετικά.

Ο έλεγχος endAt > startAt επαναλαμβάνεται όποτε αλλάζει κάποιο από τα δύο, σε σύγκριση με την υπάρχουσα τιμή του άλλου. Ο έλεγχος επικάλυψης εκτελείται ξανά για το τελικό εύρος, εξαιρώντας το ίδιο το ραντεβού.

Παράμετροι διαδρομής

Πεδίο	Τύπος	Περιγραφή
appointmentIdΥποχρεωτικό	uuid	Κανονικό UUID.

Παράδειγμα αιτήματος

{
  "startAt": "2026-07-08T10:30:00.000Z",
  "endAt": "2026-07-08T11:30:00.000Z"
}

Απόκριση · 200

{
  "data": {
    "id": "a7c30e51-....",
    "startAt": "2026-07-08T10:30:00.000Z",
    "endAt": "2026-07-08T11:30:00.000Z"
  },
  "requestId": "req_5f2c1e40-...."
}

Σφάλματα

Κωδικός	Κατάσταση	Πότε
validation_failed	400	Άκυρο πεδίο, άγνωστο chairId ή patientId, ή άγνωστο πεδίο.
conflict	409	Η νέα ώρα επικαλύπτεται με άλλη εγγραφή στην ίδια έδρα.
not_found	404	Δεν υπάρχει τέτοιο ραντεβού στο ιατρείο.

DELETE/api/v1/appointments/:appointmentId

Διαγράφει ραντεβού και ακυρώνει την υπενθύμιση που είχε προγραμματιστεί.

Παράμετροι διαδρομής

Πεδίο	Τύπος	Περιγραφή
appointmentIdΥποχρεωτικό	uuid	Κανονικό UUID.

Απόκριση · 200

{
  "data": { "deleted": true },
  "requestId": "req_5f2c1e40-...."
}

Σφάλματα

Κωδικός	Κατάσταση	Πότε
not_found	404	Δεν υπάρχει τέτοιο ραντεβού στο ιατρείο.

GET/api/v1/appointments/availability

Υπολογίζει τα ελεύθερα διαστήματα μίας έδρας για μία ημερολογιακή ημέρα.

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

Παράμετροι ερωτήματος

Πεδίο	Τύπος	Προεπιλογή	Περιγραφή
dateΥποχρεωτικό	string	—	YYYY-MM-DD, στη ζώνη ώρας του ιατρείου.
chairIdΥποχρεωτικό	uuid	—	Πρέπει να ανήκει στο ιατρείο σας.
durationMinutesΥποχρεωτικό	integer	—	Ζητούμενη διάρκεια διαστήματος, 1–1440.

Απόκριση · 200

{
  "data": {
    "slots": [
      { "startAt": "2026-07-08T06:00:00.000Z", "endAt": "2026-07-08T07:00:00.000Z" }
    ]
  },
  "requestId": "req_5f2c1e40-...."
}

Σφάλματα

Κωδικός	Κατάσταση	Πότε
validation_failed	400	Λείπει ή είναι άκυρη η date, το chairId δεν είναι UUID ή ανήκει σε άλλο ιατρείο, ή το durationMinutes είναι εκτός ορίων.
not_found	404	Δεν βρέθηκε το ιατρείο.

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

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

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

Δύο καταχωρίσεις στην ίδια έδρα των οποίων τα χρονικά διαστήματα επικαλύπτονται υπό κανόνα αυστηρής ανισότητας, όπου το να αγγίζονται ακριβώς σε ένα όριο δεν μετράει ως επικάλυψη. Οι καταχωρίσεις τύπου reminder εξαιρούνται πλήρως, ακόμη και με ορισμένο chairId, αφού δεν καταλαμβάνουν έδρα. Μια συγκρουόμενη δημιουργία ή ενημέρωση απορρίπτεται με απάντηση 409.

Όχι. Η δημιουργία, ενημέρωση ή διαγραφή ενός ραντεβού συνδεδεμένου με ασθενή προγραμματίζει, επαναπρογραμματίζει ή ακυρώνει αυτόματα την υπενθύμισή του στο παρασκήνιο, με βάση τον ρυθμισμένο χρόνο προειδοποίησης του ιατρείου. Δεν υπάρχει ξεχωριστό endpoint γι' αυτό — συμβαίνει ως παρενέργεια των κανονικών endpoints εγγραφής ραντεβού.