Guida all'integrazione Hepsiburada 2026: API REST, HepsiJet & gestione centralizzata del venditore

1. Architettura dell'API Hepsiburada 2026

REST su mpop.hepsiburada.com

L'API per venditori di Hepsiburada è un puro servizio REST/JSON ospitato sotto l'host ombrello mpop.hepsiburada.com (mpop = "Merchant Platform Open API"). Non esiste una variante GraphQL o gRPC. Tutto il traffico autenticato avviene su HTTPS, associato a un Merchant ID rilasciato durante l'onboarding HMS. La superficie dell'API è suddivisa in sotto-domini logici anziché in un'unica radice monolitica:

• listing-external.hepsiburada.com — CRUD delle inserzioni (prezzo, stock, stato dell'inserzione)
• mpop.hepsiburada.com/product/api/products — creazione prodotti e attributi di categoria
• oms-external.hepsiburada.com — gestione ordini (ordini, pacchi, spedizioni)
• returns-external.hepsiburada.com — resi e rimborsi
• integration.hepsiburada.com/finance — caricamento fatture e riconciliazione finanziaria

Ogni sotto-dominio condivide lo stesso schema di autenticazione HTTP Basic ma espone i propri limiti di frequenza e convenzioni di paginazione. Il connettore HB di Zunapro astrae questo fan-out dietro un'unica interfaccia normalizzata.

Autenticazione: HTTP Basic su HTTPS

A differenza dell'API leggermente più permissiva di Trendyol o del flusso OAuth SP-API di Amazon, Hepsiburada usa uno schema di autenticazione HTTP Basic deliberatamente semplice: l'header Authorization contiene Basic base64(username:password), dove username è la tua chiave API e password è il secret abbinato. Ogni richiesta deve inoltre includere un header User-Agent che contenga il tuo Merchant ID. Valori User-Agent mancanti o malformati sono la causa singola più comune di 401 Unauthorized in produzione.

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

HMS — Il pannello Hepsiburada Marketplace Service

Il pannello HMS su merchant.hepsiburada.com è la console web operativa abbinata all'API. Ogni capacità dell'API ha un equivalente HMS — modifiche alle inserzioni, accettazione ordini, emissione rimborsi, riconciliazione finanziaria — e HMS è l'unico luogo in cui si generano le chiavi API, si configurano gli indirizzi di ritiro HepsiJet e si gestiscono i permessi utente. Il redesign HMS del 2024–2026 ha portato una navigazione sinistra unificata, la reportistica di settlement in tempo reale e una nuova dashboard "API Health" che espone i tassi di 4xx/5xx per endpoint, preziosissima per il debug di un'integrazione.

Limiti di frequenza e idempotenza

Hepsiburada applica limiti di frequenza generosi ma rigorosi — tipicamente ~30 richieste/secondo per merchant sugli aggiornamenti delle inserzioni e più bassi (~10/s) sugli endpoint degli ordini. Le importazioni prodotti in blocco sono limitate separatamente e restituiscono 202 Accepted con un trackingId; occorre poi interrogare /import/{trackingId} per il completamento. L'API degli ordini supporta l'idempotenza tramite ID di pacco e ordine che restano stabili tra le letture.

2. Connessione tramite API REST — passo dopo passo

Prerequisiti: account HMS & ETBİS

Prima di qualsiasi chiamata API, un'azienda registrata in Turchia con un vergi numarası (codice fiscale), la registrazione ETBİS (Elektronik Ticaret Bilgi Sistemi — il registro delle imprese e-commerce del Ministero del Commercio) e un IBAN turco (TR…) deve completare l'onboarding tramite HMS. La verifica KYC di solito si conclude entro 1–3 giorni lavorativi per le entità registrate su ETBİS; i venditori non ETBİS sono instradati in una coda di revisione manuale che può richiedere 1–2 settimane.

Onboarding API passo dopo passo

1. Crea un account HMS su merchant.hepsiburada.com con il tuo vergi numarası e IBAN. Carica il certificato ETBİS, la circolare delle firme e il documento del registro fiscale.
2. Genera le credenziali API sotto Hesabım → Entegrasyon Bilgileri → API Anahtarı. Il sistema restituisce username, password e il tuo Merchant ID stabile. Conserva i secret in un vault — Hepsiburada non mostrerà più la password.
3. Metti in whitelist gli IP in uscita se la tua piattaforma di integrazione lo richiede. Zunapro pubblica un intervallo di IP di egress fisso così che i venditori possano fissarlo nella allow-list HMS.
4. Fai uno smoke test con una lettura delle inserzioni — chiama GET /listings/merchantid/{MERCHANT_ID} e conferma un 200 OK con il tuo inventario esistente.
5. Iscriviti ai webhook per gli eventi ordine: POST /webhook-subscriptions con la tua URL di callback e i tipi di evento (order.created, order.cancelled, return.created).
6. Pubblica il tuo primo prodotto usando POST /product/api/products/import — Hepsiburada restituisce un trackingId; interrogalo fino a status:DONE.
7. Vai in produzione — imposta l'integrazione su "Aktif" in HMS una volta superati gli smoke test.

Header e insidie comuni

La regressione di integrazione più frequente è uno User-Agent mancante o malformato. Hepsiburada richiede rigorosamente il formato {MERCHANT_ID} - {AppName}; uno User-Agent predefinito come axios/1.6 o okhttp/4 restituisce 401 Unauthorized senza alcun corpo descrittivo. Imposta sempre lo User-Agent esplicitamente e registralo nel middleware delle richieste.

3. Sincronizzazione prodotti — albero delle categorie, attributi, varianti

L'albero delle categorie

Il catalogo di Hepsiburada è organizzato come un rigido albero di categorie di tre-cinque livelli esposto tramite GET /product/api/categories/get-all-categories. Ogni prodotto deve essere mappato su un ID di categoria a livello foglia; i nodi intermedi vengono rifiutati con VALIDATION_ERROR. La revisione delle categorie del 2024 ha unito diversi nodi legacy (le voci separate "Bluetooth Kulaklık" e "Kablosuz Kulaklık" sono state fuse in "Kablosuz Kulaklık & Bluetooth"), quindi qualsiasi integrazione più vecchia richiede un aggiornamento della mappatura delle categorie.

Gli attributi obbligatori bloccano l'approvazione

Ogni categoria espone un elenco di attributi obbligatori e facoltativi tramite GET /product/api/categories/{categoryId}/attributes. A differenza di Trendyol, Hepsiburada tratta gli attributi obbligatori mancanti come un blocco definitivo dell'inserzione — il prodotto entra in uno stato WAITING_FOR_APPROVAL e non raggiunge mai "Active" finché ogni attributo richiesto non è popolato con un valore di lookup valido. Errori comuni:

• Marca — deve corrispondere esattamente al registro marche di Hepsiburada; "Apple" e "APPLE" sono ID diversi
• Colore, taglia, capacità — presi da vocabolari controllati, non da testo libero
• Periodo di garanzia — richiesto per l'elettronica, espresso in mesi come enum
• Paese d'origine (Menşei) — richiesto per cosmetici, alimenti, integratori

Varianti: separazione tra inserzione & prodotto

Hepsiburada usa una separazione tra prodotto e inserzione più rigida rispetto alla maggior parte dei concorrenti. Un singolo prodotto (HB-SKU, identificatore interno) può avere molte inserzioni (merchantSku) — una per venditore, con il proprio prezzo, stock, condizione (nuovo/ricondizionato) e garanzia. Per i prodotti con varianti (ad es. una T-shirt in S/M/L × Rosso/Blu/Nero), ogni combinazione è un nodo prodotto separato, opzionalmente raggruppato sotto un varyantGroupID in modo che la pagina prodotto mostri i campioni di colore e taglia.

Importazione in blocco tramite trackingId

I push del catalogo in produzione usano POST /product/api/products/import con un array di massimo 100 prodotti per richiesta. L'API restituisce un trackingId; gli integratori devono interrogare GET /product/api/products/import/{trackingId} finché lo stato non è DONE, poi scorrere i risultati riga per riga alla ricerca di errori di validazione. Zunapro raggruppa le importazioni in blocchi da 100 righe, ripete i soft failure e mostra i report di errore a livello di riga all'interno del pannello venditore.

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. Gestione ordini — webhook, flusso di stato, etichette

Il ciclo di vita dell'ordine

Un ordine Hepsiburada si muove attraverso una macchina a stati fissa che ogni integrazione deve implementare. Gli stati contano — le transizioni premature attivano punti di penalità sul tuo punteggio venditore:

• Open — ordine ricevuto, in attesa di accettazione (SLA di 24 ore per la maggior parte delle categorie, 48h per i mobili)
• InProgress / Picking — venditore ha confermato, prelievo e imballaggio
• Packaged — pacco creato tramite API, in attesa della consegna al corriere
• Shipped — il corriere ha scansionato il collo; numero di tracciamento attivo
• Delivered — consegna dell'ultimo miglio confermata
• Cancelled / Returned — portale resi avviato dal cliente o dal venditore

Webhook vs polling

Hepsiburada supporta sia i webhook (preferiti) sia il polling. I webhook si configurano per Merchant ID in HMS o tramite POST /webhook-subscriptions; la piattaforma invia eventi JSON al tuo endpoint HTTPS con firme HMAC nell'header X-HB-Signature. Il polling ricade su GET /orders?status=Open&offset=0&limit=100 con un cron di 30–60 secondi. Zunapro usa i webhook come impostazione predefinita con un riconciliatore di polling ogni 5 minuti che cattura eventuali eventi persi — uno schema con doppia sicurezza che mantiene la completezza degli ordini sopra il 99,99%.

Etichette di spedizione: generazione automatica HepsiJet

Quando contrassegni un ordine come Packaged con HepsiJet selezionato, l'API genera automaticamente un'etichetta di spedizione PDF stampabile e restituisce una URL di download più un numero di tracciamento. Non c'è una richiesta di etichetta separata — l'etichetta è inclusa nella risposta di creazione del pacco:

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"
}

