Orders API

Pazaryerlerinden çekilen siparişleri listelemek ve detayını okumak içindir. Sipariş oluşturma veya statü değiştirme API'si yoktur — siparişler pazaryerinden bize akar; sen sadece okursun.

Base URL: https://api.entegrasyoner.com/v1

Auth: Tüm endpoint'lerde Authorization: Bearer <API_KEY> zorunlu — bkz. Authentication.

Genel akış

[Trendyol / TGo / Hepsi ...]
        │
        │  bizim poll job'ları periyodik çeker (~dakika başı)
        ▼
[Entegrasyoner DB — orders tablosu]
        │
        │  sen `GET /v1/orders` ile çekersin
        ▼
[Senin ERP / muhasebe / depo yazılımın]

Yeni sipariş için polling kullanılır (GET /v1/orders?status=... periyodik). Anlık webhook için aşağıdaki "Anlık bildirim" notuna bak.

İçerik

• GET /orders — listele (paginate + filter)
• GET /orders/{id} — tek sipariş detay (kalemler + ham payload dahil)
• GET /orders/statuses — bu tenant'ta görülen distinct statü değerleri

Liste

GET /v1/orders?platform=trendyol-go&status=Created&per_page=50&page=1
Authorization: Bearer <API_KEY>
Accept: application/json

Query parametreleri

Parametre	Tip	Açıklama
platform	string	Pazaryeri slug'ı (trendyol, trendyol-go, hepsiburada vb.). Çoklu seçim yok — birden fazla pazaryeri için ayrı çağrı yap.
status	string	Tam eşleşme. Pazaryerine göre değişir — geçerli değerleri GET /orders/statuses ile çek.
credential_id	int	Belirli bir pazaryeri bağlantısı (tek pazaryerinde birden fazla mağaza varsa kullan).
search	string	order_number, sync_id, customer_name alanlarında LIKE araması.
per_page	int	Sayfa başı kayıt (default 25, max 100).
page	int	Sayfa numarası (default 1).

Sıralama sabittir: en yeni siparişten eskisine (source_created_at DESC, id DESC).

Response — 200 OK

{
  "data": [
    {
      "id": 1542,
      "sync_id": "TGO-PKG-7891234",
      "external_order_id": "TGO-ORD-558899",
      "customer_id": "C-883",
      "order_number": "TGO558899",
      "status": "Created",
      "prev_status": null,
      "customer_name": "Ahmet Yılmaz",
      "total_price": 480.00,
      "gross_amount": 500.00,
      "total_discount": 20.00,
      "total_cargo": 0.00,
      "invoice_tax_amount": 80.00,
      "platform": {"id": 3, "name": "Trendyol Go", "slug": "trendyol-go"},
      "credential": {"id": 7, "label": "Trendyol Go Bağlantım"},
      "store": {"id": 12, "label": "İstanbul Şube", "platform_store_id": "1001"},
      "source_created_at": "2025-12-15T11:42:00+00:00",
      "source_modified_at": "2025-12-15T11:43:11+00:00",
      "fetched_at": "2025-12-15T11:43:30+00:00",
      "created_at": "2025-12-15T11:43:30+00:00"
    }
  ],
  "links": {
    "first": "https://api.entegrasyoner.com/v1/orders?page=1",
    "last":  "https://api.entegrasyoner.com/v1/orders?page=12",
    "prev":  null,
    "next":  "https://api.entegrasyoner.com/v1/orders?page=2"
  },
  "meta": {"current_page": 1, "per_page": 50, "total": 583}
}

Alan açıklaması

