EntwicklerdokumentationAPI-ReferenzProjekte

Projekt aktualisieren

Benennt ein Projekt um, ändert seine Optionen oder ersetzt seine Fahrzeuge oder seine Artikel (mit Gruppen).

PATCHhttps://runner.cargoduo.com/v1/projects/{id}

Werden Fahrzeuge oder Artikel ersetzt, wird der gespeicherte Plan gelöscht; offene App-Sitzungen laden neu. Kostenlos: Es werden keine Credits abgebucht.

Authentifizierung

Bearer-API-Schlüssel mit Berechtigungresources:writeMehr erfahren

Pfadparameter

NameTypErforderlichBeschreibung

idstringerforderlich

string

Projekt-ID (prj_…).

Body-Parameter

application/json

NameTypErforderlichBeschreibung

namestring

string

Nein

≤ 255 chars

vehiclesProjectVehicle[]

ProjectVehicle[]

Nein

Fahrzeug-Slots.

idstring

string

Nein

Slot-ID (pv_…). Ergebnisse der Jobs des Projekts verweisen darauf als vehicle_id. Schreibgeschützt.

vehicle_idstringerforderlich

string

Eine Fahrzeug-ID aus GET /v1/vehicles (vordefiniert oder veh_…).

namestring

string

Nein

Name des gespeicherten Fahrzeugs. Schreibgeschützt.

typestring

string

Nein

Typ des gespeicherten Fahrzeugs. Schreibgeschützt.

trucktrailerflatbedcontainerpalletaircraftship

lengthnumber · cm

number · cm

Nein

Der Wert, mit dem der Slot geplant wird; gesendet, überschreibt er den des gespeicherten Fahrzeugs.

widthnumber · cm

number · cm

Nein

Der Wert, mit dem der Slot geplant wird; gesendet, überschreibt er den des gespeicherten Fahrzeugs.

heightnumber · cm

number · cm

Nein

Der Wert, mit dem der Slot geplant wird; gesendet, überschreibt er den des gespeicherten Fahrzeugs.

max_weightnumber · kg

number · kg

Nein

Der Wert, mit dem der Slot geplant wird; gesendet, überschreibt er den des gespeicherten Fahrzeugs.

quantityinteger

integer

Nein

Wie viele identische Fahrzeuge dieser Definition verfügbar sind.

Standard 11–100

aux_deckboolean

boolean

Nein

Das Fahrzeug hat eine zweite Ladeebene (Doppelstock).

Standard false

aux_deck_heightnumber · cm

number · cm

Nein

Höhe der zweiten Ebene über dem Boden. Erforderlich, wenn aux_deck true ist.

aux_deck_max_weightnumber · kg

number · kg

Nein

Lastgrenze der zweiten Ebene. Erforderlich, wenn aux_deck true ist.

blocked_areasRect[]

Rect[]

Nein

Bodenbereiche, auf denen nichts stehen darf (Radkästen, Schäden, reservierter Platz). Jeder Bereich muss auf dem Fahrzeugboden liegen.

≤ 32 items

tractor_weightFreischaltung nötignumber · kg

number · kg

Nein

Achsmodell Sattelzug: Gewicht der Zugmaschine.

empty_trailer_weightFreischaltung nötignumber · kg

number · kg

Nein

Achsmodell Sattelzug: Leergewicht des Aufliegers.

front_axle_to_middle_axleFreischaltung nötignumber · cm

number · cm

Nein

Achsmodell Sattelzug: Vorderachse der Zugmaschine bis Antriebsachse (Mittelachse).

front_axle_to_tractor_cogFreischaltung nötignumber · cm

number · cm

Nein

Achsmodell Sattelzug: Vorderachse bis Schwerpunkt der Zugmaschine.

front_axle_to_kingpinFreischaltung nötignumber · cm

number · cm

Nein

Achsmodell Sattelzug: Vorderachse bis Königszapfen (Sattelkupplung).

kingpin_to_rear_axleFreischaltung nötignumber · cm

number · cm

Nein

Achsmodell Sattelzug: Königszapfen bis Hinterachsgruppe des Aufliegers.

trailer_cog_to_rear_axleFreischaltung nötignumber · cm

number · cm

Nein

Achsmodell Sattelzug: Schwerpunkt des Aufliegers bis Hinterachsgruppe.

