Hepsiburada Integration Guide 2026: REST API, HepsiJet & Centralized Seller Management

1. Hepsiburada API Architecture 2026

REST on mpop.hepsiburada.com

Hepsiburada's seller API is a pure REST/JSON service hosted under the umbrella host mpop.hepsiburada.com (mpop = "Merchant Platform Open API"). There is no GraphQL or gRPC variant. All authenticated traffic happens over HTTPS, scoped to a Merchant ID issued during HMS onboarding. The API surface is split into logical sub-domains rather than a single monolithic root:

• listing-external.hepsiburada.com — listing CRUD (price, stock, listing status)
• mpop.hepsiburada.com/product/api/products — product creation and category attributes
• oms-external.hepsiburada.com — order management (orders, packages, shipments)
• returns-external.hepsiburada.com — returns and refunds
• integration.hepsiburada.com/finance — invoice upload and finance reconciliation

Each sub-domain shares the same HTTP Basic auth scheme but exposes its own rate limits and pagination conventions. Zunapro's HB connector abstracts this fan-out behind a single normalised interface.

Authentication: HTTP Basic over HTTPS

Unlike Trendyol's slightly more permissive API or Amazon's SP-API OAuth flow, Hepsiburada uses a deliberately simple HTTP Basic auth scheme: the Authorization header carries Basic base64(username:password), where username is your API key and password is the paired secret. Every request must also carry an User-Agent header that includes your Merchant ID. Missing or malformed User-Agent values are the single most common cause of 401 Unauthorized in production.

GET /listings/merchantid/{MERCHANT_ID}/sku/{MERCHANTSKU}
Host: listing-external.hepsiburada.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
User-Agent: {MERCHANT_ID} - SelfIntegration
Accept: application/json

HMS — The Hepsiburada Marketplace Service Panel

The HMS panel at merchant.hepsiburada.com is the operational web console paired with the API. Every API capability has an HMS equivalent — listing edits, order acceptance, refund issuance, finance reconciliation — and HMS is the only place where you provision API keys, configure HepsiJet pickup addresses and manage user permissions. The 2024–2026 HMS redesign brought a unified left navigation, real-time settlement reporting and a new "API Health" dashboard that surfaces 4xx/5xx rates per endpoint, which is invaluable when debugging an integration.

Rate Limits and Idempotency

Hepsiburada applies generous but enforced rate limits — typically ~30 requests/second per merchant on listing updates and lower (~10/s) on order endpoints. Bulk product imports are throttled separately and return 202 Accepted with a trackingId; you then poll /import/{trackingId} for completion. The order API supports idempotency via package and order IDs that remain stable across reads.

2. Connecting via REST API — Step by Step

Prerequisites: HMS Account & ETBİS

