İçeriğe geç
siparis.app geliştiriciAnahtarları yönet ↗

Kargo

Gönderi oluştur

POST/v1/orders/{id}/shipments

Siparişi kargoya verin: seçtiğiniz firmayla BasitKargo gönderisi açılır, ücret bakiyenizden düşer.

Gereken izin

Bearer anahtarı ve shipments:write

Yanıtı genişleten izin

personal_data:read, costs:read: yanıttaki ilgili alanları açar; izin yoksa bu alanlar atlanır, istek reddedilmez.

Maliyet

10 puan (bağlantı başına 60 saniyede 600 puan)

Tekrar anahtarı

Gerekir: Idempotency-Key başlığı.

İstek

Temel adres: https://api.siparis.app/v1

Yol parametreleri

AlanTürZorunluAçıklamaÖrnek
idmetinEvetOkunacak kaynağın ord_ önekli dış kimliği."ord_1234567890abcdef1234567890abcdef"

Başlıklar

AlanTürZorunluAçıklamaÖrnek
Idempotency-Keymetin · null olabilirEvetZorunlu tekrar anahtarı; en çok 200 karakter. Yeni işte yeni değer; ağ tekrarında aynı gövde ve aynı değer."ilk-esitleme-20261016-001"
If-Matchmetin · null olabilirHayırİsteğe bağlı önkoşul: son ETag değerini çift tırnaklarıyla gönderin. Komutun kilidi altında farklıysa 412 revision_mismatch."\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""

Gövde (application/json)

AlanTürZorunluAçıklamaÖrnek
carriermetin (en çok 40 karakter)EvetFiyat yanıtındaki açık kargo firmasının code değeri; standart gönderi hizmeti."YURTICI"
merge_ordersliste: metin (en çok 99 öğe)HayırAynı marka, alıcı, adres ve depodaki diğer ord_ siparişleri; birleştirme açık seçimdir.
packagenesne · null olabilirHayırYalnız bu sorgu için ölçüler; sorgu siparişi değiştirmez. Açarken aynı ölçüleri gönderin.
boxesliste: nesne (en çok 99 öğe)EvetGerçek ölçülmüş koliler; toplam en çok 99 koli.
depthsayı (en çok 1000)EvetBir kolinin boyu, cm.20
heightsayı (en çok 1000)EvetBir kolinin yüksekliği, cm.20
weightsayı (en çok 10000)EvetBir kolinin ağırlığı, kg.1
widthsayı (en çok 1000)EvetBir kolinin eni, cm.20
counttam sayı (en az 1; en çok 99)HayırAynı ölçüdeki koli sayısı.1
versionmetin (en çok 32 karakter) · null olabilirHayırFiyat 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" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ornek-post-v1-orders-ord-1234567890abcdef1234567890abcdef-shipments-001' \
  --data-binary @- <<'JSON'
{
  "carrier": "YURTICI"
}
JSON
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",
    "Idempotency-Key": "ornek-post-v1-orders-ord-1234567890abcdef1234567890abcdef-shipments-001",
}
request = Request(base + "/orders/ord_1234567890abcdef1234567890abcdef/shipments", headers=headers, method="POST",
    data="{\"carrier\":\"YURTICI\"}".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", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SIPARIS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "ornek-post-v1-orders-ord-1234567890abcdef1234567890abcdef-shipments-001",
  },
  redirect: "manual", // 307 hedefini Bearer olmadan ayrı istekte okuyun.
  signal: AbortSignal.timeout(30_000),
  body: JSON.stringify({
  "carrier": "YURTICI"
}),
});
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

202 Kargo işlemi kuyruğa alındı; gönderiyi Location ile izleyin.

İçerik türü: application/json

