İnteqrasiya sənədi · v1

AVİ Partnyor API

Tətbiqinizdən AVİ-yə analiz sifarişi verin. Kataloqu göstərin, qiyməti hesablayın, ödənişi özünüz qəbul edin və sifarişi yaradın.

Test

https://avi.medicare.az/integration/v1

Production

https://api.avimed.az/integration/v1

Format: JSON, UTF-8

Valyuta: AZN

Vaxt zonası: Asia/Baku (+04:00)

Kataloq dili: Accept-Language: az | en | ru

Autentifikasiya

Hər sorğuda X-API-KEY header-i göndərin. Format: <partnerCode>.<secret>. Açarı AVİ bir dəfə verir. İtirilmiş açarı bərpa etmək mümkün deyil; yeni açar verilir.

TƏHLÜKƏSİZLİK

Açarı yalnız serverinizdə saxlayın. Mobil tətbiqə yazmayın. Tətbiqiniz backend-inizə, backend-iniz isə AVİ API-yə müraciət edir.

Header

Təsvir

{{ f.n }}{{ f.req }}

Sorğu nümunəsi

curl {{ base }}/medical-categories \
  -H "X-API-KEY: $AVI_API_KEY" \
  -H "X-Trace-Id: 7f3c1a90-2b6e-4d51-9c0f-8a12d4e7b331"

401 — açar yoxdur və ya yanlışdır

{
  "success": false,
  "messageKey": "INVALID_API_KEY",
  "message": "API açarı yanlışdır və ya deaktivdir",
  "timestamp": "2026-10-04T15:22:34Z"
}

Cavab formatı

Bütün cavablar eyni formatda qaytarılır. Nəticəni messageKey ilə yoxlayın. message istifadəçi üçün nəzərdə tutulub və dəyişə bilər.

Sahə

Təsvir

{{ f.n }}

{{ f.t }}

Zərf

{
  "success": true,
  "message": "Əməliyyat uğurla yerinə yetirildi",
  "messageKey": "OK",
  "data": { },
  "errors": null,
  "timestamp": "2026-09-30T07:04:25Z"
}

Sifariş axını

Hər ssenari dörd addımdır. Ödənişi siz qəbul edirsiniz; AVİ ödəniş prosesinə müdaxilə etmir. Sifariş dərhal PAID statusunda yaradılır.

01

Kataloq

Müştəri xidməti və ya check-up paketini seçir. Nəticə: serviceIds.

GET /medical-categories

02

Qiymət və klinika

Həmin xidmətlərin göstərildiyi klinikalar və onların qiymətləri qaytarılır.

POST /medical-services/calculate

03

Ödəniş

Müştəri klinikanı seçir və ödənişi tətbiqinizdə həyata keçirir.

Sizin tərəfinizdə

04

Sifariş

Sifarişi yaradın. Qaytarılan paymentCode-u müştəriyə göstərin.

POST /orders

Müştəri paymentCode-u klinikada və ya kuryerə təqdim edir. Statusu GET /orders/{orderCode} ilə yoxlayın.

Ssenarilər

Ssenarilər yalnız kataloq və delivery parametrlərinə görə fərqlənir. Check-up paketi adi serviceId-dir. Paketi həm klinikada, həm də evdə sifariş etmək olar.

Check-up paketi

Evdə xidmət

Klinikada

{{ r.a }}

{{ r.b }}

{{ r.c }}

{{ st.c }}

GET/medical-categories

Kateqoriyalar

Kataloqun ən yüksək səviyyəsidir. Kateqoriyalar: LAB, FUN, KON, CHECKUP. Adlar Accept-Language başlığında göstərilən dildə qaytarılır.

Cavab — data[]

{{ f.n }}

{{ f.t }}

Sorğu

curl {{ base }}/medical-categories \
  -H "X-API-KEY: $AVI_API_KEY" \
  -H "Accept-Language: az"

200 OK

"data": [
  { "id": "LAB", "description": "Laboratoriya" },
  { "id": "FUN", "description": "Funksional diaqnostika" },
  { "id": "KON", "description": "Konsultasiya" },
  { "id": "CHECKUP", "description": "Check-up" }
]

GET/medical-sub-categories

Alt-kateqoriyalar

Kateqoriya daxilindəki qruplar, məs. «Qan», «Hormonlar». category məcburidir. Göndərilmədikdə — 400 VALIDATION_ERROR.

Query parametrləri

categoryMəcburi

string

Kateqoriya kodu: LAB, FUN, KON və ya CHECKUP.

Cavab — data[]

{{ f.n }}

{{ f.t }}

Sorğu

curl "{{ base }}/medical-sub-categories?category=LAB" \
  -H "X-API-KEY: $AVI_API_KEY" \
  -H "Accept-Language: az"

200 OK

"data": [
  { "id": 1, "description": "Qan", "icon": "https://…/blood.svg" },
  { "id": 7, "description": "Hormonlar", "icon": "https://…/hormones.svg" }
]

GET/medical-services

Xidmətlər

Analiz və xidmətlərin siyahısı. Qiymət burada göstərilmir, çünki klinikadan asılıdır. Qiyməti calculate sorğusu ilə əldə edin.

Query parametrləri

subCategoryŞərti

long

Alt-kateqoriya ID-si.

categoryŞərti

string

Kateqoriya kodu, məs. CHECKUP.

Parametrlərdən birini mütləq göndərin. Hər ikisi göndərilərsə, subCategory əsas götürülür. Heç biri yoxdursa — 400 VALIDATION_ERROR.

Cavab — data[]

{{ f.n }}

{{ f.t }}

CHECK-UP PAKETLƏRİ

Paketləri ?category=CHECKUP sorğusu ilə əldə edin. Paket adi xidmətdir: onun id-sini serviceIds-ə əlavə edin.

Sorğu

curl "{{ base }}/medical-services?subCategory=1" \
  -H "X-API-KEY: $AVI_API_KEY" \
  -H "Accept-Language: az"

200 OK

"data": [
  {
    "id": 101,
    "description": "Ümumi qan analizi",
    "group": { "id": 1, "description": "Qan", "icon": "https://…/blood.svg" },
    "price": null,
    "alternatives": []
  }
]

GET/clinics

Klinikalar

Aktiv klinikaların siyahısıdır; məsələn, xəritədə göstərmək üçün istifadə oluna bilər. Sifariş üçün adətən lazım deyil: klinika və qiymət calculate sorğusunun cavabında qaytarılır.

Cavab — data[]

{{ f.n }}

{{ f.t }}

Sorğu

curl {{ base }}/clinics \
  -H "X-API-KEY: $AVI_API_KEY"

200 OK

"data": [
  {
    "id": 12,
    "name": "AVİ Medicare - Nəsimi filialı",
    "address": "Əhməd Rəcəbli 15",
    "phone": "+994125550101",
    "workingHour": "08:00 - 20:00",
    "latitude": "40.409264",
    "longitude": "49.867092",
    "delivery": true
  }
]

POST/medical-services/calculate

Qiymət hesabla

Seçilmiş xidmətlər üzrə klinikaları və qiymətləri qaytarır. Sifariş yaratmır.

Request body

{{ f.n }}{{ f.req }}

{{ f.t }}

Cavab — data[], hər element bir klinika

{{ f.n }}

{{ f.t }}

QAYDALAR

Müştəriyə price + deliveryPrice göstərin. Sifarişdə bu məbləği payment.amount kimi göndərin.

Xidmətin göstərilmədiyi klinikalar cavabda qaytarılmır. delivery=true olduqda evdə xidmət göstərməyən klinikalar da siyahıdan çıxarılır.

failedCount > 0 — klinikada bəzi xidmətlər yoxdur. Bu klinika üçün sifariş yaradıla bilməz; 404 SERVICE_NOT_AVAILABLE qaytarılır. Onu siyahıdan çıxarın və ya «natamam» kimi göstərin.

Sorğu — evdə xidmət

curl -X POST {{ base }}/medical-services/calculate \
  -H "X-API-KEY: $AVI_API_KEY" \
  -H "Accept-Language: az" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceIds": [101, 204, 305],
    "delivery": true,
    "latitude": "40.409264",
    "longitude": "49.867092"
  }'

200 OK

"data": [
  {
    "branchResponse": {
      "id": 12,
      "info": "AVİ Medicare - Nəsimi filialı",
      "address": "Əhməd Rəcəbli 15",
      "phone": "+994125550101",
      "workingHour": "08:00 - 20:00",
      "image": "https://…/branch-12.jpg",
      "icon": "https://…/branch-12.svg",
      "latitude": "40.409264",
      "longitude": "49.867092"
    },
    "price": 84.50,
    "deliveryPrice": 5.00,
    "successCount": 3,
    "failedCount": 0,
    "details": []
  }
]

POST/orders

Sifariş yarat

Müştəri ödədikdən sonra sifarişi yaradın. Uğurlu sorğuda 200 OK qaytarılır. Şəbəkə xətasında eyni externalOrderId ilə təkrarlayın. İkinci sifariş yaradılmır (ətraflı).

Request body

{{ f.n }}{{ f.req }}

{{ f.t }}

patient

{{ f.n }}{{ f.req }}

{{ f.t }}

payment

{{ f.n }}{{ f.req }}

{{ f.t }}

detail — yalnız delivery=true

{{ f.n }}{{ f.req }}

{{ f.t }}

Cavab — data

{{ f.n }}

{{ f.t }}

orderCode ≠ paymentCode

paymentCode müştəriyə göstərilir. orderCode yalnız backend üçündür: status və ləğv sorğularında.

Sorğu — evdə xidmət

curl -X POST {{ base }}/orders \
  -H "X-API-KEY: $AVI_API_KEY" \
  -H "X-Trace-Id: 7f3c1a90-2b6e-4d51-9c0f-8a12d4e7b331" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderId": "PRT-2026-0012345",
    "branchId": 12,
    "serviceIds": [101, 204, 305],
    "delivery": true,
    "patient": {
      "firstName": "Aysel",
      "lastName": "Məmmədova",
      "fatherName": "Elçin",
      "finCode": "5XY9ABC",
      "dateOfBirth": "1991-04-17",
      "gender": "FEMALE",
      "phone": "994501234567"
    },
    "payment": {
      "amount": 89.50,
      "currency": "AZN",
      "paidAt": "2026-09-30T11:04:22+04:00",
      "reference": "PRT-PAY-889231"
    },
    "detail": {
      "city": "Bakı",
      "region": "Nəsimi",
      "address": "Əhməd Rəcəbli 15, mənzil 42",
      "deliveryDay": "2026-10-01",
      "deliveryTime": "10:00-12:00",
      "contactName": "Aysel",
      "contactSurName": "Məmmədova",
      "contactPhone": "994501234567",
      "latitude": "40.409264",
      "longitude": "49.867092",
      "additionalInfo": "Domofon işləmir, zəng edin"
    }
  }'

200 OK

"data": {
  "orderCode": "9f14c8e2-3b7a-4d51-9c02-6e8a1f4b7d33",
  "externalOrderId": "PRT-2026-0012345",
  "traceId": "7f3c1a90-2b6e-4d51-9c0f-8a12d4e7b331",
  "paymentCode": 48213765,
  "orderStatus": "PAID",
  "amount": 89.50,
  "delivery": true,
  "patient": { … },
  "branch": {
    "id": 12,
    "name": "AVİ Medicare - Nəsimi filialı",
    "address": "Əhməd Rəcəbli 15",
    "phone": "+994125550101",
    "workingHour": "08:00 - 20:00",
    "latitude": "40.409264",
    "longitude": "49.867092",
    "delivery": true
  },
  "items": [
    { "serviceId": 101, "name": "Ümumi qan analizi", "amount": 24.00, "itemStatus": "PENDING" },
    { "serviceId": 204, "name": "TSH", "amount": 30.50, "itemStatus": "PENDING" },
    { "serviceId": 305, "name": "D vitamini", "amount": 30.00, "itemStatus": "PENDING" }
  ],
  "createdAt": "2026-09-30T11:04:25"
}

GET/orders/{orderCode}

Sifariş statusu

Cavab POST /orders ilə eynidir. Yalnız öz sifarişlərinizi görürsünüz. Başqa sifariş üçün 404 ORDER_NOT_FOUND qaytarılır.

Statuslar

{{ f.n }}

{{ f.t }}

QEYD

Yeni sifariş PAID statusunda yaradılır. Ləğvdən sonra REJECTED olur. PARTIALLY_* — xidmətlərin yalnız bir hissəsi bu statusdadır.