Il portale resi

I resi sono avviati dal cliente tramite il portale resi standard di Hepsiburada (Iade Talepleri) e arrivano ai venditori tramite GET /returns?status=Open. I venditori hanno 3 giorni lavorativi per approvare o contestare il reso; trascorso tale termine scatta l'approvazione automatica. I resi approvati attivano un rimborso attraverso il circuito di pagamento di Hepsiburada (che il venditore vedrà nel prossimo settlement finanziario), e l'inventario dovrebbe essere ripristinato tramite PUT /listings/{merchantSku}/stock.

5. Sincronizzazione stock & prezzi — tempo reale, Buy Box, repricer

L'endpoint dello stock

Lo stock viene aggiornato tramite l'API delle inserzioni con un payload delta-aware:

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

L'endpoint accetta prezzo e stock nella stessa chiamata, ma la cache interna di Hepsiburada può impiegare 30–90 secondi per propagarsi alla vetrina. Gli aggiornamenti in blocco usano POST /listings/import con lo stesso schema di trackingId dell'importazione prodotti.

Sincronizzazione in tempo reale vs cron

I venditori di livello produzione usano la sincronizzazione event-driven (ogni variazione di stock nel tuo ERP invia una PUT a Hepsiburada in pochi secondi) anziché un cron di 15 minuti. Il rischio della sincronizzazione solo-cron è il sovravendita durante i periodi flash (Ramazan kampanyası, Black Friday, Efsane Cuma). Il modello ibrido di Zunapro invia PUT immediate e un riconciliatore ogni 15 minuti in caso di eventi persi — lo stesso schema documentato nella nostra architettura di auto-sincronizzazione prezzi & stock master→local→targets.

