Create Domestic Consignment

This API is used to create domestic cargo and logistics shipments within Turkey. Both sender and recipient addresses must be within Turkey's borders.

Endpoint Information

Property Value
URL {{BASE_URL}}/api/v1/consignments
HTTP Method POST
Content Type application/json
Authentication APIKEY header
Rate Limit 300 requests / 1 minute (sliding window)

Rate Limit Exceeded: When the limit is exceeded, the API returns a 429 Too Many Requests error. For details, see Rate Limit.

Idempotency: This endpoint supports duplicate request protection. For details, see Idempotency.


Quick Start

To create a domestic consignment, you need the following basic information:

Requirement Description
API Key API key assigned to your account
Provider Selection Specify carrier with provider_id or preference
Sender Information Name, address, phone (Turkey address)
Recipient Information Name, address, phone (Turkey address)
Package Information Weight, dimensions, content value

How to Select a Provider?

You can specify the carrier in two ways when creating a consignment:

Method When to Use? Example
provider_id When you want to work with a specific carrier "provider_id": 1
preference When you want the system to select the best carrier "preference": 1

Note: If using provider_id, set preference to 0. For available providers, see the Provider List page.

Minimal Request Example

Below is the simplest consignment creation request containing only required fields:

{
    "provider_id": 1,
    "preference": 0,
    "consignor": {
        "name": "Sender Company",
        "country": "TR",
        "state": "İstanbul",
        "city": "Şişli",
        "postal_code": "34381",
        "address": "Sample District, Sample Street No:1",
        "phone_number": "+902121234567"
    },
    "consignee": {
        "name": "Recipient Name",
        "country": "TR",
        "state": "Ankara",
        "city": "Çankaya",
        "postal_code": "06690",
        "address": "Recipient address",
        "phone_number": "+905551234567"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "quantity": 1,
            "weight": 1,
            "length": 20,
            "width": 15,
            "height": 10
        }
    ]
}

Optional Headers

Label Format (X-Label-Format)

You can specify the format of the shipping label returned when creating a consignment using the X-Label-Format header.

Header Value Description
X-Label-Format application/pdf Default. Returns label in PDF format
X-Label-Format application/zpl Returns label in ZPL (Zebra Programming Language) format. Ideal for thermal printers

What is ZPL? ZPL (Zebra Programming Language) is a language understood by Zebra thermal label printers. If you're using a thermal printer, ZPL format can be sent directly to the printer for much faster printing.

Example Header Usage

curl -X POST "{{BASE_URL}}/api/v1/consignments" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -H "X-Label-Format: application/zpl" \
  -d '{ ... }'

Note: The default output format is PDF. If this field is not sent or an unsupported format is requested, the system automatically produces output in PDF format.


Request Parameters

Basic Parameters

Parameter Name Parameter Type Required Description
preference Integer CONDITIONAL Carrier preference. Required if provider_id is not specified. Available Values
provider_id Integer CONDITIONAL Carrier ID. Required if preference is 0 or not specified. Available Values
address_resolver_type Integer OPTIONAL Address resolution type. Default: 0. See below for details
reference_no String (MAX 255) OPTIONAL Reference number

Address Resolution Type (address_resolver_type)

This parameter determines how the submitted address information (province, district) is processed. It's critical for standardizing address data coming from different sources.

Value Constant Name Description
0 NONE Default. System matches province/district in database. Submitted state and city values are matched with system records. Returns error if no match is found.
1 RESOLVE_FROM_POSTAL_CODE Province/district information is resolved from postal code. Submitted state and city values are ignored, only postal_code is used to determine address.
2 RESOLVE_FROM_POSTAL_CODE_IF_NOT_FOUND First tries to match in system database. If no match is found, resolves from postal code. Most flexible option.

When Should I Use Which Value?

Scenario Recommended Value
My address info exactly matches system province/district names 0 (NONE)
I only have postal code or my postal code is definitely correct 1 (RESOLVE_FROM_POSTAL_CODE)
My address info comes from different sources, some may not match 2 (RESOLVE_FROM_POSTAL_CODE_IF_NOT_FOUND)

Example Scenarios

Scenario 1: E-commerce integration (Recommended: 2)

{
    "address_resolver_type": 2,
    "consignee": {
        "state": "istanbul",      // lowercase, system corrects to "İstanbul"
        "city": "kadikoy",        // lowercase, system corrects to "Kadıköy"
        "postal_code": "34710"    // Used if no match found
    }
}

