Fatura Yönetimi

9 görüntülenme Markdown

Fatura kesen, okuyan, düzenleyen ve gelir özetini veren altı uç.

Genel Bakış

Bu altı uç faturanın kendisiyle ilgilenir: listelemek, kesmek, okumak, başlık alanlarını düzenlemek ve silmek. Yanına bir de dönem toplamı veren gelir özeti girer.

Fatura anlık bir görüntü taşır: müşterinin adı, adresi ve vergi bilgileri kesim anındaki hâliyle kaydın içinde durur. Müşteri sonradan adresini değiştirse bile fatura değişmez, çünkü kesilmiş bir belge geçmişi anlatır.

Para tarafı üç katmanlıdır: kalemler ara toplamı, vergi onun üstüne geleni, komisyon ve vade farkı ise ödeme yönteminin getirdiğini anlatır. Üçü birlikte genel toplamı verir.

Referans

Faturaları Listeleme

get/api/v1/admin/invoices
Invoices/GetInvoices admin

Faturaları süzerek ve sayfalayarak döndürür.

Sorgu 15
pageintKaçıncı sayfa.
limitintSayfa başına kayıt. Aralık dışı bir değer öntanımlıya döner.
searchstringFatura numarası ve müşteri bilgilerinde arar.
statusstringDuruma göre süzer: waiting, unpaid, paid, cancelled, refund. Ayrıca vadesi geçmiş, yaklaşan, resmî ve resmî olmayan gibi türetilmiş süzgeçler alır.
client_idintMüşteriye göre süzer.
currency_idintPara birimine göre süzer.
taxedboolResmileştirilmiş olanları ayırır.
amountstringTutara göre süzer.
amount_opstringTutar karşılaştırmasının yönü.
item_descriptionstringKalem açıklamalarında arar.
cdatestringKesim tarihine göre süzer.
cdate_opstringKesim tarihi karşılaştırmasının yönü.
duedatestringVade tarihine göre süzer.
duedate_opstringVade karşılaştırmasının yönü.
daterangestringİki tarih arasını süzer. Yönü kendi karşılaştırma alanıyla verilir.
Dönen alanlar data[] — 14 + meta — 4
idintFaturanın numarası.
numberstring | nullFatura numarası. Henüz numara verilmediyse boştur.
statusstringFaturanın durumu: waiting, unpaid, paid, cancelled, refund.
currency_idintFaturanın para birimi.
subtotalfloatAra toplam.
taxfloatVergi tutarı.
totalfloatGenel toplam.
formalizedboolResmî faturaya çevrilmiş mi.
payment_methodstring | nullÖdeme yöntemi.
created_atstring | nullKesildiği an.
due_datestring | nullVadesi.
paid_atstring | nullÖdendiği an.
refund_datestring | nullİade edildiği an.
clientobjectMüşteri: numarası, adı, firması ve e-postası. Fatura anındaki hâlidir.
total intSüzgece uyan toplam kayıt. Meta altında döner.
pageintBulunulan sayfa.
limitintSayfa boyutu.
next_pageintSonraki sayfa. Sıfır, son sayfadasınız demektir.
Hatalar 1
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/invoices?status=unpaid&limit=25' \
  -H "Authorization: Bearer $API_KEY"
const url = new URL('https://panel.ornek.com/api/v1/admin/invoices');
url.searchParams.set('status', 'unpaid');

