API Referansı

İndirip Muhasebe API v1 — LucaNet Ticari REST servislerini saran güvenli entegrasyon katmanı. Tüm alanlar, enum değerleri ve koşullu zorunluluklar aşağıda eksiksiz olarak dokümante edilmiştir.

Genel Bakış

Tüm istekler https://muhasebe.indirip.com/api/v1 altında çalışır. HTTPS zorunludur. Gövdeler (request body) JSON formatındadır.

Boolean Konvansiyonu (E/H)

LucaNet tüm boolean/bayrak alanlarda Türkçe kısaltma kullanır:

Örnekler: alici: "E", satici: "H", aktif: "E", kdvHesapla: "E", bosOlarakGuncelle: "H", internettenSatis: "E".

Döviz Kodları

Boş kur gönderildiğinde LucaNet belge tarihine ait TCMB döviz kurunu otomatik çeker.

Kart Tipleri (kartTipId)

KDV Oranları

Standart Response Yapısı

Aşağı hemen her endpoint'in yanıtı bu iskeleti paylaşır. Endpoint bölümlerinde sadece endpoint'e özgü json.* alanları listelenir; aşağıdaki session ve message alanları her yanıtta ortaktır:

{
  "ok": true,
  "data": {
    "session": {
      "jsession_id": "<string>",
      "kullanici": {
        "kullaniciAdi": "<string>",
        "musteriId":    <long>,
        "firmaId":      <long>,
        "firmaAdi":     "<string>",
        "donemKod":     <long>,
        "donemBas":     "GG/AA/YYYY",
        "donemBit":     "GG/AA/YYYY",
        "eposta":       "<string>"
      }
    },
    "message": "<string>",
    "json":    { /* endpoint'e özgü alanlar — aşağı bkz */ },
    "error":   false
  }
}

Kimlik Doğrulama

Her endpoint (sadece /health hariç) dört header bekler. Bu header'lar olmadan veya hatalı gönderilirse 401 UNAUTHORIZED döner.

İmza hesaplama

string_to_sign = METHOD + "\n" + REQUEST_URI + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + sha256(BODY_RAW)
signature      = hmac_sha256(string_to_sign, SECRET)  // hex encoded, küçük harf

Notlar:

• REQUEST_URI → tam path + query string (/api/v1/cari/ekle veya /api/v1/cari/liste?page=2)
• BODY_RAW → ham JSON string. Gövde yoksa boş string'in sha256'sı alınır.
• SECRET → istemci başına üretilir, sadece istemci tarafında (Laravel .env) saklanır.
• İmza eşleşmezse 401 döner — yapılan isteğin içeriği kesinlikle karşı tarafa iletilmez.

Yanıt Formatı & Hata Kodları

Başarılı (200):

{ "ok": true, "data": { /* LucaNet'in ham yanıtı */ } }

Hata:

{ "ok": false, "error": "ERROR_CODE", "message": "İnsan okuyabilir açıklama" }

Laravel'den Çağrı Örneği

HMAC imzalı istek için paylaşılabilir bir istemci sınıfı:

// config/services.php
'muhasebe_api' => [
    'base'   => 'https://muhasebe.indirip.com/api/v1',
    'key'    => 'laravel-panel',
    'secret' => env('MUHASEBE_API_SECRET'),
],

// app/Services/MuhasebeApiClient.php
use Illuminate\Support\Facades\Http;

class MuhasebeApiClient
{
    public function post(string $path, array $body = []): array
    {
        $cfg  = config('services.muhasebe_api');
        $json = json_encode($body, JSON_UNESCAPED_UNICODE);

        $ts    = (string) time();
        $nonce = bin2hex(random_bytes(8));
        $uri   = '/api/v1' . $path;

        $str = implode("\n", ['POST', $uri, $ts, $nonce, hash('sha256', $json)]);
        $sig = hash_hmac('sha256', $str, $cfg['secret']);

        return Http::withHeaders([
            'X-Api-Key'    => $cfg['key'],
            'X-Timestamp'  => $ts,
            'X-Nonce'      => $nonce,
            'X-Signature'  => $sig,
            'Content-Type' => 'application/json;charset=UTF-8',
        ])->withBody($json, 'application/json')->post($cfg['base'] . $path)->json();
    }
}

Kullanım:

