Αναφορά API / Ασθενείς
Ασθενείς και σημειώσεις ασθενών
Ο φάκελος του ασθενή, οι κλινικές σημειώσεις με ιστορικό αναθεωρήσεων και η εναλλαγή ετικετών. Κάθε πεδίο, κάθε endpoint και τα ακριβή σφάλματα που επιστρέφει το καθένα.
Η κατάσταση δεν είναι σταθερή λίστα
Οι έγκυρες τιμές κατάστασης προέρχονται από το τρέχον pack του ιατρείου και όχι από λίστα ορισμένη στο API. Διαβάστε τες από το GET /api/v1/me αντί να τις γράψετε σταθερά, αλλιώς ένα ιατρείο με άλλο pack θα απορρίψει εγγραφές που ο client θεωρεί έγκυρες.
Εμβέλεια και αναγνωριστικά
Κάθε endpoint εδώ απαιτεί ταυτοποίηση και λειτουργεί αποκλειστικά εντός του ιατρείου του καλούντος: το αίτημα δεν δηλώνει ποτέ δικό του practice id και δεν μπορεί να φτάσει σε αρχεία άλλου ιατρείου.
Κάθε endpoint μπορεί επίσης να επιστρέψει τα σφάλματα ταυτοποίησης, 403 mfa_required ή 403 subscription_read_only, και 429. Οι πίνακες παρακάτω δείχνουν μόνο ό,τι είναι ειδικό για το καθένα. Η αναφορά σφαλμάτων έχει το πλήρες σύνολο.
Τα τμήματα διαδρομής (patientId, noteId, tagId) πρέπει να είναι κανονικά UUID. Ένα κακοδιατυπωμένο id επιστρέφει not_found (404) χωρίς να φτάσει στο επίπεδο δεδομένων, οπότε ένα λανθασμένο id και ένα έγκυρο που δεν υπάρχει είναι δυσδιάκριτα. Αυτό είναι σκόπιμο: εμποδίζει το API να επιβεβαιώνει ποια id υπάρχουν.
Το αντικείμενο του ασθενή
{
"id": "0f1c7a2e-....",
"practiceId": "8b3d1f60-....",
"firstName": "Jo",
"lastName": "Doe",
"dob": "1990-05-14",
"gender": null,
"email": null,
"phoneMobile": null,
"address": null,
"postcode": null,
"country": null,
"socialSecurityNumber": null,
"taxId": null,
"taxOffice": null,
"status": "active",
"statusChangedAt": "2026-01-01T00:00:00.000Z",
"tagIds": [],
"notifyByEmail": false,
"notifyBySms": false,
"metadata": {},
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
Τα statusChangedAt, createdAt και updatedAt είναι χρονοσφραγίδες ISO 8601· το null παραμένει null. Το dob είναι ημερομηνία YYYY-MM-DD και στην εγγραφή και στην ανάγνωση, όχι χρονοσφραγίδα: είναι ημερολογιακή ημερομηνία, και μια ώρα θα της επινοούσε ζώνη ώρας.
Οι γραμμές της λίστας παραλείπουν δύο από αυτά. Το GET /api/v1/patients επιστρέφει κάθε πεδίο παραπάνω εκτός από τα socialSecurityNumber και taxId· μόνο η ανάγνωση ενός ασθενή τα επιστρέφει.
Το αντικείμενο της σημείωσης
{
"id": "c41a8e93-....",
"patientId": "0f1c7a2e-....",
"practiceId": "8b3d1f60-....",
"title": null,
"body": "Called patient to confirm appointment.",
"revisions": [],
"createdBy": "3d9b2c15-....",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
Το revisions συγκεντρώνει τις προηγούμενες εκδοχές της σημείωσης σε κάθε επεξεργασία, είναι ιστορικό ελέγχου και όχι προαιρετική λειτουργία, και κρατά τις 20 πιο πρόσφατες εκδοχές. Το createdBy είναι το id του χρήστη που την έγραψε. Το title έχει έως 200 χαρακτήρες και το body έως 20.000.
Endpoints
GET/api/v1/patients
Επιστρέφει τους ασθενείς του ιατρείου, με προαιρετική αναζήτηση και φίλτρα.
Μια τιμή σελιδοποίησης εκτός ορίων περικόπτεται αντί να απορριφθεί: το limit=5000 επιστρέφει 200 αποτελέσματα, δεν αποτυγχάνει. Μια τιμή που **δεν είναι σκέτα ψηφία** είναι άλλο θέμα και επιστρέφει 400 `validation_failed`: τα `abc`, `1.5`, `1e2`, `0x10`, `+5` και `-3` αποτυγχάνουν αντί να πέσουν στην προεπιλογή. Η απόκριση επαναλαμβάνει τα πραγματικά limit και offset, ώστε ο client να αντιληφθεί την περικοπή.
Παράμετροι ερωτήματος
| Πεδίο | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
| limit | integer | 50 | Περιορίζεται από 1 έως 200. Οτιδήποτε άλλο από σκέτα ψηφία είναι 400. |
| offset | integer | 0 | Περιορίζεται από 0 έως 100.000. Οτιδήποτε άλλο από σκέτα ψηφία είναι 400. |
| search | string | — | Αντιπαραβάλλεται με όνομα, επώνυμο, πλήρες όνομα, email και κινητό· ένα ερώτημα σε μορφή τηλεφώνου αντιπαραβάλλεται και σε μορφή E.164. Οι χαρακτήρες μπαλαντέρ δεν ερμηνεύονται. |
| status | string | — | Φιλτράρει με βάση κατάσταση ορισμένη από το pack. |
| tagId | string | — | Φιλτράρει ασθενείς με τη συγκεκριμένη ετικέτα. Ένα κακοδιατυπωμένο id είναι 400 `validation_failed`, όχι 404. |
| format | string | — | Το `csv` επιστρέφει όλη τη λίστα ως αρχείο CSV αντί για JSON, έως 10.000 γραμμές, αγνοώντας τα limit και offset. Μόνο ο ιδιοκτήτης (403 `forbidden`) και με επιβεβαιωμένο email (403 `email_not_verified`). |
Απόκριση · 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 | Ελεύθερο κείμενο, έως 50 χαρακτήρες. |
| string | null | Έγκυρη διεύθυνση, εφόσον δοθεί. | |
| phoneMobile | string | null | Ελεύθερο κείμενο. |
| address | string | null | Ελεύθερο κείμενο. |
| postcode | string | null | Ελεύθερο κείμενο. |
| country | string | null | Ελεύθερο κείμενο, έως 100 χαρακτήρες. |
| socialSecurityNumber | string | null | Καθαρίζεται από κενά· η κενή τιμή γίνεται null. Δεν γίνεται έλεγχος μορφής, οπότε δεκτός είναι αριθμός από οποιαδήποτε χώρα. |
| taxId | string | null | Χρειάζεται πριν εκδοθεί τιμολόγιο για τον ασθενή. |
| taxOffice | string | null | Ελεύθερο κείμενο, έως 80 χαρακτήρες. |
| status | string | Πρέπει να ανήκει στις καταστάσεις του pack του ιατρείου, όχι σε σταθερή λίστα. Προεπιλογή `active`. |
| notifyByEmail | boolean | Αν επιτρέπεται email προς τον ασθενή. Προεπιλογή `false`. |
| notifyBySms | boolean | Αν επιτρέπεται SMS προς τον ασθενή. Προεπιλογή `false`. |
Παράδειγμα αιτήματος
{
"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-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| service_unavailable | 503 | Τα αρχεία του ασθενή δεν μπόρεσαν να διαγραφούν, ή η διαγραφή άργησε. Δεν διαγράφηκε τίποτα· δοκιμάστε ξανά. |
| 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-...."
}Σφάλματα
| Κωδικός | Κατάσταση | Πότε |
|---|---|---|
| validation_failed | 400 | Ένα σωστά διατυπωμένο `tagId` που δεν αντιστοιχεί σε ετικέτα του ιατρείου. Είναι 400 στο πεδίο, όχι 404. |
| 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 | Προαιρετικός τίτλος. |
Παράδειγμα αιτήματος
{
"body": "Called patient to confirm appointment."
}Απόκριση · 201
{
"data": {
"id": "c41a8e93-....",
"body": "Called patient to confirm appointment.",
"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 | Αν δοθεί, δεν επιτρέπεται να είναι κενό. |
Παράδειγμα αιτήματος
{ "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 | Δεν υπάρχει τέτοιος ασθενής ή σημείωση στο ιατρείο. |
Συχνές ερωτήσεις
Οι καρτέλες ασθενών κρυπτογραφούνται, και εκεί που φυλάσσονται και καθώς έρχονται στην οθόνη σας. Τα αρχεία είναι ιδιωτικά, και ο σύνδεσμος προς ένα αρχείο σταματά να δουλεύει μετά από λίγο. Οι αλλαγές στις καρτέλες των ασθενών καταγράφονται, με το ποιος τις έκανε και πότε. Δεν υπάρχει κοινός κωδικός ιατρείου: ο καθένας έχει τον δικό του λογαριασμό. Στο πακέτο Complete, ο ιδιοκτήτης του ιατρείου μπορεί επίσης να απαιτεί σύνδεση σε δύο βήματα για όλη την ομάδα.
Όχι. Οι έγκυρες τιμές προέρχονται από το τρέχον pack του ιατρείου και όχι από σταθερή λίστα του API, και επιστρέφονται από το GET /api/v1/me. Δημιουργία ή ενημέρωση με κατάσταση εκτός λίστας επιστρέφει validation_failed με τη διαδρομή του πεδίου.
Επειδή ένα κακοδιατυπωμένο id και ένα έγκυρο id άλλου ιατρείου πρέπει να φαίνονται ίδια από έξω. Αν το ένα επέστρεφε 400 και το άλλο 404, η διαφορά θα επέτρεπε σε κάποιον να επιβεβαιώσει ποια id υπάρχουν σε άλλα ιατρεία.
Ναι. Κάθε σημείωση έχει πίνακα revisions που συγκεντρώνει τις προηγούμενες εκδοχές του περιεχομένου σε κάθε επεξεργασία (τις 20 πιο πρόσφατες), μαζί με το id του χρήστη που τη δημιούργησε. Είναι ιστορικό ελέγχου και όχι προαιρετική λειτουργία εκδόσεων.