---
title: "Αναφορά API ασθενών - πεδία και endpoints"
description: "Αναλυτική αναφορά για τον πόρο patients: οι μορφές ασθενή και σημείωσης, οι παράμετροι κάθε endpoint, και τα σφάλματα που μπορεί να επιστραφούν."
canonical: "https://hypercrm.app/el/docs/api/patients"
lang: "el"
updated: "2026-07-26"
---

_Αναφορά API / Ασθενείς_

# Ασθενείς και σημειώσεις ασθενών

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

[Ξεκινήστε δωρεάν δοκιμή](/dashboard) · [Πίσω στην αναφορά API](/el/docs/api)

> **Η κατάσταση δεν είναι σταθερή λίστα** — Οι έγκυρες τιμές κατάστασης προέρχονται από το τρέχον pack του ιατρείου και όχι από λίστα ορισμένη στο API. Διαβάστε τες από το GET /api/v1/me αντί να τις γράψετε σταθερά, αλλιώς ένα ιατρείο με άλλο pack θα απορρίψει εγγραφές που ο client θεωρεί έγκυρες.

## Εμβέλεια και αναγνωριστικά

Κάθε endpoint εδώ απαιτεί ταυτοποίηση και λειτουργεί αποκλειστικά εντός του ιατρείου του καλούντος — το αίτημα δεν δηλώνει ποτέ δικό του practice id και δεν μπορεί να φτάσει σε αρχεία άλλου ιατρείου.

Τα τμήματα διαδρομής (`patientId`, `noteId`, `tagId`) πρέπει να είναι κανονικά UUID. Ένα κακοδιατυπωμένο id επιστρέφει `not_found` (404) χωρίς να φτάσει στο επίπεδο δεδομένων, οπότε ένα λανθασμένο id και ένα έγκυρο που δεν υπάρχει είναι δυσδιάκριτα. Αυτό είναι σκόπιμο: εμποδίζει το API να επιβεβαιώνει ποια id υπάρχουν.

## Το αντικείμενο του ασθενή

```json
{
  "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` κατά την εγγραφή και επιστρέφεται ως πλήρης χρονοσφραγίδα.

## Το αντικείμενο της σημείωσης

