API за Пациенти

Што ќе изградите

Dentare нуди REST API за програмско управување со пациенти. Користете го за импорт на постара листа на пациенти, синхронизација на пациенти од друг систем, или изградба на прилагодени интеграции врз податоците на вашата клиника.

Овој водич ве води од нула до функционална интеграција: генерирате токен, го извршувате вашиот прв автентициран повик, потоа поминувате низ целосниот CRUD циклус со curl примери подготвени за копирање за секоја операција.

Пред да започнете

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

Како функционира

Секое барање до API-то мора да вклучи Bearer токен во Authorization хедерот. Токените се ограничени на вашата сметка - можат само да читаат или менуваат податоци кои ѝ припаѓаат на вашата клиника, не на други Dentare сметки.

Токените никогаш не истекуваат автоматски. Можете да ги отповикате во секое време од панелот.

Генерирајте API токен

Направете го вашиот прв автентициран повик

Наједноставниот „пинг" што можете да го извршите е да го преземете вашиот кориснички профил од /api/v1/me.json. Ако вашиот токен функционира, ќе добиете 200 одговор со информациите за вашата сметка.

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

Очекуван одговор:

{
  "id": 1,
  "name": "Вашето Име",
  "avatar_url": "https://dentare.io/users/1/avatar.png",
  "sgid": "BAh7CEkiCGdpZAY6BkVUS..."
}

200 со ова тело потврдува дека токенот функционира. Полињата id и name се најкорисни за брза проверка. sgid е потпишано глобално ID користено внатрешно и можете да го игнорирате.

Чести грешки при автентикација

Отповикајте токен

Ако токен истече, заврши во погрешни раце, или повеќе не е потребен, отповикајте го од панелот. Токенот веднаш престанува да работи.

Основен URL и хедери

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

GET /api/v1/patients

Враќа страничена листа на пациенти во вашата сметка. Само активни пациенти стандардно.

Основен пример

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

Одговор:

{
  "data": [
    {
      "id": 4821,
      "first_name": "Стефан",
      "last_name": "Николовски",
      "display_name": "Стефан Николовски",
      "email": "[email protected]",
      "phone": "+38970123456",
      "phone_e164": "+38970123456",
      "locale": "mk",
      "is_active": true,
      "created_at": "2026-04-25T14:32:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 137
  }
}

Страничење

Проследете page и per_page за да поминете низ резултатите. Стандардната големина на страница е 20, максимум е 100.

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

Пребарување

Параметарот q пребарува по име, email, телефон, и матичен број.

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

Филтрирање

Проследете кој било од овие за да го стесните множеството резултати. Сите се опционални и се комбинираат со AND.

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

Поддржува ?lang=en|sq|mk за локализирање на display_name во одговорот. Видете Заеднички параметри.

Земете еден пациент

GET /api/v1/patients/:id

Враќа целосен запис за еден пациент. Проследете fields (одделени со запирки) за да вклучите дополнителни податоци кои не се враќаат стандардно.

Пример

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

Одговор:

{
  "data": {
    "id": 4821,
    "first_name": "Стефан",
    "last_name": "Николовски",
    "display_name": "Стефан Николовски",
    "display_first_name": "Стефан",
    "display_last_name": "Николовски",
    "email": "[email protected]",
    "phone": "+38970123456",
    "phone_e164": "+38970123456",
    "phone_country": "MK",
    "birthdate": "1992-08-10",
    "gender": "male",
    "personal_no": null,
    "external_id": null,
    "legacy_id": null,
    "locale": "mk",
    "is_active": true,
    "created_at": "2026-04-25T14:32:00Z",
    "updated_at": "2026-04-25T14:32:00Z"
  }
}

Со полиња за проширување

Стандардниот одговор ги исклучува медицинските, контактните за итни случаи, осигурителните, и VIP полињата за да го одржи payload-от мал. Барајте ги експлицитно со fields:

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

Поддржува ?lang=en|sq|mk за локализирање на display_name, display_first_name и display_last_name. Видете Заеднички параметри.

Пациентот не е пронајден

{
  "error": "Not Found"
}

404 одговор значи дека пациентот не постои, или припаѓа на друга сметка. API-то никогаш не пропушта податоци меѓу сметки.

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

POST /api/v1/patients

Задолжителни полиња

Само две:

• first_name (string)
• last_name (string)

Сè друго е опционално.

Минимален пример

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": "Стефан",
    "last_name": "Николовски"
  }'

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

Body (raw, JSON):
{
  "first_name": "Стефан",
  "last_name": "Николовски"
}

