This API is used to create domestic cargo and logistics shipments within Turkey. Both sender and recipient addresses must be within Turkey's borders.
| 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.
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 |
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.
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
}
]
}
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.
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.
| 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 |
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. |
| 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) |
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
}
}
| 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 |
| 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 |
| 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 |
| 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) |
| 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) |
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 |
{
//other consignment parameters...
"documents": [
{
"id": 4617
}
]
//other consignment parameters...
}
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 |
{
//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...
}
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
}
]
}
]
}'
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
}
}
}
}
| 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.
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"
}
]
}
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"
}
]
}
| 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 |
After successfully creating a consignment:
base64label field and print the labeltrackingUrl or c2hBarcode