Како да Управувате со Пациенти преку API

Користете го REST API на Dentare за програмско креирање, ажурирање, листање и прегледување на пациенти. Овој водич покрива креирање на API токен, автентикација на барања, и користење на endpoint-ите за пациенти — сè без отворање на веб интерфејсот на Dentare.

Во оваа статија:

• Што ви е Потребно

• Чекор 1 — Креирајте API Токен

• Чекор 2 — Автентицирајте ги API Барањата

• Креирајте Пациент

• Ажурирајте Пациент

• Листајте Пациенти

• Добијте Детали за Пациент

• Достапни Полиња

• Полиња за Проширување

• Резиме на API Референцата

• Решавање на Проблеми

Што ви е Потребно

• Активна Dentare сметка со администраторски пристап

• Алатка за испраќање HTTP барања (на пр., curl, Postman, или вашиот сопствен код)

Чекор 1 — Креирајте API Токен

Пред да можете да го повикате API-то, ви треба API токен. Овој токен ги автентицира вашите барања и ги поврзува со вашата Dentare сметка.

1. Најавете се на Dentare како администратор на сметката

2. Одете на API Tokens од навигацијата на сметката (или навигирајте директно до API Tokens)

3. Кликнете Create an API Token

4. Внесете описно име (на пр., "Интеграција за Пациенти" или "Скрипта за Миграција")

5. Кликнете Create

По креирањето, Dentare го покажува вашиот токен. Копирајте го веднаш — од безбедносни причини, целосниот токен е видлив само во овој момент.

Важно: Третирајте го вашиот API токен како лозинка. Не го споделувајте јавно и не го ставајте во контрола на верзии. Секој со токенот може да пристапи до податоците на вашата сметка.

За да отповикате токен:

1. Одете на API Tokens

2. Кликнете на името на токенот

3. Кликнете Revoke

Токенот веднаш се брише и повеќе не може да се користи.

Чекор 2 — Автентицирајте ги API Барањата

Секое API барање мора да го вклучи вашиот токен во Authorization header-от користејќи Bearer шема:

Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА

Пример со curl:

curl https://dentare.io/api/v1/me.json -H "Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА" -H "Accept: application/json"

Успешниот одговор го враќа вашиот кориснички профил, потврдувајќи дека токенот функционира.

Ако добиете 401 Unauthorized одговор, проверете дека:

• Токенот е правилно копиран (без дополнителни празнини)

• Токенот не е отповикан

• Authorization header-от го користи префиксот Bearer

Креирајте Пациент

Барање:

POST https://dentare.io/api/v1/patients

Header-и:

• Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА

• Content-Type: application/json

Тело (JSON):

{"first_name": "Марко", "last_name": "Стојановски", "email": "marko@primer.com", "phone": "+38970123456", "birthdate": "1990-05-15", "gender": "male"}

Пример со curl:

curl -X POST https://dentare.io/api/v1/patients -H "Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА" -H "Content-Type: application/json" -d '{"first_name": "Марко", "last_name": "Стојановски", "email": "marko@primer.com", "phone": "+38970123456"}'

Успешен одговор (201 Created):

Го враќа целосниот запис на пациентот во формат {data: {...}} вклучувајќи го доделениот id, display_name, phone_e164 (нормализиран телефон), created_at, и сите останати полиња.

Одговор за грешка (422 Unprocessable Entity):

Враќа {error: "...", errors: {...}} со пораки за валидација (на пр., "Името не може да биде празно").

Забелешка: Само first_name и last_name се задолжителни. Сите останати полиња се опционални.

Ажурирајте Пациент

Барање:

PATCH https://dentare.io/api/v1/patients/PATIENT_ID

Header-и:

• Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА

• Content-Type: application/json

Тело (JSON) — вклучете само полињата што сакате да ги промените:

{"email": "novemail@primer.com", "phone": "+38971999888"}

Пример со curl:

curl -X PATCH https://dentare.io/api/v1/patients/123 -H "Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА" -H "Content-Type: application/json" -d '{"email": "novemail@primer.com"}'

Успешен одговор (200 OK):

Го враќа ажурираниот целосен запис на пациентот во формат {data: {...}}.

Одговори за грешки:

• 404 Not Found — пациентот не постои или припаѓа на друга сметка

• 422 Unprocessable Entity — грешка при валидација

Листајте Пациенти

Барање:

GET https://dentare.io/api/v1/patients

Header-и:

• Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА

Параметри за пребарување (сите опционални):

• q — барање за пребарување (пребарува по име, email, телефон, матичен број)

• page — број на страница (стандардно: 1)

• per_page — записи по страница (стандардно: 20, макс: 100)

• lang — јазик за имиња за приказ: en, sq, или mk

• email — филтрирај по точен email

• phone — филтрирај по телефонски број (делумно совпаѓање)

• personal_no — филтрирај по матичен број (ЕМБГ)

• external_id — филтрирај по надворешен ID

• legacy_id — филтрирај по стар ID

• is_active — филтрирај по активен статус (true или false; стандардно само активни)

Пример со curl:

curl "https://dentare.io/api/v1/patients?q=Марко&per_page=50" -H "Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА"

Успешен одговор (200 OK):

Одговорот содржи листа data и објект meta:

• data — листа на записи за пациенти, секој со: id, first_name, last_name, display_name, email, phone, phone_e164, locale, is_active, created_at

• meta — информации за страници со page, per_page, total

