# Fatura Durumu ve Bildirimleri

https://dev.wisecp.com/tr/fatura-durumu-ve-bildirimleri

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.

refund_methodstringİadenin nasıl yapılacağı. Ödeme modülü üzerinden iade istenebilir.

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 5

not_found404Fatura bulunamadı.

invalid_status422Durum tanınmıyor.

same_status422Fatura zaten bu durumda.

blocked_by_gate422Bir kanca değişimi reddetti.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
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}'
```

```javascript
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();
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
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"}'
```

```javascript
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();
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
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"}'
```

```javascript
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();
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
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}'
```

```javascript
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();
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/invoices/1231/remind' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
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();
```

```php
$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);
```

```php
// 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.

## İlgili Makaleler

- [Fatura Yönetimi](https://dev.wisecp.com/tr/fatura-yonetimi)
- [Fatura Kalemleri ve Ödemeler](https://dev.wisecp.com/tr/fatura-kalemleri-ve-odemeler)
- [Kasa Kayıtları](https://dev.wisecp.com/tr/kasa-kayitlari)