Kurye Çağırma

Bu API, bir veya birden fazla gönderi için kurye çağırma (pickup request) talebi oluşturur.

Endpoint Bilgileri

Özellik Değer
URL {{BASE_URL}}/api/v1/pickups
HTTP Metodu POST
Content-Type application/json
Kimlik Doğrulama APIKEY header
Route Name api_v1_pickups_create

Request Body Şeması

{
  "appointment": {
    "start": "string (datetime)",
    "end": "string (datetime)"
  },
  "address": {
    "name": "string",
    "country_id": "integer",
    "state_id": "integer",
    "city_id": "integer",
    "street": "string",
    "postal_code": "string|null"
  },
  "consignments": [
    {
      "type": "id|barcode|reference",
      "value": "string"
    }
  ]
}

Request Parametreleri

appointment

Alan Tip Zorunluluk Açıklama
start Datetime String ZORUNLU Pickup başlangıç zamanı
end Datetime String ZORUNLU Pickup bitiş zamanı

address

Alan Tip Zorunluluk Açıklama
name String ZORUNLU Adres etiketi/adı (örn. "Merkez Depo")
country_id Integer ZORUNLU Ülke ID bilgisi
state_id Integer ZORUNLU İl/eyalet ID bilgisi
city_id Integer ZORUNLU İlçe/şehir ID bilgisi
street String ZORUNLU Açık adres satırı
postal_code String Opsiyonel Posta kodu

consignments[]

Alan Tip Zorunluluk Açıklama
type Enum String ZORUNLU Eşleştirme tipi. Geçerli değerler: id, barcode, reference
value String ZORUNLU Seçilen tipe karşılık gelen değer

Validasyon Kuralları

Yapısal ve zorunluluk kuralları

  • appointment, address, consignments alanları zorunludur.
  • consignments en az 1 eleman içermelidir.
  • consignments[*].type sadece id, barcode, reference olabilir.
  • consignments[*].value boş olamaz.
  • address.name ve address.street boş olamaz.
  • country_id, state_id, city_id alanları integer tipinde olmalıdır.

Uzunluk kuralları

  • address.name maksimum 255 karakter.
  • address.street maksimum 255 karakter.
  • address.postal_code maksimum 20 karakter.

Tarih/saat kuralları

  • appointment.start ve appointment.end parse edilebilir datetime formatında olmalıdır (önerilen: ISO 8601 / RFC3339).
  • appointment.end, appointment.start değerinden büyük olmalıdır.
  • Randevu aralığı en az 30 dakika olmalıdır.
  • appointment.end geçmişte olamaz.
  • appointment.start en az yaklaşık 1 saat ileri bir zaman olmalıdır.

Örnek Kullanım

API İsteği

curl --location '{{BASE_URL}}/api/v1/pickups' \
  --header 'APIKEY: {{APIKEY}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "appointment": {
      "start": "2026-03-28T10:00:00+03:00",
      "end": "2026-03-28T12:00:00+03:00"
    },
    "address": {
      "name": "Acme Depo",
      "country_id": 223,
      "state_id": 34,
      "city_id": 1,
      "street": "Maslak Mah. Buyukdere Cad. No:100",
      "postal_code": "34485"
    },
    "consignments": [
      {
        "type": "barcode",
        "value": "C2H000123456"
      }
    ]
  }'

Başarılı Cevap

HTTP Status: 201 Created

{
  "status": true,
  "message": "Pickup request created successfully.",
  "data": {
    "id": 1452,
    "tracking_number": "PCK-20260328-0001452",
    "customer": {
      "id": 17,
      "name": "Acme Lojistik A.S."
    },
    "status": "scheduled",
    "appointment": {
      "start": "2026-03-28T10:00:00+03:00",
      "end": "2026-03-28T12:00:00+03:00",
      "is_past": false
    },
    "address": {
      "name": "Acme Depo",
      "country": {
        "id": 223,
        "code": "TR",
        "name": "Turkey",
        "iso2": "TR",
        "iso3": "TUR"
      },
      "state": {
        "id": 34,
        "name": "Istanbul",
        "stateCode": "34",
        "country": {
          "id": 223
        }
      },
      "city": {
        "id": 1,
        "name": "Sisli",
        "state": {
          "id": 34
        },
        "country": {
          "id": 223
        }
      },
      "address": "Maslak Mah. Buyukdere Cad. No:100",
      "formatted": "Maslak Mah. Buyukdere Cad. No:100, Sisli/Istanbul",
      "postalCode": "34485",
      "stateName": "Istanbul",
      "cityName": "Sisli"
    },
    "consignments": [
      {
        "id": 9988,
        "barcode": "C2H000123456",
        "reference_number": "REF-1001",
        "desi": 3.5,
        "weight": 2.1,
        "status": "pending",
        "tracking_code": null,
        "drop_off_event_at": null
      }
    ],
    "statistics": {
      "total_consignments": 1,
      "dropped_off_count": 0,
      "pending_count": 1,
      "progress_percentage": 0
    },
    "created_at": "2026-03-27T11:15:42+03:00",
    "updated_at": "2026-03-27T11:15:42+03:00"
  }
}

Hata Cevapları

Hata response yapısı:

{
  "status": false,
  "errors": [
    {
      "message": "string",
      "field": "string|null"
    }
  ]
}

400 - Validation Error (Örnek)

{
  "status": false,
  "errors": [
    {
      "message": "pickup.validation.appointment_end_after_start",
      "field": "appointment.end"
    },
    {
      "message": "pickup.validation.country_integer",
      "field": "address.countryId"
    }
  ]
}

400 - Domain Rule Error (Örnek)

{
  "status": false,
  "errors": [
    {
      "message": "Appointment window must be at least 30 minutes"
    }
  ]
}

401 - Authentication Error (Örnek)

{
  "status": false,
  "errors": [
    {
      "message": "Invalid credentials"
    }
  ]
}

404 - Consignment Not Found (Örnek)

{
  "status": false,
  "errors": [
    {
      "message": "Consignment not found with barcode: C2H000123456"
    }
  ]
}

Örnek Senaryolar

Senaryo 1: Tek gönderi için barcode ile pickup oluşturma

  • consignments listesinde tek eleman kullanılır.
  • type = "barcode" ve value = "{barcode}" gönderilir.
  • Başarılı işlemde 201 Created döner.

Senaryo 2: Birden fazla gönderi için karma identifier kullanımı

  • consignments listesinde birden fazla eleman gönderilir.
  • Her eleman için type farklı olabilir (id, barcode, reference).
  • Sistem tüm gönderileri doğrulayıp pickup oluşturur.