Fatura Durumu ve Bildirimleri

1.9k görüntülenme Markdown

Faturanın durumunu, müşteri bilgisini ve müşteriye giden bildirimleri yöneten beş uç.

Genel Bakış

Bu beş uç kesilmiş bir faturanın yaşamını yürütür: durumunu değiştirmek, müşteri bilgilerini düzeltmek, bildirim göndermek, resmileştirmek ve hatırlatmak.

Durum değişimi bu alandaki en ağır işlemdir. Ödenmiş yapmak gelir kaydı açar, ödenmiş fatura numarası verir ve bağlı hizmetleri harekete geçirir; iade etmek bunları geri sarar ve istenirse ödeme modülüne iade emri verir.

Üç uç müşteriye posta gönderir: bildirim, hatırlatma ve dosyası varken resmileştirme. Bir betikte bunları çağırırken gerçek insanlara ulaştığınızı unutmayın.

Referans

Durumu Değiştirme

put/api/v1/admin/invoices/{id}/status
Invoices/UpdateInvoiceStatus admin yan etkileri var

Faturanın durumunu değiştirir ve durumun getirdiği işleri yürütür.

Gövde 5
statusstringreqYeni durum: paid, unpaid, refund ya da cancelled.
payment_methodstringÖdeme yöntemi. Ödenmiş bir faturada yalnız bunu göndererek yöntemi değiştirebilirsiniz; Balance orada ancak faturada bakiyeden alınmış bir ödeme satırı varsa kabul edilir. Tutar değişmez; ödeme satırı olmadan alınan tutarın kasa kaydı yeni yönteme geçer. Ödeme satırlarının kasa kayıtları kendi yönteminde kalır. Balance, açık faturayı paid yaparken kalan tutarı müşterinin hesap bakiyesinden düşer. Ödemesi olmayan açık fatura paid yapılırken bu yöntemin (gönderilmezse kayıtlı yöntemin) bugünkü komisyon oranıyla yeniden fiyatlanır; başka bir yöntemin komisyonu kalmaz. Gönderilmezse faturanın kayıtlı yöntemi geçerlidir; o da Balance ise tutar yine bakiyeden düşülür.
refund_methodstringİadenin nasıl yapılacağı. gateway ile iade ödeme modülü üzerinden yapılır. credit ile iade tutarı müşterinin hesap bakiyesine, bakiyenin para biriminde eklenir; iade satırının yanına bir bakiye hareketi yazılır. Ödendi durumundan çıkış bakiyeden yalnız bakiye yükleme faturasında bir şey geri alır.
cancel_servicesboolFaturaya bağlı hizmetleri de iptal eder. İade ve iptal durumlarında işler.
notifyboolMüşteriye bildirim gönderir.
Dönen alanlar data
dataobjectGüncel fatura. Detay ucuyla aynı şekildedir.
Hatalar 8
not_found404Fatura bulunamadı.
invalid_status422Durum tanınmıyor.
same_status422Fatura zaten bu durumda.
balance_requires_open_invoice422Fatura zaten ödenmiş, yalnız yöntemi Balance değerine çevrilmek isteniyor ve faturada bakiyeden alınmış ödeme satırı yok. O faturada hesap bakiyesinden tutar düşülmez. Ayrıntıda faturanın durumu döner; yöntem ve bakiye değişmez.
blocked_by_gate422Bir kanca değişimi reddetti.
insufficient_balance422Gönderilen ya da kayıtlı yöntem Balance ve hesap bakiyesi kalan tutarı karşılamıyor. Ayrıntıda gereken ve mevcut tutar bakiyenin para biriminde döner; fatura ve bakiye değişmez.
invoice_payment_in_progress429Fatura o anda başka bir istekle ödeniyor. Kısa süre sonra yeniden deneyin.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X PUT 'https://panel.ornek.com/api/v1/admin/invoices/1212/status' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"paid","payment_method":"Balance","notify":true}'
const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}/status`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 'paid',
    payment_method: 'Balance',
    notify: true,
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id . '/status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'status'         => 'paid',
        'payment_method' => 'Balance',
        'notify'         => true,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Odenmis yapmak GELIR KAYDI acar, numara verir ve hizmetleri harekete gecirir.
Api::Invoices()->UpdateInvoiceStatus([
    'id'     => $id,
    'status' => 'paid',
    'notify' => true,
]);

Müşteri Bilgilerini Düzeltme

patch/api/v1/admin/invoices/{id}/client-details
Invoices/UpdateInvoiceClientDetails admin yalnız bu faturayı etkiler

Faturaya donmuş müşteri ve adres bilgilerini düzeltir. Gönderdiğiniz adres saklı adresle birleşir: göndermediğiniz anahtarlar korunur, belgenin okuduğu ülke, il, ilçe ve posta kodu adları yeniden kurulur.

Gövde 10
kindstringMüşterinin bireysel mi kurumsal mı olduğu. Kurumsal olmayanda firma adı boşalır.
first_namestringAd. Tam ad bundan türer.
last_namestringSoyad.
emailstringE-posta adresi.
phonestringTelefon.
identitystringKimlik ya da vergi numarası.
company_namestringFirma adı. Kurumsal müşteride işler.
tax_numberstringVergi numarası.
tax_officestringVergi dairesi.
addressobjectAdres: açık adres, ülke, il, şehir ve posta kodu. İl ve şehir sayı verilirse kimlikten çözülür, metin verilirse olduğu gibi saklanır.
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/client-details' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"corporate","company_name":"Ornek A.S.","tax_number":"0000000000"}'
const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}/client-details`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    kind: 'corporate',
    company_name: 'Example Inc.',
    tax_number: '000000000',
    address: { detail: '123 Market Street', country_id: 840, zipcode: '94105' },
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id . '/client-details');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'kind'         => 'corporate',
        'company_name' => 'Example Inc.',
        'tax_number'   => '000000000',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Bu uc CANLI musteriye DOKUNMAZ; yalniz bu faturanin uzerindeki kopyayi duzeltir.