const res  = await fetch(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices?' . http_build_query(['status' => 'unpaid', 'limit' => 25]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Taslak ve sistem faturalari listeye HIC girmez; sayim tabloyla birebir tutmaz.
$rows = Api::Invoices()->GetInvoices([], ['status' => 'unpaid'])['data'];

Fatura Kesme

post/api/v1/admin/invoices
Invoices/CreateInvoice admin bildirim isteğe bağlı

Bir müşteriye elle fatura keser ve kalemlerini yazar.

Gövde 8
client_idintreqFaturanın kesileceği müşteri.
itemsarrayreqFatura kalemleri. En az bir kalem gerekir.
currency_idintFaturanın para birimi. Verilmezse müşterinin para birimi kullanılır.
statusstringFaturanın açılış durumu. Öntanımlı olarak ödenmemiş.
payment_methodstringÖdeme yöntemi.
created_atstringKesim tarihi. Verilmezse şu an alınır.
due_datestringVade tarihi. Verilmezse bugünün sonu alınır.
send_notificationboolMüşteriye duruma uygun bildirimi gönderir.
Kalem alanları items[] — 8
descriptionstringreqKalemin açıklaması.
quantityintreqAdet. En az bir olmalı.
amountfloatreqBirim tutar.
discountfloatİndirim değeri.
discount_typestringİndirimin tutar mı yüzde mi olduğu.
tax_ratefloatKaleme özgü vergi oranı.
tax_exemptboolKalemi vergiden muaf tutar.
user_pidintBağlanacak hizmet. Sıfır, kalemin bağımsız olduğunu söyler.
Dönen alanlar 201 — data
dataobjectKesilen fatura. Detay ucuyla aynı şekildedir.
Hatalar 6
invalid_client422Müşteri verilmedi.
not_found404Müşteri bulunamadı.
currency_required422Para birimi çözülemedi.
items_required422Hiç kalem verilmedi.
create_failed422Fatura kesilemedi.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X POST 'https://panel.ornek.com/api/v1/admin/invoices' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"client_id":87,"currency_id":840,"items":[{"description":"Hosting","quantity":1,"amount":12.5}]}'
const res = await fetch('https://panel.ornek.com/api/v1/admin/invoices', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    client_id: 87,
    currency_id: 840,
    due_date: '2026-07-01',
    items: [
      { description: 'Hosting Plan', quantity: 1, amount: 12.5 },
    ],
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'client_id'   => 87,
        'currency_id' => 840,
        'items'       => [
            ['description' => 'Hosting Plan', 'quantity' => 1, 'amount' => 12.5],
        ],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Bildirim ISTEGE BAGLIDIR: gondermezseniz musteri faturadan haberdar olmaz.
Api::Invoices()->CreateInvoice([
    'client_id'         => $uid,
    'items'             => $lines,
    'send_notification' => true,
]);

Gelir Özetini Okuma

get/api/v1/admin/invoices/stats
Invoices/GetInvoiceStats admin

Seçtiğiniz tip ve dönem için toplam tutarı döndürür.

Sorgu 2
typestringNeyin toplanacağı: ödenmemiş, ödenmiş, vadesi geçmiş ya da vergi. Öntanımlı olarak ödenmemişler.
periodstringHangi dönem: son yedi gün, son on beş gün, bu ay, geçen ay, bu yıl ya da geçen yıl. Öntanımlı olarak bu ay.
Dönen alanlar data — 5
typestringUygulanan tip.
periodstringUygulanan dönem.
amountfloatToplam tutar. Ham sayıdır ve farklı para birimleri yerel para birimine çevrilerek toplanır.
countintToplama giren fatura sayısı.
currency_idintToplamın para birimi.
Hatalar 1
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/invoices/stats?type=unpaid&period=this-month' \
  -H "Authorization: Bearer $API_KEY"
const url = new URL('https://panel.ornek.com/api/v1/admin/invoices/stats');
url.searchParams.set('type', 'unpaid');
url.searchParams.set('period', 'this-month');

const res  = await fetch(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/stats?' . http_build_query(['type' => 'unpaid', 'period' => 'this-month']));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Tutar CEVRILMIS bir toplamdir: gunun kuruna gore hesaplanir, biciminizi siz verirsiniz.
$s = Api::Invoices()->GetInvoiceStats([], ['type' => 'unpaid'])['data'];
$sum = Money::formatter_symbol($s['amount'], $s['currency_id']);

Fatura Detayı

get/api/v1/admin/invoices/{id}
Invoices/GetInvoice admin

Faturayı kalemleri, ödemeleri ve müşteri anlık görüntüsüyle döndürür.

Dönen alanlar data — 33
idintFaturanın numarası.
numberstring | nullFatura numarası.
statusstringFaturanın durumu: waiting, unpaid, paid, cancelled, refund.
currency_idintFaturanın para birimi.
created_atstring | nullKesildiği an.
due_datestring | nullVadesi.
paid_atstring | nullÖdendiği an.
refund_datestring | nullİade edildiği an.
subtotalfloatAra toplam.
taxfloatVergi tutarı. Komisyon ve vade farkı vergileri buraya girmez.
additional_taxfloatEk vergi.
totalfloatGenel toplam.
total_paidfloatÖdeme kayıtlarından çıkan ödenmiş tutar.
balancefloatKalan bakiye.
tax_ratefloatVergi oranı.
taxation_typestringVerginin tutara dahil olup olmadığı.
formalizedboolResmî faturaya çevrilmiş mi.
taxfreeboolVergiden muaf mı.
localboolYerel fatura mı.
recurringboolYinelenen bir fatura mı.
recurring_timeintYineleme aralığı.
recurring_periodstringYineleme dönemi.
payment_methodstring | nullÖdeme yöntemi.
payment_method_statusstring | nullÖdeme yönteminin durumu.
payment_method_dataobjectÖdeme yönteminin ek verisi.
payment_method_commissionfloatÖdeme komisyonu.
payment_method_commission_ratefloatKomisyon oranı.
payment_method_commission_taxfloatKomisyonun vergisi. Genel toplama girer ama vergi alanına girmez.
installment_surchargefloatTaksit vade farkı.
installment_surcharge_taxfloatVade farkının vergisi. Bu da genel toplama girer, vergi alanına girmez.
installment_countintTaksit sayısı.
send_bill_to_addressfloatAdrese fatura gönderim tutarı.
notesstringFaturaya düşülen not.
unreadboolMüşterinin faturayı okumamış olması.
exchange_ratefloatKesim anındaki kur.
discountsobjectİndirim kalemleri ve toplamı.
user_dataobjectMüşterinin ve adresinin fatura anındaki hâli.
clientobjectMüşteri: numarası, adı, firması ve e-postası.
itemsarrayFatura kalemleri.
paymentsarrayÖdeme kayıtları.
Kalem alanları items[] — 17
idintKalemin numarası.
parent_idintÜst kalem. Alt kalemler bir üst kaleme bağlanır.
owner_idintBağlı olduğu fatura.
client_idintMüşteri.
service_idintBağlı hizmet. Sıfır, kalemin bağımsız olduğunu söyler.
descriptionstringKalemin açıklaması.
quantityintAdet.
tax_exemptboolVergiden muaf mı.
tax_ratefloatKalemin vergi oranı. Eksi bir, oranın faturadan alındığını söyler.
additional_taxesarrayKaleme işlenen ek vergiler.
additional_tax_totalfloatEk vergilerin toplamı.
amountfloatBirim tutar.
total_amountfloatKalemin toplamı. Adet ile tutarın çarpımından indirim düşülür.
currency_idintKalemin para birimi.
due_datestring | nullKalemin dönem sonu.
rankintFaturadaki sırası.
optionsarrayKaleme ait ek bilgiler.
Ödeme alanları payments[] — 14
idintÖdemenin numarası.
amount_infloatGelen tutar.
amount_outfloatÇıkan tutar.
feesfloatKesilen komisyon.
currency_idintÖdemenin para birimi.
ratefloatÖdeme anındaki kur.
payment_methodstring | nullÖdeme yöntemi.
transaction_idstring | nullİşlem numarası.
descriptionstringÖdemenin açıklaması.
paid_atstring | nullÖdemenin yapıldığı an.
created_atstring | nullKaydın açıldığı an.
created_byintKaydı açan personel.
recorded_bystring | nullKaydı açanın adı.
ipstring | nullKaydın geldiği adres.
Hatalar 2
not_found404Fatura bulunamadı.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/invoices/1212' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Toplami YENIDEN URETIRKEN iki vergiyi ayrica ekleyin; 'tax' alani onlari icermez.
$inv = Api::Invoices()->GetInvoice(['id' => $id])['data'];
$sum = $inv['subtotal'] + $inv['tax']
     + $inv['payment_method_commission'] + $inv['payment_method_commission_tax']
     + $inv['installment_surcharge']     + $inv['installment_surcharge_tax'];

Faturayı Düzenleme

patch/api/v1/admin/invoices/{id}
Invoices/UpdateInvoice admin

Faturanın başlık alanlarını değiştirir ve gerekirse toplamları yeniden hesaplar.

Gövde 11
numberstringFatura numarası.
payment_methodstringÖdeme yöntemi.
taxation_typestringVerginin tutara dahil olup olmadığı. Değişirse toplamlar yeniden hesaplanır.
currency_idintFaturanın para birimi. Değişirse toplamlar yeniden hesaplanır.
tax_ratefloatVergi oranı.
formalizedboolFaturayı resmî faturaya çevirir. İlk çevrildiğinde müşteriye bildirim gider.
taxfreeboolFaturayı vergiden muaf yapar. Resmileştirmeye göre önceliklidir.
created_atstringKesim tarihi.
due_datestringVade tarihi.
paid_atstringÖdenme tarihi.
refund_datestringİade tarihi.
Dönen alanlar data
dataobjectGüncel fatura. Detay ucuyla aynı şekildedir.
Hatalar 2
not_found404Fatura bulunamadı.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X PATCH 'https://panel.ornek.com/api/v1/admin/invoices/1212' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"number":"INV-2026-0042","tax_rate":20}'
const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    number: 'INV-2026-0042',
    tax_rate: 20,
    due_date: '2026-07-15 23:59:00',
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'number'   => 'INV-2026-0042',
        'tax_rate' => 20,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Vergiden muaf yapmak RESMILESTIRMEYI EZER; ikisini birlikte gondermek anlamsizdir.
Api::Invoices()->UpdateInvoice(['id' => $id, 'formalized' => true]);

Faturayı Silme

delete/api/v1/admin/invoices/{id}
Invoices/DeleteInvoice admin kayıt zincirini çözer

Faturayı ve ona bağlı bütün kayıtları kaldırır.

Dönen alanlar data — 2
deletedboolSilme çalıştı mı.
idintSilinen faturanın numarası.
Hatalar 3
not_found404Fatura bulunamadı.
blocked_by_gate422Bir kanca silmeyi reddetti.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/invoices/1226' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Silmek yerine IPTAL edin: muhasebe izi durur, fatura da odenecekler arasindan cikar.
Api::Invoices()->SetInvoiceStatus(['id' => $id, 'status' => 'cancelled']);

Tuzaklar

Vergi alanı bütün vergileri içermez

Ödeme komisyonunun ve taksit vade farkının vergileri genel toplama girer ama vergi alanına girmez. Ara toplam ile vergiyi toplayıp genel toplama eşit çıkmasını beklerseniz aradaki farkı bulamazsınız. Toplamı yeniden üretmek için bu iki vergiyi kendi alanlarından ayrıca eklemeniz gerekir.

Taslak faturalar listede yoktur

Listeleme ucu taslak ve sistem faturalarını gizler. Bu, panelin gördüğüyle aynıdır, ama listeden çıkan sayı veritabanındaki satır sayısıyla tutmaz. Muhasebe raporu yazarken bu fark hesaba katılmalıdır; süzgeç eklemek gizlenenleri geri getirmez.

Resmî ve vergisiz aynı alanda yaşar

Faturanın vergi durumu tek bir alanda üç değerden birini alır: normal, resmî ya da vergisiz. Bu yüzden vergiden muaf yapmak resmileştirmeyi ezer; ikisini birlikte göndermenin bir anlamı yoktur. Resmileştirme ilk kez uygulandığında müşteriye bildirim de gider.

Silmek zinciri çözer

Fatura silmek yalnız kaydı kaldırmaz: kalemleri, gelir ve gider kayıtlarını, hizmetlerle kurulan bağları ve bekleyen metrik kayıtlarını da çözer. Bir kanca silmeyi engelleyebilir, çünkü bazı faturaların gitmesi muhasebeyi bozar. Vazgeçmek istiyorsanız silmek yerine iptal edin; iz kalır, borç kalmaz.

Boş tarihler boş döner

Ödeme ve iade tarihleri gibi henüz gerçekleşmemiş alanlar boş gelir. Veritabanında bunlar yer tutucu tarihlerle durur; yanıt onları temizler. Yani bir tarihi okumadan önce varlığını sınayın, yoksa yer tutucu bir tarihi gerçek sanan bir ekran ortaya çıkar.

Faydalı oldu mu?

Geri bildiriminiz için teşekkürler!

Hâlâ Yardıma mı İhtiyacınız Var?

Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.

Bize Ulaşın Destek Talebi Oluştur

Oturumunuzu açık tutmak, dil ve para birimi tercihinizi hatırlamak ve siteyi geliştirmek için çerez kullanıyoruz. Çerez Politikası