Tracking API

Show your customers where their package is. Fetch the same tracking timeline, per-package progress and proofs you see in your panel.

GET/tracking/{tracking_number}

Track by tracking number

Get the full tracking record for an order using its 4N NextDay tracking number. Merchant tokens can only see their own orders; anything else is reported as not found.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number: 4N or SH followed by 12 digits (e.g. 4N202502030001). Required.

Response Fields

Name
tracking_number
Type
string
Description
The order tracking number.
Name
delivery_state
Type
string
Description
Current state: pending, picked_up, in_transit, out_for_delivery, partially_delivered, delivered, closed_with_return, failed or nulled.
Name
estimated_delivery_date
Type
string|null
Description
Expected delivery date (ISO 8601).
Name
delivery_date
Type
string|null
Description
Actual delivery date, once delivered.
Name
packages_count
Type
integer
Description
Total number of packages in the order.
Name
picked_up_packages_count
Type
integer
Description
Packages collected from the sender.
Name
pending_pickup_packages_count
Type
integer
Description
Packages not yet collected.
Name
delivered_packages_count
Type
integer
Description
Packages handed to the recipient.
Name
failed_packages_count
Type
integer
Description
Packages whose last delivery attempt failed.
Name
returned_packages_count
Type
integer
Description
Packages returned to the sender.
Name
pending_packages_count
Type
integer
Description
Packages with no delivery outcome yet.
Name
timeline
Type
array
Description
State changes in chronological order, starting with pending at creation. Each entry has state and timestamp; failure entries add type: "failure" and failure_info.
Name
delivery_proof
Type
object|null
Description
Proof of delivery. Present when delivery_state is delivered or partially_delivered and a proof was recorded; null otherwise.
Name
pickup_proof
Type
object|null
Description
Proof captured when the order was collected from the sender. Same shape as failure_proof (no recipient fields). null until a photographed pickup proof exists.
Name
failure_proof
Type
object|null
Description
Proof captured at the failed delivery attempt — location, notes, photos, created_at. No recipient fields (it documents the scene, not a signee). Present only when delivery_state is failed and photos were captured; null otherwise.
Name
delivery_attempts
Type
array
Description
One record per visit to the recipient, oldest first. See below.
Name
packages
Type
array
Description
Per-package progress. See below.

Timeline entry

Name
state
Type
string
Description
The delivery state reached at this point.
Name
timestamp
Type
string
Description
When it happened (ISO 8601).
Name
type
Type
string
Description
Only on failure entries. Always failure.
Name
failure_info
Type
object
Description
Only on failure entries. type (display label, platform language), reason (normally one of not_home, refused, wrong_address, inaccessible, business_closed, pending_stock_break, no_cargo_ready, no_cargo_to_ship, customer_unavailable, other) and notes (driver notes or null).

Proof blocks

delivery_proof, pickup_proof and failure_proof share these fields. Photo links are signed and valid for 60 minutes.

Name
recipient_name
Type
string|null
Description
delivery_proof only. Who received the package.
Name
recipient_rut
Type
string|null
Description
delivery_proof only. Their Chilean ID, if captured.
Name
recipient_role
Type
string|null
Description
delivery_proof only. merchant_staff, recipient, operator or other.
Name
location
Type
object|null
Description
latitude and longitude where the proof was recorded.
Name
notes
Type
string|null
Description
Driver notes.
Name
photos
Type
array
Description
Objects with url (full size) and preview_url (thumbnail).
Name
created_at
Type
string
Description
When the proof was recorded.

Delivery attempt

Photo links inside attempts are signed and valid for 2 hours.

Name
attempt
Type
integer
Description
1-based attempt number.
Name
outcome
Type
string
Description
success or failed.
Name
recipient_name
Type
string|null
Description
Who received the package, on successful attempts.
Name
recipient_rut
Type
string|null
Description
Their Chilean ID, if captured.
Name
recipient_role
Type
string|null
Description
merchant_staff, recipient, operator or other.
Name
location
Type
object|null
Description
latitude and longitude.
Name
notes
Type
string|null
Description
Driver notes.
Name
photos
Type
array
Description
Objects with url and preview_url.
Name
packages
Type
array
Description
Per-package outcome: tracking_number, delivered (boolean) and failure_reason (a reason code, or null when delivered).
Name
created_at
Type
string
Description
When the attempt was recorded.

Package

Name
tracking_number
Type
string
Description
Package tracking number: the order's number plus a 3-digit suffix (4N202502030001-001).
Name
delivery_state
Type
string
Description
pending, delivered, failed or returned.
Name
picked_up_at
Type
string|null
Description
When it was collected from the sender.
Name
delivered_at
Type
string|null
Description
When it was delivered.
Name
returned_at
Type
string|null
Description
When it was returned to the sender.

GET

/tracking/{tracking_number}

curl https://api.4nortes.app/api/v1/tracking/4N202502030001 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Response — delivered on the second attempt

