Dokümantasyon

Giriş

apibir; Türkiye ve dünya piyasalarına ait ekonomik, tarımsal, kamusal ve hukuki verileri tek bir REST API çatısı altında sunar. Tüm servisler aynı kimlik doğrulamayı, aynı yanıt zarfını ve aynı kredi havuzunu paylaşır — bir servisi öğrendiğinizde hepsini öğrenmiş olursunuz.

• Tüm uçlar HTTPS üzerinden çalışır; HTTP istekleri 301 ile yönlendirilir.
• Yanıtlar daima UTF-8 JSON döner. Accept: application/json önerilir.
• Tarih ve saatler ISO-8601 formatında, varsayılan olarak Europe/Istanbul saat diliminde döner.
• Sayısal alanlar string değil, number tipindedir.

Temel adres & sürümleme

Sürüm numarası yol içinde taşınır. Geriye dönük uyumsuz bir değişiklik yapılacaksa /v2 yayınlanır ve /v1 en az 12 ay daha desteklenir. Uyumlu eklemeler (yeni alan, yeni uç nokta) mevcut sürüme yapılır; bu nedenle istemcinizin bilmediği alanları yok sayacak şekilde yazılması gerekir.

Kimlik doğrulama

Her istekte API anahtarınızı Authorization başlığında gönderin:

curl "https://api.apibir.com/v1/fx/latest" \
  -H "Authorization: apikey APIBIR-8f2c4b7e9a1d3c5f7b2e9d41"

const headers = {
  Authorization: `apikey ${process.env.APIBIR_KEY}`,
  Accept: "application/json"
};

headers = {
    "Authorization": f"apikey {os.environ['APIBIR_KEY']}",
    "Accept": "application/json",
}

Başlık kullanamadığınız durumlarda ?apikey= sorgu parametresi de kabul edilir, ancak anahtar sunucu loglarına düşebileceği için üretimde önerilmez.

Yanıt zarfı

Başarılı ve başarısız tüm yanıtlar aynı üst düzey yapıyı kullanır:

{
  "success": true,
  "creditsUsed": 1,
  "creditsRemaining": 48213,
  "requestId": "req_01J9XK3M2P7QZ",
  "meta": { "page": 1, "limit": 100, "total": 42, "totalPages": 1 },
  "data": [ /* ... */ ]
}

{
  "success": false,
  "creditsUsed": 0,
  "requestId": "req_01J9XK4A8B2NC",
  "error": {
    "code": "invalid_parameter",
    "message": "'date' parametresi YYYY-MM-DD formatında olmalıdır.",
    "field": "date",
    "docs": "https://apibir.com/dokumantasyon.html#hata-kodlari"
  }
}

Kredi sistemi

apibir'de her plan aylık bir kredi havuzu içerir ve bu havuz tüm servisler arasında ortaktır. Standart bir okuma isteği 1 kredi harcar. Ağır sorgular (uzun zaman serileri, tam metin arama, toplu istek) daha fazla kredi tüketebilir; harcanan miktar her yanıtın creditsUsed alanında görünür.

Krediler her ayın 1'i saat 00:00'da (Europe/Istanbul) sıfırlanır. Devretmez. Panelden %80 ve %95 eşiklerinde e-posta uyarısı kurabilirsiniz.

Hız limitleri

Kredi limitinden bağımsız olarak, ani yük oluşturmayı engellemek için saniyelik istek limiti uygulanır.

Limit aşıldığında 429 Too Many Requests döner ve yanıtta şu başlıklar bulunur:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1754557325
Retry-After: 1

Sayfalama & sıralama

Çok kayıt dönebilen uçlarda page ve limit parametreleri kullanılır. Varsayılan limit=100, üst sınır limit=500'dür.

curl "https://api.apibir.com/v1/vehicles/new/prices?brand=toyota&page=2&limit=50" \
  -H "Authorization: apikey $APIBIR_KEY"

{
  "success": true,
  "meta": {
    "page": 2,
    "limit": 50,
    "total": 187,
    "totalPages": 4,
    "hasNext": true,
    "nextPage": "/v1/vehicles/new/prices?brand=toyota&page=3&limit=50"
  },
  "data": [ /* 50 kayıt */ ]
}

Sıralama için sort parametresini kullanın: sort=price_desc, sort=date_asc gibi. Desteklenen alanlar her API'nin kendi sayfasında listelenir.

Filtreleme

Çoğu uçta virgülle ayrılmış çoklu değer, tarih aralığı ve karşılaştırma operatörleri desteklenir.

Önbellek & ETag

Her yanıt bir ETag ve uygun Cache-Control başlığı içerir. Bir sonraki isteğinizde If-None-Match gönderirseniz veri değişmemişse 304 Not Modified alırsınız — bu yanıt kredi harcamaz.

# İlk istek
curl -i "https://api.apibir.com/v1/hal/prices?city=istanbul" \
  -H "Authorization: apikey $APIBIR_KEY"
# ← ETag: "a91f7c33"   (creditsUsed: 1)

# İkinci istek
curl -i "https://api.apibir.com/v1/hal/prices?city=istanbul" \
  -H "Authorization: apikey $APIBIR_KEY" \
  -H 'If-None-Match: "a91f7c33"'
# ← HTTP/1.1 304 Not Modified   (creditsUsed: 0)

