Skip to content
/
Siparişler
Son güncelleme

Sipariş İşlemleri

Sipariş endpoint'leri araç kiralama rezervasyonları oluşturmanıza ve yönetmenize olanak tanır. Sipariş sistemi, araç seçimi, yolcu bilgileri, fatura detayları ve ödeme işleme entegrasyonunu içeren eksiksiz rezervasyon iş akışını ele alır.

Sipariş Oluştur

Yeni bir araç kiralama siparişi oluşturur. Bu endpoint, araç rezervasyonu, yolcu kaydı ve ödeme hazırlığını içeren kapsamlı rezervasyon sürecini başlatır.

Endpoint

POST /order

Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin:

Authorization: Bearer ERIŞIM_JETONUNUZ

Son Kullanıcı IP Adresi

Entegre acenta sistemleri, son kullanıcının IP adresini X-Forwarded-For başlığı ile iletmelidir. Bu bilgi denetim ve güvenlik amaçları için gereklidir.

İstek Gövdesi

AlanTürGerekliAçıklama
paymentTypestringEvetÖdeme yöntemi: creditCard veya limit
searchIDstringEvetAraç arama sonuçlarından alınan arama kimliği
codestringEvetArama sonuçlarından seçilen araç ürün kodu
extraProductsarrayHayırEk ürün ve hizmetler listesi
passengerobjectEvetBirincil yolcu bilgileri
billingobjectHayırÖzel fatura adresi (isteğe bağlı, varsayılan olarak yolcu bilgileri)
isFullCreditbooleanHayırTam kredi ödemesi kullan (acenta yetkilendirilmeli)
isLimitedCreditbooleanHayırSınırlı kredi ödemesi kullan (acenta yetkilendirilmeli)
trackingIDstringHayırAcentenin kendi rezervasyon/takip numarası

Ekstra Ürünler

AlanTürGerekliAçıklama
codestringEvetEkstra ürün aramasından ürün kodu
quantityintegerEvetEklenecek miktar (minimum 1)

Yolcu Bilgileri

AlanTürGerekliAçıklama
firstNamestringEvetYolcu adı
lastNamestringEvetYolcu soyadı
emailstringEvetGeçerli e-posta adresi
nationalitystringEvetISO ülke kodu (2 karakter)
phonestringEvetE.164 formatında telefon numarası (ör. +905551234567)
birthDatestringEvetDoğum tarihi (YYYY-MM-DD formatı)
identityNumberstringHayır11 haneli kimlik numarası (Türk vatandaşları için)
passportNostringHayırPasaport numarası (uluslararası seyahatçiler için)

Fatura Adresi (İsteğe Bağlı)

AlanTürGerekliAçıklama
typestringEvetAdres türü: individual, privateCompany veya corporateCompany
labelstringHayırAdres için özel etiket
firstNamestringEvetFatura adı
lastNamestringHayırFatura soyadı
emailstringHayırFatura e-posta adresi
phonestringHayırE.164 formatında fatura telefon numarası
countryNamestringEvetTam ülke adı
countryCodestringEvetISO ülke kodu (2 karakter)
adm1stringEvetİdari bölüm seviye 1 (il/eyalet)
adm2stringHayırİdari bölüm seviye 2 (şehir/ilçe)
linestringHayırAdres satırı (sokak adresi)
zipCodestringHayırPosta/ZIP kodu
taxDivisionstringHayırVergi dairesi/bölümü
taxIdentifierstringHayırVergi kimlik numarası

Örnek İstek