```json
{
  "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**

```json
{
  "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` | Ελεύθερο κείμενο. |
| `email` | `string \| null` | Έγκυρη διεύθυνση, εφόσον δοθεί. |
| `phoneMobile` | `string \| null` | Ελεύθερο κείμενο. |
| `address` | `string \| null` | Ελεύθερο κείμενο. |
| `postcode` | `string \| null` | Ελεύθερο κείμενο. |
| `country` | `string \| null` | Ελεύθερο κείμενο. |
| `status` | `string` | Πρέπει να ανήκει στις καταστάσεις του pack του ιατρείου, όχι σε σταθερή λίστα. |
| `notifyByEmail` | `boolean` | Αν επιτρέπεται email προς τον ασθενή. |
| `notifyBySms` | `boolean` | Αν επιτρέπεται SMS προς τον ασθενή. |

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

```json
{
  "firstName": "Jo",
  "lastName": "Doe",
  "dob": "1990-05-14",
  "status": "active"
}
```

**Απόκριση · 201**

```json
{
  "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**

```json
{
  "data": { "id": "0f1c7a2e-....", "firstName": "Jo", "lastName": "Doe" },
  "requestId": "req_5f2c1e40-...."
}
```

**Σφάλματα**

| Κωδικός | Κατάσταση | Πότε |
| --- | --- | --- |
| `not_found` | 404 | Το id δεν είναι UUID, δεν υπάρχει, ή ανήκει σε άλλο ιατρείο — και οι τρεις περιπτώσεις είναι δυσδιάκριτες. |

### PATCH /api/v1/patients/:patientId

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

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

| Πεδίο | Τύπος | Περιγραφή |
| --- | --- | --- |
| `patientId` (Υποχρεωτικό) | `uuid` | Κανονικό UUID. |

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

```json
{ "firstName": "Joanna" }
```

**Απόκριση · 200**

```json
{
  "data": { "id": "0f1c7a2e-....", "firstName": "Joanna" },
  "requestId": "req_5f2c1e40-...."
}
```

**Σφάλματα**

| Κωδικός | Κατάσταση | Πότε |
| --- | --- | --- |
| `validation_failed` | 400 | Ίδιοι κανόνες με τη δημιουργία ασθενή. |
| `not_found` | 404 | Δεν υπάρχει τέτοιος ασθενής στο ιατρείο. |

### DELETE /api/v1/patients/:patientId

Διαγράφει ασθενή.

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

| Πεδίο | Τύπος | Περιγραφή |
| --- | --- | --- |
| `patientId` (Υποχρεωτικό) | `uuid` | Κανονικό UUID. |

**Απόκριση · 200**

```json
{
  "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**

```json
{
  "data": { "id": "0f1c7a2e-....", "tagIds": ["b7e42d18-...."] },
  "requestId": "req_5f2c1e40-...."
}
```

**Σφάλματα**

| Κωδικός | Κατάσταση | Πότε |
| --- | --- | --- |
| `not_found` | 404 | Ο ασθενής ή η ετικέτα δεν υπάρχει στο ιατρείο. |

### GET /api/v1/patients/:patientId/notes

Επιστρέφει τις σημειώσεις ενός ασθενή.

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

| Πεδίο | Τύπος | Περιγραφή |
| --- | --- | --- |
| `patientId` (Υποχρεωτικό) | `uuid` | Κανονικό UUID. |

**Απόκριση · 200**

```json
{
  "data": { "notes": [] },
  "requestId": "req_5f2c1e40-...."
}
```

**Σφάλματα**

| Κωδικός | Κατάσταση | Πότε |
| --- | --- | --- |
| `not_found` | 404 | Δεν υπάρχει τέτοιος ασθενής στο ιατρείο. |

### POST /api/v1/patients/:patientId/notes

Προσθέτει σημείωση σε ασθενή.

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

| Πεδίο | Τύπος | Περιγραφή |
| --- | --- | --- |
| `patientId` (Υποχρεωτικό) | `uuid` | Κανονικό UUID. |

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

| Πεδίο | Τύπος | Περιγραφή |
| --- | --- | --- |
| `body` (Υποχρεωτικό) | `string` | Χωρίς κενά στα άκρα· δεν επιτρέπεται κενό. |
| `title` | `string \| null` | Προαιρετικός τίτλος. |
| `isNext` | `boolean` | Σημειώνει τη σημείωση ως επόμενη ενέργεια. |

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

```json
{
  "body": "Called patient to confirm appointment.",
  "isNext": true
}
```

**Απόκριση · 201**

```json
{
  "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` | Σημειώνει τη σημείωση ως επόμενη ενέργεια. |

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

```json
{ "title": "Follow-up" }
```

**Απόκριση · 200**

```json
{
  "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**

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

**Σφάλματα**

| Κωδικός | Κατάσταση | Πότε |
| --- | --- | --- |
| `not_found` | 404 | Δεν υπάρχει τέτοιος ασθενής ή σημείωση στο ιατρείο. |

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

### Πώς προστατεύονται τα δεδομένα των ασθενών;

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

### Είναι η κατάσταση ασθενή σταθερό σύνολο τιμών;

Όχι. Οι έγκυρες τιμές προέρχονται από το τρέχον pack του ιατρείου και όχι από σταθερή λίστα του API, και επιστρέφονται από το GET /api/v1/me. Δημιουργία ή ενημέρωση με κατάσταση εκτός λίστας επιστρέφει validation_failed με τη διαδρομή του πεδίου.

### Γιατί ένα λανθασμένο id επιστρέφει 404 και όχι 400;

Επειδή ένα κακοδιατυπωμένο id και ένα έγκυρο id άλλου ιατρείου πρέπει να φαίνονται ίδια από έξω. Αν το ένα επέστρεφε 400 και το άλλο 404, η διαφορά θα επέτρεπε σε κάποιον να επιβεβαιώσει ποια id υπάρχουν σε άλλα ιατρεία.

### Κρατούν οι σημειώσεις ιστορικό αλλαγών;

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