İçeriğe atla
Geliştirici dokümanlarıAPI referansıYükleme

Yükleme işi oluştur

İsteği doğrular, en kötü durumdaki fiyatı kredilerinizden rezerve eder ve işi kuyruğa alır.

POSThttps://runner.cargoduo.com/v1/pack

İşle birlikte 202 döner; durumu GET /v1/jobs/{id} ile sorgulayın ya da yanıtı iş bitene kadar bekletmek için ?wait= gönderin. Doğrulama hataları (422) ücretsizdir ve iş oluşturmaz.

Kimlik doğrulama

Bearer API anahtarı, gereken yetki:pack:writeDaha fazla bilgi

Sorgu parametreleri

AdTürZorunluAçıklama
waitinteger
integer
Hayır

İşin bitmesi için yanıtın bekletileceği süre (saniye). Zamanında biterse: sonucu içeren 200. Aksi halde: 202.

Varsayılan 00–60

Header parametreleri

AdTürZorunluAçıklama
Idempotency-Keystring
string
Hayır

UUID ya da sipariş numaranız gibi benzersiz herhangi bir dize. Aynı anahtar 24 saat içinde tekrar gönderilirse yeni bir iş oluşturulup ücretlendirilmez, ilk iş döner.

≤ 128 chars

Gövde parametreleri

application/json
AdTürZorunluAçıklama
referencestring
string
Hayır

Kendi referansınız (sipariş numarası, sevkiyat ID'si…). İşin yanıtında aynen geri döner.

≤ 128 chars
vehiclesVehicle[]zorunlu
Vehicle[]
Evet

Araç tanımları. Her birinde quantity > 1 olabilir. En az bir tane gerekir.

itemsItem[]zorunlu
Item[]
Evet

Öğe tanımları. Her birinde quantity > 1 olabilir. En az bir tane gerekir.

groupsGroup[]
Group[]
Hayır

İsteğe bağlı gruplar (müşteriler, duraklar, siparişler). options.group_routing değeri "none" değilse, öğelerin adını verdiği her grup için zorunludur; aksi halde gruplar, öğelerdeki grup adlarından görülme sırasına göre oluşturulur.

optionsOptions
Options
Hayır

Yükleme seçenekleri. Tüm alanlar isteğe bağlıdır.

Örnek istek

curl -X POST "https://runner.cargoduo.com/v1/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }'

Örnek yanıt

202 Accepted · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "created_at": "2026-10-19T09:12:03Z",
  "started_at": null,
  "finished_at": null,
  "progress": {
    "stage": "queued",
    "vehicles_done": 0,
    "placed_items": 0
  },
  "summary": {
    "items_requested": 58,
    "items_placed": 0,
    "items_unplaced": 0,
    "vehicles_used": 0,
    "total_weight": 0,
    "volume_utilization": 0,
    "queue_ms": 0,
    "compute_ms": 0
  },
  "cost": {
    "credits": 0,
    "reserved_credits": 1.11,
    "rate_card_version": 1,
    "breakdown": {
      "base": 0,
      "vehicles": 0,
      "compute": 0,
      "large_load": 0
    }
  },
  "error": null,
  "warnings": [],
  "result_url": "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f/result",
  "pdf_url": "",
  "expires_at": "2026-11-02T09:12:03Z"
}

