Entegrasyon API'si

API'yi şirketin bilgi işlem ekibi ya da entegrasyonu kuran danışman kullanır. Burdaa tarafında kurulum gerekmez:

1. Burdaa panelinde Şirket Ayarları → Entegrasyonlar → API anahtarları bölümünden anahtar oluşturun. Anahtar yalnızca bir kez gösterilir.
2. Her isteğe anahtarı başlık olarak ekleyin.
3. Cevaplar JSON; kayıtlar data alanında, sayfa sayfa gelir (bkz. sayfalama).

curl "https://app.burdaa.co/api/v1/timesheet?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer brd_..."

Her istekte Authorization: Bearer <anahtar> başlığı gönderilir. Anahtarlar brd_ ile başlar ve şirkete özeldir: yalnızca o şirketin verisini döndürür.

• Burdaa anahtarın kendisini saklamaz, yalnızca özetini (SHA-256) tutar.
• Ücret verisi ayrı izindir: anahtar oluşturulurken "Ücret özetini de okuyabilsin" işaretlenmezse /pay-summary 403 döner.
• Anahtar panelden iptal edildiği anda çalışmaz; son kullanım zamanı panelde görünür.

Anahtar başına dakikada 60 istek. Aşılırsa 429 ve Retry-After: 60 döner; bekleyip tekrar deneyin. Günlük ya da aylık toplu çekim için bu sınır fazlasıyla yeterlidir.

Tüm liste uçları aynı biçimde döner. Sayfa başına varsayılan 1000 kayıt gelir; limit ile 5000'e kadar artırabilirsiniz. has_more true ise aynı isteği offset=next_offset ile tekrarlayın. Sıralama sabittir, sayfalar arasında kayıt kaymaz.

{
  "data": [ … ],
  "has_more": true,
  "next_offset": 1000
}

import requests

def fetch_all(path, **params):
    rows, offset = [], 0
    while True:
        r = requests.get(f"https://app.burdaa.co/api/v1{path}", params={**params, "offset": offset},
                         headers={"Authorization": "Bearer brd_..."})
        r.raise_for_status()
        page = r.json()
        rows += page["data"]
        if not page["has_more"]:
            return rows
        offset = page["next_offset"]

timesheet = fetch_all("/timesheet", **{"from": "2026-09-01", "to": "2026-09-30"})

Şirketin tüm çalışanları. İşten ayrılanlar da gelir; is_active ile ayırın. Kendi sisteminizdeki kayıtla employee_code (sicil no) üzerinden eşleştirin.

Kişi × gün puantajı: giriş-çıkış, çalışılan süre, geç kalma, mesai. Süreler dakika cinsinden.

• Yalnızca kapanmış günler: to bugünden önce olmalı. Gün içindeki anlık durum için webhook kullanın.
• İstek başına en fazla 63 gün.

{
  "data": [
    {
      "employee_id": "3f6c…",
      "employee_code": "1042",
      "full_name": "Ayşe Yılmaz",
      "work_date": "2026-09-01",
      "day_type": "worked",
      "location_name": "Kadıköy",
      "store_code": "M012",
      "shift_start": "09:00:00",
      "shift_end": "18:00:00",
      "check_in": "2026-09-01T06:12:00+00:00",
      "check_out": "2026-09-01T15:31:00+00:00",
      "worked_minutes": 559,
      "late_minutes": 12,
      "early_leave_minutes": 0,
      "overtime_minutes": 0,
      "shortfall_minutes": 0
    }
  ]
}

Burdaa'nın ücret hesabının özeti: maaş, mesai ücretleri, kesintiler, avans ve net tutar. Yalnızca ücret izni verilmiş anahtarla. Vergi ve SGK içermez; bordro programınız için girdidir.

Giriş-çıkış okutmalarının kendisi, zaman sırasıyla. Puantajın aksine bugün de alınabilir. Alanlar webhook bildirimindeki data ile aynıdır; webhook'ta kaçırılan bir olayı bu uçla telafi edebilirsiniz.

• Gün sınırları şirketin saat dilimine göredir. İstek başına en fazla 63 gün.
• Silinen okutmalar listede yer almaz; düzeltilen okutma son haliyle gelir.

Tarih aralığıyla kesişen izin kayıtları. Puantajdaki day_type izni yalnızca geçmiş günlerde gösterir; bu uç nokta ileri tarihli ve onay bekleyen izinleri de verir. Değişiklikleri anında almak için izin webhook olaylarını kullanın.

• İstek başına en fazla 366 gün; gelecek tarihler serbest.
• Çalışan ve yönetici notları ile ekler (ör. rapor) gizlilik nedeniyle verilmez.

Hatalar { "error": { "code": "…", "message": "…" } } biçiminde döner. code sabittir, kodunuzda onu kontrol edin.

• Zamanlar ISO 8601, UTC. work_date ve vardiya saatleri şirketin yerel saatindedir (Türkiye için Europe/Istanbul).
• Sürümleme: adresler /v1 altındadır. Alan eklemek geriye dönük uyumlu kabul edilir; kırıcı bir değişiklik olursa yeni sürüm açılır, eskisi çalışmaya devam eder.
• Logo, Mikro gibi masaüstü bordro programları için dosya aktarımı ya da özel bir entegrasyon ihtiyacınız varsa bize yazın.