Одговор (201 Created):

{
  "data": {
    "id": 4821,
    "first_name": "Стефан",
    "last_name": "Николовски",
    "display_name": "Стефан Николовски",
    "email": null,
    "phone": null,
    "phone_e164": null,
    "is_active": true,
    "created_at": "2026-04-25T14:32:00Z",
    "updated_at": "2026-04-25T14:32:00Z"
  }
}

Целосен пример

Пореалистичен creation со контактни, демографски, и 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": "Марија",
    "last_name": "Петровска",
    "email": "[email protected]",
    "phone": "+38978445566",
    "phone_country": "MK",
    "birthdate": "1990-05-15",
    "gender": "female",
    "personal_no": "1505990450123",
    "locale": "mk",
    "external_id": "ext_2841"
  }'

Сите достапни полиња

Грешки во валидација

Ако задолжително поле недостасува или вредност е невалидна, API-то враќа 422 Unprocessable Entity со разложување по поле:

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

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

PATCH /api/v1/patients/:id

PATCH е делумен: испратете само полиња што сакате да ги промените. Сè што ќе изоставите останува како што е.

Пример

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": "+38971222333"
  }'

Одговор (200 OK):

{
  "data": {
    "id": 4821,
    "first_name": "Стефан",
    "last_name": "Николовски",
    "email": "[email protected]",
    "phone": "+38971222333",
    "phone_e164": "+38971222333",
    "updated_at": "2026-04-25T15:10:00Z"
  }
}

Зошто PATCH а не PUT

PATCH ги ажурира само полињата во телото на барањето. За да исчистите поле, испратете null експлицитно. Dentare API не поддржува PUT (целосна замена) на пациенти - користете PATCH за сè.

Архивирајте пациент

API-то за Пациенти не изложува DELETE ендпоинт. За да отстраните пациент од активните листи, архивирајте го со поставување на is_active на 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}'

Архивираните пациенти се исклучуваат од одговорите на листата стандардно. Проследете is_active=false за да ги видите, или испуштете го филтерот за да ги видите само активните пациенти.

Заеднички параметри

Овие четири модели важат за секој GET ендпоинт:

• Страничење - ?page=N&per_page=M (стандардно 20, макс 100). Само за колекциски ендпоинти.
• Филтрирање - која било комбинација на email, phone, personal_no, external_id, legacy_id, is_active, плус параметарот за пребарување q. Само за колекциски ендпоинти.
• Проширување - ?fields=pole1,pole2,... за да вклучите полиња исклучени од стандардниот одговор.
• Локализирани одговори - ?lang=en|sq|mk за да го контролирате јазикот на пресметаните полиња како display_name. Стандардно се користи зачуваниот locale на пациентот ако е поставен, инаку англиски. Достапно на сите ендпоинти за читање.

За ендпоинтот за детали на пациент, достапни полиња за проширување се:

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

Референца за грешки

HTTP статус кодови

Форма на одговорот за грешка

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

error е секогаш стринг читлив за луѓе. errors (множина, со мали букви) е присутно во 422 одговорите и мапира секое невалидно поле со низа пораки за грешка.

Лимити на брзина

API-то за Пациенти моментално не наметнува лимити на брзина по токен. Бидете добар граѓанин: избегнувајте тесни циклуси, страничете големи читања, и повлечете се ако почнете да гледате 429 одговори (кои би доаѓале од работ на платформата, не од самото API).

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

401 Unauthorized на секое барање

Проверете дали вашиот Authorization хедер го користи правилниот формат: Bearer YOUR_API_TOKEN. Литералниот збор Bearer е задолжителен, со едно празно место пред токенот. Ако форматот е точен, потврдете дека токенот не е отповикан од панелот.

404 Not Found при пристап до пациент

Пациентот или не постои или припаѓа на друга сметка. API барањата се ограничени на вашата сметка: не можете да читате или менувате пациенти од друга клиника, дури и ако погодите валидно ID.

422 Грешка при валидација при креирање

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

Телефонскиот број изгледа поинаку по креирање или ажурирање

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

Пребарувањето не враќа резултати

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

Специјалните карактери се појавуваат искривени

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

Postman

Моделот базиран на променливи во Postman секцијата погоре е препорачана почетна точка: копирајте еден пример, зачувајте го во колекција „Dentare API", и повторно користете {{baseUrl}} и {{apiToken}} низ секое барање.

Што следува

• Увезете Пациенти од CSV - алтернативата без код за еднократни миграции
• Импортирајте Пациенти од CSV - алтернатива без код за еднократни миграции