# Sipariş eklemek ve ilerletmek

> **Ne yaparsınız:** Kendi sitenizden, ERP’nizden veya başka bir yazılımdan sipariş açar; sonra onaylar, hazırlar, teslim eder, düzeltir ya da iptal edersiniz.
> **Hangi uçlar:** [Sipariş oluştur](https://developer.siparis.app/uc/siparis-olustur), [Siparişi onayla](https://developer.siparis.app/uc/siparisi-onayla), [Siparişi hazırlamaya başla](https://developer.siparis.app/uc/siparisi-hazirlamaya-basla), [Teslim almaya hazır işaretle](https://developer.siparis.app/uc/teslim-almaya-hazir-isaretle), [Siparişi teslim et](https://developer.siparis.app/uc/siparisi-teslim-et), [Alınan ödemeyi kaydet](https://developer.siparis.app/uc/alinan-odemeyi-kaydet), [Sipariş durumunu düzelt](https://developer.siparis.app/uc/siparis-durumunu-duzelt), [Siparişi düzelt](https://developer.siparis.app/uc/siparisi-duzelt), [Siparişi iptal et](https://developer.siparis.app/uc/siparisi-iptal-et)
> **Gereken izin:** `orders:write`; müşteri ve adres için ayrıca `personal_data:write`, para iadesi doğuran iptal veya düzeltmede `money_out:write`.

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](https://siparis.app/panel/developer) 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:

| Yapacağınız iş | Gereken kapsam |
| --- | --- |
| Sipariş açmak, düzeltmek, hazırlamak ve teslim etmek | `orders:write` |
| Müşteri veya adres göndermek | Ayrıca `personal_data:write` |
| İç not yazmak | Ayrıca `internal_notes:write` |
| Yerel para iadesi doğuran iptal, durum veya kalem düzeltmesi | Ayrıca `money_out:write` |
| Siparişi sonradan GET ile okumak | `orders:read` |
| Yanıtta müşteri/adres görmek | Ayrıca `personal_data:read` |
| Seçenek kimliğini API’den bulmak | `products:read` |

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:

```bash
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](https://developer.siparis.app/uc/siparis-olustur) 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):

| Alan | Tür | Açıklama | Örnek |
| --- | --- | --- | --- |
| `delivery_method` | metin (seçenekler: shipping, hand, pickup, digital) | shipping: kargo; hand: elden; pickup: markadan teslim; digital: dijital teslim. | `"hand"` |
| `items` | liste: nesne (en çok 100 öğe) | Satılacak seçenekler ve miktarları. |  |
| `items[].quantity` | sayı (en çok 100000) veya metin | Miktar; en çok üç ondalık hane. Adetle satılan üründe tam sayı gerekir. | `"2"` |

Bütün alanlar: [Sipariş oluştur](https://developer.siparis.app/uc/siparis-olustur).

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

```json
{
  "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:

```bash
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ı](https://developer.siparis.app/hiz-siniri) sayfasındadır.

## 4. Siparişi ilerletin veya düzeltin

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

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

```json
{
  "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:

| İş | Uç | Dikkat |
| --- | --- | --- |
| Bekleyen siparişi onaylamak | [Siparişi onayla](https://developer.siparis.app/uc/siparisi-onayla) | Ödeme alındı kaydı oluşturmaz. |
| Hazırlamaya başlamak | [Siparişi hazırlamaya başla](https://developer.siparis.app/uc/siparisi-hazirlamaya-basla) | İsteğe bağlı `expected_status`. |
| Markadan teslim için hazır bilgisi | [Teslim almaya hazır işaretle](https://developer.siparis.app/uc/teslim-almaya-hazir-isaretle) | Müşteriye haber verdikten sonra `notified: true`; bu uç mesaj göndermez. |
| Teslim etmek | [Siparişi teslim et](https://developer.siparis.app/uc/siparisi-teslim-et) | Kalan ödeme varsa `collection_method`: `cash`, `pos`, `bank` veya marka izin veriyorsa `later`. |
| Ödeme alındığını kaydetmek | [Alınan ödemeyi kaydet](https://developer.siparis.app/uc/alinan-odemeyi-kaydet) | `parts` ve gördüğünüz kalan tutar `expected_due`. |
| Yanlış durumu düzeltmek | [Sipariş durumunu düzelt](https://developer.siparis.app/uc/siparis-durumunu-duzelt) | Zorunlu `reason`; para iadesi doğuyorsa ayrıca `money_out:write`. |

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:

```bash
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](https://developer.siparis.app/uc/siparisi-duzelt) 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.

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

```json
{
  "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](https://developer.siparis.app/iade-yapmak) rehberini kullanın.

## 6. Sık hatalar

| Kod | Ne yapmalıyım? |
| --- | --- |
| `422 store_required` | Çok markada gövdeye `store` ekleyin. |
| `400 insufficient_stock` | Adedi azaltın; gerçekten bekleyen satış istiyorsanız panel kuralıyla `allow_waiting: true` gönderin. |
| `409 duplicate_external_reference` | `existing_order` önceki siparişin kimliğidir; onu kullanın. |
| `412 revision_mismatch` / `409 status_mismatch` | Güncel siparişi okuyup yeni bilgilerle yeniden değerlendirin. |
| `409 refund_confirm` | Kalem düzeltmesi para döndürüyor; tutarı kontrol edip `refund_amount` ve yeni tekrar anahtarıyla gönderin. |
| `400 invalid_request` / `409 conflict` | `detail` alanındaki panel iş kuralını kontrol edin. |

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