@hubcommerce/hepsiburada

Hepsiburada TR Marketplace API SDK — multi-host REST, upload poll, webhook inbound helpers.

Yalnızca server-side kullanın. API credential tarayıcıda, mobil uygulamada veya public repo'da asla bulunmamalı.

• Node >=20.10.0 · ESM-only · sıfır runtime dependency
• HepsiburadaResult<T> — throw yerine ok / error
• ~95 documented REST metodu + upload poll, order reconciler, webhook inbound

Detay: docs/CONFORMANCE.md · docs/QA.md · docs/MIGRATION.md

Kurulum

npm install @hubcommerce/hepsiburada

Monorepo yerel:

npm install file:../commerce-packages/marketplace/hepsiburada

Yapılandırma

.env.example dosyasını kopyalayın:

copy marketplace\hepsiburada\.env.example .env

| Değişken | Açıklama | |----------|----------| | HB_MERCHANT_ID | Satıcı kimliği | | HB_API_USERNAME | Basic Auth kullanıcı | | HB_API_PASSWORD | Basic Auth şifre | | HB_ENV | sit (varsayılan) veya production | | HB_INTEGRATOR_NAME | User-Agent — bare integrator adı (G1) |

Multi-host matrisi

SDK HostRouter ile host seçer — adapter host bilmez. Özet:

| Kaynak | Production host | |--------|-----------------| | Listings | listing-external.hepsiburada.com | | OMS | oms-external.hepsiburada.com | | Katalog | mpop.hepsiburada.com | | Shipping | shipping-external.hepsiburada.com |

SIT: -sit suffix. Tam tablo: CONFORMANCE.md.

Yasak: returns-external.* — iade/claim OMS + claim-stub üzerinden.

Hızlı başlangıç

import { createHepsiburadaClient } from "@hubcommerce/hepsiburada";

const client = createHepsiburadaClient({
  merchantId: process.env.HB_MERCHANT_ID!,
  apiUsername: process.env.HB_API_USERNAME!,
  apiPassword: process.env.HB_API_PASSWORD!,
  env: "sit",
  integratorName: process.env.HB_INTEGRATOR_NAME ?? "SelfIntegration",
});

const conn = await client.testConnection();
if (!conn.ok) {
  console.error(conn.error?.message ?? conn.reason);
}

Modül örnekleri

Sipariş poll reconciler (webhook yedek)

Hepsiburada stream API yok; webhook birincil, poll belt-and-braces.

for await (const order of client.orders.pollOrdersSince({
  lookbackMs: 300_000, // varsayılan 5 dk
})) {
  // adapter: map → InternalOrder
}

Listing stok/fiyat + upload poll

const submit = await client.listings.uploadPrice([
  { hepsiburadaSku: "HB-1", price: 199.9 },
]);

if (submit.ok && submit.data.id) {
  const result = await client.upload.waitForResult(submit.data.id, {
    kind: "priceUpload",
  });
  // partial fail: result.data.priceValidations / errors
}

uploadInventory (stok+fiyat+kargo) vs uploadStock (yalnız stok) — CONFORMANCE § Listings.

Katalog import

import { buildIntegratorPayload, createIntegratorImportFormData } from "@hubcommerce/hepsiburada";

const payload = buildIntegratorPayload([/* categoryId, merchantSku, attributes */]);
const form = createIntegratorImportFormData(payload);
await client.catalog.uploadProductViaFile(form);

Webhook inbound

Hepsiburada merchant endpoint'inize PUT ile 12 event gönderir. Güvenlik Basic Auth (G2 — HMAC/imza yok).

import {
  parseWebhookEvent,
  verifyWebhookBasicAuth,
  ORDER_WEBHOOK_EVENTS,
  CLAIM_WEBHOOK_EVENTS,
} from "@hubcommerce/hepsiburada";

for (const event of [...ORDER_WEBHOOK_EVENTS, ...CLAIM_WEBHOOK_EVENTS]) {
  app.put(`/hb/${event}`, express.json(), (req, res) => {
    if (!verifyWebhookBasicAuth(req.headers, process.env.HB_WEBHOOK_USER!, process.env.HB_WEBHOOK_PASS!)) {
      res.status(401).end();
      return;
    }
    const parsed = parseWebhookEvent(event, req.body);
    if (!parsed.ok) {
      res.status(400).end();
      return;
    }
    // Adapter: dedup + persist + domain event — 2xx <= 5 sn ACK
    res.status(204).end();
  });
}

HMS webhook kayıt adımları: QA.md § HMS webhook kayıt.

Exhaustive switch örneği: tests/webhook-exhaustive-switch.test.ts

Testing subpath (SIT)

import {
  assertSitEnvironment,
  createTestOrder,
  ORDER_FIXTURE,
} from "@hubcommerce/hepsiburada/testing";

assertSitEnvironment(client.config);

Production config ile stub path → forbiddenPathGuard throw.

QA smoke

npm run qa:smoke --workspace=@hubcommerce/hepsiburada

Credential yoksa exit 0 (skip). Detay: QA.md.

Dokümantasyon

| Dosya | İçerik | |-------|--------| | CONFORMANCE.md | Endpoint checklist, tuzaklar | | ADAPTER-CONTRACT.md | SDK vs adapter | | OFFICIAL-ANSWERS.md | Portal gate G1–G6 | | DOC-SOURCES.md | Resmi SoT + snapshot | | QA.md | Partner checklist, HMS webhook | | MIGRATION.md | Sürüm geçişi | | VERSIONING.md | SemVer politikası | | TECH-DEBT.md | Teknik borç |

Lisans

MIT