Partner Sipariş API'si

Bu doküman, önceki Turor OMS paketinin (POST /restApi/v1/dropShippingOrder, GET /restApi/v1/dropShippingOrderItem/{id}) yerine geçer. O uçlar ve HTTP Basic kullanıcı bilgileri kullanımdan kaldırılmıştır, artık kullanılmamalıdır. Alan bazında karşılaştırma için bu sayfanın sonundaki Ek A'ya bakın.

---

Bu API'ye ihtiyacınız var mı?

Çoğu partnerin ihtiyacı yok. WooCommerce veya Shopify kullanıyorsanız eklentimizi kullanın — WooCommerce veya Shopify. Bu API'yi yalnızca kendi sisteminiz varsa kullanın.

Kataloğu aktarmak, stok ve fiyatları güncel tutmak ve marj ayrı bir sayfada: Katalog feed'i.

Geliştiricileriniz için bu sayfanın PDF sürümü: Partner Sipariş API'si v1.0 (PDF).

1. Ortamlar

Bu dokümandaki tüm örnekler canlı ortam URL'ini kullanır. Token'lar ortamlar arasında paylaşılmaz — önce test etmek isterseniz hesap yöneticinizden bir staging token'ı isteyin.

---

2. Kimlik doğrulama

Her istek hesap token'ınızı bearer token olarak taşır:

Authorization: Bearer HESAP_TOKENINIZ

Bu, ürün katalog feed'i (GET /api/v1/feeds/catalog.csv) için kullandığınız token'ın aynısıdır. Cosmetic Wholesale hesabınızın Account sayfasında, feed URL'inizle birlikte bulabilirsiniz.

Notlar:

• Token hesabınızı temsil eder. Tarayıcı tarafı kodda veya herkese açık bir depoda asla yayımlamayın.
• Token'lar hesabınızdan istediğiniz zaman iptal edilip yenilenebilir. İptal edilmiş token 401 döner.
• Kullanıcı adı/şifre kullanılmaz. Eski HTTP Basic bilgileri sipariş gönderimi için artık geçerli değildir.
• Alternatif olarak X-Feed-Token: HESAP_TOKENINIZ başlığı da kabul edilir.

---

3. Ön koşullar

Bir sipariş yalnızca aşağıdakilerin tamamı sağlandığında kabul edilir:

1. Hesabınız onaylı ve dropshipping kanalında olmalı.
2. Dropshipping aboneliğiniz aktif olmalı — aksi halde her istek 403 subscription_required döner.
3. Cüzdan bakiyeniz siparişi karşılamalı — karşılamıyorsa sipariş oluşturulur ve beklemeye alınır (402, bkz. bölüm 6).
4. Siparişteki her ean katalog feed'inizde bulunmalı ve stokta olmalı.

Ürün başlığı, görseli ve fiyatı sizin tarafınızdan gönderilmez — bunlar bizim kataloğumuzdan gelir. Siz yalnızca EAN ve adet gönderirsiniz.

---

4. Sipariş oluşturma

POST /dropshipping/orders

İstek başlıkları

Authorization: Bearer HESAP_TOKENINIZ
Content-Type: application/json

İstek gövdesi

{
  "externalRef": "ORD123456",
  "payment": "WALLET",
  "shipping": {
    "firstName": "Ad",
    "lastName": "Soyad",
    "company": "TestFirma",
    "address1": "Main Street 123",
    "address2": "",
    "postcode": "1072 HM",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "",
    "email": "musteri@ornek.com"
  },
  "lines": [
    { "ean": "6291107455365", "quantity": 2 },
    { "ean": "3607348816552", "quantity": 3 }
  ]
}

Alanlar

Geriye dönük uyumluluk için snake_case karşılıkları da kabul edilir: external_ref, first_name, last_name, address_1, address_2 ve quantity yerine qty.

Yanıt

{
  "id": "8f1c0b2e-6a3d-4f21-9b7e-0c5a4d2e1f33",
  "externalRef": "ORD123456",
  "omsReference": "ds:usr_2f9a1c:ORD123456",
  "createdVia": "dropshipping-api",
  "status": "PAID",
  "walletDebited": true,
  "omsPushStatus": "pending",
  "omsOrderItemIds": [],
  "tracking": []
}

HTTP durum kodları

---

5. Idempotency (tekrar gönderim güvenliği)

externalRef idempotency anahtarıdır. Aynı externalRef ile iki kez gönderim yapmak asla ikinci bir sipariş oluşturmaz ve cüzdanınızdan iki kez tahsilat yapmaz:

• İlk deneme başarılıysa, ikincisi mevcut siparişle birlikte 200 döner.
• İlk deneme bakiye yetersizliğinden beklemeye alındıysa, ikinci deneme cüzdan ödemesini yeniden dener ve bakiye yeterli olduğunda 201/200 döner.

Bu sayede zaman aşımı ve ağ hatalarında tekrar denemek güvenlidir. Her zaman aynı externalRef ile tekrar deneyin — aynı müşteri siparişi için asla yeni bir referans üretmeyin.

---

6. Bakiye yetersizliği: 402 HOLD sözleşmesi

Bu davranışın eski OMS API'sinde karşılığı yoktu ve en sık yapılan entegrasyon hatasıdır.

Cüzdanınız siparişi karşılamadığında:

HTTP/1.1 402 Payment Required

{
  "id": "8f1c0b2e-6a3d-4f21-9b7e-0c5a4d2e1f33",
  "externalRef": "ORD123456",
  "status": "HOLD",
  "reason": "INSUFFICIENT_WALLET",
  "walletDebited": false,
  "omsPushStatus": null,
  "omsOrderItemIds": [],
  "tracking": []
}

Bunun anlamı:

