Quick start
Make your first request
API access is available to approved SPED business accounts. Requests use HTTPS and form-encoded parameters. Keep credentials on your server and never include them in browser or mobile-app code.
Base URLhttps://clientportal.spedtt.com/cscourier/API/<operation>curl -X POST "https://clientportal.spedtt.com/cscourier/API/test_connection" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "api_key=YOUR_SERVER_SIDE_KEY"
Authentication
Send the issued api_key with every request. Access is scoped to the business account, its shipments, and enabled services. Contact SPED immediately if a credential is exposed so it can be replaced.
Operations are enabled per integration account. A documented route may return a permission error until SPED has approved and enabled it.
Standard responses
Successful requests return status: done. Failed requests return status: failed, an error code, and a safe message.
{
"status": "done",
"data": {},
"message": "Request completed"
}
POST /API/list_services
Returns account-enabled main or optional services. Always use identifiers returned for the connected account.
| Parameter | Required | Description |
|---|
api_key | Yes | Server-side SPED API credential. |
type | Yes | Use main for shipment services or extra for optional services. |
POST /API/list_cities
Returns supported cities and regional information for integration profiles with location-directory permission.
| Parameter | Required | Description |
|---|
api_key | Yes | Server-side SPED API credential. |
country | No | Preferred ISO two-letter country code. |
county | No | State, county, province, or region filter. |
POST /API/get_price
Calculates the current price for a proposed shipment. Send complete route, dimensions, weight, insurance, and optional-service information.
| Parameter | Required | Description |
|---|
api_key | Yes | Server-side SPED API credential. |
type | Yes | package or envelope. |
service_type | Yes | An enabled main service identifier. |
cnt / weight | Yes | Piece count and weight in kilograms. |
length / width / height | Service-dependent | Parcel dimensions in centimetres. |
from_country / from_city | Yes | Origin country and city. |
to_country / to_city | Yes | Destination country and city. |
insurance | No | Value to insure. |
POST /API/create_shipment
Creates a shipment using an enabled main service and complete sender, recipient, parcel, and optional-service information.
| Parameter | Required | Description |
|---|
api_key | Yes | Server-side SPED API credential. |
type / service_type | Yes | Shipment type and enabled main service. |
customer_reference | Recommended | Your unique order or shipment reference. |
cnt / weight | Yes | Piece count and weight in kilograms. |
content | Yes | Accurate contents description. |
from_* / to_* | Yes | Structured sender and recipient contact and address fields. |
pickup_requested | No | Send true when a pickup should be requested. |
awb_event_handler | No | HTTPS endpoint for shipment events. |
POST /API/get_status
Returns the current status for one shipment number.
| Parameter | Required | Description |
|---|
api_key | Yes | Server-side SPED API credential. |
awbno | Yes | SPED shipment or tracking number. |
POST /API/get_history
Returns chronological tracking events. Use this after a webhook to refresh customer-visible tracking.
| Parameter | Required | Description |
|---|
api_key | Yes | Server-side SPED API credential. |
awbno | Yes | SPED shipment or tracking number. |
full | No | Request expanded history when permitted. |
POST /API/print
Returns the shipping label for an accessible shipment.
| Parameter | Required | Description |
|---|
api_key | Yes | Server-side SPED API credential. |
awbno | Yes | SPED shipment or tracking number. |
type | Yes | pdf, html, or zpl. |
format | No | a4 or a6; defaults to a6. |
Shipment event webhooks
Supply an HTTPS event endpoint when creating a shipment. Treat each notification as a prompt to retrieve current status or history. Deduplicate events before updating customers or business systems.
{
"no": "SPED_SHIPMENT_NUMBER",
"customer_reference": "ORDER-10042",
"type": "status",
"status": "in_transit"
}
Security, retries and production readiness
- Keep API credentials server-side and rotate exposed credentials immediately.
- Use HTTPS for every request and webhook.
- Validate and escape all customer-provided shipment data.
- Use a unique customer reference and persist every shipment response.
- Retry reads with exponential backoff. Do not blindly retry shipment creation after a timeout.
- Recheck prices immediately before shipment creation or payment.
- Test services, labels, webhooks, and error handling in staging before production.
