# İlk eşitleme + olay akışı

> **Ne yaparsınız:** İlk bağlantıda siparis.app kayıtlarını tek bir anın tutarlı dosyasıyla alır, sonra değişikliklere olay akışından kayıpsız devam edersiniz.
> **Hangi uçlar:** [Dışa aktarma başlat](https://developer.siparis.app/uc/disa-aktarma-baslat), [Dışa aktarmanın durumunu getir](https://developer.siparis.app/uc/disa-aktarmanin-durumunu-getir), [Dışa aktarma dosyasını indir](https://developer.siparis.app/uc/disa-aktarma-dosyasini-indir), [Olayları listele](https://developer.siparis.app/uc/olaylari-listele)
> **Gereken izin:** `exports:write`, `events:read` ve seçilen kaynağın okuma kapsamı (ör. `orders:read`).

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](https://developer.siparis.app/uc/disa-aktarma-baslat).

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

```json
{
  "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](https://developer.siparis.app/uc/disa-aktarma-baslat) 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):

```json
{
  "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ışı](https://developer.siparis.app/olaylar) 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.