Guia de integração Hepsiburada 2026: API REST, HepsiJet & gestão centralizada do vendedor

1. Arquitetura da API Hepsiburada 2026

REST em mpop.hepsiburada.com

A API para vendedores do Hepsiburada é um puro serviço REST/JSON alojado sob o host guarda-chuva mpop.hepsiburada.com (mpop = "Merchant Platform Open API"). Não existe variante GraphQL ou gRPC. Todo o tráfego autenticado ocorre sobre HTTPS, associado a um Merchant ID emitido durante a integração no HMS. A superfície da API está dividida em subdomínios lógicos em vez de uma única raiz monolítica:

• listing-external.hepsiburada.com — CRUD de anúncios (preço, stock, estado do anúncio)
• mpop.hepsiburada.com/product/api/products — criação de produtos e atributos de categoria
• oms-external.hepsiburada.com — gestão de pedidos (pedidos, pacotes, envios)
• returns-external.hepsiburada.com — devoluções e reembolsos
• integration.hepsiburada.com/finance — carregamento de faturas e reconciliação financeira

Cada subdomínio partilha o mesmo esquema de autenticação HTTP Basic, mas expõe os seus próprios limites de taxa e convenções de paginação. O conector HB do Zunapro abstrai este fan-out por trás de uma única interface normalizada.

Autenticação: HTTP Basic sobre HTTPS

Ao contrário da API ligeiramente mais permissiva do Trendyol ou do fluxo OAuth SP-API da Amazon, o Hepsiburada usa um esquema de autenticação HTTP Basic deliberadamente simples: o cabeçalho Authorization transporta Basic base64(username:password), em que username é a sua chave de API e password é o secret associado. Cada pedido tem ainda de transportar um cabeçalho User-Agent que inclua o seu Merchant ID. Valores de User-Agent em falta ou malformados são a causa individual mais comum de 401 Unauthorized em produção.

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

HMS — O painel Hepsiburada Marketplace Service

O painel HMS em merchant.hepsiburada.com é a consola web operacional associada à API. Cada capacidade da API tem um equivalente no HMS — edições de anúncios, aceitação de pedidos, emissão de reembolsos, reconciliação financeira — e o HMS é o único local onde se geram chaves de API, se configuram os endereços de recolha do HepsiJet e se gerem as permissões de utilizador. O redesenho do HMS de 2024–2026 trouxe uma navegação esquerda unificada, relatórios de settlement em tempo real e um novo painel "API Health" que expõe as taxas de 4xx/5xx por endpoint, o que é inestimável ao depurar uma integração.

Limites de taxa e idempotência

O Hepsiburada aplica limites de taxa generosos mas rigorosos — tipicamente ~30 pedidos/segundo por merchant nas atualizações de anúncios e mais baixos (~10/s) nos endpoints de pedidos. As importações de produtos em massa são limitadas separadamente e devolvem 202 Accepted com um trackingId; depois deve consultar /import/{trackingId} para verificar a conclusão. A API de pedidos suporta idempotência através de IDs de pacote e pedido que permanecem estáveis entre leituras.

2. Ligar através da API REST — passo a passo

Pré-requisitos: conta HMS & ETBİS

Antes de qualquer chamada de API, uma empresa registada na Turquia com um vergi numarası (número de contribuinte), o registo ETBİS (Elektronik Ticaret Bilgi Sistemi — o registo de empresas de comércio eletrónico do Ministério do Comércio) e um IBAN turco (TR…) tem de concluir a integração através do HMS. A verificação KYC costuma resolver-se em 1–3 dias úteis para entidades registadas no ETBİS; os vendedores sem ETBİS são encaminhados para uma fila de revisão manual que pode demorar 1–2 semanas.

Integração da API passo a passo

