Sipariş eklemek ve ilerletmek

API temel adresi https://api.siparis.app/v1. Sipariş panelde API kaynağıyla görünür; stok, fiyat, tahsilat ve iptal kuralları paneldeki elle siparişle aynıdır.

1. Anahtarı ve ürünü hazırlayın

İşletme sahibi İşletme › Entegrasyonlar › Geliştirici sayfasında “Özel” kapsam seçimiyle anahtar oluşturur. Kapsamlar (anahtarın erişim izinleri) yapılan işe göre ayrıdır; personal_data:write seçilirken kişisel veri uyarısı okunur:

Yazma kapsamı okuma kapsamını kendiliğinden vermez: oluşturma yanıtı sipariş kimliğini verir, kişisel okuma izni yoksa müşteri alanları yanıttan çıkarılır. Hazır anahtar şablonları okuma kapsamlarıyla başlar; yazma izinlerini ihtiyacınıza göre seçin. Anahtarı sunucuda SIPARIS_API_KEY ortam değişkeninde tutun; tarayıcı koduna veya AI sohbetine koymayın.

Ürünün paneldeki stok kodunu aşağıdaki KUPA-MAVI yerine yazın; ürün siparişin markasında satışta olmalıdır. unit_price yazılmazsa markanın kampanya dahil fiyatı uygulanır; fiyat yazmak orders:write ile açılan orders.price eylemine tabidir.

Önce bağlantıyı doğrulayın:

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/me" \
  -H "Authorization: Bearer $SIPARIS_API_KEY"

Tek markalı işletmede veya marka sınırlı anahtarda store alanını atlayabilirsiniz. Birden fazla markaya erişen anahtarda /me yanıtından siparişin satış markasını seçip gövdeye "store": "sto_…" ekleyin. Marka sınırlı anahtar başka markaya yazamaz.

2. Siparişi açın

Bu örnek elden teslim, ödemesi gerçekten nakit alınmış, iki adet ürün siparişidir. Ödeme henüz alınmadıysa paid: false gönderin. API karttan para çekmez: POS ile alınmış kart ödemesi credit_card, havale bank_transfer olarak kaydedilir. Kapıda ödeme, parçalı ödeme ve kapora alanları Sipariş oluştur sayfasındadır.

İstek gövdesini dosyaya yazın ve örnek müşteri bilgilerini kendi alıcınızla değiştirin. Elden veya markadan teslimde müşterisiz satış için customer alanını tamamen kaldırabilirsiniz; o durumda personal_data:write gerekmez.

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

Bütün alanlar: Sipariş oluştur.

cat > siparis.json <<'JSON'
{
  "customer": {
    "name": "Örnek Müşteri",
    "phone": "05000000000",
    "email": "musteri@example.com"
  },
  "items": [{"sku": "KUPA-MAVI", "quantity": "2"}],
  "delivery_method": "hand",
  "payment_method": "cash",
  "paid": true,
  "external_reference": {"id": "WEB-2026-001"}
}
JSON

export SIPARIS_TEKRAR_ANAHTARI='siparis-WEB-2026-001-ac'
curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_TEKRAR_ANAHTARI" \
  -H 'Content-Type: application/json' \
  --data-binary @siparis.json \
  --dump-header siparis-basliklari.txt --output siparis-yaniti.json
cat siparis-yaniti.json

Idempotency-Key başlığı tekrar anahtarıdır: aynı isteği güvenle yeniden göndermek için sizin ürettiğiniz benzersiz metin. Başarı 201 Created döner. id yeni ord_… kimliğidir, Location siparişi okuma yoludur. ETag siparişin o anki sürüm etiketidir (güncel içeriğin çift tırnaklı SHA-256 özeti); siparişte revision alanı bulunmaz. Yanıt modeli sipariş okuma ucuyla aynıdır; tutarlar TRY cinsinden ondalık metindir.

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

{
  "channel": "whatsapp",
  "created_at": "2026-10-16T09:00:00Z",
  "currency": "TRY",
  "customer": null,
  "delivery_day": "2026-10-17",
  "delivery_method": "shipping",
  "discount_total": "0.00",
  "gift_wrap_fee": "0.00",
  "id": "ord_1234567890abcdef1234567890abcdef",
  "number": "48273910",
  "payment_fee": "0.00",
  "payment_method": "bank_transfer",
  "payment_state": "paid",
  "preorder_from": null,
  "shipping_total": "0.00",
  "source": "api",
  "status": "confirmed",
  "store": "sto_1234567890abcdef1234567890abcdef",
  "subtotal": "120.00",
  "tax_status": "standard",
  "tax_total": "20.00",
  "total": "120.00",
  "updated_at": "2026-10-16T10:00:00Z"
}

external_reference.id sizin sisteminizdeki sipariş numarasıdır; aynı bağlantıda (paneldeki API erişim kaydı) ikinci sipariş için kullanılamaz. Anahtarı döndürmek bu eşlemeyi değiştirmez; ayrı bağlantıların dış numaraları birbirinden bağımsızdır.

Kargolu siparişte delivery_method: "shipping", müşteri ve geçerli shipping_address gerekir; markanın paneldeki kargo koşulları uygulanır. Dijital üründe paneldeki fatura adresi koşulu geçerlidir.

3. Aynı isteği güvenle tekrarlayın

Bağlantı kesildiyse aynı dosyayı ve aynı tekrar anahtarını gönderin:

curl --fail-with-body --silent --show-error --include \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_TEKRAR_ANAHTARI" \
  -H 'Content-Type: application/json' \
  --data-binary @siparis.json