$client = new MuhasebeApiClient();
$res = $client->post('/fatura/kes', [
    'faturaTipi'     => 102,
    'cariKart'       => 'CR000042',
    'seriNo'         => 'A2026000001',
    'tarih'          => '18/04/2026',
    'efaturaSenaryo' => 1,
    'detaylar' => [[
        'stokKart'   => 'STK001',
        'miktar'     => 2,
        'birimFiyat' => 100,
        'tutar'      => 200,
        'kdvOran'    => 20,
        'birim'      => 'ADET',
    ]],
]);

Cari (Müşteri / Tedarikçi)

Cari kart yönetimi. 5 endpoint. Zorunlu: kart.kartKodu. alici ve satici'dan en az biri "E" olmalıdır.

Cari Ekle

LucaNet ham endpoint: POST /service/rest/cari/add

Minimal Örnek

{
  "alici": "E",
  "satici": "H",
  "vergiNo": "1234567890",
  "vergiDairesiKodu": "034276",
  "unvani": "Örnek Teknoloji Ltd Şti",
  "earsivGonderimSekli": "ELEKTRONIK",
  "kart": {
    "kartKodu": "CR000042",
    "kartAdi": "Örnek Teknoloji",
    "dovizKod": "TL",
    "aktif": "E"
  },
  "adres": {
    "tanim": "Fatura Adresi",
    "il": "İstanbul",
    "ilce": "Ümraniye",
    "adresMetin": "Atatürk Mah. Barbaros Cad. No:5",
    "postaKodu": "34776",
    "eposta": "muhasebe@ornek.com"
  }
}

Request Alanları — Üst Seviye

Request Alanları — kart Alt Objesi (Zorunlu)

Request Alanları — adres Alt Objesi (Opsiyonel)

Response — json.* Alanları

Gönderilen alanların tümü geri döner. Ek olarak:

Cari Güncelle

LucaNet ham endpoint: POST /service/rest/cari/edit

Minimal Örnek — Sadece E-posta Güncelle

{
  "kart": { "kartKodu": "CR000042" },
  "adres": { "eposta": "yeni@ornek.com" }
}

Ek Alan (diğer tüm alanlar /ekle ile aynı)

Cari Sorgu

LucaNet ham endpoint: POST /service/rest/cari/select

Request Alanları

Response — Ek Alan (bakiyeli: "E" ise)

Cari Liste

LucaNet ham endpoint: POST /service/rest/cari/list

Request Alanları

Response — Koleksiyon

E-Fatura Mükellef Sorgusu

LucaNet ham endpoint: POST /service/rest/cari/search

Karşı tarafın GİB'de e-fatura mükellefi olup olmadığını kontrol eder. Mükellef listesi günlük güncellenir — gün içi değişiklikler yansımayabilir.

Request Alanları

Response — json.*

Stok

Stok kartı yönetimi. 3 endpoint. Üst seviye alanlar + zorunlu kart alt objesi yapısı kullanılır.

Stok Tipleri (stokTipi)

Stok Ekle

LucaNet ham endpoint: POST /service/rest/stok/add

Minimal Örnek

{
  "stokTipi": 0,
  "birim": "ADET",
  "satisTutar": 100.00,
  "satisKdvOran": 20,
  "alisKdvOran": 20,
  "kart": {
    "kartKodu": "STK001",
    "kartAdi": "Örnek Ürün",
    "dovizKod": "TL",
    "aktif": "E"
  }
}

Request Alanları — Üst Seviye (Stok Özellikleri)

Request Alanları — Muhasebe Hesap Kodları (Hepsi Opsiyonel)

Request Alanları — kart Alt Objesi (Zorunlu)

Response — json.* Ek Alanları

Stok Sorgu

LucaNet ham endpoint: POST /service/rest/stok/select

Request Alanları

Response — json.bakiye (bakiyeli: "E" ise)

Stok Liste

LucaNet ham endpoint: POST /service/rest/stok/list. Sayfa başına 500 kayıt.

Request Alanları

Response — Koleksiyon

collection.list[] her eleman: kart bilgileri + satisTutar, alisTutar, satisKdvOran, stokTipi, birim vb. özellikler.

Fatura

Fatura oluşturma, sorgulama ve PDF linki alma. E-fatura / e-arşiv entegratörüne otomatik gönderim tetiklenir. Sistemin en büyük ve en kritik modülüdür.

Fatura Tipleri (faturaTipi)

E-Fatura Senaryoları (efaturaSenaryo)

Boş bırakılırsa: 1) cari kartında tanımlı "EFatura Senaryo" değeri kullanılır, 2) yoksa firma işlemlerinde tanımlı varsayılan alınır.

Ödeme Türleri (paymentType — internet satış)

Fatura Kes

LucaNet ham endpoint: POST /service/rest/faturaWs/add

