Hepsinde API

Ürün, stok ve fiyatınızı kendi sitenize alın; site siparişlerinizi Hepsinde'ye gönderin. Stok bütün pazaryerleriyle tek kaynaktan yönetilir.

Genel bakış

• Adres: https://api.hepsinde.app/v1. Bütün istek ve cevaplar JSON.
• Tutarlar TL cinsinden ondalık sayıdır (249.9). Tarihler ISO 8601 (2026-10-25T09:30:00Z).
• Stok, ürünün satılabilir adedidir: set ürünlerde en kısıtlı bileşene göre hesaplanır, bağlantıdaki stok tamponu düşülür.
• Fiyat, Hepsinde'deki satış fiyatına bu bağlantının kanal kuralı (yüzde/sabit fark, yuvarlama) uygulanmış haliyle gelir. Kuralı Fiyatlar sayfasından değiştirirsiniz.

Kimlik doğrulama

Hepsinde panelinde Bağlantılar › Mağaza bağla › Kendi siteniz › Özel site (API) ile bir bağlantı açın. Açılışta iki değer bir kez gösterilir:

Hızlı başlangıç

curl https://api.hepsinde.app/v1/ping \
  -H "Authorization: Bearer hs_live_…"

{"ok":true,"connection":{"id":"…","name":"mamacim.com"}}

Önerilen akış: ilk kurulumda GET /v1/products ile bütün kataloğu alın; sonra ya webhook'u dinleyin ya da birkaç dakikada bir updated_since ile yalnız değişenleri çekin. Her siparişi POST /v1/orders ile gönderin.

Ürünler

GET/v1/products

{
  "products": [
    {
      "id": "6f1c…",
      "sku": "MAMA-2KG",
      "barcode": "8680000000011",
      "title": "Kedi maması somonlu 2 kg",
      "description": "…",
      "brand": "Mamacım",
      "images": ["https://…/1.jpg"],
      "kind": "simple",
      "vatRate": 20,
      "desi": 2.5,
      "quantity": 8,
      "price": 274.89,
      "listPrice": 329.89,
      "currency": "TRY",
      "updatedAt": "2026-10-25T09:30:00.000Z"
    }
  ],
  "nextCursor": "WyIyMDI2LTEw…"
}

listPrice üstü çizili (liste) fiyattır, yoksa null. kind simple ya da set ürün için bundle.

GET/v1/products/{sku} — tek ürün (SKU ya da barkodla). Yoksa 404 product_not_found.

Stok listesi

GET/v1/stock — bütün ürünlerin yalnız stok ve fiyatı; tam eşitleme için hafif liste. limit 1–1000 (varsayılan 500), cursor.

{ "items": [ { "sku": "MAMA-2KG", "barcode": "8680000000011", "quantity": 8, "price": 274.89, "listPrice": 329.89 } ], "nextCursor": null }

Sipariş gönderme

POST/v1/orders

Sitenizde sipariş oluştuğunda ya da durumu değiştiğinde gönderin. Aynı id ile yeniden göndermek siparişi günceller; stok yalnız bir kez düşer. cancelled gönderilince stok geri gelir. Değişen stok bütün pazaryerlerine gider.

curl -X POST https://api.hepsinde.app/v1/orders \
  -H "Authorization: Bearer hs_live_…" -H "Content-Type: application/json" \
  -d '{
    "id": "WEB-1001", "number": "1001", "status": "processing", "total": 549.8,
    "customer": { "name": "Ayşe Yılmaz" },
    "lines": [ { "id": "1", "sku": "MAMA-2KG", "title": "Kedi maması 2 kg", "quantity": 2, "unitPrice": 274.9 } ]
  }'

201 { "order": { "id": "WEB-1001", "hepsindeId": "…", "number": "1001", "status": "picking", "cargo": { … } }, "created": true }

Hepsinde içindeki durum adları: awaiting, new, picking, invoiced, shipped, delivered, cancelled, returned.

Sipariş durumu

GET/v1/orders/{id} — Hepsinde'deki durum ve kargo bilgisi (ör. panelden paketlendi işaretlendiyse).

Webhook

Bağlantı ayarına bir https:// adresi girerseniz, stok ya da fiyat değiştiğinde Hepsinde o adrese POST gönderir. Adres girmezseniz bildirim gitmez; değişiklikleri updated_since ile çekersiniz.

{
  "id": "1b0e…",
  "event": "stock_price.updated",
  "sentAt": "2026-10-25T09:31:02.114Z",
  "data": {
    "items": [
      { "sku": "MAMA-2KG", "barcode": "8680000000011", "quantity": 7, "price": 274.89, "listPrice": 329.89 },
      { "sku": "KUM-10L", "barcode": null, "quantity": 3 }
    ]
  }
}

Fiyat değişmediyse kalemde yalnız quantity bulunur. 2xx dışında bir cevap ya da 15 saniyede cevap gelmezse bildirim birkaç kez yeniden denenir; başarısız kalan değişiklikler sonraki gönderimde yine gelir. Aynı kalem birden çok kez gelebilir; son gelen geçerlidir.

İmza doğrulama

Gövdeyi ham haliyle (JSON'a çevirmeden önce) imzalayın ve sabit zamanlı karşılaştırın.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return header?.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

PHP

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('HEPSINDE_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_HEPSINDE_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$event = json_decode($raw, true);

Hatalar ve sınırlar

{ "error": { "code": "invalid_api_key", "message": "API anahtarı geçersiz" } }

Hazır altyapılar

Siteniz WooCommerce, Shopify ya da ikas üzerindeyse kod yazmanız gerekmez: Bağlantılar'dan altyapınızı seçip mağaza anahtarınızı girin; Hepsinde ürünleri barkod/SKU ile eşler, stok ve fiyatı gönderir, siparişleri kendisi çeker. Başka bir altyapı (Ticimax, İdeasoft, T-Soft…) kullanıyorsanız bu API ile bağlayabilirsiniz; destek için [email protected].