Create Contract Consignment

This API is used to create contract-type consignments with the PTT Contract provider. The request is sent through the standard consignment creation endpoint; contract details are submitted in the package items array.

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 contract consignment, you need the following information:

Requirement	Description
API Key	API key assigned to your account
Provider Selection	Select the provider with `provider_id` or `preference`
Sender Information	Name, address, and contact details
Recipient Information	Name, address, contact details, and Turkish identity number
Package Information	Contract package with `package_type: 6`
Contract Information	Approved contract ID and contract name

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 provider	`"provider_id": 12`
`preference`	When you want the system to select a suitable provider	`"preference": 1`

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

Minimal Request Example

{
    "provider_id": 12,
    "preference": 0,
    "reference_no": "CON-20260807-0001",
    "consignor": {
        "name": "Sender Company",
        "country": "TR",
        "state": "Istanbul",
        "city": "Sisli",
        "postal_code": "34381",
        "address": "Sample District, Sample Street No:1",
        "phone_number": "+902121234567"
    },
    "consignee": {
        "name": "Recipient Name",
        "country": "TR",
        "state": "Ankara",
        "city": "Cankaya",
        "postal_code": "06690",
        "address": "Recipient address",
        "phone_number": "+905551234567",
        "tax_number": "12345678901"
    },
    "packages": [
        {
            "package_type": 6,
            "post_type": 7,
            "quantity": 1,
            "weight": 0.1,
            "length": 20,
            "width": 15,
            "height": 1,
            "items": [
                {
                    "description": "CONTRACT-10001",
                    "category": "Housing Loan Contract"
                }
            ]
        }
    ]
}

Note: package_type: 6 represents the contract package type. For all package type values, see Package Types.

Note: post_type: 7 in the examples represents the document post type. For all post type values, see Consignment Post Types.

Contract Consignment Rules

Contract Approval and Contract ID

Contract documents must be submitted to ComToHome and approved before the consignment is shipped. After approval, send the received contract ID in the packages[].items[].description field.

The contract name must be sent in the packages[].items[].category field of the same item.

Package Type

For contract consignments, send 6 as the package package_type value.

{
    "packages": [
        {
            "package_type": 6
        }
    ]
}

Single Package Usage

Contract consignments must be created as a single package. Creating one contract consignment with multiple packages is not supported.

Sending Multiple Contracts

To add more than one contract to the same consignment, add multiple records to the items array of the single package.

{
    "packages": [
        {
            "package_type": 6,
            "items": [
                {
                    "description": "CONTRACT-10001",
                    "category": "Housing Loan Contract"
                },
                {
                    "description": "CONTRACT-10002",
                    "category": "Insurance Contract"
                }
            ]
        }
    ]
}

Contract Details

For PTT Contract consignments, approved contract details are submitted through the packages[].items[] fields:

Parameter	Required	Description
`packages[].items[].description`	REQUIRED	PTT contract ID (`sozlesmeId`)
`packages[].items[].category`	REQUIRED	PTT contract name (`sozlesmeAdi`)

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	PTT Contract provider ID. Required if `preference` is 0. Available Values
`address_resolver_type`	Integer	OPTIONAL	Address resolution type. Default: `0`. Details
`reference_no`	String (MAX 255)	OPTIONAL	Reference number
`invoice_number`	String (MAX 255)	OPTIONAL	Invoice number
`specific_provider_barcode`	String (MAX 255)	OPTIONAL	Custom barcode definition. Contact your account representative for barcode assignment.
`is_pickup_requested`	Bool	OPTIONAL	Courier pickup request. 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	State/Province
`consignor.city`	String (MAX 100)	REQUIRED	City/District
`consignor.postal_code`	String (MAX 30)	OPTIONAL	Postal code
`consignor.address`	String (MAX 1000)	REQUIRED	Full address
`consignor.phone_number`	String (MAX 20)	OPTIONAL	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	State/Province
`consignee.city`	String (MAX 100)	REQUIRED	City/District
`consignee.postal_code`	String (MAX 30)	OPTIONAL	Postal code
`consignee.address`	String (MAX 1000)	REQUIRED	Full address
`consignee.phone_number`	String (MAX 20)	OPTIONAL	Phone number
`consignee.email`	String (MAX 255)	OPTIONAL	Email address
`consignee.tax_number`	String (MAX 255)	REQUIRED	Recipient's Turkish identity number