curl -X POST https://api.pro.yolcu360.com/api/v1/order \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
  -H "X-Forwarded-For: 203.0.113.195" \
  -d '{
    "paymentType": "creditCard",
    "searchID": "search_123456789",
    "code": "ECAR",
    "isFullCredit": true,
    "isLimitedCredit": false,
    "trackingID": "AGENCY-RES-12345",
    "extraProducts": [
      {
        "code": "GPS",
        "quantity": 1
      },
      {
        "code": "CDW",
        "quantity": 1
      }
    ],
    "passenger": {
      "firstName": "Ahmet",
      "lastName": "Yılmaz",
      "email": "ahmet.yilmaz@example.com",
      "nationality": "TR",
      "phone": "+905551234567",
      "birthDate": "1990-01-15",
      "identityNumber": "12345678901"
    },
    "billing": {
      "type": "individual",
      "label": "Ev Adresi",
      "firstName": "Ahmet",
      "lastName": "Yılmaz",
      "email": "ahmet.yilmaz@example.com",
      "phone": "+905551234567",
      "countryName": "Türkiye",
      "countryCode": "TR",
      "adm1": "İstanbul",
      "adm2": "Beşiktaş",
      "line": "Barbaros Bulvarı No:123",
      "zipCode": "34349"
    }
  }'

Şahıs Şirketi Fatura Örneği:

curl -X POST https://api.pro.yolcu360.com/api/v1/order \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
  -d '{
    ...
    "billing": {
      "type": "privateCompany",
      "firstName": "Ayşe",
      "lastName": "Demir",
      "email": "ayse@sirket.com",
      "phone": "+905551234567",
      "countryName": "Türkiye",
      "countryCode": "TR",
      "adm1": "İstanbul",
      "adm2": "Kadıköy",
      "line": "İş Caddesi No:456",
      "zipCode": "34000",
      "taxDivision": "Kadıköy VD",
      "taxIdentifier": "1234567890"
    }
  }'

Yanıt

Başarılı Yanıt (201 Created):

{
  "id": "order_123456789",
  "paymentType": "creditCard",
  "paymentCurrency": "TRY",
  "language": "tr",
  "createdAt": "2024-12-25T10:00:00Z",
  "updatedAt": "2024-12-25T10:00:00Z",
  "passenger": {
    "firstName": "Ahmet",
    "lastName": "Yılmaz",
    "email": "ahmet.yilmaz@example.com",
    "nationality": "TR",
    "phone": "+905551234567"
  },
  "billing": {
    "type": "individual",
    "firstName": "Ahmet",
    "lastName": "Yılmaz",
    "email": "ahmet.yilmaz@example.com",
    "phone": "+905551234567"
  },
  "orderedCarProduct": {
    "id": 1001,
    "status": "pending",
    "quantity": 1,
    "isFullCredit": true,
    "isLimitedCredit": false,
    "vendorCancelled": false,
    "trackingID": "AGENCY-RES-12345",
    "createdAt": "2024-12-25T10:00:00Z",
    "updatedAt": "2024-12-25T10:00:00Z",
    "car": {
      "code": "ECAR",
      "searchID": "search_123456789",
      "brand": {
        "id": "toyota",
        "name": "Toyota"
      },
      "model": {
        "id": "corolla",
        "name": "Corolla"
      },
      "class": {
        "id": "economy",
        "name": "Ekonomi"
      },
      "imageURL": "https://example.com/car-image.jpg",
      "pricing": {
        "total": {
          "amount": 50000,
          "currency": "TRY"
        },
        "paymentTotal": {
          "amount": 50000,
          "currency": "TRY"
        }
      }
    }
  },
  "orderedExtraProducts": [
    {
      "id": 1002,
      "status": "pending",
      "quantity": 1,
      "vendorCancelled": false,
      "trackingID": "AGENCY-RES-12345",
      "createdAt": "2024-12-25T10:00:00Z",
      "updatedAt": "2024-12-25T10:00:00Z",
      "extraProduct": {
        "code": "GPS",
        "name": "GPS Navigasyon Sistemi",
        "type": "equipment",
        "pricing": {
          "total": {
            "amount": 1500,
            "currency": "TRY"
          }
        }
      }
    },
    {
      "id": 1003,
      "status": "pending",
      "quantity": 1,
      "vendorCancelled": false,
      "trackingID": "AGENCY-RES-12345",
      "createdAt": "2024-12-25T10:00:00Z",
      "updatedAt": "2024-12-25T10:00:00Z",
      "extraProduct": {
        "code": "CDW",
        "name": "Çarpışma Hasarı Muafiyeti",
        "type": "insurance",
        "pricing": {
          "total": {
            "amount": 3000,
            "currency": "TRY"
          }
        }
      }
    }
  ]
}