{
  "carrier": "YURTICI",
  "cod_amount": "120.00",
  "collected_amount": null,
  "combined": false,
  "created_at": "2026-10-16T09:00:00Z",
  "currency": "TRY",
  "delivered_at": null,
  "id": "shp_1234567890abcdef1234567890abcdef",
  "shipping_fee": "0.00",
  "state": "ready",
  "status": "pending",
  "updated_at": "2026-10-16T09:00:00Z"
}
Yanıt alanları (21)
AlanTürZorunluAçıklamaÖrnek
carriermetin · null olabilirEvetKargo firmasının kodu."YURTICI"
cod_amountmetin · null olabilirEvetKapıda tahsil edilecek tutar; sipariş alt kaynağında siparişin payı, tek gönderi okumasında fiziksel toplam; TRY cinsinden ondalık metin. Kuruş kaybını önlemek için ondalık sayı kütüphanesiyle işleyin."120.00"
collected_amountmetin · null olabilirEvetKargoda tahsil edilen tutar; sipariş alt kaynağında siparişin payı, tek gönderi okumasında fiziksel toplam; TRY cinsinden ondalık metin. Kuruş kaybını önlemek için ondalık sayı kütüphanesiyle işleyin."120.00"
combinedtrue/falseEvetGönderi birden fazla sipariş içeriyorsa true; sipariş alt kaynağı payı, tek gönderi okuması toplamı verir.false
created_attarih-saatEvetOluşturulma zamanı; RFC 3339 UTC."2026-10-16T09:00:00Z"
delivered_attarih-saat · null olabilirEvetTeslim zamanı; RFC 3339 UTC. Değer yoksa null."2026-10-16T09:00:00Z"
idmetinEvetKaynağın dış kimliği; shp_ ve 32 küçük onaltılık karakter. İç sayısal kimlik kullanılmaz."shp_1234567890abcdef1234567890abcdef"
shipping_feemetin · null olabilirEvetMüşteriden alınan kargo ücreti; sipariş alt kaynağında siparişin payı, tek gönderi okumasında fiziksel toplam; TRY cinsinden ondalık metin. Kuruş kaybını önlemek için ondalık sayı kütüphanesiyle işleyin."0.00"
statusmetin · null olabilirEvetKargo firmasının gönderi durumu; pending açılış sonucu bekleniyor, failed gönderi açılamadı. Firmadan bağımsız okumak için state. Değerler: pending, failed, created, NEW, READY_TO_SHIP, SHIPPED, OUT_FOR_DELIVERY, DELIVERED, COMPLETED, NEEDS_SUPPORT, DELAYED, RETURNING, RETURNED, LOST, DELETED, cancelled. Türkçe karşılıkları: https://developer.siparis.app/referans#gonderi-durumlari."created"
updated_attarih-saatEvetSon değişiklik zamanı; RFC 3339 UTC."2026-10-16T09:00:00Z"
barcodemetin · null olabilirHayırGönderi barkodu; personal_data:read gerekir.null
cancellation_statusmetin · null olabilirHayırİptal isteğinin pending, unknown, succeeded veya failed durumu; kargonun durumu kesin sonuçtan sonra değişir."pending"
cod_costmetin · null olabilirHayırKapıda ödeme maliyeti; costs:read gerekir; TRY cinsinden ondalık metin. Kuruş kaybını önlemek için ondalık sayı kütüphanesiyle işleyin."5.00"
cod_statemetin · null olabilirHayırKapıda ödeme tahsilatının kargo firmasından bağımsız ortak durumu; kapıda ödemesiz gönderide ve tanınmayan kodda null. Değerler: pending, collected, settled, settled_direct, not_collected. Türkçe karşılıkları: https://developer.siparis.app/referans#kapida-odeme-durumlari."collected"
cod_statusmetin · null olabilirHayırKapıda ödeme tahsilat durumu; cod_state ile aynı değer (önceki ad)."collected"
currencysabit "TRY"HayırPara birimi; v1 tutarları Türk lirasıdır."TRY"
error_codemetin · null olabilirHayırGönderi açılamadıysa kararlı hata kodu; yeni gönderi öncesi hatayı giderin.null
return_costmetin · null olabilirHayırDönüş kargo maliyeti; costs:read gerekir; TRY cinsinden ondalık metin. Kuruş kaybını önlemek için ondalık sayı kütüphanesiyle işleyin."0.00"
shipping_costmetin · null olabilirHayırKargo maliyeti; costs:read gerekir; TRY cinsinden ondalık metin. Kuruş kaybını önlemek için ondalık sayı kütüphanesiyle işleyin."40.00"
statemetin · null olabilirHayırGönderinin kargo firmasından bağımsız ortak durumu; açılış beklerken (status pending), açılamadıysa (failed) ve firmanın tanınmayan kodunda null. Değerler: draft, ready, in_transit, delivered, returning, returned, lost, cancelled. Türkçe karşılıkları: https://developer.siparis.app/referans#gonderi-ortak-durumlari."ready"
tracking_codemetin · null olabilirHayırKargo takip kodu; personal_data:read gerekir."TEST-TAKIP-001"

Bu uca özgü yanıt başlıkları: ETag (Gönderinin API görünümünden hesaplanan güçlü sürüm etiketi; iptalin If-Match başlığında kullanın.); Location (Gönderiyi izleme yolu.).

Hatalar

HTTPcodeAnlamıNasıl düzelir?
403forbiddenMevcut ticari kural bu işlemi yapmanıza izin vermiyor.Gerekli kapsamları ve siparişin durumunu kontrol edin.
409shipment_not_allowedGö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.
400shipping_balance_insufficientKargo bakiyesi yetersiz.BasitKargo bakiyesini yükleyin; yeni tekrar anahtarıyla deneyin.
400shipping_address_invalidAlıcı adresi eksik veya geçersiz.Siparişin il, ilçe, mahalle ve açık adresini düzeltin; yeni tekrar anahtarı kullanın.
400shipping_carrier_disabledKargo firması kapalı veya seçilemez.Fiyat yanıtındaki açık firma kodunu seçin.
400shipping_cod_unavailableKapıda ödeme bu hesapta veya firmada kullanılamıyor.BasitKargo kapıda ödeme ayarlarını ve siparişin ödeme yöntemini kontrol edin.
400shipping_quote_unavailableBu paket ve ödeme yöntemi için ücret bulunamadı.Koli ölçülerini ve firma seçimini kontrol edin.
409shipping_not_connectedBasitKargo hesabı bağlı değil.İşletme ayarları > Kargo’dan hesabı bağlayın.
429shipping_rate_limitedKargo 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.
503shipping_unavailableKargo hizmetine şu an ulaşılamıyor.Retry-After saniye bekleyin; aynı anahtar/gövdeyle tekrar edin.
400invalid_if_matchIf-Match geçerli bir güçlü ETag değil.GET kaynak yanıtındaki ETag değerini çift tırnaklarıyla aynen kullanın.
412revision_mismatchKayıt siz okuduktan sonra değişmiş.Güncel kaydı okuyun; düzeltmeyi yeniden değerlendirip yeni tekrar anahtarıyla gönderin.

Ortak hatalar (anahtar, izin, istek biçimi, hız sınırı, tekrar anahtarı) her uçta aynıdır: Hata kodları › Ortak hatalar.