Kargoya vermek

API kökü https://api.siparis.app/v1. Fiyat sor → gönderi aç → etiketi indir → takip ve olayları izle → gerekiyorsa iptal et. İşletmenin BasitKargo hesabı bağlı, firma açık ve sipariş onaylanmış veya hazırlanıyor olmalıdır. Paneldeki Kargoya ver ile aynı bakiye, adres, koli ve kapıda ödeme kuralları uygulanır.

1. Bağlantıyı hazırlayın

İşletme ayarları > Geliştirici > Depo / kargo yazılımı şablonunu seçin. Sipariş altındaki liste ayrıca orders:read, olaylar events:read, maliyet alanları costs:read kapsamını (erişim iznini) ister. Marka sınırlı bağlantı yalnız o markanın siparişlerini görür; başka markanın kimliği 404 döner. İşletme bağlantısı bütün izinli markalarda çalışır.

Aşağıdaki değişkenlere kendi anahtarınızı ve sipariş listesinden aldığınız dış kimliği yazın. Anahtarı sohbete veya kaynak koduna koymayın.

export SIPARIS_API_URL="https://api.siparis.app/v1"
export SIPARIS_API_KEY="KENDI_API_ANAHTARINIZ"
export SIPARIS_ORDER_ID="ord_1234567890abcdef1234567890abcdef"

2. Fiyat sorun

Bu yan etkisiz POST isteği Idempotency-Key (tekrar anahtarı) istemez: bakiye düşmez, sipariş ve koli kaydı değişmez. Tutarlar TRY cinsinden ondalık metindir. İşletme başına 60 saniyede 20 fiyat sorgusu sınırı vardır ve bütün bağlantılar aynı sayacı paylaşır; farklı koli ölçüsü veya yeni anahtar bu sınırı yenilemez. Aşımda 429 quote_rate_limited gelir; gönderi açma bu sayaçtan etkilenmez.

curl --fail-with-body -sS -X POST \
  "$SIPARIS_API_URL/orders/$SIPARIS_ORDER_ID/shipments/quote" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

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

{
  "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
}

carriers açık firmaları verir; code gönderi açarken kullanılır, fee tahmini toplam ücrettir. available=false ise problem_code ve detail engeli açıklar. note varsa tahsilat bedeli henüz kesinleşmemiştir; maliyet sonradan değişebilir. Fiyat sorgusu bakiye ayırmaz, açılışta yeniden kontrol edilir. Yanıt alanlarının tamamı Kargo fiyatı sor sayfasındadır.

Ürün ölçüleri eksikse package_warning değerini kullanıcıya gösterin. Gerçek ölçüleri kullanmak için sorguya ve açılışa aynı package nesnesini gönderin (ölçüler cm, ağırlık koli başına kg):

{"package":{"boxes":[{"count":1,"width":20,"depth":30,"height":15,"weight":2}],"version":"FIYAT_YANITINDAKI_PACKAGE_VERSION"}}

version isteğe bağlıdır; verilirse arada değişen koli bilgisiyle açılış reddedilir. Sorguda verilen ölçüler kalıcı değildir; açılışta panelin koli düzeltme yolu kullanılır.

3. Gönderiyi açın

Fiyat yanıtından uygun firmanın kodunu seçin. Her yeni işte benzersiz tekrar anahtarı (aynı isteği güvenle yeniden göndermek için ürettiğiniz metin) üretin; ağ tekrarında bu değişkeni değiştirmeyin. Aşağıdaki komutlar python3 kullanır.

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

Bütün alanlar: Gönderi oluştur.

export SIPARIS_SHIPMENT_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"
export SIPARIS_CARRIER="YURTICI"
curl --fail-with-body -sS -D gonderi-basliklari.txt -o gonderi.json \
  -X POST "$SIPARIS_API_URL/orders/$SIPARIS_ORDER_ID/shipments" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_SHIPMENT_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"carrier\":\"$SIPARIS_CARRIER\"}"
