Shipping API integration is a critical piece of infrastructure that automates your e-commerce site's order processes, eliminates manual data entry and gives customers real-time tracking. Through the APIs of Turkish carriers such as PTT Kargo, MNG Kargo, Yurtiçi Kargo and Aras Kargo, you can manage every logistics process, from label printing to tracking notifications, from a single integration point. In this guide we take a detailed look at the main shipping APIs and the steps involved in integrating them.
What Is a Shipping API and Why Does It Matter?
A shipping API is an interface that lets your e-commerce platform communicate programmatically with a carrier's systems. Without an API integration, you have to log in to the carrier's portal manually for every order, create the shipment, then download the label and send it to the printer. This process wastes time and creates a workflow that is prone to human error. With an API integration, a shipping barcode is generated automatically the moment an order is completed, the label is prepared, a tracking number is sent to the customer and the entire process is recorded.
- Automation: A shipping record is opened automatically when an order is created; no manual step is required.
- Speed: With bulk label printing you can prepare hundreds of orders a day in a matter of minutes.
- Fewer Errors: Because address and weight details are transferred automatically from the system, typing errors are minimised.
- Customer Experience: Real-time tracking notifications increase customer satisfaction and trust.
- Cost Analysis: Rate-calculation data retrieved via the API lets you identify the most cost-effective shipping option.
PTT Kargo API Integration
PTT Kargo is the parcel service offered to e-commerce businesses by the Turkish Post. To access the PTT Kargo API you first need to sign a PTT Kargo corporate customer agreement and obtain your API credentials (username, password and customer code). The PTT Kargo API supports both SOAP (XML-based) and REST protocols; REST endpoints are preferred for modern projects.
Creating a Shipment with the PTT Kargo API
A shipment-creation request carries the sender details (name, address, phone), the recipient details and the parcel attributes (volumetric weight/weight, content type). A successful response returns a barcode number and a shipment reference code. This barcode is used to generate a label in ZPL or PDF format. An important point to note in the PTT Kargo API integration is that address validation is performed through a separate endpoint; incorrect addresses should be caught at the address-validation stage, not during shipment creation.
MNG Kargo API Integration
MNG Kargo is one of Turkey's long-established private carriers and has a mature REST API infrastructure. The MNG Kargo API requires an authorised dealer or corporate agreement; the sandbox (test) environment is accessed with separate credentials. The MNG API works with JSON requests and responses and uses OAuth 2.0 token-based authentication. The core endpoints are: shipment creation, label download (PDF or ZPL), shipment enquiry and cancellation.
Yurtiçi Kargo API Integration
Yurtiçi Kargo is a carrier with one of the widest distribution networks in Turkey. The Yurtiçi Kargo API supports shipment creation, bulk shipments (manifest), barcode enquiry and return-shipment creation. For API access you need to obtain your UserName, Password and CustomerNumber from your Yurtiçi Kargo corporate account representative. The Yurtiçi Kargo API supports both XML/SOAP and JSON/REST formats; REST is preferred for new integrations, however.
Aras Kargo API Integration
Aras Kargo is a carrier that stands out for its fast delivery and comprehensive returns-management infrastructure. The Aras Kargo API is built on a REST architecture and uses JWT-based authentication. Notable features of the Aras API include real-time location tracking, multi-parcel support and online return-shipment code generation. With its advanced webhook support, your system can receive instant notifications whenever a shipment's status changes (delivered, not delivered, waiting at branch).
Multiple Carrier Options and Rate Comparison
Working with more than one carrier offers advantages in both operational flexibility and cost optimisation. In a multi-carrier integration, the most suitable carrier can be selected automatically according to the order's weight, dimensions, delivery region and speed preference. This selection logic can be managed with a "shipping routing engine". For example, MNG or Yurtiçi could be chosen for orders within Istanbul, PTT Kargo for orders to Anatolia, and a motorcycle courier service for urgent orders.
- Volumetric Weight Calculation: Volumetric weight is calculated with the formula (Width x Length x Height) / 3000; it is compared with the actual weight and the higher value is used.
- Zone-Based Pricing: Carriers divide Turkey into zones; surcharges may apply for remote areas.
- Cash on Delivery: A separate parameter must be sent in the shipping API for the COD (Cash on Delivery) option.
- Insurance: Insurance can be added via the API for high-value shipments.
Automatic Tracking Notifications via Webhooks
One of the most valuable features of a shipping API integration is receiving shipment status updates instantly via webhooks. With carriers that support this (Aras, MNG), you define an endpoint so that a POST request is sent to your system whenever a shipment is delivered, the recipient cannot be found at the address or the parcel is held at a branch. Relaying this information to the customer by SMS, email or push notification dramatically reduces customer support requests and "where is my parcel?" queries. For carriers that do not support webhooks, you can pull status updates manually by polling at regular intervals.
Frequently Asked Questions
Do I need technical knowledge for a shipping API integration?
A basic understanding of REST API integration is sufficient. For ready-made platforms such as WooCommerce or Shopify, plugins for these carriers are available and no custom development is needed. For bespoke systems, a backend developer can typically complete the API integration in 3-7 days.
Is it possible to manage all carriers through a single API?
Yes, shipping integration platforms built for exactly this purpose exist. In Turkey, multi-carrier platforms such as Kolay Gönderi and Sendeo provide access to several carriers, including PTT, MNG, Yurtiçi and Aras, through a single API. This approach lowers integration costs and simplifies management.
How does automatic label printing work?
A request is sent to the label endpoint using the barcode number returned by the shipping API; the response is a label file in PDF or ZPL format. PDF labels are printed on standard printers, while the ZPL format is designed for direct printing on thermal label printers. At high order volumes, the combination of ZPL and a thermal printer offers a significant speed advantage.
Can the API be used to show shipping rates to customers?
Many carriers offer a rate-query endpoint. When the shipment weight, dimensions and delivery address are sent to this endpoint, it returns an estimated shipping cost. You can use this feature for real-time shipping-cost calculation on the checkout page.
Conclusion
Shipping API integration is one of the most effective ways to scale your e-commerce operations and improve the customer experience. By integrating the PTT, MNG, Yurtiçi and Aras APIs correctly, you can take advantage of powerful features such as automatic label printing, real-time tracking notifications and multi-carrier comparison. Get in touch with Toserof Tech. for your e-commerce integration projects.
