Kargo
Kargo fiyatı sor
POST/v1/orders/{id}/shipments/quote
Gönderi açmadan önce açık kargo firmalarının fiyatını ve gönderim engellerini görün.
- 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 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. | |
boxes | liste: nesne (en çok 99 öğe) | Evet | Gerçek ölçülmüş koliler; toplam en çok 99 koli. | |
depth | sayı (en çok 1000) | Evet | Bir kolinin boyu, cm. | 20 |
height | sayı (en çok 1000) | Evet | Bir kolinin yüksekliği, cm. | 20 |
weight | sayı (en çok 10000) | Evet | Bir kolinin ağırlığı, kg. | 1 |
width | sayı (en çok 1000) | Evet | Bir kolinin eni, cm. | 20 |
count | tam sayı (en az 1; en çok 99) | Hayır | Aynı ölçüdeki koli sayısı. | 1 |
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
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'
{}
JSONimport 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
// 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);
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ı uygulayın.
Yanıt
200 İstek başarıyla tamamlandı.
İçerik türü: application/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ı (23)
| Alan | Tür | Zorunlu | Açıklama | Örnek |
|---|---|---|---|---|
boxes | liste: nesne | Evet | Hesapta kullanılan koliler; ağırlık kg, ölçüler cm. | |
depth | sayı (en çok 1000) | Evet | Bir kolinin boyu, cm. | 20 |
height | sayı (en çok 1000) | Evet | Bir kolinin yüksekliği, cm. | 20 |
weight | sayı (en çok 10000) | Evet | Bir kolinin ağırlığı, kg. | 1 |
width | sayı (en çok 1000) | Evet | Bir kolinin eni, cm. | 20 |
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. | |
available | true/false | Evet | Ücret, adres ve bakiye yönünden gönderim uygunsa true; açılışta yeniden denetlenir. | true |
cod_fee | metin · null olabilir | Evet | Ücrete dahil kapıda tahsilat bedeli, TRY; bilinmiyorsa null. | "29.90" |
code | metin | Evet | Gönderi açarken carrier alanına gönderilecek firma kodu. | "YURTICI" |
detail | metin · null olabilir | Evet | Engelin Türkçe açıklaması; yoksa null. | null |
fee | metin · null olabilir | Evet | Bu fiziksel gönderinin TRY ücreti; bilinen kapıda tahsilat bedeli dahil. null ise açılamaz. | "124.80" |
name | metin | Evet | Kargo firmasının adı. | "Yurtiçi Kargo" |
note | metin · null olabilir | Evet | Varsa kapıda ödeme bedeli uyarısı. | null |
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.