Yanıtlar

  • 200OKİş ?wait süresi içinde bitti, sonuç yanıtın içinde. Tamamlanmış bir işin idempotent tekrarı da bu yanıtı alır.
    AdTürZorunluAçıklama
    idstringzorunlu
    string
    Evet

    İş ID'si (job_…).

    objectstringzorunlu
    string
    Evet

    Her zaman job.

    job
    statusstringzorunlu
    string
    Evet

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Hayır

    İstekte gönderdiğiniz referans.

    sourcestring
    string
    Hayır

    İşin oluşturulduğu yer.

    apiplayground
    project_idstring
    string
    Hayır

    POST /v1/projects/{id}/pack işinin planını kaydettiği proje (prj_…). Diğer işlerde bulunmaz.

    created_atstringzorunlu
    string
    Evet

    RFC 3339 zaman damgası.

    started_atstring | null
    string | null
    Hayır

    Hesaplamanın başladığı zaman (RFC 3339) ya da null.

    finished_atstring | null
    string | null
    Hayır

    İşin bittiği zaman (RFC 3339) ya da null.

    progressJobProgress
    JobProgress
    Hayır

    İş sıradayken ya da çalışırken anlık ilerleme.

    summaryJobSummary
    JobSummary
    Hayır

    Sayılar ve süreler.

    costJobCost
    JobCost
    Hayır

    Düşülen krediler (iş bitince kesinleşir) ve iş çalışırken tutulan rezervasyon.

    errorJobError | null
    JobError | null
    Hayır

    İşin neden başarısız olduğu ya da iptal edildiği; aksi halde null.

    warningsWarning[]
    Warning[]
    Hayır

    İstekle ilgili engelleyici olmayan uyarılar (sonuçta da yinelenir).

    result_urlstring
    string
    Hayır

    status değeri succeeded olduğunda tam sonuç için bu URL'ye GET isteği gönderin.

    pdf_urlstring
    string
    Hayır

    Yükleme planını PDF olarak oluşturan tarayıcı bağlantısı (3B görünümler + yükleme adımları). expires_at zamanına kadar geçerlidir. Süresi dolunca boştur.

    expires_atstring
    string
    Hayır

    İstek/sonuç gövdelerinin ve PDF bağlantısının silineceği zaman (RFC 3339). İşin meta verileri ve ücretleri saklanır.

    resultResult
    Result
    Hayır

    Tam sonuç; yalnızca istendiğinde (?include=result) ya da POST /v1/pack?wait= zamanında bittiğinde yanıtın içinde gelir.

  • 202Acceptedİş kabul edildi (sırada ya da çalışıyor).
    AdTürZorunluAçıklama
    idstringzorunlu
    string
    Evet

    İş ID'si (job_…).

    objectstringzorunlu
    string
    Evet

    Her zaman job.

    job
    statusstringzorunlu
    string
    Evet

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Hayır

    İstekte gönderdiğiniz referans.

    sourcestring
    string
    Hayır

    İşin oluşturulduğu yer.

    apiplayground
    project_idstring
    string
    Hayır

    POST /v1/projects/{id}/pack işinin planını kaydettiği proje (prj_…). Diğer işlerde bulunmaz.

    created_atstringzorunlu
    string
    Evet

    RFC 3339 zaman damgası.

    started_atstring | null
    string | null
    Hayır

    Hesaplamanın başladığı zaman (RFC 3339) ya da null.

    finished_atstring | null
    string | null
    Hayır

    İşin bittiği zaman (RFC 3339) ya da null.

    progressJobProgress
    JobProgress
    Hayır

    İş sıradayken ya da çalışırken anlık ilerleme.

    summaryJobSummary
    JobSummary
    Hayır

    Sayılar ve süreler.

    costJobCost
    JobCost
    Hayır

    Düşülen krediler (iş bitince kesinleşir) ve iş çalışırken tutulan rezervasyon.

    errorJobError | null
    JobError | null
    Hayır

    İşin neden başarısız olduğu ya da iptal edildiği; aksi halde null.

    warningsWarning[]
    Warning[]
    Hayır

    İstekle ilgili engelleyici olmayan uyarılar (sonuçta da yinelenir).

    result_urlstring
    string
    Hayır

    status değeri succeeded olduğunda tam sonuç için bu URL'ye GET isteği gönderin.

    pdf_urlstring
    string
    Hayır

    Yükleme planını PDF olarak oluşturan tarayıcı bağlantısı (3B görünümler + yükleme adımları). expires_at zamanına kadar geçerlidir. Süresi dolunca boştur.

    expires_atstring
    string
    Hayır

    İstek/sonuç gövdelerinin ve PDF bağlantısının silineceği zaman (RFC 3339). İşin meta verileri ve ücretleri saklanır.

    resultResult
    Result
    Hayır

    Tam sonuç; yalnızca istendiğinde (?include=result) ya da POST /v1/pack?wait= zamanında bittiğinde yanıtın içinde gelir.

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_jsonGövde geçerli bir JSON değil ya da bir alanın türü yanlış.
    • idempotency_key_invalidIdempotency-Key header'ı 128 karakterden uzun.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedAPI anahtarı eksik, hatalı biçimde ya da tanınmıyor.
    • key_revokedAnahtar iptal edildi.
    • key_expiredAnahtarın geçerlilik süresi doldu.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları
  • 402Payment requiredinsufficient_credits
    • insufficient_creditsKullanılabilir krediler, bu işin olabilecek en düşük maliyetini bile karşılamıyor.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedİsteği gönderen IP, anahtarın izin listesinde değil.
    • subscription_inactiveOrganizasyonun API'yi içeren etkin bir aboneliği yok.
    • account_inactiveOrganizasyon askıya alınmış ya da hesabı etkin olan bir organizasyon sahibi yok.
    • scope_missingAnahtarda bu endpoint'in gerektirdiği bir yetki eksik.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları
  • 413Payload too largepayload_too_large
    • payload_too_largeİstek gövdesi 10 MB sınırını aşıyor.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları
  • 422Unprocessable entityvalidation_failed
    • validation_failedİstek geçerli bir JSON ama geçersiz bir iş tanımlıyor. Tüm sorunlar details[] içinde listelenir.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları
  • 429Too many requeststoo_many_jobsrate_limited
    • too_many_jobsOrganizasyonun sıradaki + çalışan iş sayısı zaten üst sınırda.
    • rate_limitedGeçerli dakika, saat ya da gün içinde çok fazla istek gönderildi (anahtar ya da organizasyon başına) veya IP adresinizden gelen başarısız kimlik doğrulama denemeleri dakikada 60 sınırını aştı.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları
  • 500Internal server errorinternal_error
    • internal_errorBizim tarafımızda bir hata oluştu.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları
  • 503Service unavailableapi_disabled
    • api_disabledAPI geçici olarak devre dışı (bakım) ya da organizasyon için kapatılmış.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları