Teslimatlar

Kendi müşterileriniz için Veni kuryesi çağırırsınız. Erişim anlaşmaya bağlıdır; anahtarı Veni üretir ve IP kısıtınızla birlikte ayarlar (Erişim modeli).

Authorization: Bearer vnps_live_…

Teslimat açma

POST/api/v1/b2b/deliveriesPartner anahtarı

POST /api/v1/b2b/deliveries
Authorization: Bearer vnps_live_…
Idempotency-Key: SIP-1024
Content-Type: application/json

{
  "pickup_address": {
    "latitude": 39.9208,
    "longitude": 32.8541,
    "text": "Kızılay Mah. Atatürk Blv. No:1, Çankaya/Ankara",
    "contact_name": "Depo",
    "contact_phone": "05xxxxxxxxx"
  },
  "dropoff_address": {
    "latitude": 39.9072,
    "longitude": 32.8092,
    "text": "Cemal Gürsel Cad. No:45 D:8, Çankaya/Ankara",
    "contact_name": "Merve Yıldırım",
    "contact_phone": "05xxxxxxxxx"
  },
  "package_desc": "2 dürüm, 1 ayran",
  "package_size": "medium",
  "payment_method": "card",
  "external_ref": "SIP-1024"
}

Alanlar

Alan	Zorunlu	Kural
pickup_address · dropoff_address	evet	Aşağıdaki adres alanları
payment_method	evet	card ya da cash
package_size	hayır	evrak · minimal · small · medium · large · xlarge. Fiyata girer
package_desc	hayır	En çok 500 karakter
cod_amount_kurus	hayır	Kapıda tahsil edilecek tutar, kuruş
external_ref	hayır	Kendi sipariş numaranız, en çok 128 karakter. Webhook'larda size geri döner

Adres alanları:

Alan	Zorunlu	Kural
latitude · longitude	evet	Geçerli koordinat
text	evet	5–500 karakter
district	hayır	En çok 64 karakter
contact_name	hayır	En çok 200 karakter
contact_phone	hayır	En çok 20 karakter

Kurye koordinata gider, metne değil

text kuryenin kapıda okuduğu şeydir; navigasyon latitude/longitude ile yapılır. Kendi haritanızın çözdüğü noktayı gönderin, mahalle merkezini değil. Yanlış koordinat kuryeyi başka sokağa yollar ve kurye yola çıktıktan sonra düzeltilemez.

external_ref göndermenizi öneririz: webhook geldiğinde teslimatı kendi sipariş numaranızla eşlersiniz.

Yanıt

201. Teslimat ve kartla ödemede ödeme adımı birlikte döner:

{
  "data": {
    "delivery": {
      "id": "…",
      "status": "pending",
      "price_kurus": 8900,
      "payment_method": "card",
      "pickup_address": { "…": "…" },
      "dropoff_address": { "…": "…" },
      "created_at": "2026-10-12T09:14:07Z"
    },
    "payment_intent": {
      "id": "…",
      "status": "requires_action",
      "three_ds_redirect_url": "https://…"
    }
  },
  "meta": { "request_id": "01JB2K9X7Q" }
}

payment_intent.status requires_action ise kullanıcıyı three_ds_redirect_url adresine yönlendirin. Kart bilgisi hiçbir uçtan geçmez; kart verisi ödeme sağlayıcısının kendi sayfasında girilir.

Idempotency

Idempotency-Key başlığını gönderin; değeri kendi sipariş numaranız olsun.

Bu başlık teslimatı tekilleştirmez

Idempotency-Key yalnız ödeme adımına iletilir; teslimat kaydı için tekilleştirme yok. Aynı anahtarla ikinci kez POST atarsanız ikinci bir teslimat açılır ve ikinci bir kurye çağrılır.

Ağ zaman aşımında körlemesine yeniden göndermeyin. Şu sırayı izleyin: GET /api/v1/b2b/deliveries ile son teslimatlarınızı okuyun, kendi siparişinize karşılık gelen bir kayıt var mı bakın, yoksa yeniden gönderin.

⚠️ external_ref yanıt gövdesinde dönmüyor ve yalnız delivery.created webhook'una giriyor — bu yüzden eşlemeyi kendi tarafınızda tutmanız gerekir (aşağıda).

Listeleme

GET/api/v1/b2b/deliveriesPartner anahtarı

Kendi teslimatlarınızı döndürür (limit / offset ile sayfalanır). limit varsayılanı 20; üst sınır yoktur, ama büyük sayfalar yanıtı yavaşlatır.

{
  "data": { "deliveries": [{ "id": "…", "status": "assigned", "price_kurus": 8900 }] },
  "meta": { "request_id": "01JB2K9X7Q" }
}

Tek teslimat

GET/api/v1/b2b/deliveries/{id}Partner anahtarı

Teslimat nesnesi; zaman damgaları durum ilerledikçe dolar: assigned_at, picked_up_at, delivered_at, cancelled_at. Kurye atandıysa courier_id gelir.

İptal

PATCH/api/v1/b2b/deliveries/{id}/cancelPartner anahtarı

{ "reason": "Müşteri siparişten vazgeçti" }

reason zorunlu, 3–500 karakter. Başarılıysa gövdesiz 204 döner.

Teslimat iptal edilebilecek durumda değilse (kurye paketi çoktan aldıysa) 409 b2b.delivery_not_cancellable alırsınız.

İptal ayrı bir yetki ister (deliveries:cancel) ve deliveries:writetan türemez — Kimlik doğrulama.

Ret kodları

HTTP	Kod	Ne zaman
401	b2b.auth.missing	Authorization başlığı yok
401	b2b.auth.invalid	Anahtar geçersiz, iptal, süresi dolmuş, partner askıda ya da IP allowlist dışı — beşi de aynı yanıtı verir
403	b2b.partner_not_active	Partner hesabı aktif değil
403	b2b.scope.insufficient	Anahtarın bu uç için yetkisi yok
404	b2b.delivery_not_found	Teslimat yok ya da sizin değil
409	b2b.delivery_not_cancellable	Bu durumda iptal edilemez
422	b2b.out_of_range	Mesafe hizmet kapsamı dışında
402	b2b.payment_declined	Ödeme reddedildi
503	b2b.payment_unavailable	Ödeme şu an alınamıyor; birazdan tekrar deneyin
429	b2b.rate_limit · b2b.quota_exceeded	Dakikalık sınır ya da tanımlıysa kota aşıldı

Allowlist dışındaki bir IP'den gelen istek, anahtar doğru olsa bile reddedilir. Liste tekil adres ve ağ aralığı (CIDR) kabul eder; 0.0.0.0/0 gibi tüm adres uzayını kapsayan bir satır kabul edilmez.

Teslimat olayları

Beş teslimat olayı katalogda tanımlıdır; ikisi yayınlanır: delivery.created ve delivery.cancelled.

⚠️ delivery.assigned, delivery.picked_up ve delivery.delivered tetiklenmez — kurye adımlarını webhook ile beklerseniz hiç gelmez. Kurye durumunu izlemek için GET /api/v1/b2b/deliveries/{id} ile sorgulayın.

external_ref alanınız yalnız delivery.created gövdesinde döner; delivery.cancelled'da boş gelir. Bu yüzden teslimat kimliğini (delivery.id) kendi external_ref değerinizle eşleyip saklayın — iptal olayını başka türlü kendi siparişinize bağlayamazsınız.

Gövde biçimi ve imza başlıkları: Webhook imzası.