# Başka kanaldaki satışı bildirmek

> **Ne yaparsınız:** Etsy, kendi POS yazılımınız veya bağlı olmayan başka bir kanalda kesinleşmiş ve parası alınmış satışı kaydedip stoktan düşersiniz.
> **Hangi uçlar:** [Başka kanaldaki satışı bildir](https://developer.siparis.app/uc/baska-kanaldaki-satisi-bildir), [Siparişi iptal et](https://developer.siparis.app/uc/siparisi-iptal-et)
> **Gereken izin:** `orders:write`; müşteri ve adres için ayrıca `personal_data:write`.

Satışı `POST /v1/external_orders` ile bildirin; API temel adresi `https://api.siparis.app/v1`. Sipariş, stok ve müşteri aynı işlemde kaydedilir; kanalın müşterisinden yeniden ödeme alınmaz.

| Durum | Kullanılacak yol | Etkisi |
| --- | --- | --- |
| Yeni satış açıyorum; ödeme burada takip edilecek | `POST /v1/orders` | Panelin elle sipariş kuralları, `source=api` |
| Başka kanalda satış kesinleşti ve parası orada alındı | `POST /v1/external_orders` | Kanal siparişi, stok düşümü, `source=api_external` |
| Eski sitemin geçmişini yalnız bilgi için taşıyorum | Panelde Başka siteden taşınma | `source=import`; stok ve tahsilat etkisi yok |

Yeni satış için [Sipariş eklemek ve ilerletmek](https://developer.siparis.app/siparis-eklemek) rehberini kullanın. Aynı satışı iki uçtan göndermeyin; bağlı pazaryerinden otomatik alınan siparişi tekrar bildirmeyin.

## 1. Satışı bildirin

Yanıtta müşteri ve adresi görmek için `personal_data:read` de gerekir; yazma kapsamı (izni) okuma vermez. Marka sınırlı anahtar yalnız kendi markasına yazar; birden çok markaya açık bağlantıda `store` alanına satış markanızın `sto_` kimliğini ekleyin.

Her kalemde KDV dahil kesinleşmiş `unit_price` zorunludur; katalog fiyatı veya kampanya uygulanmaz. Kanalın aldığı kargo ücreti varsa `shipping_total` ile ekleyin.

İlk örnek için zorunlu alanlar (POST /v1/external_orders):

| Alan | Tür | Açıklama | Örnek |
| --- | --- | --- | --- |
| `channel_name` | metin (en çok 20 karakter) | Satış kanalının en çok 20 karakterlik adı. Baş/son boşluklar kaldırılır; büyük/küçük harfler farklı kanal adlarıdır. | `"Etsy"` |
| `external_reference` | metin (en çok 200 karakter) | Kanalın sipariş numarası; bu grant ve channel_name içinde kalıcı olarak tekildir. | `"ETSY-2026-001"` |
| `items` | liste: nesne (en çok 100 öğe) | var_ veya SKU, miktar ve kesinleşmiş birim fiyatıyla satış satırları. |  |
| `items[].quantity` | sayı (en çok 100000) veya metin | Miktar; en çok üç ondalık hane. Adetle satılan üründe tam sayı gerekir. | `"2"` |
| `items[].unit_price` | sayı (en az 0; en çok 10000000) veya metin | Kanalda kesinleşmiş KDV dahil TRY birim satış fiyatı; zorunludur. Kampanya uygulanmaz. | `"120.00"` |

Bütün alanlar: [Başka kanaldaki satışı bildir](https://developer.siparis.app/uc/baska-kanaldaki-satisi-bildir).

```bash
curl --fail-with-body -X POST "${SIPARIS_API_URL:-https://api.siparis.app/v1}/external_orders" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: etsy-2026-001" \
  -d '{"channel_name":"Etsy","external_reference":"ETSY-2026-001","items":[{"sku":"KUPA-MAVI","quantity":"2","unit_price":"120.00"}],"customer":{"name":"Örnek Müşteri","email":"musteri@example.com"},"ordered_at":"2026-10-15T09:00:00Z","paid_at":"2026-10-15T09:01:00Z"}'
```

`Idempotency-Key` tekrar anahtarıdır: aynı isteği güvenle yeniden göndermek için sizin ürettiğiniz benzersiz metin. Başarıda `201`, siparişin okuma modeli, `ETag` (sürüm etiketi) ve `/v1/orders/ord_…` biçiminde `Location` gelir:

Örnek HTTP 201 yanıtı (uydurma veri; yalnız ilgili alanlar):

```json
{
  "id": "ord_1234567890abcdef1234567890abcdef",
  "source": "api_external",
  "channel": "Etsy",
  "payment_method": "marketplace",
  "payment_state": "paid",
  "total": "240.00"
}
```



`channel_name` kanalın kısa adıdır; `Etsy` ve `etsy` farklı adlardır, adınızı tutarlı gönderin. `external_reference` kanalın sipariş numarasıdır; aynı API bağlantısı (paneldeki erişim kaydı; anahtarı döndürmek bunu değiştirmez) ve kanal içinde bir kez kullanılabilir. Başka kanal veya başka bağlantı ayrı sayılır.

`ordered_at` siparişin raporlardaki tarihi, `paid_at` kanalın ödeme tarihidir; geçmiş kabul edilir, gelecek reddedilir. Stok hareketi bildirimin işlendiği anda yazılır.

## 2. Stok ve para etkisini bilin

Satış kesinleştiği için sayılan stok yetmese de sipariş reddedilmez: miktarın tamamı stok defterine yazılır, stok eksiye inebilir. Panelin ve AI'ın mevcut fazla satış uyarısı geçerlidir. Stoğu sayılmayan veya sipariş üzerine hazırlanan ürünün mevcut stok kuralı korunur. Bu bildirimle ayrıca stok düşme isteği göndermeyin.

Tahsilat mevcut pazaryeri kuralıyla kanal kaydında tutulur: `payment_method=marketplace`, ödeme tamamlanmışsa `payment_state=paid` (0 TL satışta `none`). Ciro ve kâr, siparişin kendi tarihinde ve kanal adıyla hesaplanır. **Yerel kasa ve para defterine ikinci bir tahsilat yazılmaz.** `/payments` yerel para defterini okur; kanal tahsilatı orada yerel ödeme satırı olarak görünmez. Kart çekilmez; komisyon alanı sunulmaz ve kârdan komisyon düşülmez.

Müşteri bilgisi verilirse mevcut eşleştirme kullanılır; kart yoksa e-posta veya telefonla açılır. Yalnız ad verilirse yeni kart açılmaz. Müşteriye siparis.app'ten otomatik e-posta veya SMS gönderilmez; bunu açan bir seçenek yoktur.

## 3. Teslimatı ve siparişi izleyin

`fulfillment_status` verilmezse `pending`: sipariş onaylı açılır; isterseniz sonra [Kargoya vermek](https://developer.siparis.app/kargo-gondermek) yolunu kullanın. Adressiz satış da alınır; kargoya vermeden önce panelde veya sipariş düzeltme ucuyla adresi tamamlayın. Kanal kargoladıysa `shipped`, teslim ettiyse `delivered` gönderin; bu durumda siparis.app'te ikinci gönderi açılmaz. Bildirim dış kanala istek göndermez.

Yanlış bildirimi `POST /orders/{id}/cancel` ile zorunlu `reason` yazarak iptal edin: stok geri gelir, satış ciro ve kârdan düşer. `correct-status` gerekçeli durum düzeltmesini, `deliver` teslimi kaydeder. Yerel para çıkışı olmadığı için bu eylemlerde `orders:write` yeterlidir, `money_out:write` gerekmez.

Kalem ve adres düzeltmesi panelin olağan sipariş kısıtlarıyla yapılabilir; tahsilat yöntemi, ücretler ve para iadesi kanaldan yönetilir. Müşterinin vitrinden iade talebi kapalıdır. Kanalın kargoladığı sipariş müşterinin anonimleştirilmesini engellemez; burada teslimat bekleyen sipariş önce kapatılmalıdır. Bu uç mevcut dış satışı güncellemez.

**Bildirilen satışa siparis.app otomatik fatura kesmez.** Elle fatura kesilebilir; önce satış kanalının veya POS'un belge kesmediğini kontrol edin. Elle kesilen belgeye internet satışı bilgisi eklenmez, belge türü alıcının e-Fatura kaydına göre belirlenir; panel ve AI bu sınırlamayı kesimden önce gösterir.

`order.created`, müşteri ve stok olayları [olay akışı](https://developer.siparis.app/olaylar) ve [webhook](https://developer.siparis.app/webhook) yolundan gelir. Sipariş listesi ve dışa aktarmada `source=api_external`, `channel` ise gönderdiğiniz kanal adıdır; bunları `api` veya `import` olarak sınıflandırmayın.

## Sık hatalar

| Yanıt | Yapılacak iş |
| --- | --- |
| `409 duplicate_external_reference` | Satış zaten var; `existing_order` içindeki `ord_` kimliğini kullanın. |
| `404 not_found` | Seçenek, SKU veya müşteri anahtarın markasında bulunamadı. |
| `422 validation_error` | Zorunlu dış numarayı/fiyatı, kanal adını ve saat dilimli geçmiş tarihleri kontrol edin. |

Zaman aşımında aynı anahtar ve gövdeyle yeniden deneyin; `Idempotent-Replayed: true` yanıtında stok ikinci kez düşmez.