# API Dokumentáció

- [Általános tudnivalók](#általános-tudnivalók)
- [Vizsgálatkérő beküldése](#vizsgálatkérő-beküldése)
  - [Közös mezők](#közös-mezők)
  - [cytological](#cytological)
  - [dermatopathological](#dermatopathological)
  - [oncological](#oncological)
  - [pathological](#pathological)
  - [Válasz](#válasz)
- [Lezárás értesítés (Mátrix → PraxisLab)](#lezárás-értesítés-mátrix--praxislab)
- [Iktatás adatai](#iktatás-adatai)
- [Makró kép letöltése](#makró-kép-letöltése)
- [Indítási PDF letöltése](#indítási-pdf-letöltése)
- [Szimuláció (csak teszt rendszeren)](#szimuláció-csak-teszt-rendszeren)

## Általános tudnivalók

- Teszt rendszer elérhetősége: `https://matrix.matrix-lab.hu/api`
- Hitelesítés API kulccsal, amit az `X-KEY` headerben kell átadni.
- JSON alapú adat kommunikáció, ezért kötelező a `Content-Type: application/json` és az `Accept: application/json` header beállítása.
- Az `Accept: application/json` nélkül a `file1`–`file3` állományok nem kerülnek mentésre!
- Minden base64 mezőt nyers base64 formában kell küldeni, `data:...;base64,` előtag nélkül.

## Vizsgálatkérő beküldése

`POST /api/inquiry`

A `type` mező értékétől függően a közös mezők mellett további mezők szükségesek.

### Közös mezők

- **office_name** — `required|text`
  Rendelő neve
- **type** — `required|in:cytological,dermatopathological,oncological,pathological`
  Vizsgálatkérő típusa
- **veterinarian** — `required|text`
  Beküldő állatorvos
- **email** — `email`
  Extra értesítési cím. Ha nincs, a mezőt ki kell hagyni, `null` vagy üres szöveg hibát ad.
- **diagnosis** — `required|in:Egyszerű diagnózist kérek!,Részletes diagnózist kérek!`
  Diagnózis típusa (cytological típusnál nem kell)
- **sample** — `required|in:Sürgősségi minta!,Nem sürgősségi minta!`
  Sürgősségi minta (cytological típusnál nem kell)
- **animal_name** — `required|text`
  Állat neve/jelölése
- **owner_name** — `required|text`
  Tulajdonos neve
- **species** — `required|in:Kutya,Macska,Madár,Ló,Egzotikus,Állatkerti állat/Vadállat,Egyéb`
  Faj
- **species_other** — `required_if:species,Egyéb`
  Faj egyéb
- **breed** — `required|text`
  Fajta
- **sex** — `required|in:Nőivarú,Hím,Ivartalanított nőivarú,Ivartalanított hím`
  Ivara
- **age** — `required|text`
  Kor
- **color** — `required|text`
  Szín
- **file1**, **file2**, **file3** — `base64`
  Állomány 1–3
- **file1_name**, **file2_name**, **file3_name** — `required_with:fileN|text|max:255`
  Állomány 1–3 neve
- **generalize** — `in:Testszerte/generalizáltan`
  Elváltozás helye
- **sampling_date** — `text`
  Mintavétel dátuma
- **bill_name** — `text`
  Számlázási név
- **bill_address** — `text`
  Számlázási cím
- **bill_tax** — `text`
  Számlázási adószám
- **barcode_use** — `array`
  Felhasznált vonalkódok (a rendelőhöz kiadott, még fel nem használt vonalkód)
- **barcode_note** — `array`
  Vonalkódokhoz tartozó megjegyzés, a `barcode_use` azonos kulcsával

A `canvas1_image` – `canvas5_image` mezők: nyers base64, JPG vagy PNG, maximum 5MB.

### cytological

- **aspiration_sample** — `required_without:body_fluid|array|in:Hasüregi / testüregi,Mellüregi,Vese,Emlő,Tüdő,Orrüreg,Szájüreg,Máj,Prosztata,Bőr tumor (Jelölje a rajzon!),Nyirokcsomó,Egyéb`
  Aspirációs minta/lenyomati készítmény/kaparék
- **lymph_node** — `text` (nincs ellenőrizve, csak tárolásra kerül)
  Nyirokcsomó esetén
- **aspiration_other** — kötelező, ha az `aspiration_sample` tartalmazza az `Egyéb` értéket, `text`
  Egyéb esetén
- **body_fluid** — `required_without:aspiration_sample|array|in:Abdominalis vagy testüregi (Coelomicalis),Pericardialis,Thoracalis,BAL (Bronchoalveolaris lavage),CSF (Cerebrospinalis folyadék),Izületi folyadék (Synovia),Vizelet,Egyéb`
  Testüri folyadék
- **body_fluid_other** — kötelező, ha a `body_fluid` tartalmazza az `Egyéb` értéket, `text`
  Testüri folyadék egyéb
- **records** — `required|array`
  Legalább egy elem kötelező
- **records.[index].changes_tact** — `array|in:Lágy,Hullámzó,Rugalmas,Tömött,Csontkemény`
  Elváltozás tapintata
- **records.[index].nearby_lymph_nodes** — `required|array|in:Ép,Megnagyobbodott,Beolvadt,Nem vizsgált`
  Környéki nyirokcsomók
- **records.[index].other_features** — `array|in:Fájdalmas,Kifekélyesedett,Ép felszínű,Kipirult,Ödéma,Szőrtelen`
  Egyéb jellemzők
- **records.[index].lesion_size_width** — `required|text`
  Elváltozás szélessége
- **records.[index].lesion_size_height** — `required|text`
  Elváltozás magassága
- **records.[index].how_long** — `required|text`
  Mióta észlelik
- **records.[index].medical_history** — `required|text`
  Kórelőzmény
- **canvas1_image** – **canvas5_image** — `base64`

### dermatopathological

- **keeping_place** — `in:Bent tartott,Kint tartott`
  Tartás helye
- **worse** — `in:Tavasz/Nyár,Ősz/Tél`
  Rosszabb
- **further_test** — `array|in:Specifikus festés,Immunhisztokémia,Klonalitás vizsgálat,PCR`
  További vizsgálatot kérek
- **first_symptom_age** — `required|text`
  Az állat kora a tünetek első észlelésekor
- **clinical_appearance** — `required|array|in:Papula/Nodulus,Vezikulum,Pusztula,Plakk,Alopecia,Folt,Bőrpír/Vérzés,Erózió/Fekély,Hyperpigmentáció,Seborrhea/Korpázás,Epidermalis collarette,Tályog,Ödéma,Ciszta,Comedone,Lichenifikáció,Egyéb`
  Az elváltozások klinikai megjelenése
- **scratching** — `required|in:Van/Volt,Nincs`
  Vakarózás
- **seasonality** — `required|in:Igen,Nem`
  Szezonalitás
- **steroid_therapy** — `array|in:Szteroid terápia,Egyéb`
  Alkalmazott kezelések
- **steroid_therapy_other** — kötelező, ha a `steroid_therapy` tartalmazza az `Egyéb` értéket, `text`
  Alkalmazott kezelések egyéb
- **previous_diseases** — `required|text`
  Korábbi bőrgyógyászati vagy egyéb betegségek, kórelőzmény
- **canvas1_image** – **canvas5_image** — `required|base64`

### oncological

- **records** — `required|array`
  Legalább egy elem kötelező
- **records.[index].sample_type** — `required|in:Endoszkópos minta / Tűbiopszia,Punchbiopszia,Próbakimetszés,Teljes eltávolítás`
  Minta típusa
- **records.[index].submitted_type** — `required|in:Teljes kimetszés,Kimetszés részlet,Elváltozás részlet`
  Beküldve
- **records.[index].wound_edges** — `required|in:Igen,Nem`
  Sebszél-bírálatot kérek
- **records.[index].comes_from** — `required|text`
  Honnan származik? (Rajzon is lehet jelölni!)
- **records.[index].lesion_size_width** — `required|text`
  Elváltozás szélessége
- **records.[index].lesion_size_height** — `required|text`
  Elváltozás magassága
- **records.[index].how_long** — `required|text`
  Mióta észlelik?
- **records.[index].lesion_count** — `required|text`
  Az elváltozások száma
- **records.[index].changes_tact** — `array|in:Lágy,Hullámzó,Rugalmas,Tömött,Csontkemény`
  Elváltozás tapintata
- **records.[index].nearby_lymph_nodes** — `required|array|in:Ép,Megnagyobbodott,Beolvadt,Nem vizsgált`
  Környéki nyirokcsomók
- **records.[index].other_features** — `array|in:Fájdalmas,Kifekélyesedett,Ép felszínű,Kipirult,Ödéma,Szőrtelen`
  Egyéb jellemzők
- **records.[index].differencial** — `required|text`
  Kórelőzmény, differenciál diagnózis
- **skin_subcutaneous_sensory_organs** — `required_without:lymph_node|array|in:Fej,Szem tájék/Szemgolyó,Fül tájék,Pofa tájék,Orr tájék/Orrüreg,Ajak tájék,Szájüreg/Maxillofacialis tájék/Garat/Gége,Nyak tájék/Nyálmirigy/Pajzsmirigy,Váll tájék/Lapocka tájék,Hónalj tájék,Szügy/Mellkas tájék,Has tájék,Emlő tájék,Lágyék tájék,Nemi szervek tájéka,Perianalis tájék,Hát tájék,Far tájék,Farok,Láb/Lábvég`
  Bőr/Bőr alatti kötőszövet/Érzékszervek
- **lesion_color** — `text` (nincs ellenőrizve, csak tárolásra kerül)
  Elváltozás színezete
- **lymph_node** — `required_without:skin_subcutaneous_sensory_organs|array|in:Nyirokcsomó,Mellüreg/Pleura/Pericardium,Tüdő,Szív,Hasüreg/Peritoneum,Medenceüreg,Gyomor-bélcsatorna,Lép,Máj,Hasnyálmirigy,Vese,Mellékvese,Petefészek/Méh,Hím nemiszervek,Központi idegrendszer/Agy/Gerincvelő`
  Egyéb szervek/szövetek
- **further_test** — `array|in:Specifikus festés,Immunhisztokémia,Klonalitás vizsgálat,PCR` (nincs ellenőrizve, csak tárolásra kerül)
  További vizsgálatot kérek
- **canvas1_image** – **canvas5_image** — `required|base64`

### pathological

- **submitted_sample** — `required|array|in:Bőr,Csont / Csontvelő,Ízület,Vázizom,Agyvelő / Gerincvelő,Tüdő,Szív,Gyomor,Vékonybél,Vastagbél,Hasnyálmirigy,Máj,Lép,Vese,Petefészek / Méh,Here,Egyéb,Szervkolleció,Teljes hulla,Pajzsmirigy,Mellékvese`
  Beküldött minta
- **submitted_sample_other** — kötelező, ha a `submitted_sample` tartalmazza az `Egyéb` értéket, `text`
  Beküldött minta egyéb
- **medical_history** — `required|array|in:Hirtelen elhullás,Anorexia,Takarmányozással összefüggő,Multifaktoriális,Fertőző eredetű,Kullancs- / Rovarcsípés,Mérgezés,Szaporodásbiológiai,Neurológiai,Emésztőszervi,Metabolikus zavar,Légzőszervi Szív-/ érrendszeri,Húgyszervi,Csont- és/vagy vázizom rendszer,Ektoparazitás,Endoparazitás,Neonatális,Neoplasia`
  Kórelőzmény/klinikai adatok
- **autopsy** — `required|text`
  Boncolási lelet (szervkollekció esetén)
- **additional_tests** — `required|text`
  Kiegészítő vizsgálatok (bakteriológia, virológia, szerológia, stb.) eredményei
- **canvas1_image** – **canvas5_image** — `required|base64`

### Válasz

`201` – sikeres beküldés, az `id` a vizsgálatkérő azonosítója:

```json
{"success": true, "id": 123}
```

`422` – hibás adatok:

```json
{"success": false, "message": "Validation failed", "errors": {"mező": ["hibaüzenet"]}}
```

`422` – nem található rendelő:

```json
{"success": false, "message": "Unable to find office", "errors": []}
```

## Lezárás értesítés (Mátrix → PraxisLab)

Amikor egy PraxisLab-ból érkezett vizsgálatkérőből létrejött iktatás lezárásra kerül, a Mátrix egy hívást küld a PraxisLab felé. Sikertelen hívás esetén 60 másodpercenként még kétszer próbálkozik.

```
POST https://flexilab-dev.arteries.hu/api/matrix/finished
X-KEY: <PraxisLab által megadott kulcs>
```

```json
{"inquiry_id": 123, "registration_book_id": 456}
```

A `registration_book_id` azonosítóval kérhetők le az iktatás adatai az alábbi hívásokkal.

## Iktatás adatai

`GET /api/registration_book/{registration_book_id}`

`200`:

```json
{
    "success": true,
    "id": 456,
    "more_makroszkop": "Makroszkópos lelet szövege",
    "processing": true,
    "files": [
        {"id": 101, "name": "photo_1_1_101500.jpg", "mime_type": "image/jpeg", "size": 12345, "created_at": "2026-11-05T10:15:00.000000Z"}
    ]
}
```

- **processing** — van-e lekérhető indítási PDF
- **files** — makró képek listája, letöltés a [Makró kép letöltése](#makró-kép-letöltése) hívással

`401` – nem PraxisLab-ból érkezett iktatás:

```json
{"success": false, "message": "Unauthorized"}
```

## Makró kép letöltése

`GET /api/registration_book/{registration_book_id}/attachment/{file_id}`

`200`:

```json
{"success": true, "id": 101, "name": "photo_1_1_101500.jpg", "mime_type": "image/jpeg", "content": "<base64>"}
```

- `401` – `{"success": false, "message": "Unauthorized"}`
- `404` – `{"success": false, "message": "Not found"}`

## Indítási PDF letöltése

`GET /api/registration_book/{registration_book_id}/processing`

A PDF minden hívásnál az aktuális adatokból készül.

`200`:

```json
{"success": true, "name": "inditas_2026_0123.pdf", "mime_type": "application/pdf", "content": "<base64>"}
```

- `401` – `{"success": false, "message": "Unauthorized"}`
- `404` – `{"success": false, "message": "Not found"}`, még nincs indítási adatlap

## Szimuláció (csak teszt rendszeren)

`GET /api/inquiry/{inquiry_id}/simulate`

A beküldött vizsgálatkérőt végigviszi a laborfolyamaton, mintha kézzel csinálták volna: átemelés iktatásba, makroszkópos lelet szöveg, indítási adatlap 2 makró képpel, lezárás. A lezárás elküldi a [lezárás értesítést](#lezárás-értesítés-mátrix--praxislab) is.

`200`:

```json
{"success": true, "inquiry_id": 123, "registration_book_id": 456}
```

- `401` – `{"success": false, "message": "Unauthorized"}`, nem PraxisLab-ból érkezett vizsgálatkérő
- `208` – `{"success": false, "message": "Already processed"}`, már át lett emelve
- `404` – `{"success": false, "message": "Not found"}`, éles rendszeren nem elérhető