yigitfy API

Başlarken

API belirtecini panelden alırsın: https://dashboard.yigitfy.com → Ayarlar → API Erişimi → Yeni belirteç. Belirteç yalnızca bir kez gösterilir; kaybedersen yenisini üretmen gerekir.

İlk istek

curl -H "Authorization: Bearer yf_live_..." \
     "https://api.yigitfy.com/v1/me"

Kimlik doğrulama

Her istekte Authorization: Bearer <belirteç> başlığı gerekir. Panel oturum çerezi kabul edilmez. Belirteç yf_live_ ile başlar; bu önek sızıntı taraması ve günlükte tanımlama içindir, sırrın kendisi değildir.

Kapsamlar

Her belirteç yalnızca kendisine verilen kapsamlarda çalışır. x:yaz seçtiğinde x:oku kendiliğinden eklenir. Yetersiz kapsamda uç 403 insufficient_scope döner.

Uçlar

Sayfalama

Liste uçları tek bir sözleşme kullanır:

{
  "data": [ ... ],
  "hasMore": true,
  "nextCursor": "djE6eyJrIjoi..."
}

Sonraki sayfa için ?cursor=<nextCursor> gönder. İmleç opaktır — içeriğini ayrıştırma, olduğu gibi geri gönder. limit varsayılan 50, tavan 200 (ürünlerde 100). Sayfa numarası yoktur: Shopify imleçleri yalnız "sonraki"yi bilir, sayfa numarası vaat etmek her istekte baştan yürümek demekti.

Hatalar

Tüm hatalar makine okunabilir bir zarfla döner:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Bu uç 'etiket:yaz' kapsamı gerektiriyor.",
    "field": "orderIds",
    "requestId": "a1b2c3d4e5f60718"
  }
}

Hız limitleri

Belirteç başına, yaklaşık: normal uçlar 120/dakika, ağır uçlar (etiket basımı, rapor, PDF) 6/dakika. Yanıtlarda X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları gelir; 429 aldığında Retry-After saniye bekle.

Tekrar koruması (Idempotency)

Yazma uçlarında Idempotency-Key başlığı zorunludur. İstek başına benzersiz bir değer üret (örneğin UUID) ve aynı isteği yeniden denerken aynı anahtarı gönder.

• Aynı anahtar + aynı gövde → ilk yanıt aynen döner (Idempotency-Replayed: true), iş tekrar yapılmaz.
• Aynı anahtar + farklı gövde → 409 idempotency_conflict.
• İş hâlâ sürüyorsa → 409 idempotency_in_progress.
• Kayıtlar 24 saat saklanır.

Örnek akış: ERP'den sipariş çek, etiket bastır

import requests, uuid, time

KOK = "https://api.yigitfy.com/v1"
BAS = {"Authorization": "Bearer yf_live_..."}

# 1) Mağazayı bul
magaza = requests.get(f"{KOK}/stores", headers=BAS).json()["data"][0]

# 2) Basılmamış siparişleri çek (imleçle sayfala)
siparisler, imlec = [], None
while True:
    p = {"storeId": magaza["id"], "status": "unfulfilled", "limit": 100}
    if imlec:
        p["cursor"] = imlec
    y = requests.get(f"{KOK}/orders", headers=BAS, params=p).json()
    siparisler += [o for o in y["data"] if not o["printedAt"]]
    imlec = y["nextCursor"]
    if not imlec:
        break

# 3) Etiket işi başlat (ASENKRON — 202 döner)
is_ = requests.post(f"{KOK}/label-jobs", headers={**BAS,
        "Idempotency-Key": str(uuid.uuid4())},
        json={"storeId": magaza["id"],
              "orderIds": [o["id"] for o in siparisler[:50]]}).json()

# 4) Bitmesini bekle (uzun yoklama: sunucu 30 sn'ye kadar tutar)
while True:
    d = requests.get(f"{KOK}/label-jobs/{is_['jobId']}",
                     headers=BAS, params={"wait": 30}).json()
    if d["status"] != "calisiyor":
        break
# 'bitti' olsa da kargo firmasında gönderi açılamayan sipariş PARTİDEN DÜŞER:
# d["dropped"] = [{orderId, orderName, reason}], d["printedCount"] = partide kalan.
# printedCount 0 ise PDF isteği 404 batch_empty döner — düşenleri kullanıcıya göster.
for dus in d.get("dropped") or []:
    print("basılamadı:", dus["orderName"], dus["reason"])