{
  "success": true,
  "message": "Operation successful",
  "data": {
    "tracking_number": "4N202502030001",
    "delivery_state": "delivered",
    "estimated_delivery_date": "2025-02-04T00:00:00.000000Z",
    "delivery_date": "2025-02-05T11:30:00.000000Z",
    "packages_count": 2,
    "picked_up_packages_count": 2,
    "pending_pickup_packages_count": 0,
    "delivered_packages_count": 2,
    "failed_packages_count": 0,
    "returned_packages_count": 0,
    "pending_packages_count": 0,
    "timeline": [
      { "state": "pending", "timestamp": "2025-02-03T10:00:00.000000Z" },
      { "state": "picked_up", "timestamp": "2025-02-03T14:30:00.000000Z" },
      { "state": "in_transit", "timestamp": "2025-02-03T18:00:00.000000Z" },
      { "state": "out_for_delivery", "timestamp": "2025-02-04T08:00:00.000000Z" },
      {
        "state": "failed",
        "timestamp": "2025-02-04T11:05:00.000000Z",
        "type": "failure",
        "failure_info": {
          "type": "Entrega fallida",
          "reason": "not_home",
          "notes": "Nobody answered the door"
        }
      },
      { "state": "failed", "timestamp": "2025-02-04T11:05:01.000000Z" },
      { "state": "out_for_delivery", "timestamp": "2025-02-05T08:30:00.000000Z" },
      { "state": "delivered", "timestamp": "2025-02-05T11:30:00.000000Z" }
    ],
    "delivery_proof": {
      "recipient_name": "Jane Doe",
      "recipient_rut": "12345678-9",
      "recipient_role": "recipient",
      "location": { "latitude": -33.4289, "longitude": -70.6093 },
      "notes": null,
      "photos": [
        {
          "url": "https://storage.example.com/proofs/d41d8c.jpg?signature=...",
          "preview_url": "https://storage.example.com/proofs/d41d8c-preview.jpg?signature=..."
        }
      ],
      "created_at": "2025-02-05T11:30:00.000000Z"
    },
    "pickup_proof": {
      "location": { "latitude": -33.4372, "longitude": -70.6506 },
      "notes": null,
      "photos": [
        {
          "url": "https://storage.example.com/proofs/7f3a9b.jpg?signature=...",
          "preview_url": "https://storage.example.com/proofs/7f3a9b-preview.jpg?signature=..."
        }
      ],
      "created_at": "2025-02-03T14:30:00.000000Z"
    },
    "failure_proof": null,
    "delivery_attempts": [
      {
        "attempt": 1,
        "outcome": "failed",
        "recipient_name": null,
        "recipient_rut": null,
        "recipient_role": null,
        "location": { "latitude": -33.4291, "longitude": -70.6090 },
        "notes": "Nobody answered the door",
        "photos": [
          {
            "url": "https://storage.example.com/proofs/0c1e2f.jpg?signature=...",
            "preview_url": "https://storage.example.com/proofs/0c1e2f-preview.jpg?signature=..."
          }
        ],
        "packages": [
          { "tracking_number": "4N202502030001-001", "delivered": false, "failure_reason": "not_home" },
          { "tracking_number": "4N202502030001-002", "delivered": false, "failure_reason": "not_home" }
        ],
        "created_at": "2025-02-04T11:05:00.000000Z"
      },
      {
        "attempt": 2,
        "outcome": "success",
        "recipient_name": "Jane Doe",
        "recipient_rut": "12345678-9",
        "recipient_role": "recipient",
        "location": { "latitude": -33.4289, "longitude": -70.6093 },
        "notes": null,
        "photos": [
          {
            "url": "https://storage.example.com/proofs/d41d8c.jpg?signature=...",
            "preview_url": "https://storage.example.com/proofs/d41d8c-preview.jpg?signature=..."
          }
        ],
        "packages": [
          { "tracking_number": "4N202502030001-001", "delivered": true, "failure_reason": null },
          { "tracking_number": "4N202502030001-002", "delivered": true, "failure_reason": null }
        ],
        "created_at": "2025-02-05T11:30:00.000000Z"
      }
    ],
    "packages": [
      {
        "tracking_number": "4N202502030001-001",
        "delivery_state": "delivered",
        "picked_up_at": "2025-02-03T14:30:00.000000Z",
        "delivered_at": "2025-02-05T11:30:00.000000Z",
        "returned_at": null
      },
      {
        "tracking_number": "4N202502030001-002",
        "delivery_state": "delivered",
        "picked_up_at": "2025-02-03T14:30:00.000000Z",
        "delivered_at": "2025-02-05T11:30:00.000000Z",
        "returned_at": null
      }
    ]
  },
  "timestamp": "2025-02-05T12:00:00.000000Z"
}

Errors

Name
404 Not Found
Description
No order with that tracking number — or it belongs to another account. Standard error envelope.
Name
422 Unprocessable Entity
Description
The path value doesn't match 4N/SH + 12 digits. Raw validation body (no envelope).

See Error Handling for the two response shapes.

404 Not Found

{
  "success": false,
  "message": "Tracking number not found.",
  "errors": null,
  "timestamp": "2025-02-05T12:00:00.000000Z"
}

422 — malformed tracking number

{
  "message": "The tracking number format is invalid.",
  "errors": {
    "tracking_number": ["The tracking number format is invalid."]
  }
}