API e Pacientëve

Çfarë do të ndërtoni

Dentare ofron një API REST për menaxhimin e pacientëve në mënyrë programatike. Përdoreni për të importuar një listë pacientësh nga sistemi i vjetër, për të sinkronizuar pacientë nga një sistem tjetër, ose për të ndërtuar integrime të personalizuara mbi të dhënat e klinikës suaj.

Ky udhëzues ju çon nga zero deri tek një integrim funksional: gjeneroni një token, ekzekutoni kërkesën tuaj të parë të autentifikuar, pastaj ecni nëpër ciklin e plotë CRUD me shembuj curl të gatshëm për kopjim për çdo operacion.

Para se të filloni

Autentifikimi

Si funksionon

Çdo kërkesë drejt API-së duhet të përfshijë një token Bearer në header-in Authorization. Tokenët janë të kufizuar në llogarinë tuaj - mund të lexojnë ose ndryshojnë vetëm të dhënat që i përkasin klinikës suaj, jo llogarive të tjera Dentare.

Tokenët nuk skadojnë automatikisht. Mund t'i revokoni në çdo kohë nga paneli i administrimit.

Gjeneroni një token API

Bëni kërkesën tuaj të parë të autentifikuar

"Pinga" më e thjeshtë që mund të ekzekutoni është të merrni profilin tuaj nga /api/v1/me.json. Nëse tokeni juaj funksionon, do të merrni një përgjigje 200 me informacionin e llogarisë suaj.

curl https://dentare.io/api/v1/me.json \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Përgjigja e pritshme:

{
  "id": 1,
  "name": "Emri Juaj",
  "avatar_url": "https://dentare.io/users/1/avatar.png",
  "sgid": "BAh7CEkiCGdpZAY6BkVUS..."
}

Një 200 me këtë trup konfirmon se tokeni funksionon. Fushat id dhe name janë më të dobishmet për kontroll të shpejtë. sgid është një ID globale e nënshkruar e përdorur në brendësi dhe mund ta injoroni.

Gabimet e zakonshme të autentifikimit

Revokoni një token

Nëse një token rrjedh, përfundon në duar të gabuara, ose nuk është më i nevojshëm, revokojeni nga paneli i administrimit. Tokeni ndalon së punuari menjëherë.

URL bazë dhe headerët

Listoni pacientët

GET /api/v1/patients

Kthen një listë të faqezuar të pacientëve në llogarinë tuaj. Vetëm pacientët aktivë si parazgjedhje.

Shembull bazë

curl https://dentare.io/api/v1/patients \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

GET {{baseUrl}}/patients
Authorization: Bearer {{apiToken}}
Accept: application/json

Përgjigja:

{
  "data": [
    {
      "id": 4821,
      "first_name": "Arben",
      "last_name": "Krasniqi",
      "display_name": "Arben Krasniqi",
      "email": "[email protected]",
      "phone": "+38344555666",
      "phone_e164": "+38344555666",
      "locale": "sq",
      "is_active": true,
      "created_at": "2026-04-25T14:32:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 137
  }
}

Faqezimi

Kaloni page dhe per_page për të ecur nëpër rezultatet. Madhësia e parazgjedhur e faqes është 20, maksimumi është 100.

curl "https://dentare.io/api/v1/patients?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Kërkimi

Parametri q kërkon nëpër emër, email, telefon, dhe numër personal.

curl "https://dentare.io/api/v1/patients?q=krasniqi" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Filtrimi

Kaloni cilindo nga këto për të kufizuar grupin e rezultateve. Të gjitha janë opsionale dhe kombinohen me AND.

curl "https://dentare.io/api/v1/[email protected]" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Mbështet ?lang=en|sq|mk për të lokalizuar display_name në përgjigje. Shih Parametrat e zakonshëm.

Merrni një pacient

GET /api/v1/patients/:id

Kthen regjistrimin e plotë për një pacient. Kaloni fields (të ndarë me presje) për të përfshirë të dhëna shtesë që nuk kthehen si parazgjedhje.

Shembull

curl https://dentare.io/api/v1/patients/4821 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Përgjigja:

{
  "data": {
    "id": 4821,
    "first_name": "Arben",
    "last_name": "Krasniqi",
    "display_name": "Arben Krasniqi",
    "display_first_name": "Arben",
    "display_last_name": "Krasniqi",
    "email": "[email protected]",
    "phone": "+38344555666",
    "phone_e164": "+38344555666",
    "phone_country": "XK",
    "birthdate": "1988-03-22",
    "gender": "male",
    "personal_no": null,
    "external_id": null,
    "legacy_id": null,
    "locale": "sq",
    "is_active": true,
    "created_at": "2026-04-25T14:32:00Z",
    "updated_at": "2026-04-25T14:32:00Z"
  }
}

Me fushat e zgjerimit

Përgjigja parazgjedhur përjashton fushat mjekësore, kontaktit të emergjencës, sigurimit, dhe VIP për të mbajtur ngarkesat të vogla. Kërkojini ato shprehimisht me fields:

curl "https://dentare.io/api/v1/patients/4821?fields=allergies,medical_conditions,insurance_provider" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Mbështet ?lang=en|sq|mk për të lokalizuar display_name, display_first_name dhe display_last_name. Shih Parametrat e zakonshëm.

Pacienti nuk u gjet

{
  "error": "Not Found"
}

Një përgjigje 404 do të thotë që pacienti nuk ekziston, ose i përket një llogarie tjetër. API-ja kurrë nuk rrjedh të dhëna midis llogarive.

Krijoni një pacient

POST /api/v1/patients

Fushat e detyrueshme

Vetëm dy:

• first_name (string)
• last_name (string)

Çdo gjë tjetër është opsionale.

Shembull minimal

curl -X POST https://dentare.io/api/v1/patients \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Arben",
    "last_name": "Krasniqi"
  }'