1. Crie uma conta HMS em merchant.hepsiburada.com com o seu vergi numarası e IBAN. Carregue o certificado ETBİS, a circular de assinaturas e o documento do registo fiscal.
2. Gere as credenciais de API em Hesabım → Entegrasyon Bilgileri → API Anahtarı. O sistema devolve um username, password e o seu Merchant ID estável. Guarde os secrets num vault — o Hepsiburada não voltará a mostrar a password.
3. Coloque em whitelist os IP de saída se a sua plataforma de integração o exigir. O Zunapro publica um intervalo de IP de egress fixo para que os vendedores o possam fixar na allow-list do HMS.
4. Faça um smoke test com uma leitura de anúncios — chame GET /listings/merchantid/{MERCHANT_ID} e confirme um 200 OK com o seu inventário existente.
5. Subscreva os webhooks para eventos de pedido: POST /webhook-subscriptions com o seu URL de callback e os tipos de evento (order.created, order.cancelled, return.created).
6. Publique o seu primeiro produto usando POST /product/api/products/import — o Hepsiburada devolve um trackingId; consulte-o até status:DONE.
7. Entre em produção — mude a integração para "Aktif" no HMS assim que os smoke tests passarem.

Cabeçalhos e armadilhas comuns

A regressão de integração mais frequente é um User-Agent em falta ou malformado. O Hepsiburada exige rigorosamente o formato {MERCHANT_ID} - {AppName}; um User-Agent predefinido como axios/1.6 ou okhttp/4 devolve 401 Unauthorized sem corpo descritivo. Defina sempre o User-Agent explicitamente e registe-o no middleware dos pedidos.

3. Sincronização de produtos — árvore de categorias, atributos, variantes

A árvore de categorias

O catálogo do Hepsiburada está organizado como uma rigorosa árvore de categorias de três a cinco níveis exposta através de GET /product/api/categories/get-all-categories. Cada produto tem de ser mapeado para um ID de categoria de nível folha; os nós intermédios são rejeitados com VALIDATION_ERROR. A reformulação de categorias de 2024 fundiu vários nós legados (as entradas separadas "Bluetooth Kulaklık" e "Kablosuz Kulaklık" foram fundidas em "Kablosuz Kulaklık & Bluetooth"), pelo que qualquer integração mais antiga do que isso precisa de uma atualização do mapeamento de categorias.

Os atributos obrigatórios bloqueiam a aprovação

Cada categoria expõe uma lista de atributos obrigatórios e opcionais através de GET /product/api/categories/{categoryId}/attributes. Ao contrário do Trendyol, o Hepsiburada trata os atributos obrigatórios em falta como um bloqueio definitivo do anúncio — o produto entra num estado WAITING_FOR_APPROVAL e nunca chega a "Active" até que cada atributo exigido seja preenchido com um valor de lookup válido. Erros comuns:

• Marca — tem de corresponder exatamente ao registo de marcas do Hepsiburada; "Apple" e "APPLE" são IDs diferentes
• Cor, tamanho, capacidade — retirados de vocabulários controlados, não de texto livre
• Período de garantia — exigido para eletrónica, expresso em meses como enum
• País de origem (Menşei) — exigido para cosméticos, alimentos, suplementos

Variantes: separação entre anúncio & produto

O Hepsiburada usa uma separação entre produto e anúncio mais rigorosa do que a maioria dos concorrentes. Um único produto (HB-SKU, identificador interno) pode ter muitos anúncios (merchantSku) — um por vendedor, com o seu próprio preço, stock, condição (novo/recondicionado) e garantia. Para produtos com variantes (por exemplo, uma T-shirt em S/M/L × Vermelho/Azul/Preto), cada combinação é um nó de produto separado, opcionalmente agrupado sob um varyantGroupID para que a página do produto mostre amostras de cor e tamanho.

Importação em massa através de trackingId

Os pushes de catálogo em produção usam POST /product/api/products/import com uma matriz de até 100 produtos por pedido. A API devolve um trackingId; os integradores têm de consultar GET /product/api/products/import/{trackingId} até o estado ser DONE e depois percorrer os resultados linha a linha à procura de erros de validação. O Zunapro agrupa as importações em blocos de 100 linhas, repete os soft failures e mostra relatórios de erro ao nível da linha dentro do painel do vendedor.

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. Gestão de pedidos — webhooks, fluxo de estado, etiquetas

O ciclo de vida do pedido

Um pedido Hepsiburada percorre uma máquina de estados fixa que cada integração tem de implementar. Os estados são importantes — as transições prematuras acionam pontos de penalização na sua pontuação de vendedor:

• Open — pedido recebido, à espera de aceitação (SLA de 24 horas na maioria das categorias, 48h em mobiliário)
• InProgress / Picking — vendedor confirmou, picking e embalagem
• Packaged — pacote criado através da API, à espera da entrega à transportadora
• Shipped — a transportadora leu o volume; número de rastreio ativo
• Delivered — entrega de última milha confirmada
• Cancelled / Returned — portal de devoluções iniciado pelo cliente ou pelo vendedor

Webhook vs polling

O Hepsiburada suporta tanto webhooks (preferidos) como polling. Os webhooks são configurados por Merchant ID no HMS ou através de POST /webhook-subscriptions; a plataforma envia eventos JSON para o seu endpoint HTTPS com assinaturas HMAC no cabeçalho X-HB-Signature. O polling recorre a GET /orders?status=Open&offset=0&limit=100 num cron de 30–60 segundos. O Zunapro usa webhooks por predefinição com um reconciliador de polling de 5 minutos que apanha eventuais eventos perdidos — um padrão de dupla segurança que mantém a completude dos pedidos acima de 99,99%.

Etiquetas de envio: geração automática do HepsiJet

Quando marca um pedido como Packaged com o HepsiJet selecionado, a API gera automaticamente uma etiqueta de envio PDF imprimível e devolve um URL de descarga mais um número de rastreio. Não existe um pedido de etiqueta separado — a etiqueta vem incluída na resposta de criação do pacote:

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

O portal de devoluções

As devoluções são iniciadas pelo cliente através do portal de devoluções padrão do Hepsiburada (Iade Talepleri) e chegam aos vendedores através de GET /returns?status=Open. Os vendedores têm 3 dias úteis para aprovar ou contestar a devolução; a aprovação automática entra em vigor após esse prazo. As devoluções aprovadas acionam um reembolso através do circuito de pagamento do Hepsiburada (que o vendedor verá no próximo settlement financeiro), e o inventário deve ser recreditado através de PUT /listings/{merchantSku}/stock.

5. Sincronização de stock & preços — tempo real, Buy Box, repricer

O endpoint de stock

O stock é atualizado através da API de anúncios com um payload delta-aware:

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

O endpoint aceita preço e stock na mesma chamada, mas a cache interna do Hepsiburada pode demorar 30–90 segundos a propagar-se à montra. As atualizações em massa usam POST /listings/import com o mesmo padrão de trackingId da importação de produtos.

Sincronização em tempo real vs cron

Os vendedores de nível de produção usam sincronização orientada a eventos (cada alteração de stock no seu ERP dispara um PUT para o Hepsiburada em segundos) em vez de um cron de 15 minutos. O risco da sincronização apenas por cron é a sobrevenda durante períodos flash (Ramazan kampanyası, Black Friday, Efsane Cuma). O modelo híbrido do Zunapro dispara PUTs imediatos e um reconciliador de 15 minutos para o caso de eventos perdidos — o mesmo padrão documentado na nossa arquitetura de auto-sincronização de preços & stock master→local→targets.

Ganhar a Buy Box

A Buy Box do Hepsiburada (a oferta predefinida "Sepete Ekle" numa página de produto partilhada) é atribuída por uma fórmula ponderada que combina:

• Preço — competitivo dentro de 1–2% da oferta válida mais baixa
• Saúde do stock — profundidade, frescura, sem ruturas recentes
• Promessa de entrega — em igualdade de condições, o HepsiJet vence
• Avaliação do vendedor — mínimo de 9,0+ em todos os KPI de entrega e serviço
• Taxa de defeitos dos pedidos — cancelamentos, envios atrasados, devoluções penalizados

Um repricer bem afinado que reavalia os preços dos concorrentes a cada 5–10 minutos costuma aumentar a quota de Buy Box em 15–30% nos SKU disputados.

6. HepsiJet — rede de transportadoras própria

A última milha verticalmente integrada do Hepsiburada