trailer_start_to_kingpinFreischaltung nötignumber · cm

number · cm

Nein

Achsmodell Sattelzug: Aufliegervorderkante bis Königszapfen.

max_middle_axle_weightFreischaltung nötignumber · kg

number · kg

Nein

Achsmodell Sattelzug: zulässige Last der Antriebsachse (Mittelachse).

max_rear_axle_weightFreischaltung nötignumber · kg

number · kg

Nein

Achsmodell Sattelzug: zulässige Last der Hinterachsgruppe.

itemsItem[]

Item[]

Nein

Artikel (höchstens 500 Definitionen).

idstring

string

Nein

Ihre Kennung, eindeutig innerhalb der Anfrage. Ergebnisse verweisen darauf als item_id. Standard: template_id.

≤ 128 chars

template_idstring

string

Nein

Eine Vorlagen-ID (tpl_…) aus GET /v1/templates. Liefert alle Artikelfelder; daneben gesendete Felder überschreiben sie.

labelstring

string

Nein

Bezeichnung (Standard: die ID).

≤ 255 chars

shapestring

string

Nein

Form des Artikels. cylinder und drum verwenden radius + height statt length + width; pallet und drum stehen immer aufrecht.

boxcylinderpalletbagdrumStandard "box"

lengthnumber · cm

number · cm

Nein

Länge. Erforderlich, sofern shape nicht cylinder oder drum ist.

widthnumber · cm

number · cm

Nein

Breite. Erforderlich, sofern shape nicht cylinder oder drum ist.

heightnumber · cmerforderlich

number · cm

Höhe (die senkrechte Seite, wenn der Artikel wie definiert steht).

radiusnumber · cm

number · cm

Nein

Radius. Erforderlich, wenn shape cylinder oder drum ist.

weightnumber · kgerforderlich

number · kg

Gewicht EINER Einheit.

quantityinteger

integer

Nein

Anzahl identischer Einheiten.

Standard 11–10000

stackableboolean

boolean

Nein

Andere Artikel dürfen auf diesen gestellt werden.

Standard true

max_stack_weightnumber · kg

number · kg

Nein

Maximales Gewicht, das auf einer Einheit lasten darf. 0 = unbegrenzt.

Standard 0

rotationstring

string

Nein

all = jede der sechs Ausrichtungen; upright = darf nur um die senkrechte Achse gedreht werden (diese Seite oben); fixed = wird nie gedreht.

alluprightfixedStandard "all"

hazardousboolean

boolean

Nein

Gefahrgut: wird niedrig und getrennt von anderem Gefahrgut platziert.

Standard false

priorityinteger

integer

Nein

Ladepriorität. Höher = wird zuerst geladen und bei Platzmangel bevorzugt mitgenommen. 0 = keine.

Standard 0

groupstring

string

Nein

Name der Gruppe, zu der dieser Artikel gehört (siehe groups und options.group_routing).

colorstring

string

Nein

Anzeigefarbe als #rrggbb (nur 3D-Ansicht und PDF).

nesting_heightnumber · cm

number · cm

Nein

Überlappung, wenn identische Einheiten ineinander gestapelt werden (verschachtelte Kisten, Eimer).

Standard 0

groupsGroup[]

Group[]

Nein

Gruppen mit ihrer Ladereihenfolge.

optionsProjectOptions

ProjectOptions

Nein

Die Ladeoptionen, die ein Projekt speichert.

Beispielanfrage

curl -X PATCH "https://runner.cargoduo.com/v1/projects/prj_3051" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicles": [
      {
        "vehicle_id": "veh_118",
        "quantity": 2
      }
    ]
  }'

const res = await fetch("https://runner.cargoduo.com/v1/projects/prj_3051", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CARGODUO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "vehicles": [
      {
        "vehicle_id": "veh_118",
        "quantity": 2
      }
    ]
  }),
});

const data = await res.json();
console.log(res.status, data);

import os
import requests

