# Ξεκινώντας

> Από ένα κλειδί API μέχρι την ανάγνωση και εγγραφή του αρχείου FHIR R4 ενός ασθενούς στο sandbox: κλειδιά, πρώτες κλήσεις, εγγραφές με προέλευση, έγγραφα, πλαίσιο AI, IPS, συναίνεση, webhooks και εργαστηριακές αναφορές.

Source: https://developers.anpheros.com/el/guides/getting-started

Η πλατφόρμα Anpheros είναι ένα backend υγειονομικών δεδομένων: ένα αρχείο FHIR R4 ανά ασθενή, απομόνωση έργου,
προέλευση σε κάθε εγγραφή και ένα απλό REST API πάνω από τα ίδια δεδομένα. Αυτός ο οδηγός σας μεταφέρει
από το μηδέν στην ανάγνωση και εγγραφή του αρχείου ενός ασθενούς στο sandbox.

Βασικό URL (το sandbox και η παραγωγή το μοιράζονται· το κλειδί αποφασίζει το επίπεδο δεδομένων):

```
https://platform.anpheros.com
```

Διαδραστική αναφορά: `/docs` (OpenAPI) και `/fhir/R4/metadata` (CapabilityStatement).

## 1. Λήψη κλειδιού (1 λεπτό)

Το sandbox είναι αυτοεξυπηρετούμενο. Συνδεθείτε στον πίνακα ελέγχου (`https://platform.anpheros.com/dashboard/`)
με τον λογαριασμό σας Google και πατήστε **Λήψη κλειδιού sandbox**: θα λάβετε έναν οργανισμό, ένα έργο sandbox με τους δικούς του
συνθετικούς ασθενείς και ένα κλειδί — που εμφανίζεται μία φορά. Το ίδιο μέσω του Admin API, με το Firebase user token σας:

```bash
curl -X POST $BASE/admin/sandbox/quickstart -H "Authorization: Bearer $FIREBASE_ID_TOKEN"
# {"organization": {…}, "project": {"id": "proj_…", "environment": "sandbox", …}, "key": {"key": "sk_test_…", …}, "sandbox": {…}}
```

Ή βήμα προς βήμα:

```bash
# 1. an organization (you become its owner)
curl -X POST $BASE/admin/organizations -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"CardioAI SRL","kind":"developer","country":"RO"}'
# 2. a sandbox project (it comes with its own synthetic patients)
curl -X POST $BASE/admin/organizations/org_…/projects -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"CardioAI dev","environment":"sandbox"}'
# 3. a key — the plain key is returned exactly once
curl -X POST $BASE/admin/projects/proj_…/keys -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"local dev","scopes":["read","write"]}'
```

Θα λάβετε `sk_test_…`. Τα κλειδιά sandbox βλέπουν μόνο δεδομένα sandbox. Τα κλειδιά παραγωγής (`sk_live_…`)
εκδίδονται σε επαληθευμένους οργανισμούς με υπογεγραμμένη συμφωνία DPA — γράψτε στο platform@anpheros.com. Το sandbox είναι δωρεάν·
η παραγωγή ξεκινά από 99€ το μήνα και ο πρώτος μήνας είναι δωρεάν (δείτε [Τιμολόγηση](https://developers.anpheros.com/el/guides/pricing)).

## 2. Πρώτη κλήση (1 λεπτό)

Το project sandbox σας έχει ήδη τη δική του αντιγραφή 30 συνθετικών ασθενών, με έξι μήνες ιστορικό
μέχρι την ημέρα δημιουργίας του project: ενήλικες, παιδιά και ηλικιωμένους από όλη την ΕΕ, με
παθήσεις (ICD-10), φαρμακευτική αγωγή (ATC), αλλεργίες, εργαστηριακά αποτελέσματα και ζωτικά σημεία (LOINC). Η αντιγραφή
ανήκει στο project σας: αλλάξτε ή διαγράψτε οτιδήποτε — κανένα άλλο project δεν το βλέπει. Η επιλογή **Επαναφορά δοκιμαστικών ασθενών**
στο dashboard (ή `POST /admin/projects/{id}/sandbox/reset`) τους επαναφέρει όπως ήταν, με νέα ids· οι ασθενείς που δημιουργήσατε μόνοι σας δεν επηρεάζονται. Κάθε συνθετικός ασθενής διατηρεί ένα
σταθερό αναγνωριστικό μετά από επαναφορές: η `Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02`
είναι πάντα η Elena Ionescu.

```bash
export KEY=sk_test_…
curl $BASE/v1/patients -H "Authorization: Bearer $KEY"
```

```json
{"data":[{"id":"…","given":"Elena","family":"Ionescu","birth_date":"1985-09-03","gender":"female",…,"fhir":"Patient/…"}, …],"total":30,"next_cursor":null}
```

Τα όρια του Sandbox είναι γενναιόδωρα αλλά πεπερασμένα: 10.000 εγγραφές πόρων την ημέρα ανά project, 50 δικοί σας ασθενείς εκτός από τους συνθετικούς, 250 MB εγγράφων (βλ. [όρια](https://developers.anpheros.com/el/guides/limits)).

## 3. Ανάγνωση εγγραφής

```bash
# lab results, newest first
curl "$BASE/v1/patients/$PID/observations?category=laboratory&limit=10" -H "Authorization: Bearer $KEY"
# active medications
curl "$BASE/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
# everything on one timeline
curl "$BASE/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
# the same data, strict FHIR
curl "$BASE/fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date" -H "Authorization: Bearer $KEY"
```

Τα αναγνωριστικά είναι πανομοιότυπα στα `/v1` και `/fhir/R4`· κάθε αντικείμενο v1 φέρει την αναφορά `fhir` του.
Το `_summary=count` επιστρέφει μόνο το σύνολο· το `_elements=code,effectiveDateTime` επιστρέφει λιτές πηγές με την ετικέτα `SUBSETTED`.

## 4. Εγγραφή

Δηλώστε ποιος είναι ο συγγραφέας. Το `author_type` είναι `patient`, `practitioner`, `device`, `import` ή `ai`.
αν το παραλείψετε, η πλατφόρμα καταγράφει `import`, ποτέ `patient` εξ ορισμού.
Οι εγγραφές με `author_type` `ai` ακολουθούν το [HL7 AI Transparency on FHIR](https://build.fhir.org/ig/HL7/aitransparency-ig/):
ο πόρος φέρει την ετικέτα ασφαλείας `AIAST` (*Artificial Intelligence asserted*) και η Απόδειξή του (Provenance) έχει τον λόγο
`AIAST`, τον ρόλο του πράκτορα (agent role) `Artificial-Intelligence` και το προφίλ `AI-Provenance`. Για να ονομάσετε το μοντέλο, καταχωρήστε το ως
`Device` (τύπος `Artificial-Intelligence`, όνομα, έκδοση, κατασκευαστής) και στείλτε `X-Anpheros-Author-Ref: Device/<id>`.

```bash
curl -X POST "$BASE/v1/patients/$PID/observations" -H "Authorization: Bearer $KEY" \
     -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "2339-0", "display": "Glucose", "category": "laboratory",
  "value": 112, "unit": "mg/dL", "effective_at": "2026-09-19T08:10:00Z",
  "author_type": "device"
}'
```

Η απόκριση είναι η αποθηκευμένη παρατήρηση με `id`, `fhir` και `updated_at`. Η επανάληψη του ακριβώς
ίδιου αιτήματος με την ίδια `Idempotency-Key` επιστρέφει την ίδια απόκριση και δεν δημιουργεί τίποτα.

## 5. Έγγραφα

```bash
# 1. create the document → upload target
curl -X POST "$BASE/v1/patients/$PID/documents" -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"title":"Analize 2026-09-14","kind":"lab_report","content_type":"application/pdf","date":"2026-09-14"}'
# 2. upload the bytes to the returned url (direct to storage, or through the platform)
curl -X PUT "$BASE/v1/documents/$DOC/content" -H "Authorization: Bearer $KEY" -H 'content-type: application/pdf' --data-binary @analize.pdf
```

Το πρωτότυπο δεν τροποποιείται ποτέ μετά από αυτό· `sha256` και `size` καταγράφονται, και οποιεσδήποτε τιμές
εξάγετε αργότερα δείχνουν πίσω στο έγγραφο μέσω του `derived_from`.

## 6. Προέλευση

```bash
curl "$BASE/v1/patients/$PID/provenance/Observation/$OBS" -H "Authorization: Bearer $KEY"
```

Μία καταχώρηση ανά έκδοση: ποιος (τύπος συγγραφέα και έργο), πότε, από ποιο σύστημα πηγής.

## Κανόνες που αξίζει να γνωρίζετε

- **Απομόνωση**: ένα project βλέπει τους ασθενείς που δημιούργησε (συν τους κοινόχρηστους ασθενείς του sandbox). Ο ασθενής κάποιου άλλου δεν υπάρχει για εσάς: `404`, ποτέ `403`.
- **Αντίστοιχα αναγνωριστικά (Pairwise ids)**: το αναγνωριστικό ασθενούς που βλέπετε είναι δικό σας. Ένα άλλο project βλέπει το ίδιο άτομο με διαφορετικό αναγνωριστικό. Αποθηκεύστε ελεύθερα τα αναγνωριστικά μας· ποτέ μην προσπαθήσετε να τα συσχετίσετε.
- **Προέλευση (Provenance)**: κάθε εγγραφή αφήνει έναν πόρο Provenance. Τίποτα δεν αντικαθίσταται σιωπηλά· το ιστορικό είναι διαθέσιμο στο `/fhir/R4/{Type}/{id}/_history`.
- **Σφάλματα**: τα FHIR endpoints επιστρέφουν `OperationOutcome`· τα `/v1` και `/admin` επιστρέφουν `{"error": {"type", "message", "field"}}`. Κάθε απόκριση φέρει `Anpheros-Request-Id`· παραθέστε το όταν επικοινωνείτε μαζί μας.
- **Όρια**: 600 αιτήματα/λεπτό ανά κλειδί από προεπιλογή, 200 στοιχεία ανά σελίδα, 25 MB ανά έγγραφο.

## 7. Πλαίσιο για ένα μοντέλο Τεχνητής Νοημοσύνης

Αντί να ανακτάτε ακατέργαστες εγγραφές και να αποφασίζετε τι ταιριάζει σε μια προτροπή, ζητήστε από την πλατφόρμα ένα πλαίσιο:

```bash
curl -X POST "$BASE/v1/context" -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -d '{
  "patient": "'$PID'",
  "task": "medication review before a cardiology visit",
  "question": "How did blood pressure evolve over the last 3 months?",
  "budget_tokens": 1500,
  "format": "text"
}'
```

Λαμβάνετε ενότητες (κάρτα σύνοψης, καταστάσεις υγείας, φαρμακευτική αγωγή, αλλεργίες, εργαστηριακές εξετάσεις, ζωτικά σημεία με εβδομαδιαίες τάσεις και δείκτες πριν/μετά τη θεραπεία, συμπτώματα, χρονοδιάγραμμα, έγγραφα), κάθε στοιχείο επισημαίνεται με `author_type` και `source`, μια λίστα με ό,τι παραλείφθηκε για να ταιριάζει στον προϋπολογισμό, προειδοποιήσεις και ένα `manifest_id` που συνδέει την κλήση με το αρχείο ελέγχου. Οι τιμές που παράγονται από την ΤΝ δεν αναμιγνύονται ποτέ με γεγονότα: εμφανίζονται μόνο κάτω από το `ai_notes`. Γίνονται επίσης αποδεκτές ρητές ανάγκες:
`"needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]`.

## 8. Πρότυπα

- Το `GET /fhir/R4/Patient/{id}/$summary` επιστρέφει ένα έγγραφο International Patient Summary Bundle.
- Το `POST /fhir/R4/Observation/$validate?profile=eu-lab` αναφέρει πώς ένα εργαστηριακό αποτέλεσμα συγκρίνεται με το προφίλ αποτελέσματος HL7 Europe Laboratory Report 2.1.0 (σφάλματα, προειδοποιήσεις, πληροφορίες): κατηγορία, κωδικός (προτιμάται LOINC), υποκείμενο, χρόνος ισχύος, εκτελεστής και τιμή, εκτός αν το αποτέλεσμα έχει μόνο καταχωρηθεί ή ακυρωθεί.
- Το `GET /v1/terminology/loinc?q=hba1c` αναζητά το ομαδοποιημένο υποσύνολο LOINC και το `GET /v1/search?q=metformin` τον κατάλογο συμπτωμάτων, καταστάσεων και φαρμάκων. Οι παρατηρήσεις που δημιουργούνται χωρίς όνομα εμφάνισης λαμβάνουν αυτόματα το όνομα LOINC.

## 9. Συγκατάθεση ασθενούς (OAuth 2.1 + SMART on FHIR)

Τα κλειδιά API βλέπουν τους ασθενείς που δημιούργησε το έργο σας. Για να αποκτήσετε πρόσβαση σε υπάρχον αρχείο ενός ατόμου, ζητήστε του:

1. Εγγραφή μιας εφαρμογής: `POST /admin/projects/{id}/applications` με το redirect URI σας
   (`public` για εφαρμογές κινητών/web με PKCE, `confidential` για διακομιστές· το μυστικό εμφανίζεται μία φορά).
2. Στείλτε το άτομο στη σελίδα συγκατάθεσης:
   `GET /oauth/authorize?response_type=code&client_id=…&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256&scope=patient/Observation.rs?category=laboratory patient/MedicationStatement.r offline_access&purpose=treatment&lang=ro`
   Συνδέεται στο Anpheros, βλέπει τι ζητάτε σε απλή γλώσσα, επιλέγει το αρχείο (το δικό του,
   ενός εξαρτώμενου, ή αυτό που δημιούργησε η εφαρμογή σας για αυτόν) και πόσο διαρκεί η πρόσβαση.
3. Ανταλλαγή του κωδικού: `POST /oauth/token` (`authorization_code` + `code_verifier`). Λαμβάνετε ένα
   access token (30 λεπτά), ένα refresh token (30 ημέρες, εναλλάσσεται κατά τη χρήση) και το αναγνωριστικό ασθενούς.
4. Κλήση του API με `Authorization: Bearer at_…`. Βλέπετε μόνο αυτόν τον ασθενή, μόνο τους τύπους πόρων
   και τις ενέργειες στα scopes· οι αναγνώσεις εκτός scope απαντούν `403`, οι αναζητήσεις φιλτράρονται.

Το άτομο μπορεί να ανακαλέσει ανά πάσα στιγμή από το Anpheros· η επόμενη κλήση απαντά `401`. Κάθε παραχώρηση αντικατοπτρίζεται ως πόρος FHIR `Consent`, και κάθε πρόσβαση υπό αυτήν καταγράφεται και είναι ορατή στο
άτομο. Ανακάλυψη: `/.well-known/smart-configuration`.

## 10. Webhooks

Αφήστε την πλατφόρμα να σας καλέσει αντί να κάνετε polling:

```bash
curl -X POST $BASE/v1/webhooks -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://your.app/anpheros/hook", "events": ["*"]}'
```

Διατηρήστε το `secret` από την απόκριση και επαληθεύστε το `Anpheros-Signature` σε κάθε παράδοση
(`verifyWebhookSignature` και στα δύο SDKs). Τα γεγονότα φέρουν αναγνωριστικά και εκδόσεις, όχι κλινικά δεδομένα.
Λεπτομέρειες, επαναδοκιμές και παραδείγματα: [webhooks.md](https://developers.anpheros.com/el/guides/webhooks).

## 11. Οργανισμοί και Επαγγελματίες

Οι κλινικές, τα εργαστήρια και οι άνθρωποι που εργάζονται εκεί είναι πόροι πρώτης τάξεως: `Organization`, `Practitioner`, `PractitionerRole`. Είναι πόροι **καταλόγου**: κανένας ασθενής, αναγνώσιμος από κάθε έργο στο ίδιο περιβάλλον, τροποποιήσιμος μόνο από το έργο που τους δημιούργησε.

```bash
curl -X POST $BASE/fhir/R4/Practitioner -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Practitioner","active":true,"name":[{"family":"Popescu","given":["Ana"],"prefix":["Dr."]}]}'
```

Ονομάστε τον επαγγελματία πίσω από μια εγγραφή με `X-Anpheros-Author-Ref: Practitioner/<id>` (ή ένα `PractitionerRole`, `Organization`, `Device`): το Provenance που δημιουργείται από τον διακομιστή φέρει τότε το `agent.who.reference`, και το `GET /fhir/R4/Provenance?agent=Practitioner/<id>` παραθέτει όλα όσα κατέγραψε αυτό το άτομο. Αναζήτηση: `Organization?name=`, `?identifier=`, `?type=`, `Practitioner?name=`, `?family=`, `?given=`, `PractitionerRole?practitioner=`, `?organization=`, `?role=`, `?specialty=`, `?active=`.

Ποιος εργάζεται πίσω από την εφαρμογή σας; Στείλτε `X-Anpheros-Acting-As: PractitionerRole/<id>` (ή `Practitioner/<id>`) σε οποιοδήποτε αίτημα `/v1` ή `/fhir/R4` που γίνεται με κλειδί έργου. Το άτομο πρέπει να υπάρχει στον κατάλογο και να είναι ενεργό. Η αναφορά γράφεται στο αρχείο καταγραφής πρόσβασης, γίνεται ο συγγραφέας των εγγραφών του αιτήματος (εκτός αν ορίσετε `X-Anpheros-Author-Ref`) και εμφανίζεται στον ασθενή με το όνομα στις συνδέσεις του ("Δρ. Άννα Παπαδοπούλου · Clinica Dente διάβασε τα εργαστηριακά σας αποτελέσματα").

## 12. Εργαστηριακές αναφορές σε μία κλήση

Στείλτε μια ολόκληρη εργαστηριακή αναφορά (CSV, HL7 v2 ORU^R01 ή JSON) και λάβετε εργαστηριακές Παρατηρήσεις (Observations) με LOINC και εύρη αναφοράς. Η επανυποβολή είναι ασφαλής. Λεπτομέρειες: [lab-connector.md](https://developers.anpheros.com/el/guides/lab-connector).

```bash
curl -X POST "$BASE/v1/patients/$PATIENT/labs/import" -H "Authorization: Bearer $KEY" -H "Content-Type: text/csv" --data-binary @report.csv
```

## Ανατροφοδότηση συμμόρφωσης σε εγγραφές

Κάθε `POST`/`PUT` ενός κλινικού πόρου ελέγχεται έναντι του προφίλ IPS της ενότητάς του και, για
εργαστηριακές παρατηρήσεις, τους κανόνες αναφοράς εργαστηρίου HL7 Europe. Η εγγραφή δεν απορρίπτεται ποτέ για
λόγους προφίλ (δομικά σφάλματα FHIR εξακολουθούν να απορρίπτονται). Όταν κάτι λείπει, η απόκριση φέρει

```
Anpheros-Conformance: warnings=2; IPS Condition: Condition without code | ...
```

Διορθώστε αυτό που ονομάζει και ο πόρος θα συμπεριληφθεί στο `$summary` του ασθενούς. Τύποι πόρων που προστέθηκαν
στις 22 Σεπτεμβρίου 2026: `Immunization`, `MedicationAdministration` (αναζήτηση `statement=MedicationStatement/{id}`),
`RelatedPerson`, `QuestionnaireResponse`, `Basic`. Εγγραφές που γίνονται από άλλα έργα σε ένα αρχείο που μπορείτε να
δείτε, φτάνουν ως συμβάντα webhook με `data.external = true` — δείτε [`docs/webhooks.md`](https://developers.anpheros.com/el/guides/webhooks).