Orders API

Sync orders from your system, download shipping labels, and manage shipments. Everything you do in your panel, now automated.

POST/orders/create

Sync an order

Send order details from your system. This is the same as filling out the "Create Order" form in your panel.

Request Body

Name
sender_name
Type
string
Description
Name of the sender or business. Max 255 characters. Required.
Name
sender_phone
Type
string
Description
Sender phone number. Max 50 characters.
Name
sender_email
Type
string
Description
Sender email address.
Name
sender_company
Type
string
Description
Sender company name.
Name
recipient_name
Type
string
Description
Name of the recipient. Max 255 characters. Required.
Name
recipient_phone
Type
string
Description
Recipient phone number.
Name
recipient_email
Type
string
Description
Recipient email address.
Name
recipient_company
Type
string
Description
Recipient company name.
Name
destination_address
Type
string
Description
Destination street address. Required.
Name
destination_locality
Type
string
Description
Destination locality (comuna) name. Required.
Name
destination_reference
Type
string
Description
Reference or landmark for the destination.
Name
destination_building_number
Type
string
Description
Building or apartment number at destination.
Name
external_reference
Type
string
Description
Your custom order reference for tracking in your system.
Name
service_id
Type
integer
Description
Delivery service type ID.
Name
weight
Type
number
Description
Package weight in kilograms. Must be >= 0.
Name
valuation
Type
number
Description
Declared value of the package.
Name
packages_count
Type
integer
Description
Number of packages in this order.

POST

/orders/create

curl -X POST https://api.4nortes.app/api/v1/orders/create \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_name": "John Store",
    "sender_phone": "+56912345678",
    "sender_email": "store@example.com",
    "recipient_name": "Jane Doe",
    "recipient_phone": "+56987654321",
    "recipient_email": "jane@example.com",
    "destination_address": "Calle Secundaria 456",
    "destination_locality": "Providencia",
    "destination_reference": "Near the plaza",
    "weight": 2.5,
    "external_reference": "ORDER-001",
    "service_id": 1,
    "packages_count": 1
  }'

Response

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "id": 12345,
    "tracking_number": "4N000000012345",
    "external_reference": "ORDER-001",
    "delivery_state": "pending",
    "merchant_id": 1,
    "service_id": 1,
    "sender_name": "John Store",
    "sender_phone": "+56912345678",
    "sender_email": "store@example.com",
    "recipient_name": "Jane Doe",
    "recipient_phone": "+56987654321",
    "recipient_email": "jane@example.com",
    "destination": {
      "address": "Calle Secundaria 456",
      "locality": "Providencia",
      "reference": "Near the plaza",
      "building_number": null
    },
    "packages_count": 1,
    "weight": 2.5,
    "valuation": null,
    "estimated_delivery_date": "2025-02-05",
    "created_at": "2025-02-03T10:30:00.000000Z"
  },
  "timestamp": "2025-02-03T10:30:00.000000Z"
}

GET/orders/{tracking_number}

Get order details

Fetch order details using the tracking number. Same info you see when clicking an order in your panel.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number (e.g., 4N000000012345). Required.

GET

/orders/{tracking_number}

curl https://api.4nortes.app/api/v1/orders/4N000000012345 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Order retrieved successfully",
  "data": {
    "id": 12345,
    "tracking_number": "4N000000012345",
    "external_reference": "ORDER-001",
    "delivery_state": "in_transit",
    "internal_state": "in_transit",
    "merchant_id": 1,
    "service_id": 1,
    "sender_name": "John Store",
    "sender_phone": "+56912345678",
    "sender_email": "store@example.com",
    "recipient_name": "Jane Doe",
    "recipient_phone": "+56987654321",
    "recipient_email": "jane@example.com",
    "destination": {
      "address": "Calle Secundaria 456",
      "locality": "Providencia",
      "reference": "Near the plaza",
      "building_number": null
    },
    "packages_count": 1,
    "weight": 2.5,
    "valuation": null,
    "estimated_delivery_date": "2025-02-05",
    "timeline": [
      {
        "state": "pending",
        "timestamp": "2025-02-03T10:30:00.000000Z",
        "type": "state_change",
        "failure_info": null
      },
      {
        "state": "picked_up",
        "timestamp": "2025-02-03T14:30:00.000000Z",
        "type": "state_change",
        "failure_info": null
      },
      {
        "state": "in_transit",
        "timestamp": "2025-02-03T18:00:00.000000Z",
        "type": "state_change",
        "failure_info": null
      }
    ],
    "created_at": "2025-02-03T10:30:00.000000Z",
    "updated_at": "2025-02-03T18:00:00.000000Z"
  },
  "timestamp": "2025-02-04T08:00:00.000000Z"
}

