POST Upsert Internal Task
Introduction
Smart upsert endpoint for internal yard task management, designed for external system integration (e.g., Linkw). Accepts business-level identifiers (equipment number, carrier ID, load number, PO number) and internally resolves them to system IDs. If taskId is provided, the existing task is updated; otherwise, a new task is created.
Upon creation, the system automatically determines the yard action type (PRE_LOAD or DROP_OFF_RECEIVING) based on whether a load or receipt is provided, and delegates all task/entry-ticket/shuttle-task logic internally.
POST /public/internal-task/upsert
Body Request Parameters
{
"taskId": "string",
"equipmentNo": "string",
"externalCarrierId": "string",
"locationName": "string",
"assignee": "string",
"loadNo": "string",
"poNo": "string",
"shuttleTaskPosition": "BEFORE"
}Request Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
| X-Tenant-ID | header | string | Yes | none |
| X-Yard-ID | header | string | Yes | none |
| Item-Time-Zone | header | string | No | none |
| Authorization | header | string | Yes | none |
| body | body | object | No | none |
| » taskId | body | string | No | Task ID. If provided, updates the existing task; if omitted, creates a new task. |
| » equipmentNo | body | string | Yes | Equipment number. Combined with externalCarrierId to resolve the internal equipment ID. |
| » externalCarrierId | body | string | Yes | External carrier identifier. Combined with equipmentNo to resolve the internal equipment ID. |
| » locationName | body | string | No | Target location name. If omitted, the system will automatically recommend a location based on task type. |
| » assignee | body | string | No | Username to assign the task to. If provided, overrides any internally determined assignee. |
| » loadNo | body | string | No | Load number, resolved to internal load ID. Required if poNo is not provided (create mode only). |
| » poNo | body | string | No | Purchase order number, resolved to internal receipt ID. Required if loadNo is not provided (create mode only). |
| » shuttleTaskPosition | body | string | No | Controls when to create the shuttle task relative to this task. |
Detailed Description
» taskId: Task ID (optional)
Determines upsert mode. If taskId is provided and found, the existing task is updated (entry ticket is carried over). If not provided, a new task and entry ticket are created.
» equipmentNo + externalCarrierId: Equipment resolution
Both fields are required together. The system first resolves externalCarrierId to an internal carrier, then uses equipmentNo + carrierId to identify the specific equipment. A 400 Bad Request is returned if resolution fails.
» loadNo / poNo: Business reference
In create mode, at least one of loadNo or poNo must be provided. loadNo maps to a load (triggers PRE_LOAD action); poNo maps to a receipt (triggers DROP_OFF_RECEIVING action). If the resolved load or receipt already has an active task, the request is rejected.
» locationName: Location assignment
If provided, the specified location is used directly. If omitted, the system calls the location suggestion service based on the resolved action type (PRE_LOAD → pre-load zone; DROP_OFF_RECEIVING → drop-off receiving zone).
» shuttleTaskPosition: Shuttle task timing Controls when the shuttle task is created relative to this internal task.
Enum Values
| Property | Value |
|---|---|
| » shuttleTaskPosition | BEFORE |
| » shuttleTaskPosition | AFTER |
Response Example
200 Response
{
"code": 0,
"msg": "",
"success": true,
"data": {
"taskId": "TASK-20240101-001",
"locationName": "DOCK-A-01"
}
}Response
| Status Code | Definition | Description | Data Model |
|---|---|---|---|
| 200 | OK (opens in a new tab) | none | Inline |
Response Data Fields
| Field | Type | Description |
|---|---|---|
| taskId | string | ID of the created or updated task |
| locationName | string | Resolved location name (from request or auto-recommended) |