Kurum API Teknik Kullanım Dokümanı

Bu doküman banka, kurum veya entegrasyon firmasının teknik ekibine verilebilir.

Bu dokümanda TOKEN yazan yerlere size iletilen API token yazılmalıdır. Token gizli bilgidir; herkese açık paylaşılmamalıdır.

1. API Amacı

Bu API, Markest sistemindeki ilan ve ihale bilgilerini otomatik olarak almak isteyen kurumlar için hazırlanmıştır. API ile aktif, pasif veya tamamlanmış ilanlar sorgulanabilir.

2. Size Verilecek Bilgiler

Endpoint	`GET {{ url('/api/v1/listings') }}`
Token	`mk_live_...` ile başlayan gizli erişim anahtarı.
Kimlik doğrulama yöntemi	`Authorization: Bearer TOKEN`
Cevap formatı	JSON
Zaman dilimi	Europe/Istanbul, ISO 8601 formatı.

3. İlk Test Nasıl Yapılır?

Size verilen tokenı eksiksiz kopyalayın.
Bir API test aracı açın. Postman, Insomnia veya cURL kullanabilirsiniz.
Method olarak GET seçin.
URL alanına {{ url('/api/v1/listings') }} yazın.
Header olarak Accept: application/json ekleyin.
Authorization alanında Bearer Token seçin ve tokenı yazın.
Params bölümünde status=active ve per_page=10 ekleyin.
Send / Gönder butonuna basın.

4. cURL Örnekleri

Aktif ilanları getirme:

curl -X GET "{{ url('/api/v1/listings?status=active&per_page=50') }}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TOKEN"

Tamamlanmış ilanları getirme:

curl -X GET "{{ url('/api/v1/listings?status=completed&per_page=50') }}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TOKEN"

Belirli tarihten sonra güncellenen ilanları getirme:

curl -X GET "{{ url('/api/v1/listings?status=all&updated_since=2026-06-07&per_page=100') }}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TOKEN"

5. Postman Kullanımı

Postman içinde yeni request oluşturun.
Method alanını GET yapın.
URL alanına {{ url('/api/v1/listings') }} yazın.
Authorization sekmesine girin.
Type alanını Bearer Token seçin.
Token alanına size verilen tokenı yazın.
Headers sekmesine Accept = application/json ekleyin.
Params sekmesine status = active, per_page = 50 ekleyin.
Send butonuna basın.

6. PHP Örneği

<?php

$token = 'TOKEN';
$url = '{{ url('/api/v1/listings?status=active&per_page=50') }}';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer '.$token,
    ],
]);

$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if ($statusCode === 200 && ($data['success'] ?? false)) {
    foreach ($data['data'] as $listing) {
        echo $listing['realty_no'].' - '.$listing['prices']['current_price'].PHP_EOL;
    }
} else {
    print_r($data);
}

7. JavaScript / Node.js Örneği

const token = 'TOKEN';
const url = '{{ url('/api/v1/listings?status=active&per_page=50') }}';

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();

if (response.ok && data.success) {
  data.data.forEach((listing) => {
    console.log(listing.realty_no, listing.prices.current_price);
  });
} else {
  console.error(data);
}

8. Sorgu Parametreleri

Parametre	Zorunlu mu?	Örnek	Açıklama
`status`	Hayır	`active`	`active`, `passive`, `completed` veya `all`. Boş gönderilirse aktif ilanlar döner.
`bank_code`	Hayır	`ziraatkatilim`	Token tüm ilanlara yetkiliyse banka koduna göre filtreleme yapar.
`updated_since`	Hayır	`2026-06-07`	Bu tarihten sonra güncellenen ilanları getirir.
`page`	Hayır	`1`	Sayfalama için kullanılır.
`per_page`	Hayır	`50`	Sayfa başına kaç ilan döneceğini belirler. En fazla 100 olabilir.

9. Başarılı Cevap Formatı

{
  "success": true,
  "meta": {
    "count": 1,
    "total": 1,
    "per_page": 50,
    "current_page": 1,
    "last_page": 1,
    "generated_at": "2026-06-07T12:00:00+03:00",
    "schema_version": "2026-06-07"
  },
  "data": [
    {
      "listing_no": "987654",
      "realty_no": "REALTY-1001",
      "title": "Ornek Ilan",
      "status": "active",
      "bank": {
        "code": "bankakodu",
        "name": "Banka Adi"
      },
      "prices": {
        "currency": "TRY",
        "starting_price": 1500000,
        "current_price": 1525000,
        "current_price_source": "last_offer",
        "minimum_increment": 25000,
        "offer_count": 1
      },
      "e_tender": {
        "started": true,
        "starts_at": "2026-06-07T10:00:00+03:00",
        "ends_at": "2026-06-07T14:00:00+03:00"
      },
      "property": {
        "type": 0,
        "city": "Istanbul",
        "district": "Kadikoy",
        "neighborhood": "Caferaga",
        "address": "Adres",
        "gross_m2": 100,
        "net_m2": 90
      },
      "detail_url": "{{ url('/ihaleler/ornek-ilan') }}",
      "updated_at": "2026-06-07T12:00:00+03:00"
    }
  ],
  "links": {
    "next": null,
    "prev": null
  }
}

10. Alan Açıklamaları

Alan	Açıklama
`realty_no`	Gayrimenkul / ilan numarası.
`listing_no`	İlan veya ihale takip numarası.
`prices.starting_price`	Başlangıç bedeli.
`prices.current_price`	Güncel bedel. Teklif varsa son teklif tutarıdır.
`prices.current_price_source`	`last_offer` ise fiyat son tekliften, `starting_price` ise başlangıç bedelinden gelir.
`e_tender.starts_at`	E-teklif başlangıç tarihi.
`e_tender.ends_at`	E-teklif bitiş tarihi.
`detail_url`	İlanın web sitesindeki detay sayfası.

11. Hata Cevapları

{
  "success": false,
  "error": {
    "code": "invalid_token",
    "message": "API token invalid."
  }
}

HTTP	Hata kodu	Anlamı	Çözüm
401	`missing_token`	Authorization header gönderilmemiş.	`Authorization: Bearer TOKEN` headerını ekleyin.
401	`invalid_token`	Token hatalı veya eksik kopyalanmış.	Tokenı kontrol edin. Devam ederse Markest ekibinden yeni token isteyin.
403	`inactive_token`	Token pasif.	Markest ekibiyle iletişime geçin.
403	`expired_token`	Token süresi dolmuş.	Markest ekibinden yeni token veya süre uzatma isteyin.
403	`ip_not_allowed`	İstek izinli IP listesinden gelmiyor.	API isteği attığınız sabit IP adresini Markest ekibine bildirin.
429	`rate_limited`	Dakika limiti aşıldı.	İstek sıklığını azaltın veya limit artışı talep edin.
422	validation_error	Parametrelerden biri hatalı.	`per_page` en fazla 100 olmalı, `status` izinli değerlerden biri olmalıdır.

12. Entegrasyon Önerileri

Token sunucu tarafında gizli tutulmalı, tarayıcı veya mobil uygulama içine gömülmemelidir.
Liste verisi periyodik olarak çekilecekse updated_since parametresi kullanılmalıdır.
Büyük veri çekerken page ve per_page ile sayfalama yapılmalıdır.
429 hatası alınırsa en az 60 saniye beklenip tekrar denenmelidir.
Her istekte dönen X-Request-Id değeri destek taleplerinde Markest ekibine iletilmelidir.