Package Information

Parameter Name	Parameter Type	Required	Description
`packages[].package_type`	Integer	REQUIRED	Must be `6` for contract consignments
`packages[].post_type`	Integer	OPTIONAL	Post type. `7` can be used for document consignments. Available Values
`packages[].quantity`	Integer	OPTIONAL	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)
`packages[].items`	Array	REQUIRED	Contract details list

Package Item Information

Parameter Name	Parameter Type	Required	Description
`packages[].items[].description`	String (MAX 255)	REQUIRED	PTT contract ID (`sozlesmeId`)
`packages[].items[].category`	String (MAX 255)	REQUIRED	PTT contract name (`sozlesmeAdi`)
`packages[].items[].quantity`	Integer	OPTIONAL	Quantity
`packages[].items[].unit_price`	Float	OPTIONAL	Unit price
`packages[].items[].currency_code`	String (3 CHARS)	OPTIONAL	Currency code (default: TRY)

Example Usage

curl -X POST "{{BASE_URL}}/api/v1/consignments" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -d '{
    "provider_id": 12,
    "preference": 0,
    "reference_no": "CON-20260807-0001",
    "consignor": {
        "name": "Anatolia Finance Inc.",
        "country": "TR",
        "state": "Istanbul",
        "city": "Atasehir",
        "postal_code": "34758",
        "address": "Barbaros District, Sample Avenue No:10",
        "phone_number": "+902161234567",
        "email": "operations@example.com"
    },
    "consignee": {
        "name": "Jane Doe",
        "country": "TR",
        "state": "Ankara",
        "city": "Cankaya",
        "postal_code": "06690",
        "address": "Kavaklidere District, Sample Street No:5",
        "phone_number": "+905551234567",
        "tax_number": "12345678901"
    },
    "packages": [
        {
            "package_type": 6,
            "post_type": 7,
            "quantity": 1,
            "weight": 0.1,
            "length": 20,
            "width": 15,
            "height": 1,
            "items": [
                {
                    "description": "CONTRACT-10001",
                    "category": "Housing Loan Contract"
                },
                {
                    "description": "CONTRACT-10002",
                    "category": "Insurance Contract"
                }
            ]
        }
    ]
}'

<?php
$client = new \GuzzleHttp\Client();

$response = $client->request('POST', '{{BASE_URL}}/api/v1/consignments', [
    'headers' => [
        'Content-Type' => 'application/json',
        'APIKEY' => '{{APIKEY}}'
    ],
    'json' => [
        'provider_id' => 12,
        'preference' => 0,
        'reference_no' => 'CON-20260807-0001',
        'consignor' => [
            'name' => 'Anatolia Finance Inc.',
            'country' => 'TR',
            'state' => 'Istanbul',
            'city' => 'Atasehir',
            'postal_code' => '34758',
            'address' => 'Barbaros District, Sample Avenue No:10',
            'phone_number' => '+902161234567',
            'email' => 'operations@example.com'
        ],
        'consignee' => [
            'name' => 'Jane Doe',
            'country' => 'TR',
            'state' => 'Ankara',
            'city' => 'Cankaya',
            'postal_code' => '06690',
            'address' => 'Kavaklidere District, Sample Street No:5',
            'phone_number' => '+905551234567',
            'tax_number' => '12345678901'
        ],
        'packages' => [
            [
                'package_type' => 6,
                'post_type' => 7,
                'quantity' => 1,
                'weight' => 0.1,
                'length' => 20,
                'width' => 15,
                'height' => 1,
                'items' => [
                    [
                        'description' => 'CONTRACT-10001',
                        'category' => 'Housing Loan Contract'
                    ],
                    [
                        'description' => 'CONTRACT-10002',
                        'category' => 'Insurance Contract'
                    ]
                ]
            ]
        ]
    ]
]);

$body = json_decode($response->getBody(), true);
print_r($body);

const axios = require('axios');

const response = await axios.post(
  '{{BASE_URL}}/api/v1/consignments',
  {
    provider_id: 12,
    preference: 0,
    reference_no: 'CON-20260807-0001',
    consignor: {
      name: 'Anatolia Finance Inc.',
      country: 'TR',
      state: 'Istanbul',
      city: 'Atasehir',
      postal_code: '34758',
      address: 'Barbaros District, Sample Avenue No:10',
      phone_number: '+902161234567',
      email: 'operations@example.com'
    },
    consignee: {
      name: 'Jane Doe',
      country: 'TR',
      state: 'Ankara',
      city: 'Cankaya',
      postal_code: '06690',
      address: 'Kavaklidere District, Sample Street No:5',
      phone_number: '+905551234567',
      tax_number: '12345678901'
    },
    packages: [
      {
        package_type: 6,
        post_type: 7,
        quantity: 1,
        weight: 0.1,
        length: 20,
        width: 15,
        height: 1,
        items: [
          {
            description: 'CONTRACT-10001',
            category: 'Housing Loan Contract'
          },
          {
            description: 'CONTRACT-10002',
            category: 'Insurance Contract'
          }
        ]
      }
    ]
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'APIKEY': '{{APIKEY}}'
    }
  }
);

console.log(response.data);

API Response

On a successful request, the API returns a response like this:

{
    "status": true,
    "message": "Consignment created successfully",
    "data": {
        "consignment": 632280,
        "barcode": "PTT123456789",
        "c2hBarcode": "C2H07238640094",
        "providerTrackingCode": "PTT123456789",
        "trackingUrl": "https://<provider_domain>/<tracking_url>",
        "contentType": "application/pdf",
        "base64label": "...base64data",
        "detail": {
            "total_cost": 120.96,
            "currency_code": "TRY",
            "currency_rate": 1,
            "reference_no": "CON-20260807-0001",
            "packages": {
                "desi": 1,
                "weight": 0.1,
                "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 provider
`data.c2hBarcode`	String	ComToHome system barcode
`data.providerTrackingCode`	String	Provider tracking code
`data.trackingUrl`	String	Tracking page URL
`data.contentType`	String	Label file format
`data.base64label`	String	Base64 encoded consignment label
`data.detail.total_cost`	Float	Total consignment cost
`data.detail.currency_code`	String	Currency

Error Responses

If the API request fails, the API returns an error response in the following format:

{
    "status": false,
    "errors": [
        {
            "message": "This value should not be blank.",
            "field": "packages[0].items[0].description"
        }
    ]
}

Common Error Scenarios

Error	Description	Solution
Invalid `provider_id`	The provider is not assigned to your account or is not the PTT Contract provider	Retry with a valid PTT Contract provider ID
Missing contract ID	`packages[].items[].description` was not sent	Send the contract ID for each contract
Missing contract name	`packages[].items[].category` was not sent	Send the contract name for each contract
Unapproved contract information	The contract document was not approved before shipment	Submit the contract document to ComToHome and use the contract ID received after approval
Missing recipient Turkish identity number	`consignee.tax_number` was not sent	Send the recipient's Turkish identity number
Multiple packages	Contract consignments must be created as a single package	Add all contracts to the `items` array of a single package

Next Steps

After successfully creating a consignment:

Print Label: Decode and print the label from base64label
Track: Track the consignment with trackingUrl, providerTrackingCode, or c2hBarcode
Webhook: Set up Webhook to automatically receive consignment status changes