İçeriğe geç

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ı okuma
  • employees:write: Çalışan oluşturma ve güncelleme
  • leave:read: İzinleri okuma
  • org: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": "deniz.kaya@example.com",
  "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": "deniz.kaya@example.com",
  "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": "deniz.kaya@example.com",
  "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