Hızlı başlangıç
Anahtar oluşturun, API ile bir çalışan ekleyin ve izinlerini okuyun.
Geliştirici belgesi
Bu rehberin sonunda bir API anahtarınız olur, API ile bir çalışan eklersiniz ve o çalışanın izinlerini okursunuz. Komutlar curl ve jq ister. Her komut bir öncekinin bıraktığı değişkenleri ve dosyaları kullanır: aynı kabuk oturumunda, boş bir dizinde sırayla çalıştırın.
1. API modülünü açın
API erişimi hesapta kapalı başlar. Hesap sahibi Ayarlar › Sektör ve Modüller ekranından API modülünü açar. Modül planınıza bağlıdır.
2. Anahtar oluşturun
Ayarlar › API ekranında Yeni anahtar'a basın ve formu doldurun:
- Anahtar adı: anahtarı hangi sistemin kullandığını anlatan bir ad.
- Rol: anahtar bu rolün gördüğünden fazlasını göremez. Bu rehber için hesabın tamamını gören bir rol seçin (örneğin Hesap Sahibi).
- Kapsamlar: şu dördünü işaretleyin.
employees:read: Çalışanları okumaemployees:write: Çalışan oluşturma ve güncellemeleave:read: İzinleri okumaorg:read: Organizasyon yapısını okuma
- Geçerlilik süresi: varsayılan 90 gün, en çok 365 gün.
- İzinli IP adresleri: isteğe bağlıdır; boş bırakırsanız anahtar her adresten çalışır.
Oluşturma ek doğrulama ister: iki adımlı doğrulamanızın taze onayı ya da e-postanıza gelen kod. Tam anahtar biik_sk_ ile başlar ve yalnız bir kez gösterilir; hemen bir parola kasasına kaydedin.
3. Ortam değişkenlerini ayarlayın
export BIIK_API_URL="https://app.biik.io"
export BIIK_API_KEY="biik_sk_..."Uygulamanın adresi ve oluşturduğunuz anahtar. Anahtarı kaynak koda ve sürüm denetimine yazmayın.
4. Anahtarı sınayın
curl -sS "$BIIK_API_URL/api/v1/key" \
-H "Authorization: Bearer $BIIK_API_KEY"
Beklenen yanıt: 200 Başarılı
Yanıt alanları: id, name, scopes, expires_at
5. Şirketin kimliğini alın
Her çalışan bir şirkete bağlıdır. Anahtarın görebildiği ilk şirketi alıp COMPANY_ID değişkenine yazın:
curl -sS "$BIIK_API_URL/api/v1/companies?limit=1" \
-H "Authorization: Bearer $BIIK_API_KEY" | tee sirketler.json
COMPANY_ID=$(jq -r '.data[0].id' sirketler.json)
Beklenen yanıt: 200 Başarılı
Örnek yanıt (OpenAPI belgesinden)
{
"data": [
{
"id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"name": "Marmara Lojistik Ltd.",
"city": "Bursa",
"is_demo": false,
"created_at": "2026-01-05T08:00:00.000Z",
"updated_at": "2026-03-02T09:15:00.000Z"
}
],
"next_cursor": null
}6. Çalışan oluşturun
POST istekleri Idempotency-Key başlığı ister: bağlantı koparsa aynı isteği aynı anahtarla güvenle yineleyebilirsiniz (Idempotency). Yanıt başlıklarını da görmek için -i kullanılır; gövde son satırdadır.
IDEMPOTENCY_KEY="ilk-calisan-$(date +%s)"
cat > calisan.json <<JSON
{
"company_id": "$COMPANY_ID",
"first_name": "Deniz",
"last_name": "Kaya",
"hire_date": "2026-01-05"
}
JSON
curl -sS -i -X POST "$BIIK_API_URL/api/v1/employees" \
-H "Authorization: Bearer $BIIK_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
--data @calisan.json | tee olusturma.txt
EMPLOYEE_ID=$(tail -n 1 olusturma.txt | jq -r .id)
Beklenen yanıt: 201 Oluşturuldu
Örnek yanıt (OpenAPI belgesinden)
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "[email protected]",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}7. Aynı isteği yineleyin
Aynı anahtar ve aynı gövdeyle gelen istek ikinci bir çalışan açmaz: aynı kaydın güncel hâlini ve Idempotent-Replayed: true başlığını döner.
curl -sS -i -X POST "$BIIK_API_URL/api/v1/employees" \
-H "Authorization: Bearer $BIIK_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
--data @calisan.json
Beklenen yanıt: 201 Oluşturuldu · Başlık: Idempotent-Replayed: true
Yanıttaki id, EMPLOYEE_ID değişkenindeki değerle aynıdır.
Örnek yanıt (OpenAPI belgesinden)
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "[email protected]",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}8. Çalışanı okuyun
curl -sS "$BIIK_API_URL/api/v1/employees/$EMPLOYEE_ID" \
-H "Authorization: Bearer $BIIK_API_KEY"
Beklenen yanıt: 200 Başarılı
Yanıttaki id, EMPLOYEE_ID değişkenindeki değerle aynıdır.
Örnek yanıt (OpenAPI belgesinden)
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "[email protected]",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}T.C. kimlik numarası, IBAN, ücret ve kişisel bilgiler yalnız anahtar ilgili field: kapsamını, rol de aynı alan sınıfını taşıyorsa döner; bu rehberin anahtarında alanların adı da yanıtta yoktur (Kimlik ve kapsamlar).
9. İzinleri okuyun
Çalışan artık üründe Çalışanlar listesinde görünür. API'nin ilk sürümünde izin yazma yoktur: izin talebi üründen açılır ve onaylanır (İzin modülü açık olmalıdır). Örneğin İK, İzin ekranında yeni bir talep açarken kişiyi seçerek çalışan adına talep gönderir; talep onay akışında onaylanır. Talep onaylandıktan sonra:
curl -sS "$BIIK_API_URL/api/v1/leave-requests?employee_id=$EMPLOYEE_ID" \
-H "Authorization: Bearer $BIIK_API_KEY"
Beklenen yanıt: 200 Başarılı
Örnek yanıt (OpenAPI belgesinden)
{
"data": [
{
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"type_hidden": false,
"leave_type_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
"status": "approved",
"start_date": "2026-07-06",
"end_date": "2026-07-10",
"half_day": false,
"amount": 5,
"unit": "day",
"paid": true,
"is_demo": false,
"created_at": "2026-06-15T11:20:00.000Z",
"updated_at": "2026-06-16T08:05:00.000Z"
}
],
"next_cursor": null
}curl -sS "$BIIK_API_URL/api/v1/leave-balances?employee_id=$EMPLOYEE_ID" \
-H "Authorization: Bearer $BIIK_API_KEY"
Beklenen yanıt: 200 Başarılı
Örnek yanıt (OpenAPI belgesinden)
{
"data": [
{
"employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"leave_type_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
"unit": "day",
"balance": 9,
"reserved": 2,
"available": 7
}
],
"next_cursor": null
}Sonra
- Değişiklikleri sormak yerine bildirim almak için Webhook.
- Bütün uçlar ve alanlar: API başvurusu.
- Hata yanıtları ve yeniden deneme: Hata modeli.