POST {{baseUrl}}/patients
Authorization: Bearer {{apiToken}}
Content-Type: application/json
Accept: application/json

Body (raw, JSON):
{
  "first_name": "Arben",
  "last_name": "Krasniqi"
}

Përgjigja (201 Created):

{
  "data": {
    "id": 4821,
    "first_name": "Arben",
    "last_name": "Krasniqi",
    "display_name": "Arben Krasniqi",
    "email": null,
    "phone": null,
    "phone_e164": null,
    "is_active": true,
    "created_at": "2026-04-25T14:32:00Z",
    "updated_at": "2026-04-25T14:32:00Z"
  }
}

Shembull i plotë

Një krijim më realist me fusha kontakti, demografike, dhe locale:

curl -X POST https://dentare.io/api/v1/patients \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Arben",
    "last_name": "Krasniqi",
    "email": "[email protected]",
    "phone": "+38344555666",
    "phone_country": "XK",
    "birthdate": "1988-03-22",
    "gender": "male",
    "personal_no": "1234567890",
    "locale": "sq",
    "external_id": "ext_2841"
  }'

Të gjitha fushat e disponueshme

Gabimet e validimit

Nëse një fushë e detyrueshme mungon ose një vlerë është e keqformuar, API-ja kthen 422 Unprocessable Entity me një ndarje për fushë:

{
  "error": "Validation failed",
  "errors": {
    "first_name": ["can't be blank"],
    "email": ["is invalid"]
  }
}

Përditësoni një pacient

PATCH /api/v1/patients/:id

PATCH është i pjesshëm: dërgoni vetëm fushat që dëshironi të ndryshoni. Çdo gjë që lëni jashtë mbetet siç është.

Shembull

curl -X PATCH https://dentare.io/api/v1/patients/4821 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "phone": "+38344777888"
  }'

Përgjigja (200 OK):

{
  "data": {
    "id": 4821,
    "first_name": "Arben",
    "last_name": "Krasniqi",
    "email": "[email protected]",
    "phone": "+38344777888",
    "phone_e164": "+38344777888",
    "updated_at": "2026-04-25T15:10:00Z"
  }
}

Pse PATCH dhe jo PUT

PATCH përditëson vetëm fushat në trupin e kërkesës. Për të pastruar një fushë, dërgoni null shprehimisht. API-ja e Dentare nuk mbështet PUT (zëvendësim i plotë) te pacientët - përdorni PATCH për gjithçka.

Arkivoni një pacient

API-ja e Pacientëve nuk ekspozon një endpoint DELETE. Për të hequr një pacient nga listat aktive, arkivojeni duke vendosur is_active në false:

curl -X PATCH https://dentare.io/api/v1/patients/4821 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Pacientët e arkivuar përjashtohen nga përgjigjet e listës si parazgjedhje. Kaloni is_active=false për t'i parë, ose hiqeni filtrin për të parë vetëm pacientët aktivë.

Parametrat e zakonshëm

