müsaif

API Dokümanı

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

POST/orders·

Sipariş oluştur

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.

refzorunluSizin sipariş numaranız. Aynı ref ikinci kez gelirse yeni sipariş açılmaz, mevcut sipariş döner.
namezorunluAlıcı adı soyadı
phoneisteğe bağlıAlıcı telefonu: 05321234567 ya da +905321234567 (SMS bildirimi için gerekli)
cityzorunluİl adı (İstanbul) ya da plaka kodu (34)
districtzorunluİlçe adı (Kadıköy)
neighborhoodisteğe bağlıMahalle
addresszorunluAçık adres (cadde, sokak, no)
building_no / apartmentisteğe bağlıBina no / daire
desi / weightisteğe bağlıSayı, ondalık için nokta (2.5)
quantityisteğe bağlıParça adedi, varsayılan 1
payment_typeisteğ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_amountisteğe bağlıKapıda tahsil edilecek tutar (TL). 0'dan büyükse ödeme türü otomatik cod olur
noteisteğe bağlıKurye notu, en fazla 500 karakter
delivery_window_start / delivery_window_endisteğ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": [ … ] }
POST/batches·

Toplu gönderim (kuyruk)

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 }
GET/batches/{batch_id}·

Toplu gönderim durumu

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" }, …
  ]
}
GET/orders/{ref}·

Sipariş takibi

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…"
}
PATCH/orders/{ref}·

Teslim aralığını değiştir

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" }
GET/orders·

Siparişleri listele

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", … }
  ]
}
POST/orders/{ref}/cancel·

Sipariş iptali

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", … }
POSTsizin adresiniz·

Durum bildirimi (webhook)

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"
}

Durumlar

passive
Pasif (henüz okutulmadı)
active
Aktif (okutuldu, işleme alındı)
with_courier
Kuryede
at_branch
Şubede
on_branch_vehicle
Şube aracında
at_transfer_center
Transfer merkezinde
on_transfer_vehicle
Transfer aracında
out_for_delivery
Dağıtımda
delivered
Teslim edildi
carried_over
Devreden (teslim edilemedi, ertesi gün)
returned
İade edildi
cancelled
İptal edildi