Забелешка: Стандардно, само активни пациенти се враќаат. Проследете is_active=false за да вклучите неактивни пациенти.

Добијте Детали за Пациент

Барање:

GET https://dentare.io/api/v1/patients/PATIENT_ID

Header-и:

• Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА

Параметри за пребарување (опционални):

• lang — јазик за имиња за приказ: en, sq, или mk

• fields — листа одделена со запирки на полиња за проширување (видете го делот Полиња за Проширување подолу)

Пример со curl:

curl "https://dentare.io/api/v1/patients/123?fields=allergies,medical_conditions,insurance_provider" -H "Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА"

Успешен одговор (200 OK):

Го враќа целосниот запис на пациентот во формат {data: {...}} вклучувајќи: id, first_name, last_name, display_name, display_first_name, display_last_name, email, phone, phone_e164, phone_country, birthdate, gender, personal_no, external_id, legacy_id, locale, is_active, created_at, updated_at, плус побараните полиња за проширување.

Одговор за грешка:

• 404 Not Found — пациентот не постои или припаѓа на друга сметка

Достапни Полиња

Следниве полиња можат да се користат при креирање или ажурирање на пациент. Само first_name и last_name се задолжителни.

Задолжителни:

• first_name — име на пациентот

• last_name — презиме на пациентот

Опционални:

• email — email адреса

• phone — телефонски број (автоматски се нормализира во меѓународен E.164 формат)

• phone_country — двобуквен код на државата за нормализација на телефон (на пр., "MK", "XK", "AL")

• birthdate — датум на раѓање во ISO 8601 формат (YYYY-MM-DD)

• gender — male, female, или other

• personal_no — матичен број / ЕМБГ

• locale — претпочитан јазик за пораки: en, sq, или mk

• external_id — ID од друг систем (за референца)

• blood_type — крвна група

• allergies — познати алергии (слободен текст)

• medical_conditions — познати медицински состојби (слободен текст)

• emergency_contact_name — име на контакт за итни случаи

• emergency_contact_relationship — однос со пациентот

• emergency_contact_phone — телефонски број на контакт за итни случаи

• insurance_provider — име на осигурителна компанија

• insurance_id — број на полиса за осигурување

• is_active — дали пациентот е активен (true или false)

• preferred_doctor_id — ID на претпочитан доктор

Полиња за Проширување

Стандардно, одговорот за детали на пациент ги вклучува само основните полиња. За да вклучите дополнителни полиња, проследете ги како параметар fields одделен со запирки во GET барањето.

Достапни полиња за проширување:

• allergies — познати алергии

• medical_conditions — познати медицински состојби

• blood_type — крвна група

• emergency_contact_name — име на контакт за итни случаи

• emergency_contact_relationship — однос на контакт за итни случаи

• emergency_contact_phone — телефон на контакт за итни случаи

• insurance_provider — име на осигурителна компанија

• insurance_id — број на полиса за осигурување

• vip — VIP статус

• vip_start_date — датум на почеток на VIP

• vip_expiration_date — датум на истекување на VIP

• vip_notes — VIP забелешки

• preferences — преференции на пациентот

• medical_issues — медицински проблеми

Пример:

GET /api/v1/patients/123?fields=allergies,insurance_provider,emergency_contact_name

Резиме на API Референцата

Автентикација:

• Header: Authorization: Bearer ВАШИОТ_ТОКЕН_ТУКА

• Тип на содржина: application/json

Endpoint-и:

• POST /api/v1/patients — креирај пациент

• PATCH /api/v1/patients/:id — ажурирај пациент

• GET /api/v1/patients — листа на пациенти (со страници, пребарување, филтри)

• GET /api/v1/patients/:id — детали за пациент (со опционални полиња за проширување)

Вообичаени HTTP статус кодови:

• 200 — успех

• 201 — успешно креирано

• 401 — неавторизирано (невалиден или недостасува токен)

• 404 — не е пронајдено

• 422 — грешка при валидација (недостасуваат задолжителни полиња, лош формат)

Решавање на Проблеми

401 Unauthorized на секое барање Проверете дали вашиот Authorization header го користи правилниот формат: Bearer ВАШИОТ_ТОКЕН_ТУКА. Осигурајте се дека токенот не е отповикан.

404 Not Found при пристап до пациент Пациентот или не постои или припаѓа на друга сметка. API барањата се ограничени на вашата сметка — не можете да пристапите до пациенти од други сметки.

422 Грешка при валидација при креирање Најмалку, first_name и last_name се задолжителни. Проверете го објектот errors во одговорот за специфични грешки по полиња.

Телефонскиот број изгледа поинаку по креирање/ажурирање Dentare автоматски ги нормализира телефонските броеви во меѓународен E.164 формат (на пр., +38970123456). Нормализираниот број се враќа во полето phone_e164. Проследете phone_country за да помогнете со нормализацијата ако вашите телефонски броеви не вклучуваат код на држава.

Пребарувањето не враќа резултати Параметарот q пребарува по име, email, телефон и матичен број. Осигурајте се дека терминот за пребарување се совпаѓа со барем едно од овие полиња. Стандардно, само активни пациенти се враќаат — проследете is_active=false за да ги вклучите неактивните.

Специјалните карактери се појавуваат искривени Осигурајте се дека вашето барање користи UTF-8 кодирање. Поставете го header-от Content-Type: application/json; charset=utf-8.

Ви треба помош? Контактирајте Поддршка.