# 🛒 trendyol-mcp

Trendyol **Satıcı (Seller) API** için MCP (Model Context Protocol) sunucusu: ürün kataloğu, siparişler, iade/talepler, finans (settlement / diğer finansal işlemler / kargo faturası), müşteri faturaları, müşteri soruları (Q&A) ve webhook yönetimi — toplam 52 araç.

[cemre-2187/trendyol-api](https://github.com/cemre-2187/trendyol-api) paketinin bağımlılıksız portudur: HTTP çağrıları için ek kütüphane yerine Node'un yerleşik `fetch`'i kullanılır ve tüm uçlar güncel `https://apigw.trendyol.com/integration` tabanına taşınmıştır.

> ⚠️ Bu sunucu **canlı satıcı hesabınıza** bağlanır. Yazma araçları (ürün oluşturma/güncelleme, fiyat-stok, iade onaylama, fatura gönderme) gerçek veriyi değiştirir. Önce salt okunur araçlarla başlayın.

## Kurulum

Node.js 20.12+ gerekir.

```bash
git clone https://github.com/bevren/trendyol-market-mcp.git
cd trendyol-market-mcp
npm install
```

### Kimlik Bilgileri

Değerleri **Satıcı Paneli > Hesap Bilgileri > Entegrasyon Bilgileri** sayfasından alın.

```bash
Copy-Item .env.example .env   # sonra değerleri doldurun (.env git tarafından yok sayılır)
npm start
```

> ⚠️ `.env` dosyasını PowerShell ile sıfırdan **oluşturmayın**. `Set-Content -Encoding utf8` dosya başına BOM ekler; Node'un `--env-file` ayrıştırıcısı BOM'u temizlemediği için **dosyadaki ilk değişken sessizce yüklenmez**. `.env.example` dosyasını `Copy-Item` ile kopyalayın.

Alternatif olarak kimlik bilgileri çalışma anında `trendyol_configure` aracıyla da verilebilir.

| Değişken | Açıklama |
| --- | --- |
| `TRENDYOL_SELLER_ID` | Satıcı (supplier) ID |
| `TRENDYOL_API_KEY` | API anahtarı |
| `TRENDYOL_API_SECRET` | API gizli anahtarı |
| `TRENDYOL_STAGE_MODE` | `1`/`true`: tüm çağrılar `stageapigw.trendyol.com`'a gider (aşağıdaki nota bakın) |

### Claude Code

```bash
claude mcp add trendyol -- npx tsx <bu-deponun-yolu>/src/index.ts
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "trendyol": {
      "command": "npx",
      "args": ["tsx", "<bu-deponun-yolu>/src/index.ts"],
      "env": {
        "TRENDYOL_SELLER_ID": "...",
        "TRENDYOL_API_KEY": "...",
        "TRENDYOL_API_SECRET": "..."
      }
    }
  }
}
```

## Araçlar

| Grup | Araçlar |
| --- | --- |
| **Oturum** | `trendyol_configure`, `trendyol_session_info` |
| **Marka & Kategori** | `trendyol_get_brands`, `trendyol_get_brand_by_name`, `trendyol_create_brand`, `trendyol_get_category_tree`, `trendyol_get_category_attributes`, `trendyol_get_category_attribute_values` |
| **Ürün oluşturma/güncelleme** | `trendyol_create_products`, `trendyol_update_unapproved_products`, `trendyol_update_approved_product_content`, `trendyol_update_approved_product_variants`, `trendyol_update_product_delivery_info`, `trendyol_update_price_and_inventory` |
| **Ürün yaşam döngüsü** | `trendyol_archive_products`, `trendyol_unlock_products`, `trendyol_delete_products`, `trendyol_get_batch_request_result` |
| **Ürün sorgulama** | `trendyol_get_products`, `trendyol_filter_approved_products`, `trendyol_filter_unapproved_products`, `trendyol_filter_approved_products_inventory_and_price`, `trendyol_get_product_status`, `trendyol_get_buybox_info`, `trendyol_get_product_update_audits` |
| **Video** | `trendyol_create_video`, `trendyol_get_videos` |
| **Sipariş & Adres** | `trendyol_get_orders`, `trendyol_get_supplier_addresses` |
| **İade / Talep** | `trendyol_get_claims`, `trendyol_create_claim`, `trendyol_approve_claim_items`, `trendyol_create_claim_issue`, `trendyol_get_claim_issue_reasons`, `trendyol_get_claim_audits` |
| **Finans** | `trendyol_get_settlements`, `trendyol_get_other_financials`, `trendyol_get_cargo_invoice_items` |
| **Müşteri faturaları** | `trendyol_send_invoice_link`, `trendyol_delete_invoice_link`, `trendyol_send_invoice_file` |
| **Müşteri soruları** | `trendyol_get_questions`, `trendyol_get_question_by_id`, `trendyol_create_answer` |
| **Webhook** | `trendyol_register_webhook`, `trendyol_get_webhooks`, `trendyol_delete_webhook` |
| **Referans veri** | `trendyol_get_reference_data` (işlem türleri, iade nedenleri, kargo firmaları, menşei kodları, soru durumları, video içerik türleri…) |
| **Test (yalnızca stage)** | `trendyol_create_test_order`, `trendyol_update_test_order_status`, `trendyol_update_test_claim_to_waiting_in_action`, `trendyol_create_test_question` |

## Testler

```bash
npm run smoke   # MCP el sıkışması + araç listesi + şema testleri (ağ gerektirmez)
```

Smoke test sunucuyu doğrudan spawn ettiği için `.env` yüklenmez; tüm çağrılar kimlik bilgisi kapısında durur ve canlı API'ye istek gitmez.

## Bilinen Notlar

- **Stage ortamı panel kimlik bilgileriyle çalışmıyor** (16 Tem 2026'da doğrulandı): `stageapigw.trendyol.com`, panel anahtarlarını Cloudflare seviyesinde **403** ile reddeder — istek Trendyol'a hiç ulaşmaz. Aynı kimlikle prod 200 döner. Yani `TRENDYOL_STAGE_MODE=1` bir güvenlik ağı **değildir**: canlı veriyi korumaz, yalnızca her çağrıyı 403'e düşürür. Stage, Trendyol entegrasyon ekibinden talep edilen **ayrı test kimlikleri** ister; bu kimlikler olmadan `test_*` araçları kullanılamaz.
- **Finans uçları en fazla 15 günlük aralık kabul eder.** İstemci, verilen aralığı otomatik olarak 15 günlük pencerelere böler ve tüm sayfaları birleştirir. `transactionType` (tekil) veya `transactionTypes` (çoğul) zorunludur. Kayıtlar sipariş **teslim edildikten sonra** oluşur.
- **Müşteri soruları için 2 haftalık aralık sınırı sessizdir:** Trendyol aşımda hata vermez, `endDate`'i sessizce `startDate + 2 hafta` yapar. Bu yüzden araç uzun aralığı baştan reddeder.
- `invoiceNumber` biçimi 4 Ağustos 2023'ten beri **[3 alfanümerik][13 rakam] = 16 hane**'dir (Trendyol dokümanındaki `TY4874324` örneği bu kurala uymuyor; kural uygulanmıştır). Fatura bağlantısı yasal olarak 8 yıl erişilebilir kalmalıdır.
- `trendyol_get_products` eski (`/product/sellers/{id}/products`) ucu kullanır ve yeni `filter_*` araçlarıyla örtüşür; geriye dönük uyumluluk için tutulmaktadır.
- Doğrulama kuralları ağ çağrısından önce çalışır: `listPrice ≥ salePrice`, `fastDeliveryType` için `deliveryDuration=1`, barkod karakter kümesi, ≤8 görsel, ≤10 buybox barkodu, `page × size ≤ 10000`, video başlığı 3-50 karakter.