hikiehikieDeveloper Documentation
Endpoint'ler

İndirimler

Kendi sisteminizden tekil, tek kullanımlık kodlu kampanyalar oluşturun ve kodları iş ortaklarınıza dağıtın.

Mağazanız için binlerce tekil koda ihtiyaç duyduğunuzda indirim endpoint'lerini kullanın — örneğin her katılımcıya kişiye özel, tek kullanımlık %20 kod verilen bir hikie Ekim Kampanyası. Kuralı bir kampanyada bir kez kurarsınız, ona istediğiniz kadar kod eklersiniz, kodları kendi kanallarınızdan dağıtırsınız ve her alıcı ödeme sırasında bir kodu kullanır.

Kodlar yalnızca tek seferlik dijital ürünlerde ve TL ödemelerde geçerlidir. Abonelikli dijital ürünler indirim kodu kabul etmez.

Yapı

NesneNe tutarKim oluşturur
KampanyaKural: yüzde ya da tutar indirimi, minimum fiyat, başlangıç ve bitiş tarihi, hangi dijital ürünlerPanel (Kampanyalar → Tekil kodlar) ya da POST /v1/campaigns
KodAlıcının yazdığı metin ve kaç kez kullanılabileceğiPanel (Kod üret) ya da POST /v1/campaigns/{id}/codes

Kodun kendi kuralı yoktur. Kampanyayı değiştirmek (durdurmak, bitiş tarihini uzatmak) tüm kodlarına birlikte uygulanır.

Erişim

  1. Panelde Ayarlar → API Anahtarları sayfasından discount_codes:read ve discount_codes:write izinli bir anahtar oluşturun (bkz. Mağaza API anahtarları). Anahtar hks_ ile başlar ve yalnızca bir kez gösterilir. Sunucunuzun gizli anahtar deposunda saklayın. İzinli anahtarlar gelmeden önce oluşturulmuş bir mağaza API anahtarı da burada geçer.
  2. Kampanya ve kod endpoint'leri geliştirici erişiminiz onaylandığında açılır. Ayarlar → Webhooklar sayfasından başvurun; aynı onay hem webhook'ları hem bu endpoint'leri da kapsar. O zamana kadar bu endpoint'ler 403 API_ACCESS_NOT_APPROVED döner.
  3. Anahtarı Bearer olarak gönderin:
curl https://api.hikie.space/v1/campaigns \
  -H "Authorization: Bearer hks_..."

Bir anahtarı yenilemek eski gizli değerini anında geçersiz kılar. Anahtarı tarayıcıya, mobil uygulamaya ya da herkese açık bir depoya koymayın.

Her POST isteğine Idempotency-Key başlığı ekleyin. İzinli anahtarlarda zorunludur ve güvenle tekrar etmenizi sağlar; bkz. İstekler ve sınırlar.

Hızlı başlangıç

Kampanya oluşturun

curl -X POST https://api.hikie.space/v1/campaigns \
  -H "Authorization: Bearer hks_..." \
  -H "Idempotency-Key: ekim-kampanyasi-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hikie Ekim Kampanyası",
    "type": "percent",
    "percentOff": 20,
    "expiresAt": "2026-12-31T23:59:59+03:00"
  }'

Yanıtta kampanyanın id'si döner.

Kod ekleyin

curl -X POST https://api.hikie.space/v1/campaigns/{id}/codes \
  -H "Authorization: Bearer hks_..." \
  -H "Idempotency-Key: ekim-kodlari-grup-001" \
  -H "Content-Type: application/json" \
  -d '{ "codes": [ { "code": "HIKIE-7K3M9QX2TR" }, { "code": "HIKIE-H4WQ8N2ZC6" } ] }'

Tek istekte en fazla 1000 kod. numAvailable vermezseniz her kod tek kullanımlıktır. Zaten var olan bir kodu göndermek onu exists olarak döndürür; tekrarlanan bir istek asla kopya oluşturmaz.

Kullanımı takip edin

GET /v1/discount-codes/{code} numUsed ve numAvailable döner. order.paid webhook'una aboneyseniz kullanılan kod discounts[].code alanında gelir.

Kampanyalar