response = requests.patch(
    "https://runner.cargoduo.com/v1/projects/prj_3051",
    headers={"Authorization": f"Bearer {os.environ['CARGODUO_API_KEY']}"},
    json={
        "vehicles": [
            {
                "vehicle_id": "veh_118",
                "quantity": 2,
            },
        ],
    },
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "vehicles": [
    {
      "vehicle_id": "veh_118",
      "quantity": 2
    }
  ]
}`)

	req, err := http.NewRequest("PATCH", "https://runner.cargoduo.com/v1/projects/prj_3051", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CARGODUO_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "vehicles": [
                {
                  "vehicle_id": "veh_118",
                  "quantity": 2
                }
              ]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://runner.cargoduo.com/v1/projects/prj_3051"))
            .header("Authorization", "Bearer " + System.getenv("CARGODUO_API_KEY"))
            .header("Content-Type", "application/json")
            .method("PATCH", HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("CARGODUO_API_KEY"));

var json = """
    {
      "vehicles": [
        {
          "vehicle_id": "veh_118",
          "quantity": 2
        }
      ]
    }
    """;

var request = new HttpRequestMessage(HttpMethod.Patch, "https://runner.cargoduo.com/v1/projects/prj_3051")
{
    Content = new StringContent(json, Encoding.UTF8, "application/json"),
};
var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

<?php

$payload = <<<'JSON'
{
  "vehicles": [
    {
      "vehicle_id": "veh_118",
      "quantity": 2
    }
  ]
}
JSON;

$ch = curl_init('https://runner.cargoduo.com/v1/projects/prj_3051');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CARGODUO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

require "net/http"
require "uri"

uri = URI("https://runner.cargoduo.com/v1/projects/prj_3051")
request = Net::HTTP::Patch.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("CARGODUO_API_KEY")}"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
  {
    "vehicles": [
      {
        "vehicle_id": "veh_118",
        "quantity": 2
      }
    ]
  }
JSON

response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
puts response.code, response.body

Beispielantwort

200 OK · Project

{
  "id": "prj_3051",
  "object": "project",
  "name": "Order 1042",
  "status": "draft",
  "item_count": 58,
  "vehicle_count": 2,
  "app_url": "https://app.cargoduo.com/projects/3051",
  "created_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "updated_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "created_at": "2026-10-19T09:10:03Z",
  "updated_at": "2026-10-19T09:22:03Z",
  "options": {
    "packing_mode": "auto",
    "group_routing": "none",
    "allow_overweight": false
  },
  "vehicles": [
    {
      "id": "pv_5121",
      "vehicle_id": "veh_118",
      "name": "Mega trailer 13.6 m",
      "type": "trailer",
      "quantity": 2,
      "length": 1360,
      "width": 248,
      "height": 300,
      "max_weight": 24000
    }
  ],
  "items": [
    {
      "id": "item_88410",
      "label": "Euro pallet",
      "shape": "box",
      "length": 120,
      "width": 80,
      "height": 140,
      "weight": 450,
      "quantity": 18,
      "stackable": false,
      "rotation": "all",
      "color": "#3b82f6"
    },
    {
      "id": "item_88411",
      "label": "Carton A",
      "shape": "box",
      "length": 60,
      "width": 40,
      "height": 40,
      "weight": 12,
      "quantity": 40,
      "stackable": true,
      "rotation": "upright",
      "color": "#f59e0b"
    }
  ],
  "groups": [],
  "plan": null
}

Antworten

200OKDas Projekt nach der Änderung.Project
NameTypErforderlichBeschreibung
idstring
string
Nein
Projekt-ID (prj_…).
objectstring
string
Nein
project
namestring
string
Nein
statusstring
string
Nein
draft = nie berechnet oder Eingaben ersetzt; calculated = hat einen aktuellen Plan; stale = seit der Erstellung des Plans wurde eine Einstellung geändert.
draftcalculatedstaleerror
item_countinteger
integer
Nein
Artikeleinheiten (Summe der Mengen).
vehicle_countinteger
integer
Nein
Fahrzeuge (Summe der Mengen).
app_urlstring
string
Nein
Öffnet das Projekt im 3D-Editor der App.
created_byUserRef | null
UserRef | null
Nein
Das Mitglied, das es erstellt hat (bei API-Aufrufen: das Mitglied, das den Schlüssel erstellt hat). null, wenn unbekannt.
updated_byUserRef | null
UserRef | null
Nein
Das Mitglied, das es zuletzt geändert hat.
created_atstring
string
Nein
RFC 3339.
updated_atstring
string
Nein
RFC 3339.
optionsProjectOptions
ProjectOptions
Nein
Die Ladeoptionen, die ein Projekt speichert.
vehiclesProjectVehicle[]
ProjectVehicle[]
Nein
itemsItem[]
Item[]
Nein
Ladung im Item-Format von /v1/pack; IDs sind item_….
groupsGroup[]
Group[]
Nein
planProjectPlan | null
ProjectPlan | null
Nein
Der aktuelle Plan; null, wenn das Projekt keinen hat.
400Bad requestinvalid_jsonError
- invalid_jsonDer Body ist kein gültiges JSON, oder ein Feld hat den falschen Typ.
NameTypErforderlichBeschreibung
errorErrorBodyerforderlich
ErrorBody
Ja
Alle Fehlercodes
401Unauthorizedunauthorizedkey_revokedkey_expiredError
- unauthorizedAPI-Schlüssel fehlt, ist fehlerhaft oder unbekannt.
- key_revokedDer Schlüssel wurde widerrufen.
- key_expiredDer Schlüssel ist abgelaufen.
NameTypErforderlichBeschreibung
errorErrorBodyerforderlich
ErrorBody
Ja
Alle Fehlercodes
403Forbiddenplan_limit_reachedip_not_allowedsubscription_inactiveaccount_inactivescope_missingError
- plan_limit_reachedDer Tarif der Organisation erlaubt keine weiteren Projekte oder Artikel.
- ip_not_allowedDie aufrufende IP-Adresse steht nicht auf der Allowlist des Schlüssels.
- subscription_inactiveDie Organisation hat kein aktives Abonnement, das die API enthält.
- account_inactiveDie Organisation ist gesperrt oder hat keinen Inhaber mit aktivem Konto.
- scope_missingDem Schlüssel fehlt eine Berechtigung, die dieser Endpoint benötigt.
NameTypErforderlichBeschreibung
errorErrorBodyerforderlich
ErrorBody
Ja
Alle Fehlercodes
404Not foundproject_not_foundError
- project_not_foundKein Projekt mit dieser ID in Ihrer Organisation.
NameTypErforderlichBeschreibung
errorErrorBodyerforderlich
ErrorBody
Ja
Alle Fehlercodes
413Payload too largepayload_too_largeError
- payload_too_largeDer Anfrage-Body ist größer als 10 MB.
NameTypErforderlichBeschreibung
errorErrorBodyerforderlich
ErrorBody
Ja
Alle Fehlercodes
422Unprocessable entityvalidation_failedError
- validation_failedDie Anfrage ist wohlgeformtes JSON, beschreibt aber einen ungültigen Job. details[] listet alle Probleme auf.
NameTypErforderlichBeschreibung
errorErrorBodyerforderlich
ErrorBody
Ja
Alle Fehlercodes
429Too many requestsrate_limitedError
- rate_limitedZu viele Anfragen in der aktuellen Minute, Stunde oder am aktuellen Tag (pro Schlüssel oder pro Organisation) oder mehr als 60 fehlgeschlagene Authentifizierungen pro Minute von Ihrer IP-Adresse.
NameTypErforderlichBeschreibung
errorErrorBodyerforderlich
ErrorBody
Ja
Alle Fehlercodes
500Internal server errorinternal_errorError
- internal_errorAuf unserer Seite ist ein Fehler aufgetreten.
NameTypErforderlichBeschreibung
errorErrorBodyerforderlich
ErrorBody
Ja
Alle Fehlercodes
503Service unavailableapi_disabledError
- api_disabledDie API ist vorübergehend deaktiviert (Wartung) oder für die Organisation abgeschaltet.
NameTypErforderlichBeschreibung
errorErrorBodyerforderlich
ErrorBody
Ja
Alle Fehlercodes

GETProjekt abrufenEin Projekt mit Fahrzeugen, Artikeln, Gruppen, Optionen und einer Zusammenfassung des aktuellen Plans (mit PDF-Link, solange es der von einem API-Job gespeicherte Plan ist).POSTProjekt berechnenBerechnet die Fahrzeuge und Artikel des Projekts genau wie POST /v1/pack: gleicher Preis, gleiche Credit-Reservierung, Limits, Idempotency-Key, ?wait= und Job.

Authentifizierung

Pfadparameter

Body-Parameter

Beispielanfrage

Beispielantwort

Antworten

Siehe auch