Api::Invoices()->UpdateInvoiceClientDetails([
    'id'           => $id,
    'company_name' => 'Example Inc.',
]);

Bildirim Gönderme

post/api/v1/admin/invoices/{id}/notifications
Invoices/SendInvoiceNotification admin gerçek e-posta gider

Fatura için seçtiğiniz bildirim şablonunu müşteriye gönderir.

Gövde 1
templatestringreqGönderilecek şablonun anahtarı. Şablon fatura bildirimlerinden biri ve etkin olmalı.
Dönen alanlar data — 3
sentboolGönderim çalıştı mı.
templatestringGönderilen şablon.
invoice_idintFaturanın numarası.
Hatalar 4
not_found404Fatura bulunamadı.
template_required422Şablon verilmedi.
invalid_template422Şablon tanınmıyor ya da kapalı.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X POST 'https://panel.ornek.com/api/v1/admin/invoices/1231/notifications' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"template":"invoice-created"}'
const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}/notifications`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ template: 'invoice-created' }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id . '/notifications');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['template' => 'invoice-created']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Kapali bir sablon 422 verir; ekranda gorunen liste ETKIN olanlari gostermez.
Api::Invoices()->SendInvoiceNotification([
    'id'       => $id,
    'template' => 'invoice-created',
]);

Resmileştirme

post/api/v1/admin/invoices/{id}/formalize
Invoices/FormalizeInvoice admin bir kez yapılır

Faturayı resmî faturaya çevirir.

Gövde 1
notifyboolMüşteriye bildirim gönderir. Resmileştirme dosyası varsa gider.
Dönen alanlar data
dataobjectGüncel fatura. Detay ucuyla aynı şekildedir.
Hatalar 4
not_found404Fatura bulunamadı.
already_formalized422Fatura zaten resmî.
blocked_by_gate422Bir kanca işlemi reddetti.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X POST 'https://panel.ornek.com/api/v1/admin/invoices/1231/formalize' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"notify":false}'
const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}/formalize`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ notify: false }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/invoices/' . $id . '/formalize');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['notify' => false]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Ikinci cagri 422 verir; toplu bir betikte once faturanin durumunu okuyun.
$inv = Api::Invoices()->GetInvoice(['id' => $id])['data'];
if (! $inv['formalized']) Api::Invoices()->FormalizeInvoice(['id' => $id]);