# 5) Etiketleri PDF olarak indir
pdf = requests.get(f"{KOK}/label-batches/{is_['batchId']}/pdf",
                   headers=BAS, params={"storeId": magaza["id"]}).content
open("etiketler.pdf", "wb").write(pdf)

# 6) Takip numaralarını ERP'ye yaz
for o in siparisler[:50]:
    g = requests.get(f"{KOK}/shipments/{o['id']}", headers=BAS,
                     params={"storeId": magaza["id"]}).json()
    print(o["name"], g["trackingNumber"], g["trackingUrl"])

Etiket türü ve ortak barkod

POST /v1/label-jobs gövdesinde iki isteğe bağlı alan var:

• commonBarcode (true / false / yok): MNG'de gerçek gönderi barkodu üretilsin mi. Gönderilmezse mağaza ayarı geçerlidir (GET /v1/label-settings → mng.commonBarcode). Açıkça gönderilen değer, paneldeki gibi mağaza ayarına da yazılır. true iken tek etiket 30-60 saniye sürebilir; false beklemeden referans etiketi basar, şube okutup gönderiye çevirir. Sürat'ı etkilemez.
• labelType (boş / panel / kargo): yalnız doğrulanır, iş kaydında saklanmaz. Etiket türü PDF indirilirken seçilir: GET /v1/label-batches/{id}/pdf?labelType=kargo taşıyıcının kendi (ZPL) etiketini verir, boş ya da panel yigitfy'nin 100x100 etiketini. Aynı parti iki türde de indirilebilir.

Partiyi geri alma

POST /v1/label-batches/{id}/undo (etiket:yaz, Idempotency-Key zorunlu). Gövde:

{"storeId": 1, "cancelFulfillment": true, "cancelShipments": false}

• cancelShipments: false — paneldeki "geri al" ile aynı: 'yazdırıldı' işaretleri kalkar, parti kapanır, cancelFulfillment açıksa Shopify kargo kayıtları iptal edilir. Taşıyıcıdaki gönderiye dokunulmaz (barkod açık kalır; yeniden basım aynı barkodu kullanmaz).
• cancelShipments: true — partideki her sipariş için sırayla: taşıyıcıda iptal (MNG ya da Sürat, kaydın taşıyıcısına göre), Shopify kargo kaydı iptali, 'yazdırıldı' kaldırma ve gönderi kaydının silinmesi. Şubede okutulmuş / yoldaki paket geri çağrılamaz: o sipariş skipped'a düşer ve basılmış kalır; parti ancak içinde sipariş kalmayınca kapanır (batchUndone). Taşıyıcı reddederse sipariş errors'a düşer, hiçbir şey silinmez; aynı anahtarla yeniden denenebilir.

{
  "restored": 12, "cancelledFulfillments": 12, "cancelledShipments": 11,
  "skipped": [{"orderId": "gid://shopify/Order/9", "reason": "Bu gönderi şubede okutulmuş, paket yolda — ..."}],
  "errors": [], "batchUndone": false
}

Zaman aşımı ve yeniden deneme

• İstemci zaman aşımını ≥ 60 saniye yap; Shopify hız sınırına takıldığında sunucu 30 saniyeye kadar bekleyebilir.
• 429 ve 502'de üstel geri çekilme + rastgele sapma (jitter) kullan.
• Yazma isteğini yeniden denerken aynı Idempotency-Key değerini gönder.
• Basım işi 300 saniye hiç nabız atmazsa hata durumuna düşer.

Bu sürümde olmayanlar

• Giden webhook (olay bildirimi) yok — değişiklikleri yoklama ile takip et. Sonraki sürümde planlanıyor.
• Trendyol entegrasyonu askıda (18 Eyl 2026): yeni Trendyol mağazası bağlanamaz; bugün yalnız Shopify mağazaları desteklenir.
• Stok, tedarik, ret riski ve vergi uçları henüz açık değil.
• Taşıyıcı kimlik bilgileri, ekip yönetimi, abonelik, AI anahtarları ve yönetim uçları bilerek kapalıdır ve açılmayacaktır.