# Kargo fiyatı sor

`POST /v1/orders/{id}/shipments/quote` · Grup: Kargo

Gönderi açmadan önce açık kargo firmalarının fiyatını ve gönderim engellerini görün.

> **Bilmeniz gerekenler:** Yan etkisiz POST: Idempotency-Key gerekmez; bakiye düşmez, sipariş ve koli bilgileri değişmez. Her sorgu 10 hız sınırı puanı tüketir; ayrıca işletmenin bütün bağlantı ve markaları için ortak 60 saniyede 20 fiyat sorgusu sınırı vardır. Aşımda 429 quote_rate_limited ve Retry-After saniye gelir. Gönderi açma bu sayacı tüketmez. Bakiye en çok 60 saniyelik önbellekten okunur; açılışta taze denetlenir. Kapıda ödeme ve kapora siparişten hesaplanır.

- **Gereken izin:** Bearer anahtarı ve `shipments:write`
- **Maliyet:** 10 puan (bağlantı başına 60 saniyede 600 puan)
- **Tekrar anahtarı:** Gerekmez; istek hiçbir şeyi değiştirmez.

## İstek

Temel adres: `https://api.siparis.app/v1`. Yol: `/v1/orders/{id}/shipments/quote`.

### Yol parametreleri

| Alan | Tür | Zorunlu | Açıklama | Örnek |
| --- | --- | --- | --- | --- |
| `id` | metin | Evet | Okunacak kaynağın ord_ önekli dış kimliği. | `"ord_1234567890abcdef1234567890abcdef"` |

### Gövde (application/json)

| Alan | Tür | Zorunlu | Açıklama | Örnek |
| --- | --- | --- | --- | --- |
| `merge_orders` | liste: metin (en çok 99 öğe) | Hayır | Aynı marka, alıcı, adres ve depodaki diğer ord_ siparişleri; birleştirme açık seçimdir. |  |
| `package` | nesne · null olabilir | Hayır | Yalnız bu sorgu için ölçüler; sorgu siparişi değiştirmez. Açarken aynı ölçüleri gönderin. |  |
| `package.boxes` | liste: nesne (en çok 99 öğe) | Evet | Gerçek ölçülmüş koliler; toplam en çok 99 koli. |  |
| `package.boxes[].depth` | sayı (en çok 1000) | Evet | Bir kolinin boyu, cm. | `20` |
| `package.boxes[].height` | sayı (en çok 1000) | Evet | Bir kolinin yüksekliği, cm. | `20` |
| `package.boxes[].weight` | sayı (en çok 10000) | Evet | Bir kolinin ağırlığı, kg. | `1` |
| `package.boxes[].width` | sayı (en çok 1000) | Evet | Bir kolinin eni, cm. | `20` |
| `package.boxes[].count` | tam sayı (en az 1; en çok 99) | Hayır | Aynı ölçüdeki koli sayısı. | `1` |
| `package.version` | metin (en çok 32 karakter) · null olabilir | Hayır | Fiyat yanıtındaki package_version; verilirse değişen koli bilgisi reddedilir. | `"0123456789abcdef"` |

## Örnek istek

