KARGOCUM DEVELOPERS

Gönderi entegrasyonu, tek ve güvenli API.

API key ve secret ile süreli Bearer token alın; gönderiyi oluşturun, etiketi açın ve imzalı webhook olaylarıyla teslimata kadar güncel kalın.

API BASE URLhttps://lunateknoloji.com.trv1 · JSON

POST/api/auth/token

Bearer token alın

API key ve API secret yalnızca token üretmek için kullanılır. Korumalı gönderi uçlarında Authorization: Bearer <token> başlığı gönderilir.

{
  "apiKey": "cg2...",
  "apiSecret": "cgs1..."
}

POST/api/shipments

Gönderi talebi oluşturun

Aynı müşteri ve externalOrderId ile yinelenen istekler yeni kayıt açmaz. Yanıttaki X-Idempotent-Replay başlığı tekrar isteğini belirtir.

{
  "externalOrderId": "SIP-20260831-1001",
  "recipientName": "Ayşe Yılmaz",
  "recipientPhone": "05550000000",
  "recipientAddress": "Örnek Mah. No: 10",
  "recipientCity": "İstanbul",
  "recipientDistrict": "Kadıköy",
  "parcelCount": 1,
  "desi": 2.5,
  "weightKg": 1.8,
  "serviceType": "Express",
  "paymentType": "Sender",
  "smsNotification": true,
  "webhookUrl": "https://shop.example.com/api/webhooks/kargocum",
  "webhookSecret": "en-az-16-karakter"
}

Gönderi operasyonları

GET/api/shipments/{id}

Gönderi ve tarama geçmişi

GET/api/shipments/{id}/label

Etiket verisi

POST/api/shipments/{id}/cancel

Kurye teslim almadan iptal

POST/api/shipments/{id}/retry-delivery

Teslim edilemeyen kargoyu yeniden dağıt

İmzalı webhook olayları

Her olay X-Kargocum-Event-Id ve X-Kargocum-Signature: sha256=... başlıklarıyla gönderilir. İmza, ham JSON gövdesinin webhook secret ile HMAC-SHA256 değeridir.

{
  "eventId": "...",
  "shipmentId": "...",
  "trackingNumber": "KRG...",
  "status": "OutForDelivery",
  "description": "Gönderi dağıtıma çıkarıldı.",
  "location": "Kadıköy dağıtım rotası",
  "occurredAt": "2026-08-31T08:30:00Z"
}

Operasyon durumları

Etiket oluşturulduLabelCreated

Kurye bekleniyorPickupRequested

Kurye teslim aldıPickedUp

Çıkış şubesindeAtOriginBranch

Transfer sürecindeInTransit

Varış şubesindeAtDestinationBranch

DağıtımdaOutForDelivery

Teslim edilemediDeliveryFailed

Teslim edildiDelivered

İade sürecindeReturnInitiated

Göndericiye iade edildiReturned

Hasarlı gönderiDamaged

Kayıp araştırmasıLost

İptal edildiCancelled