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.
https://empuno.com/api/company/v1Authorization: Bearer <API_KEY>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 -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.
Anahtarın geçerliliğini test etmek, bağlı firmayı ve mevcut uçları görmek için ilk çağrı.
{
"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
}
}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>`.
| Parametre | Yer | Açıklama |
|---|---|---|
name |
path | Referans adı (ör. sgk_exit_codes) |
{
"name": "employee_document_types",
"data": [
{
"value": "is_sozlesmesi",
"label": "İş Sözleşmesi"
},
{
"value": "ibraname",
"label": "İbraname"
}
]
}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.
| Parametre | Yer | Açı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) |
{
"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.
Firmanın çalışanları (sayfalı).
| Parametre | Yer | Açı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) |
{
"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
}
}Kimlik ile tek çalışan.
| Parametre | Yer | Açıklama |
|---|---|---|
id |
path | Çalışan ID |
{
"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).
Firmanın izin talepleri (sayfalı, tarih aralığına göre filtrelenebilir).
| Parametre | Yer | Açı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) |
{
"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
}
}Tek izin detayı (belge yükümlülüğü bilgisi dahil; tıbbi belge dosyaları KVKK gereği paylaşılmaz).
| Parametre | Yer | Açıklama |
|---|---|---|
id |
path | İzin ID |
{
"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
}
}
}Firmanın aktif izin türleri (referans veri).
{
"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).
Firmanın masrafları (sayfalı). Fiş görseli olanlarda `receipt_url` dolu döner.
| Parametre | Yer | Açı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) |
{
"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
}
}Tek masraf detayı — kalem (items) listesi ve fiş görseli varyant URL'leri dahil.
| Parametre | Yer | Açıklama |
|---|---|---|
id |
path | Masraf ID |
{
"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"
}
}
}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.
| Parametre | Yer | Açıklama |
|---|---|---|
id |
path | Masraf ID |
variant |
query | processed (varsayılan) | original |
Firmanın aktif masraf kategorileri (referans veri).
{
"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`.
Firmanın talepleri, son mesaja göre yeniden eskiye. `unread=true` olanlarda empuno ekibinin okunmamış yanıtı vardır.
| Parametre | Yer | Açı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) |
{
"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
}
}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.
| Parametre | Yer | Açı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"}) |
{
"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"
}
]
}
}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).
| Parametre | Yer | Açıklama |
|---|---|---|
number |
path | Talep numarası (TK-…) |
{
"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"
}
]
}
}Yazışmaya mesaj ekler (`body`), talep yeniden "yanıt bekliyor" olur. Kapalı talebe yazılamaz (409) — yeni talep açıp eski numarayı belirtin.
| Parametre | Yer | Açıklama |
|---|---|---|
number |
path | Talep numarası |
body |
body | Mesaj (≤10000) |
{
"ok": true,
"message": "Mesaj eklendi."
}Konu çözüldüyse talebi kapatır; isteğe bağlı `note` son mesaj olarak eklenir.
| Parametre | Yer | Açıklama |
|---|---|---|
number |
path | Talep numarası |
note |
body | Kapanış notu (isteğe bağlı) |
{
"ok": true,
"message": "Talep kapatıldı: TK-7Q3M9X."
}Hata Kodları
| Kod | Anlamı |
|---|---|
| 401 | Anahtar eksik veya geçersiz/iptal edilmiş. |
| 403 | Anahtara bağlı firma pasif durumda ya da anahtarın kapsamı bu ucu içermiyor (scope_required). |
| 404 | Kayıt bulunamadı (veya başka bir firmaya ait). |
| 429 | Hı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.