Before any API call, a Turkish-registered business with a vergi numarası (tax number), ETBİS registration (Elektronik Ticaret Bilgi Sistemi — the Ministry of Trade's e-commerce business registry) and a Turkish IBAN (TR…) must onboard through HMS. The KYC review usually clears within 1–3 business days for ETBİS-registered entities; non-ETBİS sellers are routed to a manual review queue that can take 1–2 weeks.

Step-by-Step API Onboarding

1. Create HMS account at merchant.hepsiburada.com with your vergi numarası and IBAN. Upload your ETBİS certificate, signature circular and tax-board document.
2. Generate API credentials under Hesabım → Entegrasyon Bilgileri → API Anahtarı. The system returns a username, password and your stable Merchant ID. Store secrets in a vault — Hepsiburada will not show the password again.
3. Whitelist outbound IPs if your integration platform requires it. Zunapro publishes a fixed egress IP range so sellers can pin it on the HMS allow-list.
4. Smoke-test with a listing read — call GET /listings/merchantid/{MERCHANT_ID} and confirm a 200 OK with your existing inventory.
5. Subscribe to webhooks for order events: POST /webhook-subscriptions with your callback URL and the event types (order.created, order.cancelled, return.created).
6. Push your first product using POST /product/api/products/import — Hepsiburada returns a trackingId; poll it until status:DONE.
7. Go live — flip the integration to "Aktif" in HMS once the smoke tests pass.

Headers and Common Pitfalls

The single most frequent integration regression is a missing or malformed User-Agent. Hepsiburada strictly requires the format {MERCHANT_ID} - {AppName}; a default axios/1.6 or okhttp/4 User-Agent returns 401 Unauthorized with no descriptive body. Always set User-Agent explicitly and log it in your request middleware.

3. Product Sync — Category Tree, Attributes, Variants

The Category Tree

Hepsiburada's catalog is organised as a strict three-to-five-level category tree exposed via GET /product/api/categories/get-all-categories. Every product must map to a leaf-level category ID; intermediate nodes are rejected with VALIDATION_ERROR. The 2024 category overhaul collapsed several legacy nodes (separately listed "Bluetooth Kulaklık" and "Kablosuz Kulaklık" were merged into "Kablosuz Kulaklık & Bluetooth"), so any integration older than that needs a category-mapping refresh.

Mandatory Attributes Block Approval

Every category exposes a list of mandatory and optional attributes via GET /product/api/categories/{categoryId}/attributes. Unlike Trendyol, Hepsiburada treats missing mandatory attributes as a hard listing block — the product enters a WAITING_FOR_APPROVAL state and never reaches "Active" until every required attribute is populated with a valid lookup value. Common offenders:

• Brand — must match Hepsiburada's brand registry exactly; "Apple" and "APPLE" are different IDs
• Color, size, capacity — pulled from controlled vocabularies, not free text
• Warranty period — required for electronics, expressed in months as an enum
• Origin country (Menşei) — required for cosmetics, food, supplements

Variants: Listing & Product Separation

Hepsiburada uses a stricter product vs listing separation than most competitors. A single product (HB-SKU, internal identifier) can have many listings (merchantSku) — one per seller, with its own price, stock, condition (new/refurbished) and warranty. For variant products (e.g. T-shirt in S/M/L × Red/Blue/Black), each combination is a separate product node, optionally grouped under a varyantGroupID so the product page shows colour and size swatches.

Bulk Import via trackingId

Production catalog pushes use POST /product/api/products/import with an array of up to 100 products per request. The API returns a trackingId; integrators must poll GET /product/api/products/import/{trackingId} until status is DONE and then walk per-row results for validation errors. Zunapro batches imports in 100-row chunks, retries soft failures and surfaces row-level error reports inside the seller panel.

POST /product/api/products/import
Host: mpop.hepsiburada.com
Authorization: Basic ...
User-Agent: {MERCHANT_ID} - Zunapro

{
  "merchant": "{MERCHANT_ID}",
  "items": [{
    "merchantSku": "ZP-TSHIRT-RED-M",
    "categoryId": 18021982,
    "productName": "Premium Pamuklu T-Shirt — Kırmızı M",
    "brand": "Zuna",
    "attributes": [
      {"name":"Renk","value":"Kırmızı"},
      {"name":"Beden","value":"M"}
    ],
    "price": 249.90,
    "availableStock": 87,
    "varyantGroupID": "ZP-TSHIRT-2026"
  }]
}

4. Order Management — Webhooks, Status Flow, Labels

The Order Lifecycle

A Hepsiburada order moves through a fixed status machine that every integration must implement. The states matter — premature transitions trigger penalty points against your seller score:

• Open — order received, awaiting acceptance (24-hour SLA on most categories, 48h on furniture)
• InProgress / Picking — seller acknowledged, picking and packing
• Packaged — package created via API, awaiting carrier handover
• Shipped — carrier scanned the parcel; tracking number active
• Delivered — last-mile confirmed delivery
• Cancelled / Returned — return portal initiated by customer or merchant

Webhook vs Polling

Hepsiburada supports both webhooks (preferred) and polling. Webhooks are configured per Merchant ID in HMS or via POST /webhook-subscriptions; the platform pushes JSON events to your HTTPS endpoint with HMAC signatures in the X-HB-Signature header. Polling falls back to GET /orders?status=Open&offset=0&limit=100 on a 30–60-second cron. Zunapro defaults to webhooks with a 5-minute polling reconciler that catches any missed events — a belt-and-braces pattern that keeps order completeness above 99.99%.

Shipping Labels: HepsiJet Auto-Generation

When you mark an order as Packaged with HepsiJet selected, the API auto-generates a printable PDF shipping label and returns a download URL plus a tracking number. There is no separate label request — the label is bundled with the package creation response:

POST /packages
Host: oms-external.hepsiburada.com

{
  "orderId": "HB-72184",
  "lineItems": [{"id": "HB-72184-1", "qty": 1}],
  "cargoCompany": "HepsiJet"
}

→ 201 Created
{
  "packageId": "PKG-998812",
  "trackingNumber": "HJ73219840TR",
  "labelUrl": "https://mpop.hepsiburada.com/labels/PKG-998812.pdf",
  "status": "Packaged"
}

The Return Portal

Returns are customer-initiated through Hepsiburada's standard return portal (Iade Talepleri) and surface to sellers via GET /returns?status=Open. Sellers have 3 business days to approve or contest the return; auto-approval kicks in after that. Approved returns trigger a refund through Hepsiburada's payment rail (which the seller will see on the next finance settlement), and inventory should be re-credited via PUT /listings/{merchantSku}/stock.

5. Stock & Price Sync — Real-Time, Buy Box, Repricer

The Stock Endpoint

Stock is updated through the listing API with a delta-aware payload:

PUT /listings/merchantid/{MERCHANT_ID}/sku/{MERCHANTSKU}
{
  "availableStock": 42,
  "price": 299.90
}

The endpoint accepts price and stock in the same call, but Hepsiburada's internal cache may take 30–90 seconds to propagate to the storefront. Bulk updates use POST /listings/import with the same trackingId pattern as product import.

Real-Time vs Cron Sync

Production-grade sellers use event-driven sync (every stock change in your ERP fires a PUT to Hepsiburada within seconds) rather than a 15-minute cron. The risk of cron-only sync is oversell during flash periods (Ramazan kampanyası, Black Friday, Efsane Cuma). Zunapro's hybrid model fires immediate PUTs and a 15-minute reconciler in case of dropped events — the same pattern documented in our master→local→targets price & stock auto-sync architecture.

Winning the Buy Box

Hepsiburada's Buy Box ("Sepete Ekle" default offer on a shared product page) is awarded by a weighted formula combining:

• Price — competitive within 1–2% of the lowest valid offer
• Stock health — depth, freshness, no recent stockouts
• Delivery promise — HepsiJet wins all else equal
• Seller rating — minimum 9.0+ across delivery and service KPIs
• Order defect rate — cancellations, late shipments, returns penalised

A well-tuned repricer that re-evaluates competitor prices every 5–10 minutes typically lifts Buy Box share by 15–30% on contested SKUs.

6. HepsiJet — Own Courier Network

Hepsiburada's Vertically Integrated Last-Mile

HepsiJet is Hepsiburada's owned last-mile courier network, launched in 2017 to break dependence on Yurtiçi and Aras Kargo on time-critical SKUs. By 2026 HepsiJet operates 1,500+ pickup points across 81 provinces, runs same-day delivery in Istanbul, Ankara and Izmir, and uses its own fleet of more than 2,500 vehicles plus a network of franchisee shubeleri.

Barcode Standard and Label Format

Every HepsiJet shipping label carries a Code-128 barcode encoding a 12-character tracking number prefixed HJ (for example HJ73219840TR). The API-generated PDF label uses an A6 layout suitable for thermal printers; many Zunapro customers print labels directly via the integrated ZPL queue.

Same-Day & Yarın Kapında

HepsiJet offers two premium delivery tiers visible on the product page:

• "Yarın Kapında" — next-day delivery in 81 provinces when the order is shipped before 14:00 local time
• "Bugün Kapında" — same-day delivery in Istanbul, Ankara, Izmir, Bursa, Adana for orders placed before 11:00

Both badges materially lift conversion — Hepsiburada's own data points to a 15–25% conversion lift on listings carrying the badges, which is roughly equivalent to Trendyol's "Hızlı Teslimat" effect.

Pickup vs Shubeye Bırak

Sellers choose between HepsiJet pickup (the courier collects from the warehouse, charged per parcel) and Şubeye Bırak (the seller drops parcels at the nearest HepsiJet branch, cheaper per parcel but operationally heavier). The integration API supports both — the package response includes a pickupAddressId field that determines routing.

7. HepsiLojistik — The FBA Model

What HepsiLojistik Is

HepsiLojistik is Hepsiburada's fulfillment-by-marketplace service — the Turkish analogue to Amazon FBA, Trendyol TFC and Allegro One Fulfillment. Sellers ship inventory in bulk to Hepsiburada's fulfillment centres; Hepsiburada handles storage, picking, packing, last-mile delivery (via HepsiJet) and returns. HepsiLojistik orders carry a distinct "Hepsiburada Garanti" badge and qualify for the highest visibility weighting in the Buy Box formula.

The Fulfillment Centre Network

• Gebze (Kocaeli) — flagship fulfillment centre, ~150,000 m², serves Istanbul + Marmara
• Çorlu (Tekirdağ) — added 2023, focused on Western Turkey + Balkans cross-border
• Kemalpaşa (Izmir) — Aegean coverage, opened 2024 for South-West Turkey
• Ankara (Polatlı) — central Anatolia hub, optimised for capital region delivery

The Fee Structure

HepsiLojistik pricing is published as a per-unit fulfillment fee plus monthly storage:

• Fulfillment fee per unit — typically ₺25–₺75 depending on weight band and category
• Monthly storage — billed per m³ per month, tiered by velocity (long-tail SKUs pay more)
• Inbound shipping — seller pays inbound to the fulfillment centre
• Returns handling — included in the fulfillment fee for in-policy returns

Application & Onboarding

HepsiLojistik is not open by default. Sellers apply via HMS → Lojistik Hizmetleri → HepsiLojistik Başvuru, providing 6 months of sales history and a target SKU list. Hepsiburada prioritises sellers above ~500 monthly orders with predictable demand patterns; lower-volume sellers usually stay on the standalone HepsiJet pickup model.

8. e-Invoice (e-Fatura) Integration — GİB & ERP

GİB e-Fatura Is Mandatory

Turkey's GİB (Gelir İdaresi Başkanlığı — Revenue Administration) has required e-Fatura (structured XML invoices submitted to the GİB portal) for all companies above the annual turnover threshold (currently ~₺3M, reduced for e-commerce sellers under the 2026 amendments). Below the threshold, e-Arşiv Fatura applies — equally electronic, slightly lighter on signing. Marketplace orders are not exempt: every B2C and B2B marketplace order requires an electronic invoice issued within 7 days of the dispatch event.

The Hepsiburada Invoice Endpoint

Hepsiburada exposes a finance endpoint for invoice uploads — sellers (or their e-Fatura integrators) push the GİB UUID and the PDF rendering of the issued invoice, which then surfaces to the customer through the standard "Faturayı İndir" link on the order page:

POST /finance/invoices
Host: integration.hepsiburada.com

{
  "orderId": "HB-72184",
  "invoiceNumber": "ZUN2026000087421",
  "invoiceUuid": "f8e7d6c5-1234-5678-9abc-def012345678",
  "invoiceDate": "2026-06-09",
  "pdfBase64": "JVBERi0xLjQKJ..."
}

Compatible ERP & e-Fatura Providers

Most Turkish sellers issue the underlying invoice through their ERP / e-Fatura entegratör and pipe the result to Hepsiburada. Zunapro ships native connectors for:

• Logo Tiger 3 / Logo Wings — Türkiye's most widely deployed ERP
• Mikro Yazılım — strong in SMB retail
• Netsis (SAP partner) — for enterprise sellers
• Foriba, Uyumsoft, Digital Planet, izibiz — pure-play GİB e-Fatura integrators

The KVKK Layer

Customer PII flowing through the invoice pipeline is governed by Turkey's KVKK (Kişisel Verilerin Korunması Kanunu — Law on the Protection of Personal Data), the GDPR-equivalent local regulation enforced by the KVKK Kurumu (Data Protection Authority). Sellers are joint controllers of order-side PII and must register processing activities on VERBİS where applicable.

9. Common Errors and Solutions

Top Production Errors

HTTP / Code	Symptom	Root Cause	Fix
401 Unauthorized	All requests rejected	Missing or malformed User-Agent header	Set User-Agent: {MERCHANT_ID} - {AppName} explicitly
403 Forbidden	Specific endpoint blocked	API key lacks scope; merchant not approved for module	Re-issue key in HMS with full scopes, contact Merchant Support
VALIDATION_ERROR	Product stuck in WAITING_FOR_APPROVAL	Mandatory category attribute missing or invalid lookup value	Fetch /categories/{id}/attributes, fill required fields with valid enum values
BRAND_NOT_FOUND	Product import rejected	Brand string doesn't match HB brand registry exactly	Query /brands?name=..., use the returned ID, request brand creation if missing
429 Too Many Requests	Burst traffic throttled	Exceeded ~30 req/s on listings or ~10/s on orders	Implement exponential back-off with Retry-After header support
STOCK_UPDATE_DELAY	Storefront shows stale stock 30–90s	Cache propagation lag, not a bug	Pre-emptively reduce stock at risk of oversell; reconcile after delay
HEPSIJET_PICKUP_FAIL	Package created but no courier collection	Wrong pickupAddressId or address outside HepsiJet coverage	Verify pickup address in HMS, fall back to Yurtiçi/Aras for excluded ZIPs
INVOICE_UPLOAD_REJECTED	e-Fatura upload returns 400	Invalid UUID format or PDF base64 corruption	Validate UUID v4 format, re-encode PDF, retry with idempotent invoice number

Diagnostic Workflow

When a Hepsiburada integration starts behaving oddly, the diagnostic order Zunapro follows is:

1. Check HMS → API Health dashboard for endpoint-level error rates
2. Validate User-Agent and Basic-auth credentials with a curl smoke test
3. Inspect the X-Request-Id header from a failing response — Hepsiburada Merchant Support requires it to trace a ticket
4. Compare against the developers.hepsiburada.com changelog for recent schema changes

10. Hepsiburada Commission 2026 — 8% to 22%

Hepsiburada's 2026 commission schedule is category-tiered, published quarterly in HMS under Hesabım → Komisyon Oranları and broken into three broad bands plus a few outlier categories (gold, automotive, large appliances).

2026 Commission Comparison — Hepsiburada vs Trendyol vs Amazon TR

Marketplace	Low Tier	Mid Tier	High Tier	Subscription / Other
Hepsiburada	8% – 12%	12% – 17%	15% – 22%	Free account · HepsiAd optional · HepsiLojistik fees if used
Trendyol	9% – 13%	13% – 18%	16% – 24%	Free account · TFC fees if used · Trendyol Ads optional
Amazon TR	5% – 12%	12% – 17%	15% – 22%	Professional Seller ~₺99 / month · FBA fees if used
n11	6% – 10%	10% – 15%	13% – 18%	Free account · n11 Pro subscription tier optional
Çiçeksepeti	10% – 14%	14% – 18%	16% – 22%	Free account · same-day flowers/gifting specialism

Reading the table: Hepsiburada is roughly on par with Amazon TR and slightly cheaper than Trendyol across all bands. The differentiator is not commission but logistics — HepsiJet's owned last-mile gives Hepsiburada a structural advantage on delivery promises in major metros, while Trendyol's larger user base offsets its slightly higher fees.

Turkish Legal Framework 2026 — VAT, e-Fatura, KVKK, ETBİS

VAT (KDV) Rates 2026

Türkiye's VAT — KDV (Katma Değer Vergisi) — uses three statutory rates in 2026:

• 20% standard rate — most consumer goods, electronics, fashion, home & living
• 10% reduced rate — basic groceries, textiles for certain categories, books, hospitality
• 1% super-reduced — staple foods (bread, milk, eggs), agricultural inputs, certain medical

Marketplace sellers register for KDV via the regional Vergi Dairesi (tax office); cross-border sellers can use Türkiye's recently expanded special VAT regime for e-commerce after 2024.

e-Fatura & e-Arşiv — GİB Mandate

• e-Fatura — structured XML invoices submitted to GİB, mandatory above the annual turnover threshold and for all e-commerce sellers under 2026 amendments
• e-Arşiv Fatura — equally electronic but lighter; for B2C below the e-Fatura threshold
• 7-day issuance window — every marketplace order requires an electronic invoice within 7 days of dispatch
• e-İrsaliye, e-Müstahsil, e-Smm — companion documents for logistics, agricultural and freelance flows

KVKK — Turkey's GDPR Equivalent

KVKK (Kişisel Verilerin Korunması Kanunu), in force since 2016 and tightened in 2024 alignment with GDPR, regulates personal-data processing. Marketplace sellers are joint controllers for order-side PII (name, address, phone, IBAN where relevant) and must:

• Register on VERBİS (Veri Sorumluları Sicil Bilgi Sistemi) if above thresholds
• Maintain a written privacy policy (Aydınlatma Metni) accessible to customers
• Honour data-subject rights (access, rectification, deletion) within 30 days
• Report breaches to the KVKK Kurumu within 72 hours

ETBİS — The E-Commerce Business Registry

ETBİS (Elektronik Ticaret Bilgi Sistemi), run by the Ministry of Trade (Ticaret Bakanlığı), is the mandatory registry for every e-commerce business operating in Türkiye. Registration is free and online; the ETBİS number must be displayed in marketplace seller profiles and on own-shop footers. Hepsiburada's KYC checks ETBİS automatically during onboarding.

Logistics & Shipping — HepsiJet First, Yurtiçi/Aras Backup

The Default: HepsiJet

HepsiJet is the default carrier for Hepsiburada orders and the only one that auto-triggers the "Yarın Kapında" / "Bugün Kapında" badges. For most sellers in major metros, routing 80–100% of volume through HepsiJet is the right choice.

Integrated Third-Party Carriers

Hepsiburada also integrates with Turkey's incumbent national carriers, with shipping labels generated through the same package-creation endpoint by simply changing the cargoCompany value:

• Yurtiçi Kargo — densest rural coverage, strong on Eastern Anatolia ZIPs that HepsiJet excludes
• Aras Kargo — competitive B2B SLAs, popular for furniture and bulky goods
• MNG Kargo — flexible same-day windows in select corridors
• PTT Kargo — state postal operator, rural reach, slower SLAs
• UPS Türkiye / DHL — international cross-border lanes

Routing Logic in Zunapro

Zunapro's logistics router evaluates every order against a configurable matrix — weight, destination ZIP, declared value, SKU class — and selects HepsiJet by default, falling back to Yurtiçi for excluded ZIPs and Aras for parcels above 30 kg. The chosen carrier is pushed through the same Hepsiburada package endpoint, so the customer sees a single tracking experience.

How to Start Selling on Hepsiburada — 2026 Step-by-Step

The 5-Step Launch

1. Register on ETBİS & HMS — open your ETBİS record via etbis.ticaret.gov.tr, then onboard at merchant.hepsiburada.com with vergi numarası, IBAN and signature circular. KYC clears in 1–3 business days.
2. Generate API credentials — Hesabım → Entegrasyon Bilgileri → API Anahtarı. Store username/password in your vault; note the Merchant ID for User-Agent headers.
3. Wire up e-Fatura — pick your GİB integrator (Logo, Mikro, Foriba, izibiz) and confirm Hepsiburada's invoice upload endpoint is reachable. Test with one B2C order.
4. Choose your logistics stack — HepsiJet pickup vs Şubeye Bırak, plus Yurtiçi/Aras fallback for excluded ZIPs. Pre-stage labels and packing materials.
5. Connect via Zunapro (10 minutes) — paste API credentials into the Hepsiburada tile, map your master catalog, enable HepsiJet auto-labels and e-Fatura, flip the switch live.

The Zunapro Connection Flow

1. Sign in to Zunapro and open the Turkey module
2. Click "Connect Hepsiburada" — paste API username, password and Merchant ID
3. Auto category mapping — Zunapro ML proposes leaf-category mappings for every master SKU; confirm with a few clicks
4. Enable HepsiJet auto-labels + e-Fatura — single toggle each
5. Go live — first listing sync of a 1,000-SKU catalog completes in roughly 10 minutes; webhooks register automatically

Hepsiburada Integration FAQ 2026