Kimlik içeren yollarda örnek kimliği kendi liste yanıtınızdan alın. `SIPARIS_API_KEY` sunucu ortamında tanımlı olmalı; yerelde `SIPARIS_API_URL` ile /v1 içeren adresi değiştirin. Üretimde [tekrar kurallarını](https://developer.siparis.app/hiz-siniri) uygulayın.

### curl


```bash
curl --fail-with-body --silent --show-error --request POST \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/orders/ord_1234567890abcdef1234567890abcdef/shipments/quote" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{}
JSON
```


### Python


```python
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
from urllib.error import HTTPError

# İmzalı indirme hedefine Bearer taşımamak için yönlendirme kendiliğinden izlenmez.
class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

base = os.environ.get("SIPARIS_API_URL", "https://api.siparis.app/v1")
headers = {
    "Authorization": "Bearer " + os.environ["SIPARIS_API_KEY"],
    "Content-Type": "application/json",
}
request = Request(base + "/orders/ord_1234567890abcdef1234567890abcdef/shipments/quote", headers=headers, method="POST",
    data="{}".encode("utf-8"))
try:
    with build_opener(NoRedirect).open(request, timeout=30) as response:
        print(response.read().decode("utf-8"))
except HTTPError as error:
    print(error.code, error.read().decode("utf-8"))
    raise
```


### TypeScript


```typescript
// Node.js 22+; anahtar yalnız sunucunun ortam değişkenindedir.
const base = process.env.SIPARIS_API_URL ?? "https://api.siparis.app/v1";
if (!process.env.SIPARIS_API_KEY) throw new Error("SIPARIS_API_KEY gerekli");
const response = await fetch(base + "/orders/ord_1234567890abcdef1234567890abcdef/shipments/quote", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SIPARIS_API_KEY}`,
    "Content-Type": "application/json",
  },
  redirect: "manual", // 307 hedefini Bearer olmadan ayrı istekte okuyun.
  signal: AbortSignal.timeout(30_000),
  body: JSON.stringify({}),
});
const text = await response.text();
if (!response.ok) throw new Error(`${response.status}: ${text}`);
console.log(text);
```


## Yanıt

### 200 · İstek başarıyla tamamlandı.

İçerik türü: `application/json`.


```json
{
  "boxes": [
    {
      "depth": 20,
      "height": 20,
      "weight": 1,
      "width": 20
    }
  ],
  "carriers": [
    {
      "available": true,
      "cod_fee": "29.90",
      "code": "YURTICI",
      "detail": null,
      "fee": "124.80",
      "name": "Yurtiçi Kargo",
      "note": null,
      "problem_code": null
    }
  ],
  "cod_amount": "120.00",
  "cod_type": "cash",
  "default_carrier": "YURTICI",
  "order": "ord_1234567890abcdef1234567890abcdef",
  "package_version": "0123456789abcdef",
  "package_warning": null,
  "payment_warning": null
}
```

Yanıt alanları:

| Alan | Tür | Zorunlu | Açıklama | Örnek |
| --- | --- | --- | --- | --- |
| `boxes` | liste: nesne | Evet | Hesapta kullanılan koliler; ağırlık kg, ölçüler cm. |  |
| `boxes[].depth` | sayı (en çok 1000) | Evet | Bir kolinin boyu, cm. | `20` |
| `boxes[].height` | sayı (en çok 1000) | Evet | Bir kolinin yüksekliği, cm. | `20` |
| `boxes[].weight` | sayı (en çok 10000) | Evet | Bir kolinin ağırlığı, kg. | `1` |
| `boxes[].width` | sayı (en çok 1000) | Evet | Bir kolinin eni, cm. | `20` |
| `boxes[].count` | tam sayı (en az 1; en çok 99) | Hayır | Aynı ölçüdeki koli sayısı. | `1` |
| `carriers` | liste: nesne | Evet | Panelin açık firma seçenekleri ve ücretleri. |  |
| `carriers[].available` | true/false | Evet | Ücret, adres ve bakiye yönünden gönderim uygunsa true; açılışta yeniden denetlenir. | `true` |
| `carriers[].cod_fee` | metin · null olabilir | Evet | Ücrete dahil kapıda tahsilat bedeli, TRY; bilinmiyorsa null. | `"29.90"` |
| `carriers[].code` | metin | Evet | Gönderi açarken carrier alanına gönderilecek firma kodu. | `"YURTICI"` |
| `carriers[].detail` | metin · null olabilir | Evet | Engelin Türkçe açıklaması; yoksa null. | `null` |
| `carriers[].fee` | metin · null olabilir | Evet | Bu fiziksel gönderinin TRY ücreti; bilinen kapıda tahsilat bedeli dahil. null ise açılamaz. | `"124.80"` |
| `carriers[].name` | metin | Evet | Kargo firmasının adı. | `"Yurtiçi Kargo"` |
| `carriers[].note` | metin · null olabilir | Evet | Varsa kapıda ödeme bedeli uyarısı. | `null` |
| `carriers[].problem_code` | metin · null olabilir | Evet | Gönderim engelinin kararlı kodu; yoksa null. | `null` |
| `cod_amount` | metin · null olabilir | Evet | Kurye tarafından tahsil edilecek TRY tutarı; kapora düşülür, ortak gönderide üyelerin kalanları toplanır. | `"120.00"` |
| `cod_type` | metin (seçenekler: cash, card) · null olabilir | Evet | Kapıda nakit veya kart; kapıda ödeme yoksa null. | `"cash"` |
| `default_carrier` | metin · null olabilir | Evet | Panelin varsayılan firma kodu. | `"YURTICI"` |
| `order` | metin | Evet | Fiyat sorulan ord_ siparişi. | `"ord_1234567890abcdef1234567890abcdef"` |
| `package_version` | metin | Evet | Kalıcı koli düzeltmesinde kullanılabilecek görülen sürüm. | `"0123456789abcdef"` |
| `package_warning` | metin · null olabilir | Evet | Ölçüsü eksik ürünler için panelin uyarısı. | `null` |
| `payment_warning` | metin · null olabilir | Evet | Kapıda ödeme dışındaki kalan ödeme uyarısı. | `null` |
| `currency` | sabit "TRY" | Hayır | Ücretlerin para birimi. | `"TRY"` |

## Hatalar

| HTTP | code | Anlamı | Nasıl düzelir? |
| --- | --- | --- | --- |
| 403 | `forbidden` | Mevcut ticari kural bu işlemi yapmanıza izin vermiyor. | Gerekli kapsamları ve siparişin durumunu kontrol edin. |
| 409 | `shipment_not_allowed` | Gönderinin veya siparişin durumu bu işleme uygun değil. | Güncel gönderiyi ve siparişi okuyun; bekleyen işlemin sonuçlanmasını izleyin. |
| 400 | `shipping_balance_insufficient` | Kargo bakiyesi yetersiz. | BasitKargo bakiyesini yükleyin; yeni tekrar anahtarıyla deneyin. |
| 400 | `shipping_address_invalid` | Alıcı adresi eksik veya geçersiz. | Siparişin il, ilçe, mahalle ve açık adresini düzeltin; yeni tekrar anahtarı kullanın. |
| 400 | `shipping_carrier_disabled` | Kargo firması kapalı veya seçilemez. | Fiyat yanıtındaki açık firma kodunu seçin. |
| 400 | `shipping_cod_unavailable` | Kapıda ödeme bu hesapta veya firmada kullanılamıyor. | BasitKargo kapıda ödeme ayarlarını ve siparişin ödeme yöntemini kontrol edin. |
| 400 | `shipping_quote_unavailable` | Bu paket ve ödeme yöntemi için ücret bulunamadı. | Koli ölçülerini ve firma seçimini kontrol edin. |
| 409 | `shipping_not_connected` | BasitKargo hesabı bağlı değil. | İşletme ayarları > Kargo’dan hesabı bağlayın. |
| 429 | `shipping_rate_limited` | Kargo sağlayıcısının istek sınırına ulaşıldı. | Retry-After saniye bekleyin; gönderi açılışında aynı anahtarı koruyun. |
| 503 | `shipping_unavailable` | Kargo hizmetine şu an ulaşılamıyor. | Retry-After saniye bekleyin; aynı anahtar/gövdeyle tekrar edin. |
| 429 | `quote_rate_limited` | İşletmenin kargo fiyatı sorgulama sınırına ulaşıldı. | Retry-After saniye bekleyin; 60 saniyede 20 sorgu bütün bağlantı ve markalarda ortaktır. Gönderi açma bu sayaçtan etkilenmez. |

Ortak hatalar (anahtar, izin, istek biçimi, hız sınırı, tekrar anahtarı) her uçta aynıdır: [Hata kodları › Ortak hatalar](https://developer.siparis.app/hatalar#ortak-hatalar).