Delnext API - Developer Documentation

Base URL

URL

https://api.delnext.com

📨

Content-Type

All requests accept application/x-www-form-urlencoded or application/json

📥

Response Format

All responses are application/json with UTF-8 encoding.

🔒

HTTPS

All API calls must be made over HTTPS. Calls over plain HTTP will be refused.

Authentication

ℹ️ Authentication uses a hash_key (API key) passed as a POST body parameter — not a header. This key is provided by the Delnext team when your account is created. Contact your account manager to request your key.

The Tracking endpoint is public and does not require authentication. All other endpoints (Pickup Points, Create Order) require a valid hash_key in the request body. An invalid or missing key returns a JSON error with success: 0.

Example auth error

{
  "success": 0,
  "message": "Restricted API"
}

Error Handling

Errors are returned as JSON with a success: 0 field and a human-readable message. Validation errors return HTTP 422; all other API errors return 200 with success: 0.

HTTP Status	Meaning
200	Request processed — check `success` field for business-level error
400	Missing required parameter (e.g. no `tracking_number`)
422	Validation failed — see `message` for details
500	Internal server error — contact Delnext support

Endpoints

POST /api/v2/tracking Track one or more parcels 🌐 Public

Query the current status and full event history of one or more parcels by their Delnext tracking number. No authentication is required. You can pass up to 100 comma-separated tracking numbers in a single request.

Parameters

Parameter	Type	Required	Description
tracking_number	string	Required	Delnext tracking code(s), comma-separated. Max 100 per request.

Example Request

cURL

curl -X POST https://api.delnext.com/api/v2/tracking \
  -d "tracking_number=DNX123456"

Response

JSON

{
  "Reference":     "DNX123456",
  "Destination":   "Lisboa, PT",
  "CurrentStatus": "In transit",
  "History": [
    {
      "Date":        "2026-03-18",
      "Time":        "14:32",
      "Description": "Departed from hub"
    },
    {
      "Date":        "2026-03-17",
      "Time":        "09:10",
      "Description": "Parcel received at origin"
    }
  ]
}

ℹ️ When multiple tracking numbers are requested, the response is an object keyed by tracking number.

JSON

{
  "DNX123456": {
    "Reference":     "DNX123456",
    "CurrentStatus": "Delivered",
    "History": [ ... ]
  },
  "DNX789012": {
    "Reference":     "DNX789012",
    "CurrentStatus": "In transit",
    "History": [ ... ]
  }
}

JSON — 400

{ "Error": "Missing tracking_number parameter" }

POST /api/v2/pickup-points Find nearby pickup points 🔑 hash_key

Returns a list of available pickup/PUDO points near a given postal code. Requires a valid hash_key and the corresponding account must have Pickup Points permission enabled.

Parameters

Parameter	Type	Required	Description
hash_key	string	Required	Your API key.
zip_code	string	Required	Postal code to search around.
country_code	string	Optional	ISO 3166-1 alpha-2 country code. Default: `"PT"`.

Example Request

cURL

curl -X POST https://api.delnext.com/api/v2/pickup-points \
  -d "hash_key=YOUR_API_KEY" \
  -d "zip_code=1000-001" \
  -d "country_code=PT"

Response

JSON

{
  "success": 1,
  "message": "Completed",
  "pickup_points": [
    {
      "id":      "PP001",
      "name":    "CTT Agência Central Lisboa",
      "address": "Rua do Comércio 1, 1100-150 Lisboa",
      "lat":     38.7074,
      "lng":     -9.1368
    }
  ]
}

JSON

{
  "success": 0,
  "message": "Authentication Required"
}

POST /api/v2/create-order Create a new shipping order 🔑 hash_key

Creates a new shipping order in the Delnext platform and returns a tracking code, shipping label PDF (base64), and order ID. Requires a valid hash_key.

⚠️ Credits are debited from your account upon a successful order creation. Ensure your sender and receiver details are complete and correct before calling this endpoint.

Sender Parameters