Minimal Örnek — Satış Faturası (Ticari E-Fatura)

{
  "faturaTipi": 102,
  "efaturaSenaryo": 1,
  "fatura": {
    "cariKart": "CR000042",
    "cariKartAdi": "Örnek Teknoloji Ltd"
  },
  "hareket": {
    "seriNo": "A2026000001",
    "tarih": "18/04/2026",
    "dovizKod": "TL",
    "aciklama": "Yazılım hizmeti"
  },
  "detaylar": [{
    "stokKart": "STK-HIZMET-01",
    "miktar": 1,
    "birim": "ADET",
    "birimFiyat": 10000,
    "tutar": 10000,
    "kdvOran": 20
  }]
}

Request Alanları — Üst Seviye (Kontrol Bayrakları)

Request Alanları — fatura Alt Objesi

Request Alanları — E-Fatura / E-Arşiv Carisi Override

Request Alanları — İnternet Satış Faturası (internettenSatis: "E" ise)

Request Alanları — Yolcu Beraber (efaturaSenaryo = 3)

Request Alanları — Enerji Senaryosu (efaturaSenaryo = 6)

Request Alanları — Alış İade (Elektronik)

Request Alanları — hareket (Belge Üst Bilgileri)

Request Alanları — krediKartlar[]

Request Alanları — detaylar[] (Fatura Kalemi)

Request Alanları — detaylar[] Vergi Alanları

Request Alanları — detaylar[].dagilimList[] (Maliyet Merkezi)

Response — json.* Önemli Alanlar

Fatura Sorgu

LucaNet ham endpoint: POST /service/rest/faturaWs/select

Minimal Örnek

{ "fatura": { "faturaId": 12345 } }

Request Alanları

Response — Ek Alan

data.invoiceStatus alanı elektronik faturalar için entegratörden alınan durum bilgisini içerir:

Fatura PDF Linki

LucaNet ham endpoint: POST /service/rest/efaturaEarsivGonderim/select

E-fatura/e-arşiv entegratöründen alınan PDF indirme linkini döner (json.externalPdfUrl).

Minimal Örnek

{ "fatura": { "faturaId": 12345 } }

Response — Ek Alan

İrsaliye

Sevk belgesi (e-irsaliye / matbu). Oluşturma ve silme. Fatura ile benzer yapı, ek olarak sevk ve taşıyıcı bilgileri.

İrsaliye Tipleri (faturaTipi)

İrsaliye Kes

LucaNet ham endpoint: POST /service/rest/irsaliyeWs/add

Minimal Örnek — Satış İrsaliyesi

{
  "faturaTipi": 106,
  "fatura": {
    "cariKart": "CR000042",
    "sevkTarih": "18/04/2026",
    "sevkSaat": "14:30",
    "plaka": "34 ABC 123"
  },
  "hareket": {
    "seriNo": "IR2026000001",
    "tarih": "18/04/2026"
  },
  "detaylar": [{
    "stokKart": "STK001",
    "miktar": 5,
    "birim": "ADET",
    "birimFiyat": 100,
    "tutar": 500,
    "kdvOran": 20
  }]
}

Request Alanları — Üst Seviye

Request Alanları — fatura Alt Objesi

Request Alanları — hareket

Request Alanları — detaylar[]

Request Alanları — detaylar[].dagilimList[] (Maliyet Merkezi Dağılımı)

Request Alanları — soforList[] ve dorseList[]

İrsaliye Sil

LucaNet ham endpoint: POST /service/rest/irsaliyeWs/delete

Minimal Örnek

{ "fatura": { "faturaId": 12345 } }

Request Alanları

Tahsilat

Virman tahsilat (banka havale/EFT, nakit, kredi kartı). 1 endpoint. Tek çağrıda birden fazla detay satırı gönderilebilir.

Detay Tipleri

Tahsilat Ekle

LucaNet ham endpoint: POST /service/rest/tahsilat/add

Minimal Örnek — Banka Havale Tahsilatı

{
  "cariKartKodu": "CR000042",
  "hareket": {
    "seriNo": "TH2026000001",
    "tarih": "18/04/2026",
    "dovizKod": "TL",
    "aciklama": "Nisan 2026 tahsilatı"
  },
  "detaylar": [
    { "tip": 2, "tutar": 1000.00, "kart": "102.01.001" }
  ]
}

Minimal Örnek — Kredi Kartı Tahsilatı (3 Taksit)

