Sipariş Oluşturma¶

Yeni bir siparişi MuditaKurye platformuna göndermek için bu endpoint'i kullanın.

Endpoint¶

POST /webhook/third-party/order

Request¶

Headers¶

Header	Zorunlu	Açıklama
`X-API-Key`	Evet*	API Key (Authentication yöntemi)
`Authorization`	Evet*	Basic Auth (alternatif yöntem)
`Content-Type`	Evet	`application/json`

* X-API-Key veya Authorization header'larından biri zorunludur.

Body Parameters¶

Alan	Tip	Zorunlu	Açıklama
`orderId`	string	Evet	Sizin sisteminizdeki benzersiz sipariş ID'si
`restaurantId`	string	Evet	MuditaKurye'den aldığınız restoran ID'si (`rest_` ile başlar)
`customerName`	string	Evet	Müşteri adı soyadı
`customerPhone`	string	Hayır	Müşteri telefon numarası (E.164 formatı önerilir)
`customerEmail`	string	Hayır	Müşteri e-posta adresi
`deliveryAddress`	string	Evet	Tam teslimat adresi
`deliveryLatitude`	number	Hayır	Teslimat noktası enlemi (rotalama için önerilir)
`deliveryLongitude`	number	Hayır	Teslimat noktası boylamı
`scheduledDeliveryTime`	string	Hayır	Zamanlanmış teslimat (ISO-8601 format)
`paymentMethod`	string	Hayır	`CASH`, `CARD_POS`, veya `ONLINE_PREPAID`
`paymentCaptured`	boolean	Hayır	Ödeme alındı mı? (online ödemeler için `true`)
`subtotal`	number	Hayır	Ara toplam (ücret/indirimler hariç)
`deliveryFee`	number	Hayır	Teslimat ücreti
`serviceFee`	number	Hayır	Hizmet bedeli
`discount`	number	Hayır	İndirim tutarı
`taxAmount`	number	Hayır	KDV/vergi tutarı
`total`	number	Hayır	Toplam tutar
`currency`	string	Hayır	Para birimi (varsayılan: `TRY`)
`notes`	string	Hayır	Sipariş notları/talimatlar
`items`	array	Hayır	Sipariş kalemleri (detaylar aşağıda)

Item Object¶

Alan	Tip	Zorunlu	Açıklama
`productCode`	string	Hayır	Sizin ürün kodunuz
`productName`	string	Hayır	Ürün adı
`quantity`	number	Hayır	Adet
`unitPrice`	number	Hayır	Birim fiyat
`totalAmount`	number	Hayır	Toplam (adet × fiyat - indirim)
`discountAmount`	number	Hayır	Kalem indirimi
`productNote`	string	Hayır	Ürün notu (örn: "Az pişmiş")
`features`	string	Hayır	Ekstralar/modifikatörler (örn: "Büyük boy, ekstra peynir")

Request Örnekleri¶

cURLNode.jsPython

curl -X POST https://api.muditakurye.com.tr/webhook/third-party/order \
  -H "X-API-Key: yk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_123456",
    "restaurantId": "rest_abc1234567890",
    "customerName": "Ahmet Yılmaz",
    "customerPhone": "+905551234567",
    "deliveryAddress": "Atatürk Caddesi No: 123, Çankaya, Ankara",
    "deliveryLatitude": 39.9208,
    "deliveryLongitude": 32.8541,
    "paymentMethod": "CASH",
    "paymentCaptured": false,
    "subtotal": 85.00,
    "deliveryFee": 15.00,
    "serviceFee": 5.00,
    "discount": 10.00,
    "taxAmount": 8.50,
    "total": 103.50,
    "currency": "TRY",
    "notes": "Lütfen kapıyı çalın",
    "items": [
      {
        "productCode": "PIZZA_001",
        "productName": "Margarita Pizza",
        "quantity": 2.0,
        "unitPrice": 35.00,
        "totalAmount": 70.00,
        "discountAmount": 0.00,
        "productNote": "İnce hamur",
        "features": "BOYUT: Büyük | EKSTRA: Ekstra peynir"
      },
      {
        "productCode": "DRINK_002",
        "productName": "Coca Cola 1L",
        "quantity": 1.0,
        "unitPrice": 15.00,
        "totalAmount": 15.00
      }
    ]
  }'

const axios = require('axios');

