Αναφορά API / Ασθενείς
Ασθενείς και σημειώσεις ασθενών
Ο φάκελος του ασθενή, οι κλινικές σημειώσεις με ιστορικό αναθεωρήσεων και η εναλλαγή ετικετών. Κάθε πεδίο, κάθε endpoint και τα ακριβή σφάλματα που επιστρέφει το καθένα.
Η κατάσταση δεν είναι σταθερή λίστα
Οι έγκυρες τιμές κατάστασης προέρχονται από το τρέχον pack του ιατρείου και όχι από λίστα ορισμένη στο API. Διαβάστε τες από το GET /api/v1/me αντί να τις γράψετε σταθερά, αλλιώς ένα ιατρείο με άλλο pack θα απορρίψει εγγραφές που ο client θεωρεί έγκυρες.
Εμβέλεια και αναγνωριστικά
Κάθε endpoint εδώ απαιτεί ταυτοποίηση και λειτουργεί αποκλειστικά εντός του ιατρείου του καλούντος — το αίτημα δεν δηλώνει ποτέ δικό του practice id και δεν μπορεί να φτάσει σε αρχεία άλλου ιατρείου.
Τα τμήματα διαδρομής (patientId, noteId, tagId) πρέπει να είναι κανονικά UUID. Ένα κακοδιατυπωμένο id επιστρέφει not_found (404) χωρίς να φτάσει στο επίπεδο δεδομένων, οπότε ένα λανθασμένο id και ένα έγκυρο που δεν υπάρχει είναι δυσδιάκριτα. Αυτό είναι σκόπιμο: εμποδίζει το API να επιβεβαιώνει ποια id υπάρχουν.
Το αντικείμενο του ασθενή
{
"id": "0f1c7a2e-....",
"practiceId": "8b3d1f60-....",
"firstName": "Jo",
"lastName": "Doe",
"dob": "1990-05-14T00:00:00.000Z",
"gender": null,
"email": null,
"phoneMobile": null,
"address": null,
"postcode": null,
"country": null,
"status": "active",
"statusChangedAt": "2026-01-01T00:00:00.000Z",
"tagIds": [],
"notifyByEmail": true,
"notifyBySms": true,
"metadata": {},
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
Τα dob, statusChangedAt, createdAt και updatedAt είναι συμβολοσειρές ISO 8601· το null παραμένει null. Το dob δίνεται ως YYYY-MM-DD κατά την εγγραφή και επιστρέφεται ως πλήρης χρονοσφραγίδα.
Το αντικείμενο της σημείωσης
{
"id": "c41a8e93-....",
"patientId": "0f1c7a2e-....",
"practiceId": "8b3d1f60-....",
"title": null,
"body": "Called patient to confirm appointment.",
"isNext": false,
"revisions": [],
"createdBy": "3d9b2c15-....",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
Το revisions συγκεντρώνει τις προηγούμενες εκδοχές της σημείωσης σε κάθε επεξεργασία — είναι ιστορικό ελέγχου, όχι προαιρετική λειτουργία. Το createdBy είναι το id του χρήστη που την έγραψε.
Endpoints
GET/api/v1/patients
Επιστρέφει τους ασθενείς του ιατρείου, με προαιρετική αναζήτηση και φίλτρα.
Οι τιμές σελιδοποίησης εκτός ορίων περικόπτονται αντί να απορρίπτονται: το limit=5000 επιστρέφει 200 αποτελέσματα, δεν αποτυγχάνει. Η απόκριση επαναλαμβάνει τα πραγματικά limit και offset, ώστε ο client να αντιληφθεί την περικοπή.
Παράμετροι ερωτήματος
| Πεδίο | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
| limit | integer | 50 | Περιορίζεται στο 1–200. Μη αριθμητική τιμή επιστρέφει στην προεπιλογή. |
| offset | integer | 0 | Ελάχιστη τιμή 0. Χωρίς ανώτατο όριο. |
| search | string | — | Αντιπαραβάλλεται με τα πεδία ονόματος. Οι χαρακτήρες μπαλαντέρ δεν ερμηνεύονται. |
| status | string | — | Φιλτράρει με βάση κατάσταση ορισμένη από το pack. |
| tagId | string | — | Φιλτράρει ασθενείς με τη συγκεκριμένη ετικέτα. |
Απόκριση · 200
{
"data": {
"patients": [
{ "id": "0f1c7a2e-....", "firstName": "Jo", "lastName": "Doe" }
],
"limit": 50,
"offset": 0
},
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| missing_authorization | 401 | Δεν στάλθηκε κεφαλίδα Authorization. |
POST/api/v1/patients
Δημιουργεί ασθενή.
Το σώμα είναι αυστηρό: ένα μη αναγνωρισμένο πεδίο απορρίπτεται αντί να αγνοηθεί, ώστε ένα τυπογραφικό σε όνομα πεδίου να αποτυγχάνει φανερά αντί να χάνει σιωπηλά δεδομένα.
Σώμα αιτήματος
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| firstNameΥποχρεωτικό | string | Χωρίς κενά στα άκρα· δεν επιτρέπεται κενό. |
| lastNameΥποχρεωτικό | string | Χωρίς κενά στα άκρα· δεν επιτρέπεται κενό. |
| dob | string | null | YYYY-MM-DD και πρέπει να είναι υπαρκτή ημερομηνία. |
| gender | string | null | Ελεύθερο κείμενο. |
| string | null | Έγκυρη διεύθυνση, εφόσον δοθεί. | |
| phoneMobile | string | null | Ελεύθερο κείμενο. |
| address | string | null | Ελεύθερο κείμενο. |
| postcode | string | null | Ελεύθερο κείμενο. |
| country | string | null | Ελεύθερο κείμενο. |
| status | string | Πρέπει να ανήκει στις καταστάσεις του pack του ιατρείου, όχι σε σταθερή λίστα. |
| notifyByEmail | boolean | Αν επιτρέπεται email προς τον ασθενή. |
| notifyBySms | boolean | Αν επιτρέπεται SMS προς τον ασθενή. |
Παράδειγμα αιτήματος
{
"firstName": "Jo",
"lastName": "Doe",
"dob": "1990-05-14",
"status": "active"
}Απόκριση · 201
{
"data": {
"id": "0f1c7a2e-....",
"firstName": "Jo",
"lastName": "Doe",
"dob": "1990-05-14T00:00:00.000Z",
"status": "active",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
},
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| validation_failed | 400 | Λείπει υποχρεωτικό πεδίο, το dob ή το email είναι άκυρο, ή στάλθηκε άγνωστο πεδίο. Το details αναφέρει τη διαδρομή. |
| validation_failed | 400 | Το status δεν ανήκει στις τιμές του pack του ιατρείου. |
GET/api/v1/patients/:patientId
Επιστρέφει έναν ασθενή.
Παράμετροι διαδρομής
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| patientIdΥποχρεωτικό | uuid | Κανονικό UUID. |
Απόκριση · 200
{
"data": { "id": "0f1c7a2e-....", "firstName": "Jo", "lastName": "Doe" },
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| not_found | 404 | Το id δεν είναι UUID, δεν υπάρχει, ή ανήκει σε άλλο ιατρείο — και οι τρεις περιπτώσεις είναι δυσδιάκριτες. |
PATCH/api/v1/patients/:patientId
Ενημερώνει ασθενή. Όλα τα πεδία της δημιουργίας, όλα προαιρετικά.
Παράμετροι διαδρομής
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| patientIdΥποχρεωτικό | uuid | Κανονικό UUID. |
Παράδειγμα αιτήματος
{ "firstName": "Joanna" }Απόκριση · 200
{
"data": { "id": "0f1c7a2e-....", "firstName": "Joanna" },
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| validation_failed | 400 | Ίδιοι κανόνες με τη δημιουργία ασθενή. |
| not_found | 404 | Δεν υπάρχει τέτοιος ασθενής στο ιατρείο. |
DELETE/api/v1/patients/:patientId
Διαγράφει ασθενή.
Παράμετροι διαδρομής
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| patientIdΥποχρεωτικό | uuid | Κανονικό UUID. |
Απόκριση · 200
{
"data": { "deleted": true },
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| not_found | 404 | Δεν υπάρχει τέτοιος ασθενής στο ιατρείο. |
POST/api/v1/patients/:patientId/tags/:tagId
Εναλλάσσει μια ετικέτα στον ασθενή — την προσθέτει αν λείπει, την αφαιρεί αν υπάρχει.
Δεν υπάρχει σώμα αιτήματος ούτε ξεχωριστό endpoint αφαίρεσης: το id της ετικέτας δίνεται στη διαδρομή και η κλήση αντιστρέφει την κατάστασή της. Δύο ίδια αιτήματα επαναφέρουν τον ασθενή στην αρχική κατάσταση.
Παράμετροι διαδρομής
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| patientIdΥποχρεωτικό | uuid | Κανονικό UUID. |
| tagIdΥποχρεωτικό | uuid | Κανονικό UUID ετικέτας του ιατρείου. |
Απόκριση · 200
{
"data": { "id": "0f1c7a2e-....", "tagIds": ["b7e42d18-...."] },
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| not_found | 404 | Ο ασθενής ή η ετικέτα δεν υπάρχει στο ιατρείο. |
GET/api/v1/patients/:patientId/notes
Επιστρέφει τις σημειώσεις ενός ασθενή.
Παράμετροι διαδρομής
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| patientIdΥποχρεωτικό | uuid | Κανονικό UUID. |
Απόκριση · 200
{
"data": { "notes": [] },
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| not_found | 404 | Δεν υπάρχει τέτοιος ασθενής στο ιατρείο. |
POST/api/v1/patients/:patientId/notes
Προσθέτει σημείωση σε ασθενή.
Παράμετροι διαδρομής
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| patientIdΥποχρεωτικό | uuid | Κανονικό UUID. |
Σώμα αιτήματος
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| bodyΥποχρεωτικό | string | Χωρίς κενά στα άκρα· δεν επιτρέπεται κενό. |
| title | string | null | Προαιρετικός τίτλος. |
| isNext | boolean | Σημειώνει τη σημείωση ως επόμενη ενέργεια. |
Παράδειγμα αιτήματος
{
"body": "Called patient to confirm appointment.",
"isNext": true
}Απόκριση · 201
{
"data": {
"id": "c41a8e93-....",
"body": "Called patient to confirm appointment.",
"isNext": true,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
},
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| validation_failed | 400 | Το body λείπει ή είναι κενό, ή στάλθηκε άγνωστο πεδίο. |
| not_found | 404 | Δεν υπάρχει τέτοιος ασθενής στο ιατρείο. |
PATCH/api/v1/patients/:patientId/notes/:noteId
Επεξεργάζεται σημείωση. Η προηγούμενη εκδοχή διατηρείται στο revisions.
Παράμετροι διαδρομής
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| patientIdΥποχρεωτικό | uuid | Κανονικό UUID. |
| noteIdΥποχρεωτικό | uuid | Κανονικό UUID. |
Σώμα αιτήματος
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| title | string | null | Προαιρετικός τίτλος. |
| body | string | Αν δοθεί, δεν επιτρέπεται να είναι κενό. |
| isNext | boolean | Σημειώνει τη σημείωση ως επόμενη ενέργεια. |
Παράδειγμα αιτήματος
{ "title": "Follow-up" }Απόκριση · 200
{
"data": { "id": "c41a8e93-....", "title": "Follow-up" },
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| validation_failed | 400 | Το body δόθηκε κενό, ή στάλθηκε άγνωστο πεδίο. |
| not_found | 404 | Δεν υπάρχει τέτοιος ασθενής ή σημείωση στο ιατρείο. |
DELETE/api/v1/patients/:patientId/notes/:noteId
Διαγράφει σημείωση.
Παράμετροι διαδρομής
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
| patientIdΥποχρεωτικό | uuid | Κανονικό UUID. |
| noteIdΥποχρεωτικό | uuid | Κανονικό UUID. |
Απόκριση · 200
{
"data": { "deleted": true },
"requestId": "req_5f2c1e40-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| not_found | 404 | Δεν υπάρχει τέτοιος ασθενής ή σημείωση στο ιατρείο. |
Συχνές ερωτήσεις
Τα αρχεία ασθενών κρυπτογραφούνται κατά τη μεταφορά και την αποθήκευση, τα αρχεία φυλάσσονται ιδιωτικά και σερβίρονται μέσω συνδέσμων περιορισμένης διάρκειας, ενώ κάθε αλλαγή καταγράφεται. Το προσωπικό συνδέεται με passkeys αντί για κοινούς κωδικούς.
Όχι. Οι έγκυρες τιμές προέρχονται από το τρέχον pack του ιατρείου και όχι από σταθερή λίστα του API, και επιστρέφονται από το GET /api/v1/me. Δημιουργία ή ενημέρωση με κατάσταση εκτός λίστας επιστρέφει validation_failed με τη διαδρομή του πεδίου.
Επειδή ένα κακοδιατυπωμένο id και ένα έγκυρο id άλλου ιατρείου πρέπει να φαίνονται ίδια από έξω. Αν το ένα επέστρεφε 400 και το άλλο 404, η διαφορά θα επέτρεπε σε κάποιον να επιβεβαιώσει ποια id υπάρχουν σε άλλα ιατρεία.
Ναι. Κάθε σημείωση έχει πίνακα revisions που συγκεντρώνει τις προηγούμενες εκδοχές του περιεχομένου σε κάθε επεξεργασία, μαζί με το id του χρήστη που τη δημιούργησε. Είναι ιστορικό ελέγχου και όχι προαιρετική λειτουργία εκδόσεων.