• Sipariş sistemimizde vardır ve stoğu rezerve edilmiştir. Reddedilmemiş, silinmemiştir.
• Hiçbir tahsilat yapılmamıştır.
• Depoya henüz hiçbir şey gönderilmemiştir.

Sisteminizin yapması gerekenler:

• Siparişi kendi tarafınızda iptal etmeyin veya silmeyin. Bekliyor/hazırlanıyor durumunda tutun.
• Cüzdanınıza bakiye yükleyin.
• Aynı externalRef ile yeniden POST edin; ya da bekleyin: beklemedeki siparişler bakiye yeterli hale geldiğinde otomatik olarak yeniden denenir.
• walletDebited true olana ve status artık HOLD olmayana kadar GET ile sorgulayın.

402 üzerine iptal etmek mutabakatı bozan şeydir — sipariş bizde rezerve olarak dururken sizin sisteminiz onu başarısız sanır.

---

7. Sipariş sorgulama

GET /dropshipping/orders/{id}
GET /dropshipping/orders?externalRef=ORD123456

{id} yerine hem Cosmetic Wholesale id'si (UUID) hem de kendi externalRef'iniz kullanılabilir. Her iki biçim de sipariş oluşturma ile aynı gövdeyi döner. Siparişler token'ınıza bağlıdır — yalnızca kendi siparişlerinizi okuyabilirsiniz.

GET https://cosmeticwholesale.eu/api/v1/dropshipping/orders?externalRef=ORD123456
Authorization: Bearer HESAP_TOKENINIZ

Sipariş durumları

---

8. Kargo takibi

Takip bilgisi aynı GET içinde, dizi olarak döner (bir sipariş birden fazla kolide çıkabilir):

{
  "id": "8f1c0b2e-6a3d-4f21-9b7e-0c5a4d2e1f33",
  "externalRef": "ORD123456",
  "status": "SHIPPED",
  "walletDebited": true,
  "omsPushStatus": "pushed",
  "omsOrderItemIds": ["418224", "418225", "418226"],
  "tracking": [
    {
      "provider": "postnl-3s",
      "trackingNumber": "3SXXXX00000000",
      "dateShipped": "2026-05-06T17:39:20.000Z"
    }
  ]
}

Sipariş başına saatte birden fazla sorgu yapmayın. COMPLETED, CANCELLED veya REFUNDED durumundaki siparişleri sorgulamayın.

---

9. Hata kodları

Hatalar { "error": "<mesaj>", "code": "<kod>" } biçiminde döner.

---

10. Örnekler

cURL — sipariş oluşturma

curl -X POST https://cosmeticwholesale.eu/api/v1/dropshipping/orders \
  -H "Authorization: Bearer HESAP_TOKENINIZ" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "ORD123456",
    "shipping": {
      "firstName": "Ad",
      "lastName": "Soyad",
      "address1": "Main Street 123",
      "postcode": "1072 HM",
      "city": "Amsterdam",
      "country": "NL"
    },
    "lines": [
      { "ean": "6291107455365", "quantity": 2 }
    ]
  }'

cURL — sipariş sorgulama

curl "https://cosmeticwholesale.eu/api/v1/dropshipping/orders?externalRef=ORD123456" \
  -H "Authorization: Bearer HESAP_TOKENINIZ"

PHP — sipariş oluşturma

<?php

$token = 'HESAP_TOKENINIZ';
$url   = 'https://cosmeticwholesale.eu/api/v1/dropshipping/orders';

$payload = [
    'externalRef' => 'ORD123456',
    'shipping' => [
        'firstName' => 'Ad',
        'lastName'  => 'Soyad',
        'address1'  => 'Main Street 123',
        'postcode'  => '1072 HM',
        'city'      => 'Amsterdam',
        'country'   => 'NL',
    ],
    'lines' => [
        ['ean' => '6291107455365', 'quantity' => 2],
    ],
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$order = json_decode($response, true);

if ($status === 402) {
    // Cüzdan bakiyesi yetersiz, sipariş beklemede.
    // Siparişi açık tutun ve bakiye yükledikten sonra AYNI externalRef ile tekrar gönderin.
} elseif ($status === 201 || $status === 200) {
    // Kabul edildi. $order['id'] değerini saklayın ve takip için sorgulayın.
}
?>

PHP — sipariş sorgulama

<?php

$token       = 'HESAP_TOKENINIZ';
$externalRef = 'ORD123456';
$url = 'https://cosmeticwholesale.eu/api/v1/dropshipping/orders/' . rawurlencode($externalRef);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $token]);
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

---

Ek A — Turor OMS uçlarından geçiş

Eski paket https://omsback.turor.org/restApi/v1 adresini ve HTTP Basic kimlik bilgilerini kullanıyordu. Bu bilgiler paylaşılan bir sistem hesabına aitti ve cüzdan, stok ve abonelik katmanını atlıyordu. Artık verilmiyor, mevcut olanlar da geri çekilecek.

Uçlar

İstek alanları

Yanıt alanları

Kodunuzda gözden geçirmeniz gereken davranış değişiklikleri

1. 402 bir hata değildir. Eski API'de cüzdan katmanı yoktu. 402'yi "beklemede, aynı referansla tekrar dene" olarak ele alın — asla "siparişi iptal et" olarak değil.
2. Tekrar denemek güvenlidir. externalRef mükerrer kaydı engeller; eski orderCreated: 0 kontrolünün yerini 200 ile 201 ayrımı alır.
3. Takip sipariş seviyesine taşındı. Satır başına bir GET yerine sipariş başına tek GET, ve sonuç bir dizidir.
4. Ürün verisi bize aittir. Başlık ve görsel URL'i göndermeyi bırakın.