Siparişleri ERP’ye almak

API temel adresi https://api.siparis.app/v1; bütün isteklerde sunucunuzdaki SIPARIS_API_KEY ile Bearer doğrulaması gerekir. ERP’den siparis.app’e sipariş yazmak için Sipariş eklemek ve ilerletmek rehberine bakın.

Gerekli kapsamları seçin

Tahsilat için payments:read, gönderi için shipments:read, iade için returns:read, fatura için invoices:read kapsamlarını (anahtarın okuma izinleri) ekleyin. Alıcı bilgilerine ihtiyaç varsa işletme sahibi personal_data:read kapsamını ayrıca ve açıkça seçmelidir.

İlk aktarımı yapın

İlk eşitleme rehberindeki istekte resource=orders seçin. Dosyadaki her nesneyi id (ord_…) ile ERP siparişine bağlayın; görünen number alanını benzersiz kimlik yerine kullanmayın. Satış markanızın kimliği store alanındadır. Bir anahtar birden fazla markayı okuyabilir; marka sınırlı anahtarın dışındaki siparişler görünmez.

Sipariş dosyası üst alanları taşır; satırlar için Sipariş satırlarını listele ucunu çağırın. Alternatif olarak ayrıntıda include=lines (yanıta alt kayıtları ekleme seçimi) ilk 50 satırı getirir; devam imleci varsa aynı siparişin satır ucunda ilerleyin. Satır fiyatını güncel katalog fiyatından yeniden hesaplamayın; sipariş anındaki unit_price, quantity, discount ve total değerlerini alın.

Sürekli güncelleyin

Dosya tamamen işlendiğinde kendi resume_cursor değeriyle (dosyanın bittiği andaki olay konumu) /v1/events okuyun; bu imlece types eklemeyin. order.created, order.updated, order.status_changed geldiğinde data.object.id ile siparişin güncel halini okuyun. Alt kayıt değişiklikleri de order.updated üretebilir.

import json
import os
from urllib.request import Request, urlopen
from urllib.parse import urlencode

base = os.environ.get("SIPARIS_API_URL", "https://api.siparis.app/v1")
order_id = os.environ["SIPARIS_ORDER_ID"]  # Liste/olaydaki ord_ kimliği.
url = f"{base}/orders/{order_id}?" + urlencode({"include": "lines"})
request = Request(url, headers={"Authorization": "Bearer " + os.environ["SIPARIS_API_KEY"]})
with urlopen(request, timeout=30) as response:
    order = json.load(response)
print(order["id"], order["total"], order["currency"])
# lines.has_more varsa /orders/{id}/lines?cursor=... ile tamamlayın.

Olay kimliği evt_… ile tekrar uygulamayı engelleyin. ERP güncellemesi, işlenen olay kimliği ve yeni next_cursor (sonraki okumanın yer imi) kaydı aynı veritabanı işleminde olmalıdır. İşlem yarıda kalırsa önceki imleçle tekrar okuyun. Her olay geçmişteki özettir; kaynak okuması güncel durumu verir.

Para mutabakatını tamamlayın

Ödeme ucu Ödemeleri ve para özetini getir hem işlem sayfasını hem bütün siparişin summary para özetini verir; sayfadaki tahsilatları toplayıp bunu bütün sipariş sanmayın. Ortak gönderilerde /shipments tutarları yalnız bu siparişin payıdır. TRY tutarları ondalık metindir; Python’da Decimal, TypeScript’te bir ondalık sayı kütüphanesi kullanın.

404 not_found yanlış kimlik veya marka sınırı olabilir; boş sipariş olarak kaydetmeyin. 429 için Retry-After kadar bekleyin. Ayrıntılar hata kataloğunda ve hız/tekrar kurallarında.