# Kargo etiketini indir

`GET /v1/shipments/{id}/label` · Grup: Kargo

Koliye yapıştırılacak kargo etiketini SVG olarak indirin.

> **Bilmeniz gerekenler:** Panelle aynı image/svg+xml etiketi döner; her koli ayrı SVG’dir. page varsayılan 1, X-Label-Pages toplam etiket sayısıdır; diğer koliler için page artırılır. Olmayan sayfa 404 döner. shipments:read ve personal_data:read birlikte zorunludur. Her indirmede güncel marka, kapsam ve gönderi durumu yeniden denetlenir; Cache-Control: no-store. Etiket dosya eki olarak, nosniff ve betik/dış kaynakları engelleyen CSP sandbox başlıklarıyla sunulur. Etiket hazır değilse veya gönderi iptalse 409 gelir. İndirme 10 hız sınırı puanı tüketir.

- **Gereken izin:** Bearer anahtarı ve `shipments:read`, `personal_data:read`
- **Maliyet:** 10 puan (bağlantı başına 60 saniyede 600 puan)
- **Tekrar anahtarı:** Gerekmez (okuma).

## İstek

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

### Yol parametreleri

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

### Sorgu parametreleri

| Alan | Tür | Zorunlu | Açıklama | Örnek |
| --- | --- | --- | --- | --- |
| `page` | tam sayı (en az 1) | Hayır | Etiket sayfası; ilk koli 1. Toplam sayfa sayısı X-Label-Pages başlığında. | `1` |

## Ö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 GET \
  "${SIPARIS_API_URL:-https://api.siparis.app/v1}/shipments/shp_1234567890abcdef1234567890abcdef/label" \
  -H "Authorization: Bearer $SIPARIS_API_KEY" --output kargo-etiketi.svg
```


### Python


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

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")
request = Request(base + "/shipments/shp_1234567890abcdef1234567890abcdef/label", headers={
    "Authorization": "Bearer " + os.environ["SIPARIS_API_KEY"]
})
opener = build_opener(NoRedirect)
try:
    response = opener.open(request, timeout=30)
except HTTPError as error:
    if error.code != 307 or not error.headers.get("Location"):
        raise
    # İmzalı hedefe API anahtarı gönderilmez; ikinci yönlendirme izlenmez.
    response = opener.open(Request(error.headers["Location"]), timeout=30)
with response:
    shutil.copyfileobj(response, sys.stdout.buffer)
# Dosyaya yazmak için: python indir.py > kargo-etiketi.svg
```


### TypeScript


```typescript
// Node.js 22+; dosyayı belleğe almak yerine stdout'a aktarır.
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import type { ReadableStream } from "node:stream/web";

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");
let response = await fetch(base + "/shipments/shp_1234567890abcdef1234567890abcdef/label", {
  headers: { Authorization: `Bearer ${process.env.SIPARIS_API_KEY}` },
  redirect: "manual", signal: AbortSignal.timeout(60_000),
});
if (response.status === 307) {
  const location = response.headers.get("Location");
  if (!location) throw new Error("İndirme adresi eksik");
  // Ayrı istek: Authorization başlığı eklenmez.
  response = await fetch(location, { redirect: "error", credentials: "omit", signal: AbortSignal.timeout(60_000) });
}
if (!response.ok || !response.body) throw new Error(`İndirme başarısız: ${response.status}`);
await pipeline(Readable.fromWeb(response.body as ReadableStream), process.stdout);
```


## Yanıt

### 200 · Seçilen kolinin SVG etiketi; toplam etiket sayısı X-Label-Pages başlığındadır.

İçerik türü: `image/svg+xml`.


```text
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 600"><text x="20" y="40">Kargo etiketi</text></svg>
```


Bu uca özgü yanıt başlıkları: `Cache-Control` (Kişisel etiket önbelleklenmez.); `Content-Disposition` (Seçilen kolinin SVG etiketi dosya olarak indirilir.); `Content-Security-Policy` (SVG betikleri ve dış kaynakları tarayıcıda engellenir.); `X-Content-Type-Options` (Tarayıcı içerik türünü tahmin etmez.); `X-Label-Pages` (Gönderinin toplam etiket sayfası sayısı; her koli ayrı SVG. Diğer sayfalar için page kullanın.).

## Hatalar

| HTTP | code | Anlamı | Nasıl düzelir? |
| --- | --- | --- | --- |
| 409 | `shipping_not_connected` | BasitKargo hesabı bağlı değil. | İşletme ayarları > Kargo’dan hesabı bağlayın. |
| 409 | `shipment_label_not_ready` | Etiket hazır değil veya gönderi iptal edilmiş. | Gönderinin açılışının tamamlanmasını bekleyin. |
| 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. |
| 502 | `shipping_provider_error` | Kargo etiketi alınamadı veya yanıtta SVG etiketi bulunamadı. | Bir süre sonra aynı gönderinin etiketini yeniden indirin. |

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).