Vincere la Buy Box

La Buy Box di Hepsiburada (l'offerta predefinita "Sepete Ekle" su una pagina prodotto condivisa) viene assegnata da una formula ponderata che combina:

• Prezzo — competitivo entro l'1–2% dell'offerta valida più bassa
• Salute dello stock — profondità, freschezza, nessun stockout recente
• Promessa di consegna — a parità di condizioni vince HepsiJet
• Valutazione del venditore — minimo 9,0+ su tutti i KPI di consegna e servizio
• Tasso di difettosità degli ordini — annullamenti, spedizioni in ritardo, resi penalizzati

Un repricer ben calibrato che rivaluta i prezzi dei concorrenti ogni 5–10 minuti in genere aumenta la quota di Buy Box del 15–30% sugli SKU contesi.

6. HepsiJet — la rete di corrieri di proprietà

L'ultimo miglio verticalmente integrato di Hepsiburada

HepsiJet è la rete di corrieri dell'ultimo miglio di proprietà di Hepsiburada, lanciata nel 2017 per ridurre la dipendenza da Yurtiçi e Aras Kargo sugli SKU sensibili al tempo. Nel 2026 HepsiJet gestisce oltre 1.500 punti di ritiro in 81 province, effettua consegne in giornata a Istanbul, Ankara e Izmir e utilizza una propria flotta di oltre 2.500 veicoli più una rete di şube in franchising.

Standard del codice a barre e formato dell'etichetta

Ogni etichetta di spedizione HepsiJet riporta un codice a barre Code-128 che codifica un numero di tracciamento di 12 caratteri con prefisso HJ (ad esempio HJ73219840TR). L'etichetta PDF generata dall'API usa un layout A6 adatto alle stampanti termiche; le etichette possono essere stampate direttamente tramite la coda ZPL integrata.

Consegna in giornata & Yarın Kapında

HepsiJet offre due livelli di consegna premium visibili sulla pagina prodotto:

• "Yarın Kapında" — consegna il giorno successivo in 81 province quando l'ordine viene spedito prima delle 14:00 ora locale
• "Bugün Kapında" — consegna in giornata a Istanbul, Ankara, Izmir, Bursa, Adana per gli ordini effettuati prima delle 11:00

Entrambi i badge aumentano concretamente la conversione — i dati di Hepsiburada indicano un aumento della conversione del 15–25% sulle inserzioni che riportano i badge, all'incirca equivalente all'effetto "Hızlı Teslimat" di Trendyol.

Ritiro vs Şubeye Bırak

I venditori scelgono tra ritiro HepsiJet (il corriere raccoglie dal magazzino, addebitato per collo) e Şubeye Bırak (il venditore deposita i colli presso la filiale HepsiJet più vicina, più economico per collo ma operativamente più oneroso). L'API di integrazione supporta entrambi — la risposta del pacco include un campo pickupAddressId che determina l'instradamento.

7. HepsiLojistik — il modello FBA

Cos'è HepsiLojistik

HepsiLojistik è il servizio di fulfillment-by-marketplace di Hepsiburada — l'analogo turco di Amazon FBA, Trendyol TFC e Allegro One Fulfillment. I venditori inviano l'inventario in blocco ai centri di fulfillment di Hepsiburada; Hepsiburada si occupa di stoccaggio, prelievo, imballaggio, consegna dell'ultimo miglio (tramite HepsiJet) e resi. Gli ordini HepsiLojistik riportano un distinto badge "Hepsiburada Garanti" e ottengono il peso di visibilità più alto nella formula della Buy Box.

La rete dei centri di fulfillment

• Gebze (Kocaeli) — centro di fulfillment principale, ~150.000 m², serve Istanbul + Marmara
• Çorlu (Tekirdağ) — aggiunto nel 2023, focalizzato sulla Turchia occidentale + transfrontaliero balcanico
• Kemalpaşa (Izmir) — copertura egea, aperto nel 2024 per la Turchia sud-occidentale
• Ankara (Polatlı) — hub dell'Anatolia centrale, ottimizzato per la consegna nella regione della capitale

La struttura delle tariffe

Il prezzo di HepsiLojistik è pubblicato come una tariffa di fulfillment per unità più lo stoccaggio mensile:

• Tariffa di fulfillment per unità — tipicamente ₺25–₺75 a seconda della fascia di peso e della categoria
• Stoccaggio mensile — fatturato per m³ al mese, a scaglioni per velocità (gli SKU a coda lunga pagano di più)
• Spedizione in ingresso — il venditore paga la spedizione in ingresso al centro di fulfillment
• Gestione resi — inclusa nella tariffa di fulfillment per i resi conformi alle policy

Candidatura & onboarding

HepsiLojistik non è aperto per impostazione predefinita. I venditori fanno domanda tramite HMS → Lojistik Hizmetleri → HepsiLojistik Başvuru, fornendo 6 mesi di storico vendite e una lista di SKU obiettivo. Hepsiburada dà priorità ai venditori sopra ~500 ordini mensili con pattern di domanda prevedibili; i venditori a volume più basso di solito restano sul modello di ritiro HepsiJet autonomo.

8. Integrazione e-Fattura (e-Fatura) — GİB & ERP

L'e-Fattura GİB è obbligatoria

La GİB (Gelir İdaresi Başkanlığı — Amministrazione delle Entrate) della Turchia ha reso obbligatoria l'e-Fatura (fatture XML strutturate inviate al portale GİB) per tutte le aziende sopra la soglia di fatturato annuo (attualmente ~₺3M, ridotta per i venditori e-commerce con le modifiche del 2026). Sotto la soglia si applica l'e-Arşiv Fatura — ugualmente elettronica, leggermente più leggera sulla firma. Gli ordini da marketplace non sono esenti: ogni ordine marketplace B2C e B2B richiede una fattura elettronica emessa entro 7 giorni dall'evento di spedizione.

L'endpoint fatture di Hepsiburada

Hepsiburada espone un endpoint finanziario per il caricamento delle fatture — i venditori (o i loro integratori e-Fatura) inviano l'UUID GİB e la resa PDF della fattura emessa, che poi appare al cliente tramite il link standard "Faturayı İndir" nella pagina dell'ordine:

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

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

ERP & provider e-Fatura compatibili

La maggior parte dei venditori turchi emette la fattura sottostante tramite il proprio ERP / entegratör e-Fatura e trasferisce il risultato a Hepsiburada. Zunapro fornisce connettori nativi per:

• Logo Tiger 3 / Logo Wings — l'ERP più diffuso in Turchia
• Mikro Yazılım — forte nel retail SMB
• Netsis (partner SAP) — per i venditori enterprise
• Foriba, Uyumsoft, Digital Planet, izibiz — integratori e-Fatura GİB puri

Il livello KVKK

Le PII dei clienti che transitano nella pipeline di fatturazione sono regolate dalla KVKK (Kişisel Verilerin Korunması Kanunu — Legge sulla protezione dei dati personali) della Turchia, la normativa locale equivalente al GDPR applicata dalla KVKK Kurumu (Autorità per la protezione dei dati). I venditori sono contitolari delle PII lato ordine e devono registrare le attività di trattamento su VERBİS ove applicabile.

9. Errori comuni e soluzioni

Principali errori in produzione

HTTP / Codice	Sintomo	Causa principale	Soluzione
401 Unauthorized	Tutte le richieste rifiutate	Header User-Agent mancante o malformato	Imposta User-Agent: {MERCHANT_ID} - {AppName} esplicitamente
403 Forbidden	Endpoint specifico bloccato	La chiave API non ha lo scope; merchant non approvato per il modulo	Rigenera la chiave in HMS con tutti gli scope, contatta il Merchant Support
VALIDATION_ERROR	Prodotto bloccato in WAITING_FOR_APPROVAL	Attributo di categoria obbligatorio mancante o valore di lookup non valido	Recupera /categories/{id}/attributes, compila i campi obbligatori con valori enum validi
BRAND_NOT_FOUND	Importazione prodotto rifiutata	La stringa della marca non corrisponde esattamente al registro marche HB	Interroga /brands?name=..., usa l'ID restituito, richiedi la creazione della marca se mancante
429 Too Many Requests	Traffico a raffica limitato	Superati ~30 req/s sulle inserzioni o ~10/s sugli ordini	Implementa back-off esponenziale con supporto dell'header Retry-After
STOCK_UPDATE_DELAY	La vetrina mostra stock obsoleto per 30–90s	Ritardo di propagazione della cache, non un bug	Riduci preventivamente lo stock a rischio di sovravendita; riconcilia dopo il ritardo
HEPSIJET_PICKUP_FAIL	Pacco creato ma nessuna raccolta del corriere	pickupAddressId errato o indirizzo fuori dalla copertura HepsiJet	Verifica l'indirizzo di ritiro in HMS, ripiega su Yurtiçi/Aras per i CAP esclusi
INVOICE_UPLOAD_REJECTED	Il caricamento e-Fattura restituisce 400	Formato UUID non valido o corruzione del base64 del PDF	Valida il formato UUID v4, ricodifica il PDF, riprova con un numero di fattura idempotente

Flusso diagnostico

Quando un'integrazione Hepsiburada inizia a comportarsi in modo anomalo, l'ordine diagnostico che Zunapro segue è:

1. Controlla la dashboard HMS → API Health per i tassi di errore a livello di endpoint
2. Valida User-Agent e credenziali Basic-auth con uno smoke test curl
3. Ispeziona l'header X-Request-Id di una risposta fallita — il Merchant Support di Hepsiburada lo richiede per tracciare un ticket
4. Confronta con il changelog di developers.hepsiburada.com per recenti modifiche di schema

10. Commissioni Hepsiburada 2026 — dall'8% al 22%

Il piano commissioni 2026 di Hepsiburada è a scaglioni per categoria, pubblicato trimestralmente in HMS sotto Hesabım → Komisyon Oranları e suddiviso in tre fasce ampie più alcune categorie fuori scala (oro, automotive, grandi elettrodomestici).

Confronto commissioni 2026 — Hepsiburada vs Trendyol vs Amazon TR

Marketplace	Fascia bassa	Fascia media	Fascia alta	Abbonamento / Altro
Hepsiburada	8% – 12%	12% – 17%	15% – 22%	Account gratuito · HepsiAd opzionale · tariffe HepsiLojistik se usato
Trendyol	9% – 13%	13% – 18%	16% – 24%	Account gratuito · tariffe TFC se usate · Trendyol Ads opzionale
Amazon TR	5% – 12%	12% – 17%	15% – 22%	Venditore Professionale ~₺99 / mese · tariffe FBA se usate
n11	6% – 10%	10% – 15%	13% – 18%	Account gratuito · livello di abbonamento n11 Pro opzionale
Çiçeksepeti	10% – 14%	14% – 18%	16% – 22%	Account gratuito · specializzazione in fiori/regali con consegna in giornata

Come leggere la tabella: Hepsiburada è più o meno alla pari con Amazon TR e leggermente più economico di Trendyol su tutte le fasce. Il differenziatore non è la commissione ma la logistica — l'ultimo miglio di proprietà di HepsiJet dà a Hepsiburada un vantaggio strutturale sulle promesse di consegna nelle principali metropoli, mentre la più ampia base utenti di Trendyol compensa le sue tariffe leggermente più alte.

Quadro giuridico turco 2026 — IVA, e-Fatura, KVKK, ETBİS

Aliquote IVA (KDV) 2026

L'IVA della Turchia — KDV (Katma Değer Vergisi) — usa tre aliquote di legge nel 2026:

• aliquota standard del 20% — la maggior parte dei beni di consumo, elettronica, moda, casa & living
• aliquota ridotta del 10% — generi alimentari di base, tessili per certe categorie, libri, ospitalità
• super-ridotta all'1% — alimenti di prima necessità (pane, latte, uova), input agricoli, alcuni prodotti medici

I venditori del marketplace si registrano per la KDV tramite la Vergi Dairesi (ufficio delle imposte) regionale; i venditori transfrontalieri possono usare il regime IVA speciale per l'e-commerce, di recente ampliato dalla Turchia dopo il 2024.

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

• e-Fatura — fatture XML strutturate inviate alla GİB, obbligatorie sopra la soglia di fatturato annuo e per tutti i venditori e-commerce con le modifiche del 2026
• e-Arşiv Fatura — ugualmente elettronica ma più leggera; per il B2C sotto la soglia dell'e-Fatura
• finestra di emissione di 7 giorni — ogni ordine marketplace richiede una fattura elettronica entro 7 giorni dalla spedizione
• e-İrsaliye, e-Müstahsil, e-Smm — documenti complementari per i flussi logistici, agricoli e dei liberi professionisti

KVKK — l'equivalente turco del GDPR

La KVKK (Kişisel Verilerin Korunması Kanunu), in vigore dal 2016 e rafforzata con l'allineamento al GDPR del 2024, regola il trattamento dei dati personali. I venditori del marketplace sono contitolari delle PII lato ordine (nome, indirizzo, telefono, IBAN ove pertinente) e devono:

• Registrarsi su VERBİS (Veri Sorumluları Sicil Bilgi Sistemi) se sopra le soglie
• Mantenere una privacy policy scritta (Aydınlatma Metni) accessibile ai clienti
• Onorare i diritti degli interessati (accesso, rettifica, cancellazione) entro 30 giorni
• Segnalare le violazioni alla KVKK Kurumu entro 72 ore

ETBİS — il registro delle imprese e-commerce

ETBİS (Elektronik Ticaret Bilgi Sistemi), gestito dal Ministero del Commercio (Ticaret Bakanlığı), è il registro obbligatorio per ogni impresa e-commerce che opera in Turchia. La registrazione è gratuita e online; il numero ETBİS deve essere mostrato nei profili venditore del marketplace e nei footer dei negozi propri. La KYC di Hepsiburada verifica automaticamente l'ETBİS durante l'onboarding.

Logistica & spedizioni — prima HepsiJet, backup Yurtiçi/Aras

Il predefinito: HepsiJet

HepsiJet è il corriere predefinito per gli ordini Hepsiburada e l'unico che attiva automaticamente i badge "Yarın Kapında" / "Bugün Kapında". Per la maggior parte dei venditori nelle principali metropoli, instradare l'80–100% del volume tramite HepsiJet è la scelta giusta.

Corrieri terzi integrati

Hepsiburada si integra anche con i corrieri nazionali storici della Turchia, con etichette di spedizione generate tramite lo stesso endpoint di creazione del pacco semplicemente cambiando il valore cargoCompany:

• Yurtiçi Kargo — copertura rurale più densa, forte sui CAP dell'Anatolia orientale che HepsiJet esclude
• Aras Kargo — SLA B2B competitivi, popolare per mobili e merci ingombranti
• DHL Kargo — finestre flessibili di consegna in giornata in corridoi selezionati
• PTT Kargo — operatore postale statale, copertura rurale, SLA più lenti
• UPS Türkiye / DHL — corsie internazionali transfrontaliere

Logica di instradamento in Zunapro

Il router logistico di Zunapro valuta ogni ordine rispetto a una matrice configurabile — peso, CAP di destinazione, valore dichiarato, classe SKU — e seleziona HepsiJet per impostazione predefinita, ripiegando su Yurtiçi per i CAP esclusi e su Aras per i colli sopra i 30 kg. Il corriere scelto viene inviato attraverso lo stesso endpoint pacchi di Hepsiburada, così che il cliente veda un'unica esperienza di tracciamento.

Come iniziare a vendere su Hepsiburada — passo dopo passo 2026

Il lancio in 5 passi

1. Registrati su ETBİS & HMS — apri il tuo record ETBİS tramite etbis.ticaret.gov.tr, poi completa l'onboarding su merchant.hepsiburada.com con vergi numarası, IBAN e circolare delle firme. La KYC si conclude in 1–3 giorni lavorativi.
2. Genera le credenziali API — Hesabım → Entegrasyon Bilgileri → API Anahtarı. Conserva username/password nel tuo vault; annota il Merchant ID per gli header User-Agent.
3. Collega l'e-Fattura — scegli il tuo integratore GİB (Logo, Mikro, Foriba, izibiz) e conferma che l'endpoint di caricamento fatture di Hepsiburada sia raggiungibile. Testa con un ordine B2C.
4. Scegli il tuo stack logistico — ritiro HepsiJet vs Şubeye Bırak, più fallback Yurtiçi/Aras per i CAP esclusi. Prepara in anticipo etichette e materiali di imballaggio.
5. Collega tramite Zunapro (10 minuti) — incolla le credenziali API nel riquadro Hepsiburada, mappa il tuo catalogo master, abilita le etichette automatiche HepsiJet e l'e-Fattura, attiva lo switch in produzione.

Il flusso di connessione Zunapro

1. Accedi a Zunapro e apri il modulo Turchia
2. Clicca "Collega Hepsiburada" — incolla username, password e Merchant ID dell'API
3. Mappatura automatica delle categorie — il ML di Zunapro propone mappature di categoria a livello foglia per ogni SKU master; conferma con pochi clic
4. Abilita etichette automatiche HepsiJet + e-Fattura — un singolo toggle per ciascuno
5. Vai in produzione — la prima sincronizzazione di un catalogo da 1.000 SKU si completa in circa 10 minuti; i webhook si registrano automaticamente

FAQ sull'integrazione Hepsiburada 2026