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

Projeyi hesapla

Projenin araçları ve öğeleri için yükleme planını tıpkı POST /v1/pack gibi hesaplar: aynı fiyat, kredi rezervasyonu, limitler, Idempotency-Key, ?wait= ve iş.

POSThttps://runner.cargoduo.com/v1/projects/{id}/pack

İş başarıyla tamamlandığında planı projeye kaydedilir ve proje uygulamada bu planla açılır. İş çalışırken proje değiştiyse plan yalnızca işte kalır (project_not_saved uyarısı). Sonuçtaki ID'ler projeye aittir: vehicle_id slot ID'sidir (pv_…), item_id ise öğe ID'si (item_…).

Kimlik doğrulama

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

Yol parametreleri

AdTürZorunluAçıklama
idstringzorunlu
string
Evet

Proje ID'si (prj_…).

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

Referansınız; işin yanıtında aynen geri döner. Varsayılan: proje adı.

≤ 128 chars
optionsProjectPackOptions
ProjectPackOptions
Hayır

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

Örnek istek

curl -X POST "https://runner.cargoduo.com/v1/projects/prj_3051/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042"
  }'

Örnek yanıt

202 Accepted · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "project_id": "prj_3051",
  "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ı
  • 404Not foundproject_not_found
    • project_not_foundOrganizasyonunuzda bu ID'ye sahip bir proje yok.
    AdTürZorunluAçıklama
    errorErrorBodyzorunlu
    ErrorBody
    Evet
    Tüm hata kodları
  • 409Conflictproject_busy
    • project_busyProje şu anda hesaplanıyor (uygulamada ya da başka bir iş tarafından).
    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ı