API Dokümantasyonu

Base URL: https://eczane.medpov.com/api/v1. Tüm API yanıtları UTF-8 JSON döndürür. /status dışında üretim endpointleri API key ister.

Hızlı başlangıç

curl -H "X-API-Key: med_live_xxxxxxxxx" \
  "https://eczane.medpov.com/api/v1/duty?city=İstanbul&district=Kadıköy"

Başarılı cevapların temel yapısı:

{
  "ok": true,
  "data": [...],
  "meta": {
    "count": 12,
    "generatedAt": "2026-09-14T23:30:00+03:00"
  }
}

Kimlik doğrulama

Önerilen yöntem X-API-Key header'ıdır. Bearer token biçimi de desteklenir.

X-API-Key: med_live_xxxxxxxxx

Authorization: Bearer med_live_xxxxxxxxx

Endpointler

GET /status

Public servis ve veri kaynağı sağlık durumunu döndürür.

GET /cities

Desteklenen illeri, kaynağın durumunu ve bilinen eczane sayısını döndürür.

GET /duty

Parametreler: city, district, opsiyonel date=YYYY-MM-DD, limit (1–500).

GET /api/v1/duty?city=Ankara
GET /api/v1/duty?city=İstanbul&district=Kadıköy
GET /api/v1/duty?city=İzmir&date=2026-09-14

GET /nearby

Parametreler: lat, lng, opsiyonel radius (1–100 km), limit (1–100). Yalnız koordinatı bulunan eczaneler döner.

GET /pharmacies/{id}

Tek eczane ve varsa güncel nöbet bilgisini döndürür.

GET /me

Kullandığınız key'in istemci, paket ve efektif limitlerini gösterir. Client override varsa plan limitinin yerine o uygulanır.

GET /usage?days=30

Key bazında son 1–90 günlük endpoint kullanımını döndürür.

Flutter / Dart örneği

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<List<dynamic>> fetchDuty(String city) async {
  final uri = Uri.https(
    'eczane.medpov.com',
    '/api/v1/duty',
    {'city': city},
  );

  final response = await http.get(
    uri,
    headers: {'X-API-Key': 'med_live_xxxxxxxxx'},
  );

  if (response.statusCode == 429) {
    final retryAfter = response.headers['retry-after'];
    throw Exception('Rate limit. Retry-After: $retryAfter');
  }

  if (response.statusCode != 200) {
    throw Exception('API error ${response.statusCode}');
  }

  final body = jsonDecode(response.body) as Map<String, dynamic>;
  return body['data'] as List<dynamic>;
}

JavaScript

const response = await fetch(
  'https://eczane.medpov.com/api/v1/duty?city=İstanbul',
  { headers: { 'X-API-Key': 'med_live_xxxxxxxxx' } }
);
const body = await response.json();

PHP

$ch = curl_init('https://eczane.medpov.com/api/v1/duty?city=İstanbul');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-API-Key: med_live_xxxxxxxxx'],
]);
$data = json_decode(curl_exec($ch), true);

Rate limit sistemi

Her istemcinin efektif limiti dört pencere üzerinden kontrol edilir: dakika, saat, gün ve ay. Limitler istemci hesabı bazında ortak uygulanır; aynı istemci birden fazla key üretse bile kotayı çoğaltamaz. 0 değeri limitsiz anlamına gelir. Yönetici plan limitlerini değiştirebilir veya yalnız tek bir istemciye özel override tanımlayabilir.

Örnek Developer planı:

120 / dakika
3.000 / saat
10.000 / gün
200.000 / ay

API her istekte aşağıdaki header'ları döndürür:

RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 1789428660

X-RateLimit-Minute-Limit: 120
X-RateLimit-Minute-Remaining: 119
X-RateLimit-Minute-Reset: 1789428660
X-RateLimit-Hour-Limit: 3000
X-RateLimit-Day-Limit: 10000
X-RateLimit-Month-Limit: 200000

Limit aşıldığında HTTP 429 ve Retry-After döner:

{
  "ok": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API kullanım limiti aşıldı."
  },
  "meta": {
    "window": "minute",
    "limit": 120,
    "retryAfter": 37
  }
}

HTTP hata kodları

• 401 api_key_required — API key gönderilmedi.
• 401 invalid_api_key — key geçersiz, iptal veya süresi dolmuş.
• 422 invalid_date / invalid_coordinates — parametre doğrulanamadı.
• 429 rate_limit_exceeded — efektif kullanım limiti aşıldı.
• 500 server_error — beklenmeyen sunucu hatası.

Üretim önerileri

• Her uygulama/ortam için ayrı API key kullanın.
• Test ve production key'lerini ayırın.
• Key sızarsa Developer Panel veya Admin üzerinden iptal edip yenisini üretin.
• 429 durumunda Retry-After değerine göre exponential backoff uygulayın.
• Nöbet verisinde source_name ve source_updated_at alanlarını gerektiğinde kullanıcıya gösterin.

OpenAPI YAML dosyasını indir