Parameter	Type	Required	Description
hash_key	string	Required	Your API key.
sender_first_name	string	Required	Sender first name.
sender_last_name	string	Optional	Sender last name.
sender_company	string	Required	Sender company name.
sender_street_address	string	Required	Sender street address.
sender_post_code	string	Required	Sender postal code.
sender_city	string	Required	Sender city.
sender_country	string	Required	ISO2, ISO3 or full country name (e.g. `"PT"`).
sender_telephone	string	Required	Sender phone number.
sender_email	string	Required	Sender e-mail address.

Receiver Parameters

Parameter	Type	Required	Description
receiver_first_name	string	Required	Max 60 characters.
receiver_last_name	string	Optional	Max 60 characters.
receiver_company	string	Optional	Receiver company name.
receiver_street_address	string	Required	Max 100 characters.
receiver_post_code	string	Required	5 digits if Spain.
receiver_city	string	Required	Receiver city.
receiver_country	string	Required	ISO2, ISO3 or full country name.
receiver_telephone	string	Required	Receiver phone number.
receiver_email	string	Optional	Receiver e-mail address.

Parcel Parameters

Parameter	Type	Required	Description
parcel_weight	float	Required	Weight in kg, min 0.01.
parcel_length	float	Required	Length in cm, min 0.01.
parcel_width	float	Required	Width in cm, min 0.01.
parcel_height	float	Required	Height in cm, min 0.01.
parcel_num_of_volumes	integer	Optional	Number of volumes. Default: 1.
parcel_reference	string	Required	Your internal reference or order ID.
parcel_contents	string	Required	Description of parcel contents.
parcel_content_value	float	Conditional	Declared value (€). Required for non-business accounts.
parcel_service_type	integer	Required	Service type ID (1–10). See Service Types.
parcel_insured	string	Optional	Set to `"1"` or `"yes"` to add insurance.
pickup_point_number	string	Conditional	Required when `parcel_service_type = 4` (PUDO).
cod	integer	Optional	Cash-on-delivery flag. `0` or `1`.
products_comment	string	Optional	Internal comment. Truncated to 61 characters.

Example Request

cURL

curl -X POST https://api.delnext.com/api/v2/create-order \
  -d "hash_key=YOUR_API_KEY" \
  -d "sender_first_name=João" \
  -d "sender_company=Empresa Lda" \
  -d "sender_street_address=Rua das Flores, 10" \
  -d "sender_post_code=1000-001" \
  -d "sender_city=Lisboa" \
  -d "sender_country=PT" \
  -d "sender_telephone=211451900" \
  -d "sender_email=sender@empresa.pt" \
  -d "receiver_first_name=Maria" \
  -d "receiver_street_address=Av. da Liberdade, 50" \
  -d "receiver_post_code=4000-065" \
  -d "receiver_city=Porto" \
  -d "receiver_country=PT" \
  -d "receiver_telephone=912345678" \
  -d "parcel_weight=2.5" \
  -d "parcel_length=30" \
  -d "parcel_width=20" \
  -d "parcel_height=15" \
  -d "parcel_reference=ORDER-001" \
  -d "parcel_contents=Electronics" \
  -d "parcel_service_type=1"

Response

JSON

{
  "success":       1,
  "tracking_code": "DNX789012",
  "orders_id":     98765,
  "pdf":           "JVBERi0xLjQKJcOk..."  // base64-encoded shipping label PDF
}

JSON

{
  "success": 0,
  "message": "Insufficient credits"
}

Service Types

The parcel_service_type field in Create Order determines the delivery method. The system may auto-correct the service type based on destination postal code and country.

ID	Description	Notes
1	Standard Home Delivery	Default service for Portugal, Spain, France, Italy
2	Priority / Express	Faster delivery, subject to availability
3	Economy	Lower cost, longer transit time
4	Pickup Point (PUDO)	Requires `pickup_point_number`

Supported Countries

Country fields accept ISO 3166-1 alpha-2 codes, ISO 3166-1 alpha-3 codes, or full English country names.

ISO2	Country
PT	Portugal
ES	Spain
FR	France
IT	Italy
DE	Germany
NL	Netherlands
PL	Poland

Delnext APIDocumentation

Delnext API
Documentation