async function createOrder() {
  try {
    const response = await axios.post(
      'https://api.muditakurye.com.tr/webhook/third-party/order',
      {
        orderId: `order_${Date.now()}`,
        restaurantId: 'rest_abc1234567890',
        customerName: 'Ahmet Yılmaz',
        customerPhone: '+905551234567',
        deliveryAddress: 'Atatürk Caddesi No: 123, Çankaya, Ankara',
        deliveryLatitude: 39.9208,
        deliveryLongitude: 32.8541,
        paymentMethod: 'CASH',
        paymentCaptured: false,
        total: 103.50,
        currency: 'TRY',
        items: [
          {
            productCode: 'PIZZA_001',
            productName: 'Margarita Pizza',
            quantity: 2,
            unitPrice: 35,
            totalAmount: 70
          }
        ]
      },
      {
        headers: {
          'X-API-Key': process.env.MUDITAKURYE_API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Sipariş oluşturuldu:', response.data);
    return response.data;
  } catch (error) {
    console.error('Hata:', error.response?.data || error.message);
    throw error;
  }
}

createOrder();

import requests
import os
from datetime import datetime

def create_order():
    url = 'https://api.muditakurye.com.tr/webhook/third-party/order'
    headers = {
        'X-API-Key': os.getenv('MUDITAKURYE_API_KEY'),
        'Content-Type': 'application/json'
    }
    payload = {
        'orderId': f'order_{int(datetime.now().timestamp())}',
        'restaurantId': 'rest_abc1234567890',
        'customerName': 'Ahmet Yılmaz',
        'customerPhone': '+905551234567',
        'deliveryAddress': 'Atatürk Caddesi No: 123, Çankaya, Ankara',
        'deliveryLatitude': 39.9208,
        'deliveryLongitude': 32.8541,
        'paymentMethod': 'CASH',
        'paymentCaptured': False,
        'total': 103.50,
        'currency': 'TRY',
        'items': [
            {
                'productCode': 'PIZZA_001',
                'productName': 'Margarita Pizza',
                'quantity': 2.0,
                'unitPrice': 35.00,
                'totalAmount': 70.00
            }
        ]
    }

    response = requests.post(url, json=payload, headers=headers)

    if response.status_code == 202:
        print(f'Sipariş oluşturuldu: {response.json()}')
        return response.json()
    else:
        print(f'Hata: {response.status_code} - {response.text}')
        response.raise_for_status()

if __name__ == '__main__':
    create_order()

Response¶

Başarılı Yanıt (HTTP 202 Accepted)¶

{
  "status": "accepted",
  "orderId": "order_123456"
}

202 Accepted

Sipariş kabul edildi ve asenkron olarak işlenecek. Webhook'lar üzerinden durum güncellemelerini takip edin.

Hata Yanıtları¶

{
  "error": "Restaurant not found",
  "code": "RESTAURANT_NOT_FOUND"
}

HTTP Status	Hata Kodu	Açıklama
`400`	`MISSING_REQUIRED_FIELD`	`orderId` veya `restaurantId` eksik
`400`	`INVALID_PAYLOAD`	JSON geçersiz veya format hatalı
`401`	`AUTHENTICATION_FAILED`	API Key veya kimlik bilgileri geçersiz
`403`	`INTEGRATION_DISABLED`	Entegrasyon bu restoran için kapalı
`404`	`RESTAURANT_NOT_FOUND`	Geçersiz `restaurantId`
`409`	`DUPLICATE_ORDER_ID`	Bu `orderId` zaten kullanılmış
`422`	`VALIDATION_ERROR`	Veri doğrulama hatası (detaylar response'ta)
`429`	`RATE_LIMIT_EXCEEDED`	Çok fazla istek, 1 dakika bekleyin

Detaylı hata açıklamaları için Hata Kodları sayfasına bakın.

İdempotency (Tekrar Güvenliği)¶

orderId alanı idempotency key olarak kullanılır. Aynı orderId ile yapılan tekrar istekler:

İlk istek başarılı olduysa: HTTP 202 döner (sipariş tekrar oluşturulmaz)
İlk istek hata aldıysa: Yeniden işlenir

En İyi Uygulama

Her sipariş için benzersiz bir orderId kullanın. Örneğin: {POS_ID}_{ORDER_NUMBER}_{TIMESTAMP}

Özel Durumlar¶

Zamanlanmış Teslimat¶

Gelecekte bir zamanda teslim edilmek üzere sipariş:

{
  "orderId": "order_scheduled_123",
  "scheduledDeliveryTime": "2025-11-10T18:30:00+03:00",
  ...
}

Zamanlanmış Sipariş Onayı

Zamanlanmış siparişler iki aşamalı onay sürecinden geçer:

Ön Onay (Pre-approval): Restoran siparişi kabul eder
Final Onay: Teslimat saatinden 1 saat önce kurye ataması yapılır

Online Ödeme¶

Ödeme zaten alınmışsa paymentCaptured: true gönderin:

{
  "orderId": "order_prepaid_456",
  "paymentMethod": "ONLINE_PREPAID",
  "paymentCaptured": true,
  ...
}

Koordinat Olmadan Adres¶

Enlem/boylam bilgisi yoksa sadece adres metni gönderin. Sistem otomatik geocoding yapacaktır:

{
  "orderId": "order_789",
  "deliveryAddress": "Kızılay Mahallesi, Atatürk Bulvarı No:45 D:12, Çankaya/Ankara",
  ...
}

Koordinat Önerilir

Geocoding %100 doğru olmayabilir. Mümkünse deliveryLatitude ve deliveryLongitude gönderin.

Health Check Endpoint¶

API'nin çalışır durumda olduğunu kontrol etmek için:

curl https://api.muditakurye.com.tr/webhook/third-party/health

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2025-11-10T12:34:56+03:00"
}

Sonraki Adım¶

Sipariş oluşturduktan sonra durum güncellemelerini almak için Webhook'lar sayfasına geçin.