HepsiJet é a rede de transportadoras de última milha própria do Hepsiburada, lançada em 2017 para reduzir a dependência da Yurtiçi e da Aras Kargo em SKU sensíveis ao tempo. Em 2026, o HepsiJet opera mais de 1.500 pontos de recolha em 81 províncias, faz entregas no mesmo dia em Istambul, Ancara e Esmirna e usa a sua própria frota de mais de 2.500 veículos além de uma rede de şube em franchising.

Padrão de código de barras e formato da etiqueta

Cada etiqueta de envio do HepsiJet transporta um código de barras Code-128 que codifica um número de rastreio de 12 caracteres com o prefixo HJ (por exemplo HJ73219840TR). A etiqueta PDF gerada pela API usa um layout A6 adequado a impressoras térmicas; as etiquetas podem ser impressas diretamente através da fila ZPL integrada.

Mesmo dia & Yarın Kapında

O HepsiJet oferece dois níveis de entrega premium visíveis na página do produto:

• "Yarın Kapında" — entrega no dia seguinte em 81 províncias quando o pedido é enviado antes das 14:00 hora local
• "Bugün Kapında" — entrega no mesmo dia em Istambul, Ancara, Esmirna, Bursa, Adana para pedidos feitos antes das 11:00

Ambos os selos aumentam de forma significativa a conversão — os dados do próprio Hepsiburada apontam para um aumento de conversão de 15–25% nos anúncios que exibem os selos, aproximadamente equivalente ao efeito "Hızlı Teslimat" do Trendyol.

Recolha vs Şubeye Bırak

Os vendedores escolhem entre recolha HepsiJet (a transportadora recolhe no armazém, cobrada por volume) e Şubeye Bırak (o vendedor deixa os volumes na filial HepsiJet mais próxima, mais barato por volume mas operacionalmente mais pesado). A API de integração suporta ambos — a resposta do pacote inclui um campo pickupAddressId que determina o encaminhamento.

7. HepsiLojistik — o modelo FBA

O que é o HepsiLojistik

HepsiLojistik é o serviço de fulfillment-by-marketplace do Hepsiburada — o análogo turco ao Amazon FBA, ao Trendyol TFC e ao Allegro One Fulfillment. Os vendedores enviam o inventário em massa para os centros de fulfillment do Hepsiburada; o Hepsiburada trata do armazenamento, picking, embalagem, entrega de última milha (através do HepsiJet) e devoluções. Os pedidos HepsiLojistik exibem um distinto selo "Hepsiburada Garanti" e obtêm a maior ponderação de visibilidade na fórmula da Buy Box.

A rede de centros de fulfillment

• Gebze (Kocaeli) — centro de fulfillment principal, ~150.000 m², serve Istambul + Mármara
• Çorlu (Tekirdağ) — adicionado em 2023, focado na Turquia ocidental + transfronteiriço com os Balcãs
• Kemalpaşa (Esmirna) — cobertura do Egeu, aberto em 2024 para a Turquia sudoeste
• Ancara (Polatlı) — hub da Anatólia central, otimizado para a entrega na região da capital

A estrutura de tarifas

Os preços do HepsiLojistik são publicados como uma tarifa de fulfillment por unidade mais o armazenamento mensal:

• Tarifa de fulfillment por unidade — tipicamente ₺25–₺75 consoante a faixa de peso e a categoria
• Armazenamento mensal — faturado por m³ por mês, escalonado por velocidade (os SKU de cauda longa pagam mais)
• Envio de entrada — o vendedor paga o envio de entrada até ao centro de fulfillment
• Tratamento de devoluções — incluído na tarifa de fulfillment para devoluções dentro da política

Candidatura & integração

O HepsiLojistik não está aberto por predefinição. Os vendedores candidatam-se através de HMS → Lojistik Hizmetleri → HepsiLojistik Başvuru, fornecendo 6 meses de histórico de vendas e uma lista de SKU alvo. O Hepsiburada dá prioridade a vendedores acima de ~500 pedidos mensais com padrões de procura previsíveis; os vendedores de menor volume costumam permanecer no modelo autónomo de recolha HepsiJet.

8. Integração da e-Fatura (e-Fatura) — GİB & ERP

A e-Fatura GİB é obrigatória