Këto katër modele aplikohen për çdo endpoint GET:

• Faqezimi - ?page=N&per_page=M (parazgjedhur 20, maks 100). Vetëm endpoint-et e koleksionit.
• Filtrimi - çdo kombinim i email, phone, personal_no, external_id, legacy_id, is_active, plus parametri i kërkimit q. Vetëm endpoint-et e koleksionit.
• Zgjerimi - ?fields=fusha1,fusha2,... për të përfshirë fusha të përjashtuara nga përgjigja parazgjedhur.
• Përgjigje të lokalizuara - ?lang=en|sq|mk për të kontrolluar gjuhën e fushave të llogaritura si display_name. Si parazgjedhje përdoret locale i ruajtur i pacientit nëse është vendosur, përndryshe anglisht. E disponueshme në të gjitha endpoint-et e leximit.

Për endpoint-in e detajeve të pacientit, fushat e disponueshme të zgjerimit janë:

allergies, medical_conditions, blood_type, emergency_contact_name, emergency_contact_relationship, emergency_contact_phone, insurance_provider, insurance_id, vip, vip_start_date, vip_expiration_date, vip_notes, preferences, medical_issues

Referenca e gabimeve

Kodet e statusit HTTP

Forma e përgjigjes së gabimit

{
  "error": "Validation failed",
  "errors": {
    "first_name": ["can't be blank"],
    "phone": ["is invalid"]
  }
}

error është gjithmonë një varg i lexueshëm nga njerëzit. errors (shumës, me shkronja të vogla) është i pranishëm në përgjigjet 422 dhe çift secilën fushë të pavlefshme me një varg mesazhesh gabimi.

Kufijtë e shpejtësisë

API-ja e Pacientëve nuk imponon sot kufij shpejtësie për token. Bëhuni qytetar i mirë: shmangni ciklet e ngushta, faqezoni leximet e mëdha, dhe tërhiquni nëse filloni të shihni përgjigje 429 (që do të vinin nga skaji i platformës, jo nga vetë API-ja).

Zgjidhja e problemeve

401 Unauthorized në çdo kërkesë

Kontrolloni që header-i juaj Authorization përdor formatin e saktë: Bearer YOUR_API_TOKEN. Fjala literale Bearer është e detyrueshme, me një hapësirë para tokenit. Nëse formati është i saktë, konfirmoni që tokeni nuk është revokuar nga paneli.

404 Not Found kur aksesoni një pacient

Pacienti ose nuk ekziston ose i përket një llogarie tjetër. Kërkesat API janë të kufizuara në llogarinë tuaj: nuk mund të lexoni ose modifikoni pacientë nga një klinikë tjetër, edhe nëse merrni me mend një ID të vlefshme.

422 Gabim validimi gjatë krijimit

Minimalisht, first_name dhe last_name janë të detyrueshme. Objekti errors në përgjigje çift secilën fushë të pavlefshme me një varg mesazhesh. Lexojeni fushë për fushë.

Numri i telefonit shfaqet ndryshe pas krijimit ose përditësimit

Dentare normalizon numrat e telefonit në formatin ndërkombëtar E.164 (p.sh. +38970123456). Vlera e normalizuar kthehet në fushën phone_e164. Kaloni phone_country në trupin e kërkesës për të ndihmuar normalizimin kur numrat tuaj të hyrjes nuk përfshijnë kodin e shtetit.

Kërkimi nuk kthen rezultate

Parametri q kërkon në emër, email, telefon, dhe numër personal. Sigurohuni që termi i kërkimit përputhet me të paktën njërën nga ato fusha. Vetëm pacientët aktivë si parazgjedhje; kaloni is_active=false për të përfshirë pacientët e arkivuar.

Karakteret speciale shfaqen të prishura

Sigurohuni që kërkesa juaj përdor kodimin UTF-8. Vendosni header-in Content-Type: application/json; charset=utf-8 në kërkesat e shkrimit.

Postman

Modeli i bazuar në variabla në seksionin Postman më sipër është pikënisja e rekomanduar: kopjoni një shembull të vetëm, ruajeni në një koleksion "Dentare API", dhe ripërdorni {{baseUrl}} dhe {{apiToken}} në çdo kërkesë.

Çfarë vjen më pas

• Importoni Pacientë nga CSV - alternativa pa kod për migrime një herë
• Importoni Pacientë nga CSV - alternativa pa kod për migrime një-herë