Siparişlerinizi kendi sisteminizden oluşturun, takip edin ve iptal edin. API anahtarınızı panelde Ayarlar > API sayfasından alırsınız.
Adres: https://app.musaif.com/api/v1
Her istekte başlık: Authorization: Bearer msk_…. Gövde ve yanıtlar JSON (UTF-8).
Anahtarı panelde Ayarlar > API sayfasından alırsınız (müşteri panelinde: API). Anahtar bir göndericiye bağlıdır; siparişler o gönderici adına açılır ve yalnız onun siparişleri görünür. Ayrı test ortamı yoktur: deneme siparişlerini oluşturup iptal uç noktasıyla iptal edebilirsiniz.
Hata yanıtı: { "error": "…" } · 401 anahtar geçersiz · 404 bulunamadı · 422 işlem yapılamadı · 429 limit aşıldı
Limitler: anahtar başına dakikada 60 istek · POST /orders istek başına 500 sipariş · POST /batches istek başına 10.000 sipariş.
/orders·Tek sipariş nesnesi ya da toplu gönderim için { "orders": [ … ] } (istek başına en fazla 500). Gönderici bilgisi ve adresi anahtarın bağlı olduğu müşteriden otomatik gelir.
ref | zorunlu | Sizin sipariş numaranız. Aynı ref ikinci kez gelirse yeni sipariş açılmaz, mevcut sipariş döner. |
name | zorunlu | Alıcı adı soyadı |
phone | isteğe bağlı | Alıcı telefonu: 05321234567 ya da +905321234567 (SMS bildirimi için gerekli) |
city | zorunlu | İl adı (İstanbul) ya da plaka kodu (34) |
district | zorunlu | İlçe adı (Kadıköy) |
neighborhood | isteğe bağlı | Mahalle |
address | zorunlu | Açık adres (cadde, sokak, no) |
building_no / apartment | isteğe bağlı | Bina no / daire |
desi / weight | isteğe bağlı | Sayı, ondalık için nokta (2.5) |
quantity | isteğe bağlı | Parça adedi, varsayılan 1 |
payment_type | isteğe bağlı | sender_pays (gönderici öder) · receiver_pays (alıcı öder) · account (cari) · cod (kapıda ödeme). Boşsa anahtarın varsayılanı |
cod_amount | isteğe bağlı | Kapıda tahsil edilecek tutar (TL). 0'dan büyükse ödeme türü otomatik cod olur |
note | isteğe bağlı | Kurye notu, en fazla 500 karakter |
delivery_window_start / delivery_window_end | isteğe bağlı | Müşterinin seçtiği teslim aralığı, ISO tarih-saat (2026-11-21T09:00:00+03:00). Saat dilimi yazılmazsa Türkiye saati. Kısa yol: "delivery_date": "2026-11-21" + "delivery_window": "09:00-12:00" (tarih yoksa bugün) |
İstek
curl -X POST https://app.musaif.com/api/v1/orders \
-H "Authorization: Bearer msk_…" \
-H "Content-Type: application/json" \
-d '{
"ref": "SIP-1001",
"name": "Ayşe Yılmaz",
"phone": "05321234567",
"city": "İstanbul",
"district": "Kadıköy",
"address": "Moda Cd. No: 12 D: 3",
"desi": 3,
"cod_amount": 0
}'Yanıt
201 Created
{
"ref": "SIP-1001",
"result": "created",
"tracking_no": "KGO-2026-000123",
"tracking_url": "https://app.musaif.com/kargo-takip/4f1c…"
}
Zaten varsa 200, "result": "exists"
Hatalıysa 422, "result": "failed", "error": "Alıcı il / ilçe / adres eksik"
Toplu gönderimde: { "created": 2, "exists": 0, "failed": 1, "results": [ … ] }/batches·500'den fazla sipariş için. Tek istekte en fazla 10.000 sipariş; alanlar yukarıdakiyle aynı (teslim aralığı için tekli/500'lük gönderimi ya da PATCH /orders/{ref} kullanın). Hemen 202 ve batch_id döner, siparişler arka planda 500'erli işlenir (yaklaşık dakikada birkaç bin). Aynı anda en fazla 5 bekleyen gönderim.
İstek
curl -X POST https://app.musaif.com/api/v1/batches \
-H "Authorization: Bearer msk_…" \
-H "Content-Type: application/json" \
-d '{ "orders": [ { "ref": "SIP-1001", … }, { "ref": "SIP-1002", … } ] }'Yanıt
202 Accepted
{ "batch_id": "8d2f…", "status": "queued", "total": 3000, "processed": 0 }/batches/{batch_id}·status: queued · processing · done · failed. Bitince her satırın sonucu results içinde. Webhook adresiniz varsa bitişte batch.completed bildirimi de gelir.
İstek
curl https://app.musaif.com/api/v1/batches/8d2f… \ -H "Authorization: Bearer msk_…"
Yanıt
{
"batch_id": "8d2f…",
"status": "done",
"total": 3000, "processed": 3000,
"created": 2996, "exists": 3, "failed": 1,
"results": [
{ "ref": "SIP-1001", "result": "created", "tracking_no": "KGO-2026-000124" },
{ "ref": "SIP-1002", "result": "failed", "error": "Alıcı adı eksik" }, …
]
}/orders/{ref}·ref yerine sizin sipariş numaranız ya da takip no kullanılabilir. Güncel durum ve hareket geçmişi döner.
İstek
curl https://app.musaif.com/api/v1/orders/SIP-1001 \ -H "Authorization: Bearer msk_…"
Yanıt
{
"ref": "SIP-1001",
"tracking_no": "KGO-2026-000123",
"status": "out_for_delivery",
"status_label": "Dağıtımda",
"events": [
{ "status": "passive", "status_label": "Pasif", "at": "2026-11-18T09:12:00Z" },
{ "status": "out_for_delivery", "status_label": "Dağıtımda", "at": "2026-11-19T08:40:00Z" }
],
"tracking_url": "https://app.musaif.com/kargo-takip/4f1c…"
}/orders/{ref}·Müşterinin seçtiği teslim aralığını sipariş teslim edilene kadar değiştirir. delivery_window_start + delivery_window_end (ISO) ya da delivery_date + delivery_window ("09:00-12:00"). İkisi null ise aralık kaldırılır. Kapanmış sipariş 422.
İstek
curl -X PATCH https://app.musaif.com/api/v1/orders/SIP-1001 \
-H "Authorization: Bearer msk_…" \
-H "Content-Type: application/json" \
-d '{ "delivery_date": "2026-11-21", "delivery_window": "09:00-12:00" }'Yanıt
{ "ext_ref": "SIP-1001", "tracking_no": "KGO-2026-000123", "result": "updated",
"delivery_window_start": "2026-11-21T06:00:00+00:00", "delivery_window_end": "2026-11-21T09:00:00+00:00" }/orders·status: open · delivered · cancelled · returned · all. since tarihten sonra oluşturulanlar; limit (en fazla 200) ve offset ile sayfalama.
İstek
curl "https://app.musaif.com/api/v1/orders?status=open&since=2026-11-01&limit=50" \ -H "Authorization: Bearer msk_…"
Yanıt
{
"orders": [
{ "ref": "SIP-1001", "tracking_no": "KGO-2026-000123", "status": "passive", "status_label": "Pasif", … }
]
}/orders/{ref}/cancel·Yalnızca kurye teslim almadan önce iptal edilebilir; sonrasında 422 döner.
İstek
curl -X POST https://app.musaif.com/api/v1/orders/SIP-1001/cancel \
-H "Authorization: Bearer msk_…" \
-H "Content-Type: application/json" \
-d '{ "reason": "Müşteri vazgeçti" }'Yanıt
{ "ref": "SIP-1001", "status": "cancelled", "status_label": "İptal edildi", … }sizin adresiniz·Ayarlar'da webhook adresi (https) girerseniz, bu anahtarla açılan her siparişin durumu değiştiğinde adrese POST gelir. Doğrulama: X-Musaif-Secret başlığı girdiğiniz gizli anahtarla birebir aynı olmalı, değilse isteği reddedin. Bildirim tek sefer gönderilir, tekrar denenmez; kaçırılan durumları GET /orders/{ref} ile sorgulayın. 2xx dışında bir yanıt dönmeniz bildirimi yeniden göndermez.
Gövde
{
"event": "shipment.status",
"ext_ref": "SIP-1001",
"tracking_no": "KGO-2026-000123",
"status": "delivered",
"tracking_status": "delivered",
"note": null,
"at": "2026-11-19T14:05:00Z",
"received_by": "Ayşe Yılmaz"
}passiveactivewith_courierat_branchon_branch_vehicleat_transfer_centeron_transfer_vehicleout_for_deliverydeliveredcarried_overreturnedcancelled