GET/orders

List your orders

Get a list of your orders. Like the orders table in your panel, but in your code.

Query Parameters

Name
page
Type
integer
Description
Page number for pagination. Default: 1
Name
per_page
Type
integer
Description
Number of results per page. Default: 15, Max: 100

GET

/orders

curl "https://api.4nortes.app/api/v1/orders?page=1&per_page=10" \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Orders retrieved successfully",
  "data": {
    "items": [
      {
        "id": 12345,
        "tracking_number": "4N000000012345",
        "external_reference": "ORDER-001",
        "delivery_state": "pending",
        "recipient_name": "Jane Doe",
        "destination": {
          "locality": "Providencia"
        },
        "created_at": "2025-02-03T10:30:00.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "last_page": 5,
      "per_page": 10,
      "total": 47
    }
  },
  "timestamp": "2025-02-04T08:00:00.000000Z"
}

POST/orders/{tracking_number}/cancel

Cancel an order

Cancel an order that hasn't reached a final state. Same as the cancel button in your panel.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number to cancel. Required.

Orders can be cancelled while in any non-final state. Once an order reaches delivered or nulled, it cannot be cancelled.

POST

/orders/{tracking_number}/cancel

curl -X POST https://api.4nortes.app/api/v1/orders/4N000000012345/cancel \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Order cancelled successfully",
  "data": {
    "tracking_number": "4N000000012345",
    "delivery_state": "nulled"
  },
  "timestamp": "2025-02-03T11:00:00.000000Z"
}

GET/orders/{tracking_number}/labels

Get labels

Get the shipping label information for an order.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number. Required.

Response Fields

Name
url
Type
string
Description
URL to download the label.
Name
packages_count
Type
integer
Description
Number of label pages (one per package).
Name
generated_at
Type
string
Description
Timestamp when the label was generated.

GET

/orders/{tracking_number}/labels

curl "https://api.4nortes.app/api/v1/orders/4N000000012345/labels" \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Label generated successfully",
  "data": {
    "url": "https://storage.example.com/labels/4N000000012345.pdf",
    "packages_count": 1,
    "generated_at": "2025-02-03T10:35:00.000000Z"
  },
  "timestamp": "2025-02-03T10:35:00.000000Z"
}

Error Response

{
  "success": false,
  "message": "Order not found",
  "errors": null
}

POST/orders/labels/batch

Batch labels

Generate labels for multiple orders at once.

Request Body

Name
tracking_numbers
Type
array
Description
Array of tracking numbers to generate labels for. Required.

POST

/orders/labels/batch

curl -X POST https://api.4nortes.app/api/v1/orders/labels/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_numbers": ["4N000000012345", "4N000000012346"]
  }'

Response

{
  "success": true,
  "message": "Labels generated successfully",
  "data": {
    "url": "https://storage.example.com/labels/batch-abc123.pdf",
    "count": 2,
    "generated_at": "2025-02-03T10:35:00.000000Z"
  },
  "timestamp": "2025-02-03T10:35:00.000000Z"
}

POST/orders/{tracking_number}/packages/set

Update package count

Update the number of packages for an order.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number. Required.

Request Body

Name
packages_count
Type
integer
Description
New number of packages. Required.

POST

/orders/{tracking_number}/packages/set

curl -X POST https://api.4nortes.app/api/v1/orders/4N000000012345/packages/set \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "packages_count": 3
  }'

Response

{
  "success": true,
  "message": "Packages updated successfully",
  "data": {
    "tracking_number": "4N000000012345",
    "packages_count": 3
  },
  "timestamp": "2025-02-03T11:00:00.000000Z"
}