Sorğu

curl {{ base }}/orders/9f14c8e2-3b7a-4d51-9c02-6e8a1f4b7d33 \
  -H "X-API-KEY: $AVI_API_KEY"

POST/orders/{orderCode}/cancel

Sifarişi ləğv et

Yalnız heç bir analiz götürülməyibsə mümkündür (bütün itemStatus = PENDING). Uğurlu sorğuda 200 OK və yenilənmiş sifariş qaytarılır. orderStatus REJECTED olur. paymentCode etibarsız olur. Sifariş aylıq akta daxil edilmir.

reasonMəcburi

string(500)

Ləğv səbəbi

409

ORDER_ALREADY_CANCELLED

Sifariş artıq ləğv edilib

409

ORDER_ALREADY_IN_PROGRESS

Analiz artıq götürülüb, ləğv mümkün deyil.

GERİ ÖDƏMƏ

Ödənişi siz almısınız. Pulu müştəriyə siz qaytarırsınız.

Sorğu

curl -X POST {{ base }}/orders/9f14c8e2-3b7a-4d51-9c02-6e8a1f4b7d33/cancel \
  -H "X-API-KEY: $AVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Müştəri imtina etdi" }'

Təkrar sorğular

Sorğu serverimizə çata bilər, lakin cavab sizə çatmaya bilər. Müştəri artıq ödəyib. Təkrar sorğu ikinci sifariş yaratmamalıdır. Bunu externalOrderId təmin edir:

Hər yeni sifariş üçün yeni externalOrderId.

Retry zamanı eyni externalOrderId.

409 DUPLICATE_EXTERNAL_ORDER_ID qaytarılarsa, sifariş artıq mövcuddur. data.orderCode ilə GET /orders/{orderCode} çağırın və paymentCode-u götürün.

Eyni anda iki eyni sorğu göndərilsə belə, yalnız bir sifariş yaradılır. X-Trace-Id bunu etmir. O yalnız log üçündür.

Retry tövsiyələri

409 — təkrar externalOrderId

{
  "success": false,
  "messageKey": "DUPLICATE_EXTERNAL_ORDER_ID",
  "message": "Bu externalOrderId ilə sifariş artıq mövcuddur",
  "data": {
    "orderCode": "3f8a1c92-7b41-4e0d-9a55-2c6e8b1d4f30",
    "orderStatus": "PAID"
  }
}

Xəta kodları

Xətanı messageKey əsasında müəyyən edin. Validasiya xətasının detalları errors[]-dədir.

{{ e.h }}

{{ e.k }}

400 VALIDATION_ERROR

{
  "success": false,
  "messageKey": "VALIDATION_ERROR",
  "errors": [
    { "field": "patient.phone", "message": "phone 994XXXXXXXXX formatında olmalıdır" },
    { "field": "patient.finCode", "message": "finCode boş ola bilməz" }
  ]
}

409 AMOUNT_MISMATCH

{
  "success": false,
  "messageKey": "AMOUNT_MISMATCH",
  "data": { "expectedAmount": 89.50, "receivedAmount": 84.50 }
}

Məbləğ uyğun gəlmədikdə calculate sorğusunu yenidən göndərin. Yeni məbləği müştəriyə göstərin. 500 xətasında cavabdakı X-Trace-Id header-ini bizə göndərin.

Hesablaşma

Ödənişi siz alırsınız

AVİ ödəniş prosesinə müdaxilə etmir. Hesablaşma aylıq akt ilə aparılır.

Məbləğ yoxlanılır

payment.amount hesabladığımız məbləğlə uyğun gəlmədikdə sifariş yaradılmır.

Uzlaşdırma

payment.reference aktda uzlaşdırma üçün saxlanılır. Ləğv edilmiş sifarişlər akta daxil edilmir.

Test ssenariləri

{{ doneCount }} / {{ checkTotal }}

Real mühitə keçməzdən əvvəl test mühitində (avi.medicare.az) yoxlayın. Test açarını AVİ ayrıca verir.

{{ c.b }}

Dəstək

Texniki suallarınız üçün AVİ komandası ilə əlaqə saxlayın. Müraciətinizə aşağıdakı məlumatları əlavə edin:

X-Trace-Id externalOrderId Sorğunun təxmini vaxtı