Sipariş Durumu Değerleri

DurumAçıklama
pendingÖğe siparişe eklendi, onay bekleniyor
reservedÖğe tedarikçide başarıyla rezerve edildi
failedÖğe rezervasyonu başarısız
cancelledÖğe kullanıcı veya tedarikçi tarafından iptal edildi
removedÖğe siparişten kaldırıldı

Sipariş Detaylarını Al

Mevcut durum, yolcu bilgileri, sipariş edilen ürünler ve ödeme bilgileri dahil olmak üzere belirli bir siparişin kapsamlı detaylarını alın.

Endpoint

GET /order/{orderID}

Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

Yol Parametreleri

ParametreTürGerekliAçıklama
orderIDstringEvetBenzersiz sipariş tanımlayıcısı

Örnek İstek

curl -X GET https://api.pro.yolcu360.com/api/v1/order/order_123456789 \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"

Yanıt

Başarılı Yanıt (200 OK):

Sipariş oluşturma yanıtıyla aynı yapıyı döndürür, güncellenmiş durum bilgileri ve oluşturulduktan sonra gerçekleşen değişikliklerle birlikte.

{
  "id": "order_123456789",
  "paymentType": "creditCard",
  "paymentCurrency": "TRY",
  "language": "tr",
  "createdAt": "2024-12-25T10:00:00Z",
  "updatedAt": "2024-12-25T10:15:00Z",
  "passenger": {
    "firstName": "Ahmet",
    "lastName": "Yılmaz",
    "email": "ahmet.yilmaz@example.com",
    "nationality": "TR",
    "phone": "+905551234567"
  },
  "orderedCarProduct": {
    "id": 1001,
    "status": "reserved",
    "quantity": 1,
    "isFullCredit": true,
    "isLimitedCredit": false,
    "vendorCancelled": false,
    "vendorReservationID": "AVIS_RES_789012",
    "trackingID": "AGENCY-RES-12345",
    "paymentID": 2001,
    "createdAt": "2024-12-25T10:00:00Z",
    "updatedAt": "2024-12-25T10:15:00Z",
    "car": {
      "code": "ECAR",
      "searchID": "search_123456789",
      "brand": {
        "id": "toyota",
        "name": "Toyota"
      },
      "model": {
        "id": "corolla",
        "name": "Corolla"
      }
    }
  },
  "orderedExtraProducts": [
    {
      "id": 1002,
      "status": "reserved",
      "quantity": 1,
      "paymentID": 2001,
      "vendorReservationID": "AVIS_GPS_789013",
      "trackingID": "AGENCY-RES-12345"
    }
  ]
}

İptal Uygunluğunu Kontrol Et

Bir siparişin iptal ve iade için uygun olup olmadığını kontrol eder. Bu endpoint siparişi değiştirmez ancak iptal ve iade uygunluk durumu hakkında bilgi sağlar.

Endpoint

POST /order/{orderID}/cancel_eligibility

Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

Yol Parametreleri

ParametreTürGerekliAçıklama
orderIDstringEvetKontrol edilecek siparişin benzersiz tanımlayıcısı

Örnek İstek

curl -X POST https://api.pro.yolcu360.com/api/v1/order/YLP_123456/cancel_eligibility \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"

Yanıt

Başarılı Yanıt (200 OK):

{
  "cancellable": true,
  "refundable": true
}

Yanıt Alanları