A GİB (Gelir İdaresi Başkanlığı — Administração Fiscal) da Turquia tornou obrigatória a e-Fatura (faturas XML estruturadas submetidas ao portal GİB) para todas as empresas acima do limiar de faturação anual (atualmente ~₺3M, reduzido para vendedores de comércio eletrónico ao abrigo das alterações de 2026). Abaixo do limiar, aplica-se a e-Arşiv Fatura — igualmente eletrónica, ligeiramente mais leve na assinatura. Os pedidos de marketplace não estão isentos: cada pedido de marketplace B2C e B2B exige uma fatura eletrónica emitida no prazo de 7 dias após o evento de expedição.

O endpoint de faturas do Hepsiburada

O Hepsiburada expõe um endpoint financeiro para carregamento de faturas — os vendedores (ou os seus integradores de e-Fatura) enviam o UUID GİB e a renderização em PDF da fatura emitida, que depois surge ao cliente através da hiperligação padrão "Faturayı İndir" na página do pedido:

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 & fornecedores de e-Fatura compatíveis

A maioria dos vendedores turcos emite a fatura subjacente através do seu ERP / entegratör de e-Fatura e encaminha o resultado para o Hepsiburada. O Zunapro disponibiliza conectores nativos para:

• Logo Tiger 3 / Logo Wings — o ERP mais amplamente implementado da Turquia
• Mikro Yazılım — forte no retalho PME
• Netsis (parceiro SAP) — para vendedores enterprise
• Foriba, Uyumsoft, Digital Planet, izibiz — integradores de e-Fatura GİB puros

A camada KVKK

As PII dos clientes que fluem pelo pipeline de faturação são regidas pela KVKK (Kişisel Verilerin Korunması Kanunu — Lei de Proteção de Dados Pessoais) da Turquia, a regulamentação local equivalente ao RGPD aplicada pela KVKK Kurumu (Autoridade de Proteção de Dados). Os vendedores são cocontroladores das PII do lado do pedido e têm de registar as atividades de tratamento no VERBİS quando aplicável.

9. Erros comuns e soluções

Principais erros em produção

HTTP / Código	Sintoma	Causa raiz	Solução
401 Unauthorized	Todos os pedidos rejeitados	Cabeçalho User-Agent em falta ou malformado	Defina User-Agent: {MERCHANT_ID} - {AppName} explicitamente
403 Forbidden	Endpoint específico bloqueado	A chave de API não tem o scope; merchant não aprovado para o módulo	Reemita a chave no HMS com todos os scopes, contacte o Merchant Support
VALIDATION_ERROR	Produto preso em WAITING_FOR_APPROVAL	Atributo de categoria obrigatório em falta ou valor de lookup inválido	Obtenha /categories/{id}/attributes, preencha os campos obrigatórios com valores enum válidos
BRAND_NOT_FOUND	Importação de produto rejeitada	A string da marca não corresponde exatamente ao registo de marcas HB	Consulte /brands?name=..., use o ID devolvido, peça a criação da marca se estiver em falta
429 Too Many Requests	Tráfego em rajada limitado	Excedidos ~30 req/s nos anúncios ou ~10/s nos pedidos	Implemente back-off exponencial com suporte do cabeçalho Retry-After
STOCK_UPDATE_DELAY	A montra mostra stock desatualizado durante 30–90s	Atraso de propagação da cache, não é um bug	Reduza o stock preventivamente em risco de sobrevenda; reconcilie após o atraso
HEPSIJET_PICKUP_FAIL	Pacote criado mas sem recolha da transportadora	pickupAddressId errado ou endereço fora da cobertura do HepsiJet	Verifique o endereço de recolha no HMS, recorra à Yurtiçi/Aras para os códigos postais excluídos
INVOICE_UPLOAD_REJECTED	O carregamento da e-Fatura devolve 400	Formato de UUID inválido ou corrupção do base64 do PDF	Valide o formato UUID v4, recodifique o PDF, tente novamente com um número de fatura idempotente

Fluxo de diagnóstico

Quando uma integração Hepsiburada começa a comportar-se de forma estranha, a ordem de diagnóstico que o Zunapro segue é:

1. Verifique o painel HMS → API Health para as taxas de erro ao nível do endpoint
2. Valide o User-Agent e as credenciais Basic-auth com um smoke test em curl
3. Inspecione o cabeçalho X-Request-Id de uma resposta com falha — o Merchant Support do Hepsiburada exige-o para rastrear um ticket
4. Compare com o changelog de developers.hepsiburada.com para alterações de esquema recentes

10. Comissão do Hepsiburada 2026 — de 8% a 22%

O calendário de comissões de 2026 do Hepsiburada é escalonado por categoria, publicado trimestralmente no HMS em Hesabım → Komisyon Oranları e dividido em três faixas amplas mais algumas categorias fora do comum (ouro, automóvel, grandes eletrodomésticos).

Comparação de comissões 2026 — Hepsiburada vs Trendyol vs Amazon TR

Marketplace	Faixa baixa	Faixa média	Faixa alta	Subscrição / Outro
Hepsiburada	8% – 12%	12% – 17%	15% – 22%	Conta gratuita · HepsiAd opcional · tarifas HepsiLojistik se usado
Trendyol	9% – 13%	13% – 18%	16% – 24%	Conta gratuita · tarifas TFC se usadas · Trendyol Ads opcional
Amazon TR	5% – 12%	12% – 17%	15% – 22%	Vendedor Profissional ~₺99 / mês · tarifas FBA se usadas
n11	6% – 10%	10% – 15%	13% – 18%	Conta gratuita · nível de subscrição n11 Pro opcional
Çiçeksepeti	10% – 14%	14% – 18%	16% – 22%	Conta gratuita · especialização em flores/presentes com entrega no mesmo dia

Como ler a tabela: o Hepsiburada está aproximadamente a par da Amazon TR e ligeiramente mais barato do que o Trendyol em todas as faixas. O diferenciador não é a comissão, mas a logística — a última milha própria do HepsiJet dá ao Hepsiburada uma vantagem estrutural nas promessas de entrega nas principais metrópoles, enquanto a maior base de utilizadores do Trendyol compensa as suas tarifas ligeiramente mais altas.

Quadro jurídico turco 2026 — IVA, e-Fatura, KVKK, ETBİS

Taxas de IVA (KDV) 2026

O IVA da Turquia — KDV (Katma Değer Vergisi) — usa três taxas legais em 2026:

• taxa normal de 20% — a maioria dos bens de consumo, eletrónica, moda, casa & decoração
• taxa reduzida de 10% — géneros alimentares básicos, têxteis de certas categorias, livros, hotelaria
• super-reduzida de 1% — alimentos essenciais (pão, leite, ovos), fatores de produção agrícolas, certos produtos médicos

Os vendedores do marketplace registam-se para o KDV através da Vergi Dairesi (repartição de finanças) regional; os vendedores transfronteiriços podem usar o regime especial de IVA para comércio eletrónico da Turquia, recentemente alargado após 2024.

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

• e-Fatura — faturas XML estruturadas submetidas à GİB, obrigatórias acima do limiar de faturação anual e para todos os vendedores de comércio eletrónico ao abrigo das alterações de 2026
• e-Arşiv Fatura — igualmente eletrónica mas mais leve; para B2C abaixo do limiar da e-Fatura
• janela de emissão de 7 dias — cada pedido de marketplace exige uma fatura eletrónica no prazo de 7 dias após a expedição
• e-İrsaliye, e-Müstahsil, e-Smm — documentos complementares para fluxos logísticos, agrícolas e de trabalhadores independentes

KVKK — o equivalente ao RGPD da Turquia

A KVKK (Kişisel Verilerin Korunması Kanunu), em vigor desde 2016 e reforçada no alinhamento com o RGPD de 2024, regula o tratamento de dados pessoais. Os vendedores do marketplace são cocontroladores das PII do lado do pedido (nome, morada, telefone, IBAN quando relevante) e têm de:

• Registar-se no VERBİS (Veri Sorumluları Sicil Bilgi Sistemi) se acima dos limiares
• Manter uma política de privacidade escrita (Aydınlatma Metni) acessível aos clientes
• Honrar os direitos dos titulares dos dados (acesso, retificação, eliminação) no prazo de 30 dias
• Comunicar as violações à KVKK Kurumu no prazo de 72 horas