Hatırlatma Gönderme

post/api/v1/admin/invoices/{id}/remind
Invoices/RemindInvoice admin

Ödenmemiş fatura için müşteriye hatırlatma gönderir. Müşteriye ulaşamazsa hiçbir şey kaydetmez ve durum kodu yine 200 olur.

Gövde —
——Gövde gerekmez, boş gönderin. Faturayı adres belirler; gönderilen bildirim invoice-reminder'dır ve bunu değiştirecek bir alan yoktur.
Dönen alanlar data — 4
remindedboolHatırlatma müşteri tarafına ulaştıysa true: sahip, ek iletişim adresi ya da alt kullanıcı, gönderildi ya da kuyrukta. Yalnız personele giden kopya sayılmaz.
invoice_idintFaturanın numarası.
reasonstringYalnız reminded false iken: disabled, blocked, opted_out, client_side_off, send_failed ya da no_recipients.
messagestringYalnız reminded false iken: reason'ın İngilizce açıklaması.
Hatalar 2
not_found404Fatura bulunamadı.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X POST 'https://panel.ornek.com/api/v1/admin/invoices/1231/remind' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch(`https://panel.ornek.com/api/v1/admin/invoices/${id}/remind`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

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

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Cagri KAC KEZ yapildigini saymaz; ayni faturaya arka arkaya hatirlatma gonderebilir.
Api::Invoices()->RemindInvoice(['id' => $id]);

Tuzaklar

Durum değişimi tek başına değildir

Ödenmiş yapmak gelir kaydı açar, ödenmiş fatura numarası verir ve faturaya bağlı hizmetleri harekete geçirir. İade etmek bunları geri sarar, metrik kayıtlarını çözer ve istenirse ödeme modülüne iade emri verir. Test ederken bunu gerçek bir müşteri faturası üzerinde denemeyin.

Aynı duruma geçmek hata verir

Fatura zaten o durumdaysa çağrı reddedilir. Tek istisna ödenmiş bir faturada ödeme yöntemini değiştirmektir; orada durum aynı kalır ve yalnız yöntem yazılır. Durumları eşitleyen bir betik yazıyorsanız önce mevcut durumu okuyun.

Müşteri bilgisi düzeltmesi faturaya özeldir

Bu uç faturanın üzerine donmuş kopyayı düzeltir; canlı müşteri kaydına dokunmaz. Bir adres yanlışsa iki yerde de düzeltilmesi gerekebilir: burada geçmiş belge için, müşteri kaydında gelecek belgeler için. Buradan yapılan düzeltme diğer faturalara da yansımaz.

Resmileştirme bir kez yapılır

Zaten resmî bir faturayı yeniden resmileştirmek hata verir. Toplu bir betikte bu, ilk hatada duran bir döngüye yol açar; her fatura için önce durumu okuyun. Bir kanca da resmileştirmeyi engelleyebilir, çünkü bazı kurulumlarda bunun muhasebe tarafında karşılığı vardır.

Hatırlatma sayılmaz

Hatırlatma ucu kaç kez çağrıldığını tutmaz ve arka arkaya çağrıldığında aynı müşteriye üst üste posta gider. Vadesi geçenleri gezen bir betik yazarken hangi faturaya ne zaman hatırlatma gittiğini kendi tarafınızda saklayın; yoksa her koşuda herkes yeniden uyarılır.

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ı