AlanTürAçıklama
cancellablebooleanSiparişin iptal için uygun olup olmadığı
refundablebooleanSiparişin iptal edildiğinde iade için uygun olup olmadığı

Siparişi İptal Et

Mevcut bir siparişi iptal eder. Bu işlemin başarılı olması için siparişin iptal edilebilir durumda olması gerekir. Bu endpoint siparişi tedarikçi ile iptal etmeye çalışır ve sipariş durumunu buna göre günceller.

Endpoint

POST /order/{orderID}/cancel

Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

Yol Parametreleri

ParametreTürGerekliAçıklama
orderIDstringEvetİptal edilecek siparişin benzersiz tanımlayıcısı

Örnek İstek

curl -X POST https://api.pro.yolcu360.com/api/v1/order/YLP_123456/cancel \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ"

Yanıt

Başarılı Yanıt (200 OK):

{
  "success": true,
  "message": "Sipariş başarıyla iptal edildi",
  "orderId": "YLP_123456",
  "status": "success"
}

İptal Durumu Değerleri

DurumAçıklama
pendingİptal isteği işleniyor
successSipariş başarıyla iptal edildi
failedİptal isteği başarısız oldu

Sipariş Oluşturma İş Akışı

Sipariş oluşturma süreci, sistem tarafından otomatik olarak yürütülen birden fazla adımı içerir:

1. Sipariş Başlatma

  • Temel sipariş kaydı oluşturur
  • Arama oturumunu ve araç kullanılabilirliğini doğrular
  • Başlangıç durumunu "open" olarak ayarlar

2. Ürün Ekleme

  • Seçilen aracı siparişe ekler
  • Seçilen ekstra ürünleri ekler
  • Komisyonlar dahil toplam fiyatlandırmayı hesaplar

3. Yolcu Kaydı

  • Yolcu bilgilerini doğrular
  • Yolcu detaylarını güvenli şekilde saklar
  • Yolcuyu siparişe bağlar

4. Fatura Kurulumu

  • Sağlandıysa özel fatura adresini kullanır
  • Faturalama için yolcu bilgilerine geri döner
  • Fatura bilgilerinin eksiksizliğini doğrular

5. Ödeme Hazırlığı

  • Nihai ödeme tutarlarını hesaplar
  • Ödeme türüne göre ödeme gereksinimlerini belirler
  • Siparişi ödeme işleme için hazırlar

Sipariş Yaşam Döngüsü

Evet

Hayır

Sipariş Oluştur

Araç Ekle

Ekstra Ürünler Ekle

Yolcu Bilgilerini Ekle

Fatura Bilgilerini Ekle

Toplamları Hesapla

Sipariş Ödeme İçin Hazır

Ödemeyi İşle

Ödeme Başarılı?

Tedarikçide Rezerve Et

Ödeme Başarısız

Sipariş Tamamlandı

Ödemeyi Yeniden Dene

Evet

Hayır

Sipariş Oluştur

Araç Ekle

Ekstra Ürünler Ekle

Yolcu Bilgilerini Ekle

Fatura Bilgilerini Ekle

Toplamları Hesapla

Sipariş Ödeme İçin Hazır

Ödemeyi İşle

Ödeme Başarılı?

Tedarikçide Rezerve Et

Ödeme Başarısız

Sipariş Tamamlandı

Ödemeyi Yeniden Dene

Sipariş En İyi Uygulamaları

Yolcu Bilgileri

  • Gerekli Alanlar: Tüm zorunlu yolcu alanlarının sağlandığından emin olun
  • Belge Doğrulama: Kimlik numarası (yerli için) veya pasaport (uluslararası için) sağlayın
  • İletişim Bilgileri: Bildirimler için geçerli e-posta ve telefon numarası kullanın
  • Yaş Doğrulama: Yolcunun minimum yaş gereksinimlerini karşıladığından emin olun