ETBİS — o registo de empresas de comércio eletrónico

ETBİS (Elektronik Ticaret Bilgi Sistemi), gerido pelo Ministério do Comércio (Ticaret Bakanlığı), é o registo obrigatório para todas as empresas de comércio eletrónico que operam na Turquia. O registo é gratuito e online; o número ETBİS tem de ser exibido nos perfis de vendedor do marketplace e nos rodapés das lojas próprias. A KYC do Hepsiburada verifica automaticamente o ETBİS durante a integração.

Logística & envio — HepsiJet primeiro, Yurtiçi/Aras de reserva

A predefinição: HepsiJet

O HepsiJet é a transportadora predefinida para os pedidos do Hepsiburada e a única que aciona automaticamente os selos "Yarın Kapında" / "Bugün Kapında". Para a maioria dos vendedores nas principais metrópoles, encaminhar 80–100% do volume através do HepsiJet é a escolha certa.

Transportadoras de terceiros integradas

O Hepsiburada integra-se também com as transportadoras nacionais históricas da Turquia, com etiquetas de envio geradas através do mesmo endpoint de criação de pacote, bastando alterar o valor cargoCompany:

• Yurtiçi Kargo — cobertura rural mais densa, forte nos códigos postais da Anatólia oriental que o HepsiJet exclui
• Aras Kargo — SLA B2B competitivos, popular para mobiliário e mercadorias volumosas
• DHL Kargo — janelas flexíveis de entrega no mesmo dia em corredores selecionados
• PTT Kargo — operador postal estatal, alcance rural, SLA mais lentos
• UPS Türkiye / DHL — rotas internacionais transfronteiriças

Lógica de encaminhamento no Zunapro

O router logístico do Zunapro avalia cada pedido em relação a uma matriz configurável — peso, código postal de destino, valor declarado, classe SKU — e seleciona o HepsiJet por predefinição, recorrendo à Yurtiçi para os códigos postais excluídos e à Aras para volumes acima de 30 kg. A transportadora escolhida é enviada através do mesmo endpoint de pacotes do Hepsiburada, para que o cliente veja uma única experiência de rastreio.

Como começar a vender no Hepsiburada — passo a passo 2026

O lançamento em 5 passos

1. Registe-se no ETBİS & HMS — abra o seu registo ETBİS através de etbis.ticaret.gov.tr, depois faça a integração em merchant.hepsiburada.com com vergi numarası, IBAN e circular de assinaturas. A KYC resolve-se em 1–3 dias úteis.
2. Gere as credenciais de API — Hesabım → Entegrasyon Bilgileri → API Anahtarı. Guarde username/password no seu vault; anote o Merchant ID para os cabeçalhos User-Agent.
3. Configure a e-Fatura — escolha o seu integrador GİB (Logo, Mikro, Foriba, izibiz) e confirme que o endpoint de carregamento de faturas do Hepsiburada está acessível. Teste com um pedido B2C.
4. Escolha o seu stack logístico — recolha HepsiJet vs Şubeye Bırak, além de reserva Yurtiçi/Aras para os códigos postais excluídos. Prepare antecipadamente etiquetas e materiais de embalagem.
5. Ligue através do Zunapro (10 minutos) — cole as credenciais de API no bloco do Hepsiburada, mapeie o seu catálogo master, ative as etiquetas automáticas HepsiJet e a e-Fatura, acione o interruptor em produção.

O fluxo de ligação do Zunapro

1. Inicie sessão no Zunapro e abra o módulo Turquia
2. Clique em "Ligar o Hepsiburada" — cole username, password e Merchant ID da API
3. Mapeamento automático de categorias — o ML do Zunapro propõe mapeamentos de categoria de nível folha para cada SKU master; confirme com alguns cliques
4. Ative etiquetas automáticas HepsiJet + e-Fatura — um único toggle para cada
5. Entre em produção — a primeira sincronização de um catálogo de 1.000 SKU conclui-se em cerca de 10 minutos; os webhooks registam-se automaticamente

FAQ da integração Hepsiburada 2026