Fatura Kalemleri ve Ödemeler

1.8k görüntülenme Markdown

Fatura kalemlerini düzenleyen, bölen ve ödeme kayıtlarını tutan dört uç.

Genel Bakış

Bu dört uç faturanın para tarafını yürütür. İkisi kalemlerle ilgilenir: düzenlemek ve bir kısmını ayrı bir faturaya taşımak. İkisi de ödeme kayıtlarıyla.

Kalem yazma ucu toplu çalışır: aynı çağrıda kalem eklenir, güncellenir ve silinir. Bittiğinde toplamlar baştan hesaplanır, yani ara toplam, vergi ve genel toplam elle yazılmaz.

Ödeme kaydı faturanın durumuna tek yönlü etki eder: bakiye kapanınca fatura ödenmiş olur, ama bir ödemeyi silmek durumu geri çevirmez.

Referans

Kalemleri Yazma

put/api/v1/admin/invoices/{id}/items

Invoices/UpdateInvoiceItems admin toplamlar yeniden hesaplanır

Faturanın kalemlerini tek çağrıda ekler, günceller ve siler.

Gövde 3

itemsarrayİşlenecek kalemler. Numarası olan güncellenir, olmayan yeni kalem olarak eklenir.

deleted_idsint[]Silinecek kalem numaraları.

removed_discountsarrayKaldırılacak indirimler. Her girdi indirimin tipini ve bağlı olduğu kalemi taşır.

Kalem alanları items[] — 10

item_idintMevcut kalemin numarası. Verilmezse yeni kalem açılır.

descriptionstringreqKalemin açıklaması.

quantityintreqAdet.

amountfloatreqBirim tutar.

discountfloatKaleme özgü indirim değeri.

discount_typestringİndirimin tutar mı yüzde mi olduğu.

tax_ratefloatKaleme özgü vergi oranı. Boş bırakılırsa faturanın oranı kullanılır.

tax_exemptboolKalemi vergiden muaf tutar.

user_pidintBağlanacak hizmet.

oduedatestringKalemin dönem sonu.

Dönen alanlar data

dataobjectGüncel fatura. Toplamlar yeniden hesaplanmış hâlde gelir.

Hatalar 3

not_found404Fatura bulunamadı.

item_required422İşlem sonunda hiç kalem kalmıyor.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek

curl -X PUT 'https://panel.ornek.com/api/v1/admin/invoices/1212/items' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"item_id":2811,"description":"Hosting","quantity":1,"amount":12.5}],"deleted_ids":[2812]}'

const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}/items`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      { item_id: 2811, description: 'Hosting Plan', quantity: 1, amount: 12.5 },
      { description: 'Setup Fee', quantity: 1, amount: 5 },
    ],
    deleted_ids: [2812],
  }),
});

const body = await res.json();

$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id . '/items');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'items' => [
            ['item_id' => 2811, 'description' => 'Hosting Plan', 'quantity' => 1, 'amount' => 12.5],
            ['description' => 'Setup Fee', 'quantity' => 1, 'amount' => 5],
        ],
        'deleted_ids' => [2812],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

// Gondermediginiz mevcut kalem SILINMEZ; silmek icin numarasini silinecekler listesine koyun.
Api::Invoices()->UpdateInvoiceItems([
    'id'          => $id,
    'items'       => [['item_id' => 2811, 'description' => 'Hosting', 'quantity' => 1, 'amount' => 12.5]],
    'deleted_ids' => [2812],
]);

Kalemleri Bölme

post/api/v1/admin/invoices/{id}/items/split

Invoices/SplitInvoiceItems admin yeni fatura açar

Seçtiğiniz kalemleri yeni bir faturaya taşır.

Gövde 1

item_idsint[]reqTaşınacak kalemler. Hepsi kaynak faturaya ait olmalı ve kaynakta en az bir kalem kalmalı.

Dönen alanlar data — 4

source_invoice_idintKaynak faturanın numarası.

new_invoice_idintAçılan faturanın numarası.

new_invoice_numberstring | nullYeni faturanın numarası. Henüz numara verilmediyse boştur.

moved_item_idsint[]Taşınan kalemler.

Hatalar 6

not_found404Fatura bulunamadı.

split_required422Hiç kalem seçilmedi.

no_items422Kalemler bu faturaya ait değil.

split_one_left422Kaynakta hiç kalem kalmıyor.

split_failed422Yeni fatura açılamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek

curl -X POST 'https://panel.ornek.com/api/v1/admin/invoices/1228/items/split' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"item_ids":[2835]}'

const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}/items/split`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ item_ids: [2835] }),
});

const { data } = await res.json();
console.log(data.new_invoice_id);

$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id . '/items/split');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['item_ids' => [2835]]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

// Yeni fatura ODENMEMIS acilir ve musteriye kendiliginden BILDIRILMEZ.
$r = Api::Invoices()->SplitInvoiceItems(['id' => $id, 'item_ids' => $picked])['data'];
Api::Invoices()->SendInvoiceNotification([
    'id' => $r['new_invoice_id'], 'template' => 'invoice-created',
]);

Ödeme Kaydetme

post/api/v1/admin/invoices/{id}/payments