Scenario 2: Postal code based (Recommended: 1)

{
    "address_resolver_type": 1,
    "consignee": {
        "state": "anything",      // ignored
        "city": "anything",       // ignored
        "postal_code": "34710"    // only this is used
    }
}

Other Basic Parameters

Parameter Name Parameter Type Required Description
invoice_number String (MAX 255) OPTIONAL Invoice number
specific_shipping_method String (MAX 255) OPTIONAL Provider shipping method. Available Values
generate_provider_barcode Bool OPTIONAL Valid for providers using sequential barcode ranges. If true, system assigns automatic barcode. Default: false
specific_provider_barcode String (MAX 255) OPTIONAL Used to define custom barcode for providers using sequential barcode ranges
is_pickup_requested Bool OPTIONAL Courier pickup request. If true, automatic courier request is created for the consignment. Default: false

Sender Information

Parameter Name Parameter Type Required Description
consignor.name String (MAX 255) REQUIRED Sender name
consignor.attention_name String (MAX 255) OPTIONAL Sender alternate name
consignor.country String (2-3 CHARS) REQUIRED Country code (ISO2 or ISO3 format)
consignor.state String (MAX 100) REQUIRED Province/State
consignor.city String (MAX 100) REQUIRED District
consignor.postal_code String (MAX 30) REQUIRED Postal code
consignor.address String (MAX 1000) REQUIRED Full address
consignor.phone_number String (MAX 20) REQUIRED Phone number
consignor.email String (MAX 255) OPTIONAL Email address

Recipient Information

Parameter Name Parameter Type Required Description
consignee.name String (MAX 255) REQUIRED Recipient name
consignee.attention_name String (MAX 255) OPTIONAL Recipient alternate name
consignee.country String (2-3 CHARS) REQUIRED Country code (ISO2 or ISO3 format)
consignee.state String (MAX 100) REQUIRED Province/State
consignee.city String (MAX 100) REQUIRED District
consignee.postal_code String (MAX 30) REQUIRED Postal code
consignee.address String (MAX 1000) REQUIRED Full address
consignee.phone_number String (MAX 20) REQUIRED Phone number
consignee.email String (MAX 255) OPTIONAL Email address

Package Information

Parameter Name Parameter Type Required Description
packages.package_type Integer REQUIRED Package type Available Values
packages.provider_packaging_type Integer OPTIONAL Provider specific packaging type Available Values
packages.post_type Integer REQUIRED Shipment type Available Values
packages.quantity Integer REQUIRED Package count
packages.weight Float REQUIRED Package weight (kg)
packages.length Float REQUIRED Package length (cm)
packages.width Float REQUIRED Package width (cm)
packages.height Float REQUIRED Package height (cm)

Package Content Information

Parameter Name Parameter Type Required Description
packages.items.unit_price Float REQUIRED Unit price
packages.items.quantity Integer REQUIRED Quantity
packages.items.description String (MAX 255) OPTIONAL Product description
packages.items.category String (MAX 255) OPTIONAL Category
packages.items.origin String (2-3 CHARS) OPTIONAL Country of origin
packages.items.currency_code String (3 CHARS) OPTIONAL Currency code (default: TRY)

Document Information (Optional)

This field is completely optional and should not be used if your shipment does not contain documents.

Document upload is required before submission. For this process, please review: Consignment Document Upload API.

Note: Only some providers support Digital Document Submission. Contact us for provider and available document submission information.

Parameter Name Parameter Type Required Description
documents.id Integer REQUIRED Previously uploaded document ID

Document Information Example Data

{
  //other consignment parameters...
  "documents": [
    {
      "id": 4617
    }
  ]
  //other consignment parameters...
}

Special Services Information (Optional)

This field is completely optional and should not be used if your shipment does not include Special Services.

For more information about Special Service Types and Detail parameters available in the system, please review: Special Services

Note: Only some Providers support Special Services. Contact us for provider and available special service information.

Parameter Name Parameter Type Required Description
special_services.service_type String REQUIRED Service type (e.g., CASH_ON_DELIVERY, HOLD_AT_DEPARTMENT)
special_services.details.$dynamic Dynamic CONDITIONAL Dynamic parameters may exist for each service type. For details see Special Services

Special Service Information Example Data

{
    //other consignment parameters...
    "special_services": [
        {
            "service_type": "CASH_ON_DELIVERY",
            "details": {
                "method": "CASH",
                "amount": 134.52,
                "accountNumber": "12312312"
            }
        },
        {
            "service_type": "HOLD_AT_DEPARTMENT"
        }
    ],
    //other consignment parameters...
}

