Shipping integration is the part of e-commerce engineering that looks routine until you do it in a new country. The concepts transfer — create a shipment, get a label, track a parcel — but the details that make it work do not.
This guide covers Turkey's carrier APIs for developers who have integrated shipping elsewhere: what is structurally different, and where integrations typically fail.
Quick comparison
| Provider | Type | Access | Best for |
|---|---|---|---|
| Yurtiçi Kargo | National carrier | Commercial agreement | Broad domestic coverage |
| MNG Kargo | National carrier | Commercial agreement, developer portal | Documented developer experience |
| HepsiJet | Carrier, e-commerce oriented | Commercial agreement | Marketplace-aligned delivery |
| ShipEntegra | Aggregator | Account with provider | Multi-carrier and cross-border from one integration |
Contracts come before code
As with marketplace APIs, none of this is openly accessible. Carrier APIs are issued against a shipping agreement, and that agreement determines your pricing, the services available to you and sometimes which API features you can use at all.
The practical consequence is the same: you cannot prototype first and commercialise later. Get the agreement in motion early, because it will gate everything else, and expect the credentials you receive to reflect your specific contract rather than a generic developer tier.
It also means published documentation may not fully describe what your account can do. Verify against your own credentials rather than assuming.
The address model is the biggest structural difference
If you are integrating from a market where postcodes drive routing, this is the change that will cost you the most.
Turkish addresses are organised as a hierarchy: province (il), then district (ilçe), then neighbourhood (mahalle), then street and building. Postal codes exist but they are not the primary routing mechanism, and carriers expect the hierarchy.
The failure this produces is expensive because it happens after the fact. A shipment created with a free-text address may be accepted by the API and then fail at delivery, which means a returned parcel, a refund conversation and a support ticket.
Two rules avoid most of it. Collect the hierarchy as structured selections at checkout rather than as free text — a province dropdown, then a district dropdown filtered by province, then neighbourhood. And validate that the combination is internally consistent before you send it; a district that does not belong to the selected province is the single most common rejection.
If your checkout already has free-text addresses in the database, expect a cleanup project. Parsing Turkish addresses reliably from free text is harder than it looks, and manual review of failures is usually part of the answer.
Yurtiçi Kargo and MNG Kargo
Yurtiçi Kargo is one of Turkey's established national carriers with broad domestic coverage, including smaller settlements. For a seller shipping nationwide, coverage depth matters more than API polish, and this is where it competes.
MNG Kargo operates a developer portal, which makes the integration experience more predictable — endpoints, request shapes and error semantics are laid out rather than communicated through account managers.
Both cover the core operations you need: create a shipment, retrieve a label or barcode, query tracking status, and cancel where permitted. The differences that matter in practice are less about capability and more about operational fit: pricing under your contract, coverage in the regions you ship to, pickup arrangements and how quickly status updates propagate.
Because those factors are contract- and route-specific, benchmark them with your own volumes rather than from documentation. Ship real parcels to the regions you care about before committing.
HepsiJet
HepsiJet is oriented toward e-commerce delivery and is closely aligned with marketplace fulfilment flows. If a meaningful share of your volume comes through marketplace channels, that alignment can simplify operations.
Evaluate it on the same terms as the others: coverage for your destinations, contract pricing, and the reliability of status updates. The right carrier mix is a commercial question, and most sellers at scale use more than one.
ShipEntegra — the aggregator option
ShipEntegra takes a different approach: rather than being a carrier, it sits in front of several and gives you one integration.
The trade-off is worth stating plainly. One integration instead of three or four means less code, one set of credentials, one status vocabulary to map, and someone else maintaining carrier-side changes. It is also useful for cross-border shipping, where integrating international carriers individually is a substantial project.
Against that, you accept a margin in the pricing and a dependency sitting in your fulfilment path. If the aggregator has an outage, all your carriers are affected at once, which is a different risk profile from one carrier failing.
A reasonable rule of thumb: with one or two carriers, direct integration is usually simpler and cheaper. Beyond that, or when cross-border is involved, an aggregator often wins. Some sellers do both — direct for their highest-volume domestic carrier, aggregator for the long tail.
Tracking status mapping
There is no shared status standard across Turkish carriers. Each defines its own vocabulary and its own level of detail, and they are not interchangeable.
The correct approach is to define your own internal status set — something like created, picked up, in transit, out for delivery, delivered, failed, returned — and write a per-carrier mapping onto it. Your application logic and your customer-facing UI should only ever speak your internal vocabulary.
Handle unknown statuses explicitly. Carriers add and rename statuses, and the dangerous behaviour is silently mapping an unrecognised value to a default. Log unknowns loudly and treat them as needing review rather than assuming they mean "in transit".
Also decide how you learn about status changes. Polling every shipment on a schedule is simple but scales badly and wastes calls on parcels that have not moved. Where webhook notifications are available under your contract, they are the better mechanism — and as with any inbound webhook, verify that the request genuinely came from the carrier before acting on it.
Labels, barcodes and idempotency
Label handling is mundane until it goes wrong, and the way it goes wrong is duplicate shipments.
A shipment creation call that times out is ambiguous: the carrier may have created the shipment and you simply did not receive the response. A naive retry creates a second shipment, a second label and a second parcel charge.
Make shipment creation idempotent. Generate your own reference for each order before you call the carrier, send it with the request, and use it to detect whether a shipment already exists before retrying. Store the carrier's tracking number against your order as soon as you receive it, and never create a shipment for an order that already has one without an explicit override.
Label formats vary — barcodes, PDFs, image formats — and printing requirements differ by warehouse setup. Confirm what your fulfilment operation can actually print before choosing a format, not after.
Multi-carrier architecture
Most sellers end up with more than one carrier, so it is worth designing for that from the start even if you launch with one.
Keep an internal shipment model with your own identifiers and status vocabulary, and put each carrier behind an adapter that translates to and from it. Carrier selection — which carrier for which order — belongs in a separate rules layer, not embedded in the adapters. That rules layer will change often as pricing and coverage evolve, and you want to change it without touching integration code.
Store the raw carrier request and response alongside each shipment. When a parcel goes missing and a customer is waiting, being able to see exactly what you sent and what came back turns a long investigation into a short one.
Where this fits
Shipping is one leg of a Turkish e-commerce integration. The marketplace side — listings, stock synchronisation and order intake — is covered in Turkish marketplace seller APIs, and orders from those marketplaces feed directly into the shipping flow described here.
Access, capabilities and pricing in this article depend on your commercial agreement with each provider. Documentation links point to official sources; verify current behaviour against your own credentials during integration.
Related API Deposu entries
Sources
Frequently Asked Questions
›Can I use these APIs without a contract with the carrier?
No. Turkish carrier APIs are issued against a commercial shipping agreement. Credentials, pricing and available services all follow from that contract, so the commercial step comes before any integration work.
›Should I integrate carriers directly or use an aggregator?
Direct integration gives you the best rates and full control but multiplies the work per carrier and leaves maintenance with you. An aggregator gives you one integration across several carriers at the cost of a margin and a dependency in your fulfilment path. Under roughly two carriers, direct is usually simpler; beyond that, an aggregator often wins.
›Why do tracking statuses differ between carriers?
Each carrier defines its own status vocabulary and granularity. There is no shared standard, so you must map each carrier's statuses onto your own internal set and handle unknown values explicitly rather than defaulting them.
›How should addresses be handled?
Turkish addresses follow a province, district, neighbourhood structure rather than a postcode-first model, and carriers expect that hierarchy. Free-text address fields cause failed deliveries; collect the hierarchy as structured selections wherever possible.
›What is the most common cause of failed shipment creation?
Invalid or mismatched address hierarchy — a district that does not belong to the selected province, or a neighbourhood the carrier does not recognise. Validating the hierarchy at data entry prevents most of these failures before they reach the carrier.