İkinci sipariş açılmaz: ilk yanıtın HTTP durumu ve Location başlığı korunur, Idempotent-Replayed: true eklenir, gövde siparişin güncel halidir. İlk işlem sürüyorsa 409 idempotency_in_progress gelir; kısa süre bekleyip aynı isteği tekrarlayın. Yeni iş veya düzeltilmiş istek için yeni tekrar anahtarı kullanın. Ayrıntılı tekrar kuralları uç sayfasında ve Hız sınırı ve tekrar kuralları sayfasındadır.

4. Siparişi ilerletin veya düzeltin

Aşağıdaki örneklerde jq kurulu olmalıdır; yeni sipariş kimliğini kaydedin:

export SIPARIS_ORDER_ID="$(jq -r '.id' siparis-yaniti.json)"
curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/$SIPARIS_ORDER_ID/processing" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_ORDER_ID-hazirla-1" \
  -H 'Content-Type: application/json' \
  --data '{"expected_status":"confirmed","reason":"Hazırlamaya başlandı."}'

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

{
  "channel": "whatsapp",
  "created_at": "2026-10-16T09:00:00Z",
  "currency": "TRY",
  "customer": null,
  "delivery_day": "2026-10-17",
  "delivery_method": "shipping",
  "discount_total": "0.00",
  "gift_wrap_fee": "0.00",
  "id": "ord_1234567890abcdef1234567890abcdef",
  "number": "48273910",
  "payment_fee": "0.00",
  "payment_method": "bank_transfer",
  "payment_state": "paid",
  "preorder_from": null,
  "shipping_total": "0.00",
  "source": "api",
  "status": "processing",
  "store": "sto_1234567890abcdef1234567890abcdef",
  "subtotal": "120.00",
  "tax_status": "standard",
  "tax_total": "20.00",
  "total": "120.00",
  "updated_at": "2026-10-16T10:00:00Z"
}

expected_status isteğe bağlıdır: sizin gördüğünüz durumdur. Bu arada değişmişse 409 status_mismatch gelir ve işlem yapılmaz. Diğer adımlar aynı biçimde çağrılır; her ucun özel alanları kendi sayfasındadır:

Adres, not, teslim günü ve kalemler PATCH /orders/{id} ile düzeltilir; durum PATCH ile değişmez. Son okuduğunuz ETag değerini tırnaklarıyla SIPARIS_ETAG değişkeninde saklayın:

curl --fail-with-body --silent --show-error --request PATCH \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/$SIPARIS_ORDER_ID" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_ORDER_ID-teslim-gunu-1" \
  -H "If-Match: $SIPARIS_ETAG" \
  -H 'Content-Type: application/json' \
  --data '{"delivery_day":"2026-10-17"}'

If-Match başlığına son yanıtın ETag değerini aynen yazın: sipariş siz okuduktan sonra değiştiyse 412 revision_mismatch gelir ve yazma yapılmaz. Siparişi yeniden okuyun, değişikliği değerlendirin ve yeni tekrar anahtarı kullanın. Başlık isteğe bağlıdır. Siparişin etiketi durum, para özeti, kalemler, adresler ve zaman damgaları değişince değişir; stok bakiyesi, alan izinleri ve include seçimi (yanıta alt kayıt ekleme) etiketi değiştirmez. Kalemleri değiştiren items, add_items ve restore_items alanları Siparişi düzelt sayfasındadır.

5. Siparişi iptal edin

Bu örneği sipariş teslim edilmeden, müşteri iptal istediğinde kullanın. İptal yerel para iadesi doğuruyorsa orders:write yanında money_out:write gerekir; tahsilatsız siparişte veya başka kanalda tahsil edilmiş satışta orders:write yeterlidir.

curl --fail-with-body --silent --show-error \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/$SIPARIS_ORDER_ID/cancel" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_ORDER_ID-iptal-1" \
  -H 'Content-Type: application/json' \
  --data '{"expected_status":"processing","reason":"Müşteri vazgeçti."}'

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

{
  "channel": "whatsapp",
  "created_at": "2026-10-16T09:00:00Z",
  "currency": "TRY",
  "customer": null,
  "delivery_day": "2026-10-17",
  "delivery_method": "shipping",
  "discount_total": "0.00",
  "gift_wrap_fee": "0.00",
  "id": "ord_1234567890abcdef1234567890abcdef",
  "number": "48273910",
  "payment_fee": "0.00",
  "payment_method": "bank_transfer",
  "payment_state": "paid",
  "preorder_from": null,
  "shipping_total": "0.00",
  "source": "api",
  "status": "cancelled",
  "store": "sto_1234567890abcdef1234567890abcdef",
  "subtotal": "120.00",
  "tax_status": "standard",
  "tax_total": "20.00",
  "total": "120.00",
  "updated_at": "2026-10-16T10:00:00Z"
}

İptal paneldeki kuralla çalışır: stok geri gelir, ödeme/iade kaydı ve kargo kısıtları korunur. Kargo iptali bekliyorsa sipariş hemen cancelled olmayabilir; yanıtı ve sonraki olayları izleyin. API iptal yanıtını “müşterinin kartına para ulaştı” olarak yorumlamayın; bağımsız iade için İade almak ve para iadesi rehberini kullanın.

6. Sık hatalar

Başarılı yazmalar normal sipariş olaylarını üretir: order.created, durum ilerleyince order.status_changed. Olay ve webhook kurulumu için Olay akışı ve Webhook rehberlerine geçin. Destek isterken request_id değerini paylaşın; anahtarınızı paylaşmayın.