YöntemYolAçıklama
POST/campaignsKampanya oluşturur
GET/campaignsTekil kodlu kampanyalarınızı listeler
GET/campaigns/{id}Tek kampanya
PATCH/campaigns/{id}name, isActive ya da expiresAt değiştirir

Burada oluşturulan kampanyalar panelde Kampanyalar altında da görünür; panelde Tekil kodlar ile oluşturulan kampanyalar da burada kullanılabilir.

Oluşturma alanları

Alan

Tip

? ile gösterilse de percentOff ve amountOff'tan biri type'a göre her zaman zorunludur. Sayısal alanlar sayı içeren dizgileri de ("20") kabul eder.

Kampanya nesnesi

{
  "id": "6720c1f0a9b1c2d3e4f5a6b7",
  "name": "hikie Ekim Kampanyası",
  "type": "percent",
  "percentOff": 20,
  "amountOff": null,
  "amountMinimum": 0,
  "currency": "TRY",
  "startsAt": null,
  "expiresAt": "2026-12-31T20:59:59.000Z",
  "membershipIds": [],
  "isActive": true,
  "codes": { "total": 2000, "used": 312, "reserved": 4, "remaining": 1684 },
  "createdAt": "2026-10-01T09:00:00.000Z"
}

codes.total, kampanyadaki kodların toplam kullanım hakkıdır (2000 tek kullanımlık kod → 2000). codes.reserved ödemesi süren kullanımları sayar. GET /campaigns şu biçimde döner: { "items": [ …kampanya nesneleri… ] }.

Durdurma ya da uzatma

curl -X PATCH https://api.hikie.space/v1/campaigns/{id} \
  -H "Authorization: Bearer hks_..." \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

Kampanyayı durdurmak tüm kodlarını birlikte durdurur.

Kodlar

YöntemYolAçıklama
POST/campaigns/{id}/codesEn fazla 1000 kod ekler
GET/campaigns/{id}/codesKampanyanın kodları (page, limit ≤ 100)
GET/discount-codes/{code}Tek kod
PATCH/discount-codes/{code}isActive ayarlar
DELETE/discount-codes/{code}Hiç kullanılmamış kodu siler (204)

Kod ekleme

Alan

Tip

{ "results": [
  { "code": "HIKIE-7K3M9QX2TR", "status": "created", "id": "6720c2…" },
  { "code": "HIKIE-H4WQ8N2ZC6", "status": "exists" }
] }

Bir kod mağazanızda, tüm kampanyalar genelinde tekildir. Herhangi bir öğe geçersizse istek bütünüyle 400 döner ve hiçbir kod oluşturulmaz.

Kod nesnesi

{
  "id": "6720c2a1b2c3d4e5f6a7b8c9",
  "code": "HIKIE-7K3M9QX2TR",
  "campaignId": "6720c1f0a9b1c2d3e4f5a6b7",
  "maxUses": 1,
  "numUsed": 0,
  "numAvailable": 1,
  "isActive": true,
  "createdAt": "2026-10-01T09:05:00.000Z"
}

Gönderdiğiniz kodda numAvailable toplam kullanım hakkıdır; geri okuduğunuz kodda ise kalan haktır ve ödemesi süren kullanımları içermez.

GET /campaigns/{id}/codes şu biçimde döner: { "items": [...], "total": 2000, "page": 1, "limit": 50 }.

Silme ya da pasife alma

Kullanılmış ya da ödemesi süren bir kod silinemez — DELETE 409 DISCOUNT_CODE_IN_USE döner. Bunun yerine isActive: false gönderin.

Bir kullanım nasıl sayılır

Alıcı ödeme yaparken kod onun için ayrılır. Ödeme başarılı olursa kullanılmış sayılır; ödeme reddedilirse hemen yeniden kullanılabilir hale gelir. Alıcı ödemeyi yarıda bırakırsa kod 15 dakika sonra — aynı alıcı yeniden denerse hemen — boşalır. Son kalan hakkı iki alıcı aynı anda kullanamaz.

Sınırlar

  • Her anahtarın dakikada 1–200 istekle kendi sınırı vardır; bkz. İstekler ve sınırlar.
  • Kod: 8–40 karakter; A–Z, 0–9 ve -. Küçük harfle gönderilen kod büyük harfe çevrilir.
  • Tek istekte en fazla 1000 kod.

Bu sayfada