İlk eşitleme + olay akışı

API temel adresi https://api.siparis.app/v1. Aşağıdaki örnek siparişleri alır ve orders:read kapsamını (okuma iznini) kullanır.

1. Başlangıç dosyası isteyin

Her yeni işte benzersiz bir Idempotency-Key (tekrar anahtarı: aynı isteği güvenle yeniden göndermek için sizin ürettiğiniz metin) oluşturun ve saklayın. Aynı iş ağ hatasıyla tekrarlanırsa gövdeyi ve anahtarı aynen gönderin.

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

Bu istekte zorunlu gövde alanı yok; boş JSON nesnesi {} gönderilebilir.

Bütün alanlar: Dışa aktarma başlat.

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/exports" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ilk-siparis-dosyasi-20261016-001' \
  --data '{"resource":"orders","mode":"consistent_snapshot","format":"jsonl","filters":{}}'

Örnek HTTP 202 yanıtı (uydurma veri):

{
  "completed_at": null,
  "created_at": "2026-10-16T09:00:00Z",
  "error_code": null,
  "file": null,
  "format": "jsonl",
  "id": "exp_1234567890abcdef1234567890abcdef",
  "resource": "orders",
  "resume_cursor": null,
  "row_count": 0,
  "status": "queued"
}

Kaynaklar orders, customers, products, variants, inventory_levels. Süzgeçler ilgili liste ucuyla aynıdır ve Dışa aktarma başlat sayfasında listelenir. Her kaynağın ayrı dosyası ve ayrı devam imleci vardır.

2. Hazır olmasını bekleyin

202 yanıtındaki exp_… kimliğiyle GET /v1/exports/{id} okuyun. status=queued veya running iken kısa bekleyin; completed olunca devam edin. job.completed olayı da yalnız işi açan bağlantıya ve ilgili kaynak yetkisine görünür. failed olursa error_code değerine göre sorunu giderip yeni iş başlatın: export_too_large veya snapshot_timeout için süzgeçle daraltın, export_access_changed için güncel izinlerle yeniden başlayın, diğer hatalarda destek alın.

Örnek HTTP 200 yanıtı (uydurma veri):

{
  "completed_at": "2026-10-16T09:00:10Z",
  "created_at": "2026-10-16T09:00:00Z",
  "error_code": null,
  "file": {
    "bytes": 2048,
    "content_type": "application/x-ndjson",
    "download_path": "/v1/files/fil_1234567890abcdef1234567890abcdef",
    "expires_at": "2026-10-23T09:00:00Z",
    "id": "fil_1234567890abcdef1234567890abcdef"
  },
  "format": "jsonl",
  "id": "exp_1234567890abcdef1234567890abcdef",
  "resource": "orders",
  "resume_cursor": "SUNUCUDAN_DONEN_IMLEC",
  "row_count": 1,
  "status": "completed"
}

Aynı işletmede bir dosya hazırlanır; ikinci yeni istekte 409 export_in_progress gelir. Hazırlama 60 okuma puanı, indirme 5 puandır. Hazırlama en çok 10 dakika, dosya en çok 5 GiB olabilir; sınır aşılırsa kaynak süzgeçleriyle daraltın.

3. Dosyayı tamamen uygulayın

file.download_path zaten /v1 içerir: API kökenine ekleyin, temel adrese ikinci kez /v1 eklemeyin. Aynı Bearer anahtarıyla indirin. JSONL’de her satır liste ucunun bir nesnesidir. CSV’de her hücre JSON değeri içerir: önce CSV’yi, sonra her hücreyi JSON olarak çözün; boş metin ve null farklıdır.

8 MiB üzerindeki dosya en çok 60 saniyelik imzalı adrese 307 verebilir. Yönlendirmeyi ayrı istekte izleyin; Bearer başlığını imzalı hedefe taşımayın. Otomatik yönlendirmeyi başlıklarla birlikte açmayın. Erişim, işin created_at anından 7 gün sonra kapanır; kesin an file.expires_at alanıdır. Sonrasında 410 file_expired gelir; yeni dosya isteyin. İş kaydı, devam imleci ve olay geçmişi korunur.

4. Devam imleciyle olayları alın

Dosyanın tamamını uyguladıktan sonra resume_cursor değerini kalıcı saklayın: dosyanın bittiği andaki olay konumudur. GET /v1/events?cursor=… çağırın; bu imlece types eklemeyin. İlgili olayları kendi sisteminizde seçin. Görüntüde yer alan değişiklikler tekrar verilmez; dosya hazırlanırken sonradan tamamlanan değişiklikler akışa girer.

Süzgeçli dosya bütün kaynağı temsil etmez. Olayda güncel nesneyi okuyun, kendi süzgecinizi yeniden değerlendirin. Olayları uygulama, evt_… tekilleştirmesi ve next_cursor (sonraki okumanın yer imi) kaydı kendi veritabanınızda aynı işlemde olmalıdır. Boş sayfada has_more=true ise yeni imleçle ilerleyin; has_more=false olunca bekleyin. Ayrıntılı okuma döngüsü Olay akışı rehberindedir.

409 snapshot_publisher_changed yeni bir tutarlı dosyayla başlamanız gerektiğini bildirir. 400 invalid_cursor durumunda süzgeç ve kapsamların değişmediğini kontrol edin; konum kaybolduysa yeni ilk eşitleme yapın.