Skip to content

update_load_status.md

Latest commit

 

History

History
46 lines (33 loc) · 2.21 KB

update_load_status.md

File metadata and controls

46 lines (33 loc) · 2.21 KB
Raw

update_load_status

Not part of the API. Every call returns HTTP 501 OPERATION_NOT_AVAILABLE. The tool exists (and is documented honestly) so that agents learn the contract from the description instead of burning a call to discover it.

Price: none (nothing happens).

API equivalent: PATCH /v1/agent/loads/{loadNumber}/status · SDK: updateStatus(loadNumber, status) — throws ApiError with .status === 501.

Why it doesn't exist

PingPoint owns the load lifecycle. Statuses advance automatically from driver GPS and geofence events (PLANNED → AT_PICKUP → IN_TRANSIT → AT_DELIVERY → DELIVERED), so a status can never be hand-set or spoofed: every status you read from get_load_position is backed by the truck's recorded position. See architecture for how the geofence engine drives transitions.

What to do instead

  • The load is finished → nothing to do. Delivery closes on its own when the truck departs the last delivery zone.
  • The load is off → cancel_load (free).
  • Proof of delivery → not a vendor operation. The BOL travels through the carrier flow (the carrier sends it over Telegram), and that route answers 501 here too.

Parameters

Parameter Type Required Meaning
loadNumber string yes
status enum yes PLANNED, AT_PICKUP, IN_TRANSIT, AT_DELIVERY, DELIVERED, CANCELLED — accepted by the schema, refused by the server.

Response

Always (HTTP 501):

{
  "code": "OPERATION_NOT_AVAILABLE",
  "operation": "update status",
  "error": "'update status' is not available yet on this deployment. This is not a problem with your request or your key. Load statuses advance automatically from the driver's GPS geofence, and delivery is closed on arrival at the delivery stop, so neither operation is needed to run a load. Nothing was charged.",
  "available": [
    "POST /v1/agent/loads",
    "GET /v1/agent/loads/{loadNumber}",
    "GET /v1/agent/loads/{loadNumber}/trip-stats",
    "POST /v1/agent/loads/{loadNumber}/cancel",
    "GET /v1/agent/pricing",
    "GET /v1/agent/balance"
  ]
}

Do not retry — this is the designed behavior, not an outage.