Uniship API

Welcome to the Uniship API documentation. This comprehensive guide will help you integrate with our shipping solutions platform to create shipments, generate labels, track parcels, and receive real-time notifications.

Overview

Uniship is a unified shipping platform that connects your application to multiple shipping providers through a single API. Instead of integrating with each carrier separately, you can use our API to:

• Create shipments with automatic label generation
• Track parcels across all carriers with standardized statuses
• Manage multiple carriers through a single integration
• Receive webhooks for real-time status updates

---

Key Features

Multi-Carrier Support

Integrate with multiple shipping providers through a single API. Log in to your Uniship dashboard to see all available providers and their supported regions.

Multi-Parcel Shipments

Create shipments with multiple parcels in a single API call. Each parcel receives its own tracking number, and labels are automatically combined into a single downloadable file.

Cash on Delivery (COD)

Support for COD payments with automatic product switching for providers that require separate COD products.

Real-Time Tracking

Monitor shipment status with standardized tracking statuses across all carriers. Receive webhook notifications when statuses change.

Label Generation

Generate shipping labels in multiple formats:

• PDF - For standard office printers
• ZPL - For Zebra thermal printers
• EPL - For other thermal printers (provider-dependent)

---

Quick Start

1. Get Your API Key

Sign up at uniship.com and generate an API key from your dashboard.

2. Create a Shipping Channel

Configure your carrier credentials:

curl -X POST https://api.uniship.com/v1/shipping-channels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Shipping Channel",
    "provider": "provider_code",
    "settings": {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "productType": "BUSS",
      "sandboxMode": true
    }
  }'

3. Create a Shipment

Create a shipment with one or more parcels:

curl -X POST https://api.uniship.com/v1/shipments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_channel_id": "ch_123456",
    "label_format": "pdf",
    "sender_contact": {
      "company_name": "My Company",
      "email_address": "sender@example.com",
      "phone_number": "+420123456789"
    },
    "recipient_contact": {
      "first_name": "Jan",
      "last_name": "Novak",
      "email_address": "jan@example.com",
      "phone_number": "+420987654321"
    },
    "origin_address": {
      "street_name": "Hlavni",
      "house_number": "1",
      "city_name": "Praha",
      "postal_code": "11000",
      "country_code": "CZ"
    },
    "destination_address": {
      "street_name": "Namesti",
      "house_number": "5",
      "city_name": "Brno",
      "postal_code": "60200",
      "country_code": "CZ"
    },
    "parcels": [
      {
        "parcel_type": "package",
        "length_dimension": 30,
        "width_dimension": 20,
        "height_dimension": 15,
        "dimension_unit": "CM",
        "weight_amount": 2.5,
        "weight_unit": "KG"
      }
    ]
  }'

4. Download the Label

curl -X GET https://api.uniship.com/v1/shipments/sh_123456/label \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Authentication

All API requests require authentication using API keys. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys can be created and managed from your dashboard. Keep your API keys secure and never expose them in client-side code.

Learn more about authentication.

---

Base URL

All API requests should be made to:

https://api.uniship.com/v1

---

Request Format

Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	Yes*	application/json (for POST/PUT/PATCH requests)
Accept	No	application/json

Request Body

All request bodies should be valid JSON:

{
  "field_name": "value",
  "nested_object": {
    "property": "value"
  },
  "array_field": [
    { "item": 1 },
    { "item": 2 }
  ]
}

---

Response Format

All responses are returned in JSON format with a consistent structure.

Successful Response

{
  "data": {
    "id": "sh_123456",
    "status": "pending",
    ...
  },
  "message": "Shipment created successfully"
}

List Response (Paginated)

{
  "data": [
    { "id": "sh_123456", ... },
    { "id": "sh_123457", ... }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73
  },
  "links": {
    "first": "https://api.uniship.com/v1/shipments?page=1",
    "last": "https://api.uniship.com/v1/shipments?page=5",
    "prev": null,
    "next": "https://api.uniship.com/v1/shipments?page=2"
  }
}

Error Response

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": [
      "The field_name field is required."
    ]
  }
}

---

HTTP Status Codes

Code	Description
200	OK - Request succeeded
201	Created - Resource created successfully
204	No Content - Request succeeded with no response body
400	Bad Request - Invalid request format
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
422	Unprocessable Entity - Validation errors
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error
503	Service Unavailable - Provider unavailable

---

Common Use Cases

E-commerce Order Fulfillment

1. Customer places an order
2. Your system calls the API to create a shipment
3. Download and print the shipping label
4. Hand over parcel to carrier
5. Receive webhook notifications as package moves through delivery

Multi-Carrier Shipping

1. Create shipping channels for each carrier you use
2. Select the appropriate channel based on destination, service level, or cost
3. Create shipments through the unified API
4. Track all shipments regardless of carrier

Tracking Existing Shipments

1. Create a tracking parcel with the carrier's tracking number
2. Receive automatic status updates
3. Get webhook notifications on status changes
4. Display tracking information to your customers

Cash on Delivery

1. Configure COD settings in your shipping channel
2. Include cash_on_delivery_amount and cash_on_delivery_currency in shipment
3. System automatically handles COD product requirements
4. Receive confirmation when COD is collected

---

Guides

Get started with our detailed guides:

Guide	Description
Shipping Channels	Configure carrier connections
Shipments	Create and manage shipments
Tracking Parcels	Track shipments and status updates
Webhooks	Set up real-time notifications
Error Handling	Handle API errors gracefully

---

API Reference

Explore the complete API documentation:

Endpoint	Description
Shipping Channels	Manage carrier connections
Shipments	Create shipments and labels
Tracking Parcels	Track shipment status
Webhooks	Configure notifications

---

Rate Limits

API requests are subject to rate limiting to ensure fair usage. Current limits:

Plan	Requests per minute
Free	60
Standard	300
Enterprise	Custom

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. See Rate Limits for details.

---

Versioning

The API is versioned through the URL path (/v1/). We maintain backwards compatibility within a major version. Breaking changes will be released in a new version.

Current version: v1

---

Need Help?

• Documentation: Browse our guides and API reference
• FAQ: Check the Frequently Asked Questions
• Support: Contact our support team for assistance

---

Changelog

Stay updated with the latest API changes and improvements. Major updates include:

• Multi-parcel shipments - Create shipments with multiple parcels
• Combined labels - Download all parcel labels in a single file
• New providers - Expanded shipping provider coverage