Alan	Anlam
id	Entegrasyoner iç ID — stabil, kalıcı.
sync_id	Paket ID (pazaryeri tarafında). Bir sipariş paketlere bölünebilir (örn. TGo "split package"). Paket parçalanırsa eski sync_id ölür, yeni sync_id'li ayrı kayıt oluşur — id da değişir.
external_order_id	Sipariş ID (pazaryerinin sipariş kimliği). Paket bölünse de aynı kalır. Gerçek "sipariş bazlı" gruplama için bunu kullan — external_order_id aynı olan birden fazla sync_id olabilir.
customer_id	Pazaryerindeki müşteri kimliği.
order_number	Müşteriye gösterilen sipariş numarası (pazaryerinin format'ı).
status	Pazaryeri tarafındaki güncel statü (Created, Picking, Shipped, Delivered, Cancelled gibi — pazaryerine özel).
prev_status	Bir önceki statü (statü değişimini takip etmek için).
customer_name	Müşteri adı (kişisel veri — GDPR/KVKK saklama süresine dikkat).
total_price	Müşterinin ödediği net tutar.
gross_amount	İndirim öncesi brüt.
total_discount, total_cargo, invoice_tax_amount	Detay kalemler.
platform.slug	trendyol, trendyol-go, hepsiburada vb.
credential.label	Hangi pazaryeri bağlantısından geldi.
store	Çok mağazalı bağlantıda hangi mağaza/şubeden (TGo gibi); single-store pazaryerlerinde null.
source_created_at	Pazaryeri tarafındaki orijinal oluşturma zamanı. Sıralama bunla yapılır — sen bunu baz al.
source_modified_at	Pazaryeri tarafındaki son değişiklik (statü geçişi vb.).
fetched_at	Bizim poll job'umuzun siparişi DB'ye yazdığı an.
created_at	DB satırı oluşturma anı (genelde fetched_at ile eş zamanlı).

Tek sipariş

GET /v1/orders/1542
Authorization: Bearer <API_KEY>
Accept: application/json

Response — 200 OK

Liste cevabındaki tüm alanlara ek olarak iki alan döner:

{
  "data": {
    "id": 1542,
    "...": "(liste cevabındaki tüm alanlar)",

    "lines": [
      {
        "sku": "EX-SKU-001",
        "product_name": "Example Product 250ml",
        "quantity": 2,
        "unit_price": 180.00,
        "total_price": 360.00,
        "barcode": "1234567890123"
      },
      {
        "sku": "EX-SKU-002",
        "product_name": "Other Product",
        "quantity": 1,
        "unit_price": 120.00,
        "total_price": 120.00,
        "barcode": "9876543210987"
      }
    ],

    "raw": {
      "...": "pazaryerinden gelen ham JSON payload"
    }
  }
}

Alan	Anlam
lines	Sipariş kalemleri dizisi. Alan setleri pazaryerine göre değişebilir — yukarıdaki en yaygın alanlardır. Detay normalize edilmiş ortak şema; özel alanlar raw içinde kalır.
raw	Pazaryerinden gelen ham JSON (debugging, eksik alan tarama, custom alan okuma için). Yapısı platform-specific.

raw büyük olabilir (10–100 KB) — listeleme cevabına dahil edilmez; sadece tek sipariş çağrısında döner.

Statü listesi

Statü isimleri pazaryerine göre değişir. GET /orders?status=... filtresinde hangi değerleri kullanabileceğini öğrenmek için bu ucu çağır — bu tenant'ın siparişlerinde gerçekten görülmüş statü değerlerini döner.

GET /v1/orders/statuses
Authorization: Bearer <API_KEY>

Pazaryerine göre filtrele:

GET /v1/orders/statuses?platform=trendyol-go

Response — 200 OK

{
  "data": ["Cancelled", "Created", "Delivered", "Picking", "Shipped"]
}

Boş tenant'ta veya filtre eşleşmiyorsa {"data": []} döner.

Polling stratejisi

Yeni siparişleri çekmek için önerilen akış:

1. Kursorü saklayın — son başarıyla işlediğin siparişin source_created_at (veya id) değerini kayıt altına al.
2. Periyodik çek — 1–2 dakikada bir GET /orders?status=Created&per_page=100&page=1 ile en yeni siparişleri al.
3. Kursora kadar geri yürü — listede kursordan eski sipariş çıkana kadar sayfaları gez; eskileri atla.
4. İşle + kursoru ilerlet — kendi sistemine yazdıktan sonra kursoru en yeni source_created_at'e güncelle.
5. Statü değişimini takip et — Created → Shipped → Delivered geçişlerini yakalamak için aynı sipariş için periyodik GET /orders/{id} veya tüm statüleri içeren liste çekimi yap. prev_status ile son geçişi anlarsın.

API rate — şu an entegratör tarafında oran sınırı yok ama 5–10 saniyeden sık polling önerilmez. İleride tenant başına dakikada 60 istek civarı limit gelebilir.

Anlık bildirim (webhook) — şu an sipariş çekimi polling iledir; sipariş webhook'u public olarak açık değildir. Anlık sipariş push'una ihtiyacın varsa bizimle iletişime geç ([email protected]) — kullanım senaryona göre değerlendiriyoruz.

Hata kodları (özet)

HTTP	Senaryo
401	Token eksik/geçersiz
404	id bulunamadı (veya başka tenant'a ait)
422	Geçersiz query parametre tipi
5xx	Sunucu hatası — geçici, üstel backoff ile tekrar dene

Detaylı: errors.