Hata kodları

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Aylık kredi limitiniz doldu. 2026-09-01 tarihinde yenilenecek.",
    "docs": "https://apibir.com/fiyatlandirma.html"
  },
  "creditsUsed": 0,
  "creditsRemaining": 0,
  "requestId": "req_01J9XM7Q4T1RD"
}

Webhook

Ekonomik takvim, mevzuat değişiklikleri ve Resmi Gazete servislerinde olay bazlı bildirim alabilirsiniz. Abonelik oluşturduğunuzda belirttiğiniz URL'ye POST ile JSON gövde gönderilir.

curl -X POST "https://api.apibir.com/v1/official-gazette/webhooks" \
  -H "Authorization: apikey $APIBIR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ornek-sirket.com/hooks/apibir",
    "events": ["gazette.published"],
    "filters": { "importance": "high", "topics": ["vergi", "is-hukuku"] },
    "secret": "whsec_9c2f4a..."
  }'

{
  "event": "gazette.published",
  "deliveryId": "dlv_01J9XN2K5V8",
  "sentAt": "2026-08-08T09:02:11+03:00",
  "data": {
    "date": "2026-08-08",
    "gazetteNumber": 33024,
    "itemCount": 19,
    "highlights": ["Gelir Vergisi Genel Tebliği (Seri No: 331)"]
  }
}

Her teslimat X-Apibir-Signature başlığında HMAC-SHA256 imzası taşır. İmzayı doğrulayın:

import crypto from "node:crypto";

function dogrula(rawBody, signatureHeader, secret) {
  const beklenen = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(beklenen),
    Buffer.from(signatureHeader)
  );
}

import hmac
import hashlib

def dogrula(raw_body: bytes, signature: str, secret: str) -> bool:
    beklenen = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(beklenen, signature)

Teslimat başarısız olursa (2xx dışı yanıt) 1, 5, 30 ve 120 dakika sonra yeniden denenir. Dört deneme de başarısız olursa abonelik paused durumuna geçer ve size e-posta gönderilir.

Toplu istek (batch)

Tek HTTP çağrısında en fazla 20 alt istek gönderebilirsiniz. Her alt istek ayrı ayrı ücretlendirilir ancak ağ gidiş-dönüşünden tasarruf edersiniz.

curl -X POST "https://api.apibir.com/v1/batch" \
  -H "Authorization: apikey $APIBIR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "id": "kur",    "path": "/fx/latest",     "params": { "symbols": "USD,EUR" } },
      { "id": "yakit",  "path": "/fuel/prices",   "params": { "city": "istanbul" } },
      { "id": "endeks", "path": "/indices",       "params": { "codes": "XU100" } }
    ]
  }'

{
  "success": true,
  "creditsUsed": 3,
  "creditsRemaining": 48210,
  "results": {
    "kur":    { "success": true, "data": [ /* ... */ ] },
    "yakit":  { "success": true, "data": [ /* ... */ ] },
    "endeks": { "success": true, "data": [ /* ... */ ] }
  }
}

OpenAPI & Postman

Makine tarafından okunabilir tanımlar:

İnteraktif Swagger arayüzü: https://apibir.com/docs. Postman koleksiyonunu panelinizden tek tıkla içe aktarabilirsiniz. OpenAPI şeması aynı zamanda istemci kodu üretmek ve yapay zeka asistanlarına araç tanımı vermek için kullanılabilir — ayrıntılar AI & Dashboard sayfasında.

SDK'lar

Resmi istemci kütüphaneleri ince bir sarmalayıcıdır; kimlik doğrulama, yeniden deneme ve tip tanımlarını içerir.

npm install @apibir/sdk

# kullanım
import { ApiBir } from "@apibir/sdk";
const client = new ApiBir(process.env.APIBIR_KEY);

const kurlar = await client.fx.latest({ symbols: ["USD", "EUR"] });
const yakit  = await client.fuel.prices({ city: "istanbul" });

pip install apibir

# kullanım
from apibir import ApiBir

client = ApiBir()  # APIBIR_KEY ortam değişkeninden okunur
kurlar = client.fx.latest(symbols=["USD", "EUR"])
yakit  = client.fuel.prices(city="istanbul")

composer require apibir/apibir-php

// kullanım
$client = new \ApiBir\Client(getenv('APIBIR_KEY'));
$kurlar = $client->fx()->latest(['symbols' => 'USD,EUR']);

dotnet add package ApiBir

// kullanım
var client = new ApiBirClient(Environment.GetEnvironmentVariable("APIBIR_KEY"));
var kurlar = await client.Fx.LatestAsync(symbols: "USD,EUR");

Güvenlik

• Anahtarları asla istemci tarafı kodda, mobil uygulama paketinde veya genel bir depoda tutmayın.
• Panelden IP allowlist ve domain kısıtı tanımlayın.
• Anahtarları en az 6 ayda bir döndürün (rotate). Eski anahtar 24 saat geçerli kalır, kesinti olmaz.
• Webhook uç noktanızda imza doğrulaması yapmadan gövdeye güvenmeyin.
• Tüm veriler aktarım sırasında TLS 1.3 ile şifrelenir; kişisel veri işlenmez.

Sık sorulanlar

Faturalama, kota ve ticari sorular için SSS sayfasına bakın. Teknik bir sorun için destek ekibine requestId ile birlikte yazın.