Company API Dokümantasyonu

İzin ve masraf verilerinizi kendi sistemlerinize (ERP, muhasebe, iç panel) programatik olarak çekin. Bu API firma verisine karşı salt-okumadır — hiçbir kayıt oluşturmaz, değiştirmez veya silmez. Tek yazma yüzeyi, ajanınızın empuno ekibine açtığı taleplerdir (geliştirme isteği, hata, eleştiri, soru). Kimlik doğrulama, firma panelinden yönettiğiniz bir API anahtarıyla yapılır.

Okumanın ötesi mi lazım? İzin onayı, bordro, vardiya, PDKS, ekipman, işe alım dahil panelde yapabildiğiniz her işlemi yapay zekâ ajanlarınıza açmak için Ajan API'si ve empuno CLI rehberine bakın.
Temel URL
https://empuno.com/api/company/v1
Kimlik Doğrulama
Authorization: Bearer <API_KEY>
Erişim
read-only (talepler hariç)
Hız Sınırı
120 istek/dakika, 3000 istek/saat (anahtar başına)

Başlarken

1. Firma panelinizde Firma Ayarları → API & Ajan sekmesine gidin ve "Salt-okuma" türünde bir anahtar oluşturun. Anahtar yalnızca oluşturma anında bir kez gösterilir; güvenli bir yere kaydedin.

2. Anahtarı her isteğin Authorization başlığında gönderin:

cURL
curl -H "Authorization: Bearer emp_live_XXXXXXXX" \
  https://empuno.com/api/company/v1/me

3. Sayfalama: liste uçları ?page ve ?per_page (max 100) alır; yanıt meta içinde toplam sayfa bilgisini döner.

Genel

Anahtar doğrulama ve keşif.

GET /api/company/v1/me

Anahtarın geçerliliğini test etmek, bağlı firmayı ve mevcut uçları görmek için ilk çağrı.

Örnek yanıt
{
    "company": {
        "id": 12,
        "name": "Örnek A.Ş.",
        "timezone": "Europe/Istanbul"
    },
    "api_key": {
        "id": 3,
        "name": "Muhasebe entegrasyonu",
        "scopes": [
            "leaves.read",
            "expenses.read"
        ],
        "last_used_at": "2026-07-15T09:12:00+00:00"
    },
    "access": "read-only",
    "rate_limit": {
        "per_minute": 120,
        "per_hour": 3000
    }
}
GET /api/company/v1/reference/{name}

Bir alanın kabul ettiği değerler: sgk_exit_codes, employee_document_types, equipment_categories, currencies, ticket_kinds, departments, branches, leave_types. Adsız çağrı (/reference) mevcut listeleri döner. CLI: `empuno reference <ad>`.

ParametreYerAçıklama
name path Referans adı (ör. sgk_exit_codes)
Örnek yanıt
{
    "name": "employee_document_types",
    "data": [
        {
            "value": "is_sozlesmesi",
            "label": "İş Sözleşmesi"
        },
        {
            "value": "ibraname",
            "label": "İbraname"
        }
    ]
}
GET /api/company/v1/catalog

Ajan anahtarının çalıştırabileceği panel komutları (yöntem, yol, yol parametreleri, alanlar, gereken yetki). empuno CLI komutlarını buradan okur. Salt-okuma anahtarında liste boş döner. Ayrıntı: /api-docs/agent.

ParametreYerAçıklama
all query 1 → kapsam dışı komutlar da (allowed=false ile)
module query Modüle göre filtre (ör. leaves, payroll)
q query Komut adı / Türkçe başlık araması (ör. izin)
Örnek yanıt
{
    "base_url": "https://empuno.com",
    "cli_version": "1.0.0",
    "access": "agent",
    "count": 1,
    "commands": [
        {
            "command": "leave-requests.reject",
            "method": "POST",
            "path": "/manager/leave-requests/{leaveRequest}/reject",
            "path_params": [
                "leaveRequest"
            ],
            "kind": "write",
            "module": "leaves",
            "module_label": "İzin Yönetimi",
            "permissions": [
                "leaves.manage"
            ],
            "requires_company_admin": false,
            "title": "İzin talepleri — Reddet",
            "summary": "İzin talepleri — Reddet",
            "description": null,
            "fields": {
                "rejection_reason": "required|string|max:1000"
            },
            "allowed": true
        }
    ]
}

Çalışanlar

İzin/masraf kayıtlarındaki employee_id'yi isim ve departmana çözmek için minimal roster. Hassas alanlar (kimlik no, maaş, banka, adres) dönmez.