Example Usage

Full Request Example (All Languages)

Below are comprehensive API request examples for different programming languages.

curl -X POST "{{BASE_URL}}/api/v1/consignments" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -d '{
    "provider_id": 1,
    "preference": 0,
    "reference_no": "SIP-20241217-084523",
    "consignor": {
        "name": "Tech Store Inc.",
        "country": "TR",
        "state": "İstanbul",
        "city": "Şişli",
        "postal_code": "34381",
        "address": "Büyükdere Caddesi No:185 Kanyon AVM Floor:2",
        "phone_number": "+902123456789"
    },
    "consignee": {
        "name": "John Doe",
        "country": "TR",
        "state": "İzmir",
        "city": "Karşıyaka",
        "postal_code": "35540",
        "address": "Cemal Gürsel Caddesi No:42 Apt:5 Bostanlı District",
        "phone_number": "+905359876543"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "quantity": 1,
            "weight": 0.85,
            "length": 25,
            "width": 20,
            "height": 10,
            "items": [
                {
                    "unit_price": 2499.99,
                    "quantity": 1
                }
            ]
        }
    ]
}'

API Response

On a successful request, the API will return a response like this:

{
    "status": true,
    "message": "Consignment created successfully",
    "data": {
        "consignment": 632280,
        "barcode": "XYZ123",
        "c2hBarcode": "C2H07238640094",
        "providerTrackingCode": "XYZ123",
        "trackingUrl": "https://<provider_domain>/<tracking_url>",
        "contentType": "application/pdf",
        "base64label": "...base64data",
        "detail": {
            "total_cost": 120.96,
            "currency_code": "TRY",
            "currency_rate": 1,
            "reference_no": "XYZ123",
            "packages": {
                "desi": 1.13,
                "weight": 5.4,
                "quantity": 1
            }
        }
    }
}

Response Fields

Field Type Description
status Boolean Operation success status
message String Operation result message
data.consignment Integer Created consignment ID
data.barcode String Barcode assigned by the carrier
data.c2hBarcode String ComToHome system barcode (used for tracking)
data.providerTrackingCode String Carrier tracking code
data.trackingUrl String Cargo tracking page URL
data.contentType String Label file format (e.g., application/pdf)
data.base64label String Base64 encoded shipping label (PDF)
data.detail.total_cost Float Total shipping cost
data.detail.currency_code String Currency
data.detail.packages.desi Float Calculated volumetric weight
data.detail.packages.weight Float Total weight (kg)
data.detail.packages.quantity Integer Total package count

Label Printing: You can decode the data in the base64label field and save it as a PDF file or send it directly to the printer.


Error Responses

If the API request fails, the API will return an error response like this:

{
    "status": false,
    "errors": [
        {
            "message": "Reference number SIP-20241217-084523 is already in use.",
            "field": "reference_no"
        },
        {
            "message": "This value should not be blank.",
            "field": "consignee.name"
        }
    ]
}

Special Service Error Example

If the provider does not support the requested special service:

{
    "status": false,
    "errors": [
        {
            "message": "Carrier does not support this special service: [CASH_ON_DELIVERY]",
            "field": "specialServices[0].serviceType"
        },
        {
            "message": "Carrier does not support this special service: [VALUED_SHIPMENT]",
            "field": "specialServices[1].serviceType"
        }
    ]
}

Common Error Scenarios

Error Message Field Description Solution
Reference number [referenceNo] is already in use. reference_no Same reference number was used before Use a unique reference number
Carrier with ID [providerId] is not defined for customer with ID [customerId]. provider_id Invalid or provider not assigned to customer Get a valid ID from Provider List
This value should not be blank. consignor.name, consignee.address etc. Required field left blank Fill in the relevant field
This field is missing Relevant field Required field not in request Add the relevant field
Document IDs are invalid: [document_ids] documents Invalid document ID Upload document first and get valid ID
Carrier does not support this special service: [service_name] special_services Provider doesn't support this special service Check supported special services

Next Steps

After successfully creating a consignment:

  1. Print Label: Decode the base64label field and print the label
  2. Track: Track the consignment with trackingUrl or c2hBarcode
  3. Webhook: Set up Webhook to automatically receive consignment status changes
  4. Cancel/Update: If needed, use Cancel Consignment or Update APIs