{
  "cariKartKodu": "CR000042",
  "hareket": { "seriNo": "TH2026000002", "tarih": "18/04/2026" },
  "detaylar": [{
    "tip": 7,
    "kart": "108.01.001",
    "krediKartiForm": {
      "sozlesmeKod": "POS-YAPIKREDI-01",
      "kkTutar": 1500.00,
      "taksitSayisi": 3
    }
  }]
}

Request Alanları — Üst Seviye

Request Alanları — hareket Alt Objesi

Request Alanları — detaylar[] (En az 1 Satır Zorunlu)

Request Alanları — detaylar[].krediKartiForm (tip=7 için)

Response — json.*

Gönderilen alanlar + sistem atanan hareket.siraNo (boş göndermişsen) döner. detaylar[] her satır için aynı yapı tekrarlanır.

Ödeme

Virman ödeme (banka havale/EFT, nakit). 1 endpoint. Tahsilat'tan farkı: kredi kartı (tip 7) desteklenmez — yalnızca banka (2) ve kasa (5).

Ödeme Ekle

LucaNet ham endpoint: POST /service/rest/odeme/add

Minimal Örnek

{
  "cariKartKodu": "CR000042",
  "hareket": {
    "seriNo": "OD2026000001",
    "tarih": "18/04/2026",
    "dovizKod": "TL",
    "aciklama": "Tedarikçi ödemesi"
  },
  "detaylar": [
    { "tip": 2, "tutar": 500.00, "kart": "102.01.001" }
  ]
}

Request Alanları

Muhasebe Fişi

Muhasebe fişi aktarımı — yevmiye kayıtları, devir/açılış/kapanış, tahakkuk ve kur değerleme.

Fiş Tipleri (tip)

Satır Kart Tipleri (detaylar[].kartTipId)

Stok İşlem Tipleri (detaylar[].islemTipi, kartTipId=4 için)

Muhasebe Fişi Ekle

LucaNet ham endpoint: POST /service/rest/muhasebeFisWs/add

Minimal Örnek — Basit Yevmiye Fişi (Dengeli)

{
  "tip": "M",
  "hareket": {
    "seriNo": "MF2026000001",
    "tarih": "18/04/2026",
    "aciklama": "Nisan kira gideri"
  },
  "detaylar": [
    { "borcAlacak": "B", "tutar": 5000, "tlTutar": 5000, "kartTipId": 1, "kart": "770.01.001" },
    { "borcAlacak": "A", "tutar": 5000, "tlTutar": 5000, "kartTipId": 5, "kart": "100.01.001" }
  ]
}

Request Alanları — Üst Seviye

Request Alanları — hareket

Request Alanları — detaylar[] (En az 2 Satır, Borç=Alacak)

Response — json.*

Muhasebe Hesap Kartı

Hesap planına yeni kart ekleme. Cari ve stok kartları için LucaNet otomatik muhasebe kartı eşleştirmesi yapar; bu endpoint özel bir hesap kodu tanımlaman gerektiğinde kullanılır.

Muhasebe Kartı Ekle

LucaNet ham endpoint: POST /service/rest/muhasebe/add

Minimal Örnek

{
  "kart": {
    "kartKodu": "120.01.042",
    "kartAdi": "Örnek Teknoloji Ltd - Alacak",
    "dovizKod": "TL",
    "aktif": "E"
  }
}

Request Alanları — kart Objesi

Response — json.kart.*

Gider Pusulası

Fatura düzenleyemeyen kişilere yapılan gider veya satış iade kaydı.

Gider Türleri (giderTuru)

Tevkifat Kodları (tevkifatKod)

Tam liste için EFatura_Ozel_Kodlar.xlsx'e bak — tevkifat türlerinin açıklamaları (yük taşımacılığı, özel güvenlik, temizlik vb.) dahil.

Gelir Vergisi Oranları (gelirVergisiOran)

Gider Pusulası Ekle

LucaNet ham endpoint: POST /service/rest/giderPusulasi/add

Minimal Örnek

{
  "cariKart": "CR000042",
  "kasaKart": "100.01.001",
  "giderTuru": "1",
  "hareket": {
    "seriNo": "GP2026000001",
    "tarih": "18/04/2026",
    "aciklama": "Nakliye gideri"
  },
  "detaylar": [{
    "stokKart": "STK-NAKLIYE",
    "miktar": 1,
    "birimFiyat": 500,
    "tutar": 500,
    "kdvOran": 0,
    "gelirVergisiOran": 20
  }]
}

Request Alanları — Üst Seviye

Request Alanları — hareket

Request Alanları — detaylar[]

Response — Ek Alanlar