GET /api/company/v1/employees

Firmanın çalışanları (sayfalı).

ParametreYerAçıklama
status query active | inactive | terminated (virgülle çoklu)
search query Ad/soyad/personel no araması
page query Sayfa (varsayılan 1)
per_page query Sayfa boyutu (varsayılan 25, max 100)
Örnek yanıt
{
    "data": [
        {
            "id": 45,
            "employee_number": "ABCD-001",
            "full_name": "Ahmet Yılmaz",
            "email": "ahmet@ornek.com",
            "department": "Yazılım",
            "position": "Kıdemli Geliştirici",
            "status": "active",
            "hire_date": "2022-03-01",
            "termination_date": null,
            "sgk_exit_code": null
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 42,
        "last_page": 2,
        "from": 1,
        "to": 25
    }
}
GET /api/company/v1/employees/{id}

Kimlik ile tek çalışan.

ParametreYerAçıklama
id path Çalışan ID
Örnek yanıt
{
    "data": {
        "id": 45,
        "employee_number": "ABCD-001",
        "full_name": "Ahmet Yılmaz",
        "email": "ahmet@ornek.com",
        "department": "Yazılım",
        "position": "Kıdemli Geliştirici",
        "status": "active",
        "hire_date": "2022-03-01"
    }
}

İzinler

İzin talepleri ve izin türleri (salt-okuma).

GET /api/company/v1/leaves

Firmanın izin talepleri (sayfalı, tarih aralığına göre filtrelenebilir).

ParametreYerAçıklama
status query pending | approved | rejected | cancelled (virgülle çoklu)
employee_id query Çalışana göre filtre
leave_type_id query İzin türüne göre filtre
from query YYYY-MM-DD — bu tarihle kesişen izinler
to query YYYY-MM-DD — bu tarihle kesişen izinler
search query Çalışan adı/no araması
page query Sayfa
per_page query Sayfa boyutu (max 100)
Örnek yanıt
{
    "data": [
        {
            "id": 123,
            "status": "approved",
            "employee": {
                "id": 45,
                "employee_number": "ABCD-001",
                "full_name": "Ahmet Yılmaz",
                "department": "Yazılım"
            },
            "leave_type": {
                "id": 2,
                "name": "Yıllık İzin",
                "type_key": "annual"
            },
            "start_date": "2026-08-01",
            "end_date": "2026-08-05",
            "days": 5,
            "duration_type": "full_day",
            "start_time": null,
            "end_time": null,
            "hours": null,
            "reason": "Yıllık izin",
            "rejection_reason": null,
            "substitute_employee": null,
            "approved_at": "2026-07-15T14:30:00+00:00",
            "created_at": "2026-07-10T09:00:00+00:00",
            "updated_at": "2026-07-15T14:30:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 8,
        "last_page": 1,
        "from": 1,
        "to": 8
    }
}
GET /api/company/v1/leaves/{id}

Tek izin detayı (belge yükümlülüğü bilgisi dahil; tıbbi belge dosyaları KVKK gereği paylaşılmaz).

ParametreYerAçıklama
id path İzin ID
Örnek yanıt
{
    "data": {
        "id": 123,
        "status": "approved",
        "employee": {
            "id": 45,
            "employee_number": "ABCD-001",
            "full_name": "Ahmet Yılmaz",
            "department": "Yazılım"
        },
        "leave_type": {
            "id": 2,
            "name": "Yıllık İzin",
            "type_key": "annual"
        },
        "start_date": "2026-08-01",
        "end_date": "2026-08-05",
        "days": 5,
        "duration_type": "full_day",
        "document": {
            "deadline": null,
            "obligation_status": null,
            "has_attachments": false
        }
    }
}
GET /api/company/v1/leave-types

Firmanın aktif izin türleri (referans veri).

Örnek yanıt
{
    "data": [
        {
            "id": 2,
            "name": "Yıllık İzin",
            "type_key": "annual",
            "description": null,
            "max_days_per_year": 14,
            "quota_type": "accumulated",
            "requires_document": false,
            "affects_annual_balance": true
        }
    ]
}

Masraflar

Masraf kayıtları, kategoriler ve fiş görselleri (salt-okuma).

GET /api/company/v1/expenses

Firmanın masrafları (sayfalı). Fiş görseli olanlarda `receipt_url` dolu döner.

ParametreYerAçıklama
status query pending | approved | rejected | paid | cancelled (virgülle çoklu)
employee_id query Çalışana göre filtre
category_id query Kategoriye göre filtre
from query YYYY-MM-DD — masraf tarihi >=
to query YYYY-MM-DD — masraf tarihi <=
search query Başlık/işyeri araması
page query Sayfa
per_page query Sayfa boyutu (max 100)
Örnek yanıt
{
    "data": [
        {
            "id": 987,
            "status": "approved",
            "title": "Ofis malzemesi",
            "description": null,
            "amount": 250.5,
            "currency": "TRY",
            "tax_amount": 37.58,
            "expense_date": "2026-07-10",
            "merchant_name": "Kırtasiye A.Ş.",
            "payment_method": "kredi_karti",
            "category": {
                "id": 8,
                "name": "Ofis Malzemeleri"
            },
            "employee": {
                "id": 45,
                "employee_number": "ABCD-001",
                "full_name": "Ahmet Yılmaz",
                "department": "Yazılım"
            },
            "has_receipt": true,
            "receipt_url": "https://empuno.com/api/company/v1/expenses/987/receipt",
            "approved_at": "2026-07-11T10:30:00+00:00",
            "paid_at": null,
            "rejected_reason": null,
            "submitted_at": "2026-07-11T09:00:00+00:00",
            "created_at": "2026-07-11T08:45:00+00:00",
            "updated_at": "2026-07-11T10:30:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 30,
        "last_page": 2,
        "from": 1,
        "to": 25
    }
}
GET /api/company/v1/expenses/{id}

Tek masraf detayı — kalem (items) listesi ve fiş görseli varyant URL'leri dahil.

ParametreYerAçıklama
id path Masraf ID
Örnek yanıt
{
    "data": {
        "id": 987,
        "status": "approved",
        "title": "Ofis malzemesi",
        "amount": 250.5,
        "currency": "TRY",
        "expense_date": "2026-07-10",
        "merchant_name": "Kırtasiye A.Ş.",
        "has_receipt": true,
        "receipt_url": "https://empuno.com/api/company/v1/expenses/987/receipt",
        "items": [
            {
                "name": "Defter (5'li)",
                "quantity": 1,
                "price": 150
            }
        ],
        "receipt": {
            "url": "https://empuno.com/api/company/v1/expenses/987/receipt",
            "processed_url": "https://empuno.com/api/company/v1/expenses/987/receipt?variant=processed",
            "original_url": "https://empuno.com/api/company/v1/expenses/987/receipt?variant=original"
        }
    }
}
GET /api/company/v1/expenses/{id}/receipt

Fiş görseline erişim. Anahtar + firma sahipliği doğrulanır, taze imzalı görsel URL'ine 302 yönlendirir. HTTP istemcinizi yönlendirmeyi takip edecek şekilde ayarlayın.

ParametreYerAçıklama
id path Masraf ID
variant query processed (varsayılan) | original
302 Found → Location: imzalı görsel URL'i (image/jpeg). Fiş yoksa 404 JSON.
GET /api/company/v1/expense-categories

Firmanın aktif masraf kategorileri (referans veri).

Örnek yanıt
{
    "data": [
        {
            "id": 8,
            "name": "Ofis Malzemeleri",
            "description": null,
            "requires_receipt": true,
            "max_amount": null
        }
    ]
}

Talepler (ticket)

Ajanınızın empuno ekibine geliştirme isteği, hata bildirimi, eleştiri ya da soru iletmesi ve yazışması. Firma verisini değiştirmeyen tek yazma yüzeyidir; her anahtar türü kullanabilir. Talepler firma düzeyinde görünür; başka firmanınki 404. Yazma uçları ayrıca dakikada 6, saatte 40 istekle sınırlıdır. Kişisel veri (TCKN, maaş, sağlık) yazmayın. CLI: `empuno tickets`.

GET /api/company/v1/tickets

Firmanın talepleri, son mesaja göre yeniden eskiye. `unread=true` olanlarda empuno ekibinin okunmamış yanıtı vardır.

ParametreYerAçıklama
status query all (varsayılan) | active | open | answered | closed
unread query 1 → yalnız okunmamış yanıtı olanlar
mine query 1 → yalnız bu anahtarın açtıkları
page query Sayfa
per_page query Sayfa boyutu (max 100)
Örnek yanıt
{
    "data": [
        {
            "number": "TK-7Q3M9X",
            "title": "Toplu izin onayı komutu",
            "kind": "feature",
            "kind_label": "Geliştirme isteği",
            "priority": "normal",
            "status": "answered",
            "unread": true,
            "messages_count": 2,
            "last_message_at": "2026-11-05T10:12:00+00:00",
            "last_message_by": "staff",
            "opened_via_key": "İK asistanı (Claude)",
            "closed_at": null,
            "closed_by": null,
            "created_at": "2026-11-05T09:40:00+00:00",
            "context": {
                "command": "leave-requests.approve"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1,
        "from": 1,
        "to": 1
    }
}
POST /api/company/v1/tickets

Yeni talep ve ilk mesajı. Gövde JSON: `title` (≤200), `kind`, `body` (≤10000), isteğe bağlı `priority` ve `context` (serbest JSON, ≤8 KB — ilgili komut, hata kodu vb.). Yanıt 201 ve talep numarası (TK-…). Mükerrer koruması: aynı başlıkta açık talep varsa ya da aynı `Idempotency-Key` başlığı gönderilirse yeni talep açılmaz, mevcut talep 200 + `duplicate: true` ile döner.

ParametreYerAçıklama
title body Kısa başlık
kind body feature | bug | criticism | question | missing_command | docs
body body Ayrıntılı açıklama
priority body low | normal (varsayılan) | high
context body Serbest JSON nesnesi (ör. {"command": "leave-requests.approve"})
Örnek yanıt
{
    "ok": true,
    "message": "Talep açıldı: TK-7Q3M9X.",
    "data": {
        "number": "TK-7Q3M9X",
        "status": "open",
        "messages": [
            {
                "id": 1,
                "author_type": "agent",
                "author": "İK asistanı (Claude) · Örnek A.Ş.",
                "body": "Bekleyen izinleri tek komutla onaylamak istiyoruz.",
                "created_at": "2026-11-05T09:40:00+00:00"
            }
        ]
    }
}
GET /api/company/v1/tickets/{number}

Tüm mesajlarla talep. Okumak, empuno yanıtının "okunmadı" işaretini kaldırır. `author_type`: agent (siz), staff (empuno ekibi), system (kapatıldı / yeniden açıldı notu).

ParametreYerAçıklama
number path Talep numarası (TK-…)
Örnek yanıt
{
    "data": {
        "number": "TK-7Q3M9X",
        "status": "answered",
        "messages": [
            {
                "id": 1,
                "author_type": "agent",
                "author": "İK asistanı (Claude) · Örnek A.Ş.",
                "body": "Bekleyen izinleri tek komutla onaylamak istiyoruz.",
                "created_at": "2026-11-05T09:40:00+00:00"
            },
            {
                "id": 2,
                "author_type": "staff",
                "author": "empuno destek ekibi",
                "body": "Ne sıklıkla gerekiyor?",
                "created_at": "2026-11-05T10:12:00+00:00"
            }
        ]
    }
}
POST /api/company/v1/tickets/{number}/messages

Yazışmaya mesaj ekler (`body`), talep yeniden "yanıt bekliyor" olur. Kapalı talebe yazılamaz (409) — yeni talep açıp eski numarayı belirtin.

ParametreYerAçıklama
number path Talep numarası
body body Mesaj (≤10000)
Örnek yanıt
{
    "ok": true,
    "message": "Mesaj eklendi."
}
POST /api/company/v1/tickets/{number}/close

Konu çözüldüyse talebi kapatır; isteğe bağlı `note` son mesaj olarak eklenir.

ParametreYerAçıklama
number path Talep numarası
note body Kapanış notu (isteğe bağlı)
Örnek yanıt
{
    "ok": true,
    "message": "Talep kapatıldı: TK-7Q3M9X."
}

Hata Kodları

KodAnlamı
401Anahtar eksik veya geçersiz/iptal edilmiş.
403Anahtara bağlı firma pasif durumda ya da anahtarın kapsamı bu ucu içermiyor (scope_required).
404Kayıt bulunamadı (veya başka bir firmaya ait).
429Hız sınırı aşıldı — bir süre sonra tekrar deneyin.

Verilerinizi tek yerde yönetin

empuno; PDKS, bordro, izin ve masraf süreçlerinizi tek panelde toplar. API ile bunları kendi sistemlerinize de bağlayın.

Ücretsiz Dene →

API firma verisine karşı salt-okumadır ve yalnızca anahtarın bağlı olduğu firmanın verilerini döndürür. Taleplere kişisel veri (kimlik no, maaş, sağlık bilgisi) yazmayın. Fiş görselleri ve çalışan verileri KVKK kapsamındadır; anahtarı yalnızca yetkili sistemlerle paylaşın. Anahtarı firma panelinden istediğiniz an iptal edebilirsiniz.