Invoices/AddInvoicePayment admin bakiye biterse ödenir

Faturaya elle bir ödeme kaydı ekler.

Gövde 7

amountfloatreqÖdenen tutar. Sıfırdan büyük olmalı.

payment_methodstringreqÖdemenin nasıl alındığı.

currency_idintÖdemenin para birimi. Faturanınkinden farklıysa çevrilir.

transaction_idstringİşlem numarası. Aynı numarayla ikinci bir kayıt kabul edilmez.

descriptionstringÖdemenin açıklaması.

paid_atstringÖdemenin yapıldığı tarih.

feesfloatKesilen komisyon.

Dönen alanlar data + meta — 1

dataobjectGüncel fatura. Bakiye sıfırlandıysa durum ödenmiş olur.

payment_idintAçılan ödeme kaydının numarası. Meta altında döner.

Hatalar 5

not_found404Fatura bulunamadı.

invalid_amount422Tutar sıfır ya da altında.

method_required422Ödeme yöntemi verilmedi.

payment_rejected422Fatura zaten ödenmiş, işlem numarası tekrarlanmış ya da para birimi geçersiz.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek

curl -X POST 'https://panel.ornek.com/api/v1/admin/invoices/1212/payments' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"amount":12.5,"payment_method":"Balance","transaction_id":"TXN-1042"}'

const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}/payments`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 12.5,
    payment_method: 'Balance',
    currency_id: 840,
    transaction_id: 'TXN-1042',
  }),
});

const body = await res.json();

$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id . '/payments');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount'         => 12.5,
        'payment_method' => 'Balance',
        'transaction_id' => 'TXN-1042',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

// Islem numarasi MUKERRERI onler; ag hatasinda cagriyi tekrarlamak ikinci kayit acmaz.
Api::Invoices()->AddInvoicePayment([
    'id'             => $id,
    'amount'         => 12.5,
    'payment_method' => 'Balance',
    'transaction_id' => $txn,
]);

Ödemeyi Silme

delete/api/v1/admin/invoices/{id}/payments/{payment_id}

Invoices/DeleteInvoicePayment admin durum geri dönmez

Bir ödeme kaydını faturadan kaldırır.

Dönen alanlar data

dataobjectGüncel fatura. Ödenmiş tutar ve bakiye yeniden hesaplanır.

Hatalar 3

not_found404Ödeme bu faturada bulunamadı.

invalid_payment422Ödeme numarası geçersiz.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek

curl -X DELETE 'https://panel.ornek.com/api/v1/admin/invoices/1212/payments/31' \
  -H "Authorization: Bearer $API_KEY"

const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}/payments/${paymentId}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();

$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id . '/payments/' . $paymentId);
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);

// Fatura ODENMIS kalir: bakiye geri acilsa da durumu ayrica siz cevirmelisiniz.
Api::Invoices()->DeleteInvoicePayment(['id' => $id, 'payment_id' => $pid]);
Api::Invoices()->UpdateInvoiceStatus(['id' => $id, 'status' => 'unpaid']);

Tuzaklar

Kalemi atlamak onu silmez

Kalem yazma çağrısında göndermediğiniz mevcut bir kalem yerinde kalır. Silmek için numarasını silinecekler listesine koymanız gerekir. Faturanın kalem setini olduğu gibi gönderen bir betik, kaldırılan kalemleri kaldırmaz; iki listeyi karşılaştırıp farkı silinecekler listesine yazın.

Fatura kalemsiz kalamaz

Hem kalem yazma hem bölme çağrısı, sonunda faturada en az bir kalem kalmasını ister. Bütün kalemleri silmeye ya da hepsini bölmeye çalışmak hata verir. Faturayı tümüyle kaldırmak istiyorsanız kalemlerini değil faturanın kendisini silin ya da iptal edin.

Toplamları elle yazmayın

Kalem yazma çağrısı bittiğinde ara toplam, vergi ve genel toplam yeniden hesaplanır. Aynı anda fatura düzenleme ucundan toplam yazmaya çalışmak, iki kaynağın çekiştiği bir kayda yol açar. Toplamlar kalemlerden çıkar; onları değiştirmenin yolu kalemleri değiştirmektir.

Ödeme silmek durumu geri çevirmez

Bakiye kapanınca fatura kendiliğinden ödenmiş olur, ama ödemeyi silmek aynı yolu geri yürümez: ödenmiş tutar ve bakiye yeniden hesaplanır, durum ödenmiş kalır. Yanlış girilmiş bir ödemeyi geri alırken durumu ayrıca ödenmemişe çevirmeniz gerekir.

Bölme yeni bir borç doğurur

Bölme çağrısı ödenmemiş yeni bir fatura açar ve müşteriye bundan kendiliğinden haber vermez. Yani müşterinin haberi olmadan bir borcu daha olur. Bölmeden sonra yeni faturanın numarasını alıp bildirim gönderin; kaynak faturanın toplamı da düşeceği için iki belge de değişmiştir.

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

Genel Bakış

Referans

Kalemleri Yazma

Kalemleri Bölme

Ödeme Kaydetme

Ödemeyi Silme

Tuzaklar

İlgili Makaleler