@hubcommerce/trendyol

Trendyol TR Marketplace Integration API SDK.

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

• Node >=20.10.0 · ESM-only ("type": "module") · sıfır runtime dependency
• TrendyolResult<T> — throw yerine ok / error
• ~77 documented REST metodu + batch poll, stream, webhook inbound

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

Kurulum

npm install @hubcommerce/trendyol

Monorepo yerel:

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

Yapılandırma

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

copy marketplace\trendyol\.env.example .env

| Değişken | Açıklama | |----------|----------| | TRENDYOL_ENV | stage veya production | | TRENDYOL_SELLER_ID | Satıcı ID | | TRENDYOL_API_KEY | API key | | TRENDYOL_API_SECRET | API secret | | TRENDYOL_INTEGRATOR_NAME | Varsayılan SelfIntegration | | TRENDYOL_STORE_FRONT_CODE | Varsayılan TR |

Gateway URL matrisi

| Ortam | Gateway | |-------|---------| | Production | https://apigw.trendyol.com | | Stage | https://stageapigw.trendyol.com |

Eski api.trendyol.com/sapigw kullanılmaz.

Stage IP whitelist gerekir — değişiklik ~24 saat gecikebilir (QA.md).

Hızlı başlangıç

import { createTrendyolClient } from "@hubcommerce/trendyol";

const client = createTrendyolClient({
  sellerId: process.env.TRENDYOL_SELLER_ID!,
  apiKey: process.env.TRENDYOL_API_KEY!,
  apiSecret: process.env.TRENDYOL_API_SECRET!,
  env: "stage",
});

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

Modül örnekleri

Sipariş stream (birincil senkron)

Trendyol önerisi: webhook + periyodik stream/poll birlikte kullanın.

import { createTrendyolClient } from "@hubcommerce/trendyol";

const client = createTrendyolClient();

for await (const page of client.orders.streamPackages({
  lookbackMs: 300_000, // varsayılan 5 dk — saat kayması için
  size: 50,
  onCursorSave: (cursor) => {
    // adapter: cursor'u DB'ye persist et
  },
})) {
  for (const pkg of page.content ?? []) {
    console.log(pkg.id, pkg.status);
  }
}

Stok / fiyat

const result = await client.inventory.updatePriceAndInventory([
  { barcode: "8683772071724", quantity: 10, salePrice: 99.9, listPrice: 129.9 },
]);

// quantity: 0 → satış durabilir (JSDoc uyarısı)

// Yalnızca stok (fiyat Trendyol'da olduğu gibi kalır)
await client.inventory.updatePriceAndInventory([{ barcode: "8683772071724", quantity: 4 }]);

Ürün oluşturma + batch poll

import { validateEan13 } from "@hubcommerce/trendyol";

if (!validateEan13("8683772071724")) throw new Error("Geçersiz barkod");

const submit = await client.products.createProducts([/* ProductCreateItem[] */]);
if (!submit.ok) throw submit.error;

const batch = await client.batch.waitForResult(submit.data.batchRequestId, {
  intervalMs: 2000,
  timeoutMs: 120_000,
});

if (batch.ok && batch.data.failedItemCount > 0) {
  // partial fail — adapter başarısız barkodları işler
  console.log(batch.data.items?.filter((i) => i.status === "FAILED"));
}

Webhook inbound

import {
  parseWebhookPayload,
  verifyWebhookApiKey,
} from "@hubcommerce/trendyol";

// HTTP handler (adapter katmanında)
if (!verifyWebhookApiKey(req.headers, process.env.WEBHOOK_API_KEY!)) {
  return res.status(401).end();
}

const parsed = parseWebhookPayload(req.body);
if (!parsed.ok) {
  return res.status(400).json({ error: parsed.error });
}

// adapter: dedup + iş kuyruğu
const pkg = parsed.data;

Fatura

// Invoiced statü ≠ fatura gönderimi — iki ayrı adım
await client.orders.updatePackageStatus(packageId, { status: "Invoiced", lines: [...] });

await client.invoices.sendInvoiceLink({
  shipmentPackageId: packageId,
  invoiceLink: "https://...",
  invoiceNumber: "INV-2026-001",
});

Finans

const orders = await client.finance.getPaymentOrders({ size: 10 });
if (orders.ok && orders.data.content?.[0]) {
  const paymentOrderId = orders.data.content[0].paymentOrderId;
  const details = await client.finance.getSettlementDetails(paymentOrderId);
}

Ortak etiket (TEX / Aras, Trendyol öder)

import { isCommonLabelNotAllowed } from "@hubcommerce/trendyol";

const created = await client.labels.createCommonLabel(cargoTrackingNumber);
if (!created.ok && isCommonLabelNotAllowed(created)) {
  // capability yok — alternatif kargo akışı
}

const label = await client.labels.getCommonLabel(cargoTrackingNumber);

// AB ihracat varyantı
await client.labels.getCommonLabelWithAbProduct(cargoTrackingNumber, {
  productLabelType: "ZPL",
});

Stage test helpers

import { createTestOrder, SHIPMENT_PACKAGE_FIXTURE } from "@hubcommerce/trendyol/testing";

Yalnızca stage — production config ile runtime guard throw eder.

Geliştirme

npm run build --workspace=@hubcommerce/trendyol
npm test --workspace=@hubcommerce/trendyol
npm run test:exports --workspace=@hubcommerce/trendyol
npm run qa:smoke --workspace=@hubcommerce/trendyol

Public API yüzeyi

Facade client domain modülleri:

| Modül | Açıklama | |-------|----------| | client.orders | Stream, mutasyon, split | | client.invoices | Link, dosya, silme | | client.inventory | Fiyat/stok toplu | | client.reference | Marka, kategori, adres, geo | | client.products | V2 CRUD, filter, buybox | | client.batch | waitForResult poll | | client.video | Video upload + poll | | client.warranty | Garanti belgesi | | client.claims | İade | | client.webhooks | CRUD | | client.finance | Hakedis, settlements | | client.qna | Müşteri soruları | | client.labels | Ortak etiket ZPL | | client.compensation | TEX tazmin | | client.testConnection() | Canonical bağlantı testi |

Root export helper'lar: parseWebhookPayload, verifyWebhookApiKey, validateEan13, buildProductCreatePayload, statik sabitler (CLAIM_REASONS, ORIGIN_COUNTRIES, …).

Migration

• Ürün V1 kapanış: 15 Eylül 2026
• Sipariş V1 kapanış: 15 Ekim 2026

Detay: docs/MIGRATION.md

Lisans

MIT — LICENSE