export SIPARIS_SHIPMENT_ID="$(python3 -c 'import json; print(json.load(open("gonderi.json"))["id"])')"

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

{
  "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"
}

202 işin kaydedildiğini belirtir; status=pending henüz barkod oluşmadığı anlamındadır. Location gönderiyi izleme yoludur. İsteğe bağlı If-Match başlığında siparişin son ETag değerini (sürüm etiketi) gönderebilirsiniz; sipariş bu arada değiştiyse gönderi açılmaz.

Bağlantı kesilirse aynı anahtar ve aynı gövdeyle gönderi açma komutunu tekrar edin. Idempotent-Replayed: true gelirse iş yeniden çalışmamıştır; aynı gönderinin güncel hali gelir. İlk yanıt 202 ise tekrarda da 202 korunur; bu yüzden gövdedeki durumu okuyun. Belirsiz dış servis sonucunda aynı gönderi bekler; ikinci gönderi açılmaz. failed kesin başarısızlıkta error_code nedenini verir. Nedeni düzelttikten sonra yeni iş için yeni anahtar kullanın.

Birleştirmek için açılışa ve fiyat sorgusuna merge_orders içinde diğer siparişlerin ord_ kimliklerini ekleyin. Otomatik birleştirme yapılmaz. Aynı marka, alıcı, adres ve depo gerekir; kapıda nakit ile kapıda kart birlikte gönderilmez. Gönderici adresi siparişin deposudur; bu uçta başka gönderici adresi seçilmez. Ortak gönderide elle package verilemez; önce siparişlerin kolilerini panelde düzeltin.

Birleşik grubun gönderisi zaten açılmışsa yeni bir açılış isteği 409 shipment_not_allowed döner; güncel gönderiyi siparişin gönderi listesinden okuyun. API’deki ilk açılışın aynı tekrar anahtarıyla yinelenmesi ise aynı gönderiyi döndürmeye devam eder.

4. Hazır olmasını bekleyin ve etiketi indirin

curl --fail-with-body -sS \
  "$SIPARIS_API_URL/shipments/$SIPARIS_SHIPMENT_ID" \
  -H "Authorization: Bearer $SIPARIS_API_KEY"

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

{
  "carrier": "YURTICI",
  "cod_amount": "120.00",
  "collected_amount": null,
  "combined": true,
  "created_at": "2026-10-16T09:00:00Z",
  "currency": "TRY",
  "delivered_at": null,
  "id": "shp_1234567890abcdef1234567890abcdef",
  "shipping_fee": "0.00",
  "state": "ready",
  "status": "created",
  "updated_at": "2026-10-16T09:00:00Z"
}

pending ise birkaç saniye sonra yeniden okuyun. failed ise hatayı giderin; created olduğunda etiketi indirin. Etiket image/svg+xml döner; panelde gösterilen sağlayıcı SVG’si korunur. personal_data:read izni olmayan veya iptal edilmiş anahtar indiremez; etiketi ortak önbelleğe koymayın.

curl --fail-with-body -sS \
  "$SIPARIS_API_URL/shipments/$SIPARIS_SHIPMENT_ID/label" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -D etiket-basliklari.txt \
  -o kargo-etiketi.svg

Her koli ayrı SVG etiketidir; varsayılan page=1 ilk koliyi indirir. etiket-basliklari.txt içindeki X-Label-Pages toplam etiket sayısını verir; birden çok koli varsa kalan sayfaları da indirin. Örneğin ikinci koli için:

curl --fail-with-body -sS \
  "$SIPARIS_API_URL/shipments/$SIPARIS_SHIPMENT_ID/label?page=2" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -o kargo-etiketi-2.svg

Olmayan bir sayfa 404 not_found döner. Güvenlik başlıkları ve dosya adı Kargo etiketini indir sayfasındadır.

SVG dosyasını tarayıcıda açıp yazdırabilirsiniz. PDF gerekiyorsa kendi tarafınızda dönüştürün; örneğin bilgisayarınızda librsvg’nin rsvg-convert aracı kuruluysa:

rsvg-convert --format=pdf --output=kargo-etiketi.pdf kargo-etiketi.svg

5. Takip ve olaylar

Gönderi okuması barkod, takip numarası ve durumu verir; siparişin bütün gönderileri Siparişin gönderilerini listele ucundadır. Firma takip numarası hazır değilse barkodu takip numarası olarak göstermeyin. Entegrasyonunuzu kargo firmasının kodunu taşıyan status yerine firmadan bağımsız state (ör. ready, in_transit, delivered) ve kapıda ödemede cod_state alanına bağlayın; değerler Kodlar ve durumlar sayfasındadır.

curl --fail-with-body -sS --get "$SIPARIS_API_URL/events" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  --data-urlencode 'types=shipment.created,shipment.status_changed' \
  --data-urlencode 'limit=50'

shipment.created fiziksel gönderi oluşunca, shipment.status_changed açılış beklerken, başarısızlıkta ve sonraki durum değişikliklerinde gelir. Olayın changes alanında firmanın kodunun (status, cod_status) yanında firmadan bağımsız state ve cod_state de gelir. Olaydaki kaynak kimliğiyle güncel gönderiyi okuyun. Yanıttaki next_cursor değerini (sonraki okumanın yer imi) saklayın; devamı için olaylar, bildirim için webhook rehberini kullanın. Gönderi durumlarının anlamı Kodlar ve durumlar sayfasındadır.

6. Gerekirse iptal edin

Panelde iptal edilebilen, henüz kurye tarafından alınmamış gönderiler aynı kuralla iptal edilir. Açılışı bekleyen gönderide önce sonucu izleyin. Ortak gönderinin iptali bütün üye siparişlerin kargosunu iptal eder; siparişlerin kendisi iptal edilmez.

export SIPARIS_CANCEL_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body -sS -X POST \
  "$SIPARIS_API_URL/shipments/$SIPARIS_SHIPMENT_ID/cancel" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" \
  -H "Idempotency-Key: $SIPARIS_CANCEL_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

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

{
  "cancellation_status": "pending",
  "carrier": "YURTICI",
  "cod_amount": "120.00",
  "collected_amount": null,
  "combined": true,
  "created_at": "2026-10-16T09:00:00Z",
  "currency": "TRY",
  "delivered_at": null,
  "id": "shp_1234567890abcdef1234567890abcdef",
  "shipping_fee": "0.00",
  "state": "ready",
  "status": "created",
  "updated_at": "2026-10-16T09:00:00Z"
}

202 yanıtında cancellation_status ile iptal işini izleyin; pending veya unknown tamamlandı demek değildir. Sağlayıcı doğrulayınca status=cancelled olur. BasitKargo’nun paneldeki bakiye iadesi uygulanır; bu yanıt müşteriye para iadesi yapmaz. Zaten iptal edilmiş gönderiye yeni anahtarla iptal 200 döner, ikinci ücret/iade işlemi yapılmaz.

Bakiye ve kapıda ödeme

Bakiye BasitKargo panelinden yüklenir. Bakiye okunamazsa paneldeki gibi son denetim gönderi açılırken sağlayıcıda yapılır. Kapıda tahsil edilecek tutar siparişin ödeme yöntemi ve kalan borcundan hesaplanır; kapora düşülür, peşin ödenen tutar tekrar tahsil edilmez. Bu uçta tahsilat tutarı veya ödeme yöntemi değiştirilmez. Tahsilat bedelinin KDV durumu sağlayıcının bu fiyat yanıtında belirtilmemiştir; ayrıca KDV eklenmez. Kapıda ödeme ayarı ve firma desteği panelle aynıdır.

Sık hatalar

İlk 4xx iş hatası makbuza yazılır; düzeltilmiş yeni denemede yeni anahtar gerekir. Genel API hız sınırında 429 rate_limit_exceeded gelir; fiyat ve etiket istekleri 10’ar puandır.