Başka kanaldaki satışı bildirmek

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.

Yeni satış için Sipariş eklemek ve ilerletmek 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):

Bütün alanlar: Başka kanaldaki satışı bildir.

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):

{
  "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 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ışı ve 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

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