Fatura Adresi

  • İsteğe Bağlı Kullanım: Yalnızca yolcu adresinden farklıysa fatura adresi sağlayın
  • Kurumsal Siparişler: İş kiralamaları için şirket fatura bilgilerini kullanın
  • Vergi Bilgileri: Kurumsal fatura adresleri için vergi detaylarını ekleyin
  • Adres Doğrulama: Adres bilgilerinin eksiksiz ve doğru olduğundan emin olun

Ekstra Ürünler

  • Miktar Sınırları: Minimum ve maksimum miktar kısıtlamalarına saygı gösterin
  • Uyumluluk: Ürün uyumluluğunu seçilen araçla doğrulayın
  • Fiyat Güncellemeleri: Arama ve sipariş arasında ekstra ürün fiyatları değişebilir

Hata İşleme

Yaygın Hata Yanıtları:

  • 400 Bad Request: Geçersiz sipariş verisi veya eksik gerekli alanlar
  • 401 Unauthorized: Kimlik doğrulama gerekli veya jetonun süresi dolmuş
  • 404 Not Found: Arama oturumunun süresi dolmuş veya araç kullanılamıyor
  • 422 Unprocessable Entity: Yolcu veya fatura verilerinde doğrulama hataları
  • 500 Internal Server Error: Sipariş işleme sırasında sistem hatası

Örnek Hata Yanıtı:

{
  "code": 1001,
  "description": "Geçersiz yolcu bilgisi",
  "details": {
    "field": "passenger.email",
    "message": "Geçersiz e-posta formatı"
  }
}

Doğrulama Kuralları

Yolcu Doğrulama

  • E-posta: Geçerli e-posta formatında olmalı
  • Telefon: E.164 uluslararası formatında olmalı
  • Doğum Tarihi: Geçerli tarih olmalı ve minimum yaş gereksinimlerini karşılamalı
  • Uyruk: Geçerli ISO ülke kodu olmalı
  • Kimlik/Pasaport: Uyruk ve seyahat gereksinimlerine göre gerekli

Fatura Doğrulama

  • Tür: Şunlardan biri olmalı: individual, privateCompany, corporateCompany
  • Ülke: Ülke kodu ülke adıyla eşleşmeli
  • Kurumsal Alanlar: Şirket türleri için vergi dairesi ve tanımlayıcı gerekli
  • Adres: İdari bölümler ülke için geçerli olmalı

Entegrasyon Örnekleri

Temel Sipariş Oluşturma

async function createOrder(searchResult, passengerInfo) {
    const orderData = {
        paymentType: 'creditCard',
        searchID: searchResult.searchID,
        code: searchResult.code,
        passenger: {
            firstName: passengerInfo.firstName,
            lastName: passengerInfo.lastName,
            email: passengerInfo.email,
            nationality: passengerInfo.nationality,
            phone: passengerInfo.phone,
            birthDate: passengerInfo.birthDate
        }
    };

    const response = await fetch('/api/v1/order', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify(orderData)
    });

    if (!response.ok) {
        const error = await response.json();
        throw new Error(`Sipariş oluşturma başarısız: ${error.description}`);
    }

    return await response.json();
}

Ekstra Ürünlerle Sipariş

async function createOrderWithExtras(searchResult, passengerInfo, selectedExtras) {
    const orderData = {
        paymentType: 'creditCard',
        searchID: searchResult.searchID,
        code: searchResult.code,
        extraProducts: selectedExtras.map(extra => ({
            code: extra.code,
            quantity: extra.quantity
        })),
        passenger: passengerInfo
    };

    return await createOrder(orderData);
}

Hız Sınırlama

Sipariş endpoint'leri hız sınırlamasına tabidir:

  • Sipariş oluştur: Kullanıcı başına dakikada maksimum 5 istek
  • Sipariş al: Kullanıcı başına dakikada maksimum 60 istek

Yanıtlarda hız sınırı başlıklarını izleyin ve uygun yeniden deneme mantığını uygulayın.

Findeks Credit Eligibility

Payment