hikiehikieDeveloper Documentation
Endpoint'ler

Ürünler

Fiziksel ve dijital ürün oluşturun, düzenleyin, görsel yükleyin ve yayına alın.

Bunların hepsi products:write izni ister ve her POST Idempotency-Key ister. Tanımsız alanlar 400 ile reddedilir.

Yöntem ve yolSonuç
POST /productsTaslak ürün oluşturur
PATCH /products/{id}Ad, açıklama, fiyat ya da görselleri düzenler
POST /products/{id}/publishÜrünü satışa açar
POST /products/{id}/unpublishÜrünü satıştan kaldırır
POST /imagesÜründe kullanılacak görsel yükler

Akış

Görselleri yükleyin (isteğe bağlı)

Her görseli POST /images ile yükleyin ve dönen url'yi saklayın.

Taslağı oluşturun

POST /products ürünü taslak olarak oluşturur. Henüz satışta değildir.

Teslimat içeriğini hazırlayın

API, alıcının neyi alacağını belirlemez. Dijital ürünü panelde açıp erişilecek içeriği ekleyin ya da ürünü kendiniz teslim edin.

Yayına alın

POST /products/{id}/publish ürünü satışa açar.

Yayına almak, teslimat içeriği olup olmadığını denetlemez. Yayına almadan önce içeriği ekleyin; yoksa alıcılar boş bir ürün için ödeme yapar.

Ürün oluşturma

POST /products

Alan

Tip

? işaretli alanlar isteğe bağlıdır; tek istisna: paymentPeriod, paymentPeriodCount, durationInCycleCount ve durationInCyclePeriod alanlarının dördü de paymentType recurring iken zorunludur, diğerlerinde verilemez.

curl -X POST https://api.hikie.space/v1/products \
  -H "Authorization: Bearer hks_..." \
  -H "Idempotency-Key: seramik-kupa-2026-11-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Seramik kupa",
    "description": "El yapımı sır, 300 ml",
    "price": 289,
    "stock": 40,
    "vatRate": 20,
    "paymentType": "one-off",
    "shipmentAdressCollected": true
  }'

Yanıt, yeni ürünle birlikte 201 döner:

{
  "id": "66b1efd21c9a4e0021f3ab77",
  "type": "physical",
  "name": "Seramik kupa",
  "status": "draft",
  "price": 289,
  "images": [],
  "paymentType": "one-off",
  "vatRate": 20,
  "shipmentAdressCollected": true,
  "paymentPeriod": null,
  "paymentPeriodCount": null,
  "durationInCycleCount": null,
  "durationInCyclePeriod": null
}

Yanıt, gönderdiğiniz değerleri aynen tekrarlar; type hangi tür ürünün oluştuğunu gösterir.

Ürün türü

type göndermezsiniz. Tür, zorunlu shipmentAdressCollected ve paymentType alanlarından çıkar; type göndermek 400 döner:

shipmentAdressCollectedpaymentTypeOluşan typeSonuç
trueone-offphysicalTek varyantlı, verdiğiniz stock değerli ve ücretli kargolu taslak
falseone-off, recurring ya da freemembershipTaslak, gizli, sizin teslim ettiğiniz, stoğu sınırsız dijital ürün; bkz. Ödeme tipleri

Dijital ürünün API'deki type değeri membership'tir. Panelde daha önce açılmış eski tip dijital ürünler (type: "digital") API ile açılmaz, ama GET /products ile okunmaya ve düzenlenmeye devam eder.

stock yalnızca shipmentAdressCollected: true ile kabul edilir; aksi halde 400 STOCK_NOT_ALLOWED döner.

Ödeme tipleri

paymentType, alıcının nasıl ödeme yapacağını belirler. Zorunludur ve varsayılanı yoktur: tek seferlik ödemede de one-off gönderin.

paymentTypepriceKimler kullanabilirTekrarlayan alanlar
one-offZorunluHer ürünVerilemez
recurringZorunlu: her tahsilatın tutarıTeslimat adresi toplanmayan ürün; dijital ürün oluştururDördü de zorunlu
freenull ya da hiç vermeyinTeslimat adresi toplanmayan ürün; dijital ürün oluştururVerilemez

Ücretsiz ürünün fiyatı yoktur: price her yanıtta null döner.

shipmentAdressCollected true olduğunda ürün fizikseldir ve yalnızca one-off seçilebilir. recurring ya da free istemek 400 PAYMENT_TYPE_NOT_ALLOWED döner.

recurring ürün, durationInCycleCount × durationInCyclePeriod süresi dolana kadar her paymentPeriodCount × paymentPeriod sürede bir tahsil edilir. Toplam süre, tahsilat periyodunun tam katı olmalıdır. Toplam süre her zaman zorunludur: API bilerek süresiz abonelik açmaz; bitiş tarihi olmayan bir plan panelden açılır. Aşağıdaki dijital ürün bir yıl boyunca her ay 99 TL tahsil eder; toplam 12 tahsilat:

curl -X POST https://api.hikie.space/v1/products \
  -H "Authorization: Bearer hks_..." \
  -H "Idempotency-Key: pro-plan-2026-11-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro plan",
    "price": 99,
    "vatRate": 20,
    "shipmentAdressCollected": false,
    "paymentType": "recurring",
    "paymentPeriod": "monthly",
    "paymentPeriodCount": 1,
    "durationInCycleCount": 12,
    "durationInCyclePeriod": "month"
  }'

Ücretsiz dijital ürün:

{ "name": "Topluluk", "paymentType": "free", "vatRate": 0, "shipmentAdressCollected": false }

weekly tahsilat ve day ya da week cinsinden süre henüz yok; 400 PAYMENT_PERIOD_NOT_SUPPORTED döner. En çok 120 ay ve 60 tahsilat. Abonelikli dijital ürünün fiyatı yalnızca panelden değiştirilir.

DurumerrorCodeNe zaman
400PAYMENT_TYPE_NOT_ALLOWEDshipmentAdressCollected: true ile birlikte recurring / free
400PRICE_REQUIREDGeçerli price olmadan one-off ya da recurring
400PRICE_NOT_ALLOWEDfree üründe price verilmiş
400RECURRING_FIELDS_REQUIREDrecurring iken dört tekrarlayan alandan biri eksik
400RECURRING_FIELDS_NOT_ALLOWEDone-off ya da free üründe tekrarlayan alan verilmiş
400PAYMENT_PERIOD_NOT_SUPPORTEDweekly ya da day / week cinsinden süre
400INVALID_PAYMENT_PERIODpaymentPeriodCount, periyodun sınırını aşıyor
400INVALID_DURATIONToplam süre tahsilat periyodunun tam katı değil ya da 120 ay / 60 tahsilatı aşıyor

Sınırlar

Bir mağaza günde en çok 50 ürün oluşturabilir (Türkiye saatiyle). Aşarsanız 429 DAILY_LIMIT_REACHED alırsınız. Başarısız olan istek kotadan düşmez.

Nadiren ürün kaydedilir ama yanıt hazırlanırken henüz görünür olmaz. Bu durumda yanıtta "id": null ve "syncPending": true bulunur. Ürün oluşturulmuştur. İsteği yeni bir Idempotency-Key ile tekrar göndermeyin; yoksa çift ürün olur. Ürünü panelinizde bulun.

Ürün düzenleme

PATCH /products/{id}, name, description, price ve images alanlarından herhangi birini alır. Panelden oluşturulanlar dahil, mağazanızdaki her ürün için çalışır. Yanıt güncellenmiş üründür.

curl -X PATCH https://api.hikie.space/v1/products/66b1efd21c9a4e0021f3ab77 \
  -H "Authorization: Bearer hks_..." \
  -H "Idempotency-Key: seramik-kupa-fiyat-2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{"price": 269}'
DurumerrorCodeNe zaman
400EMPTY_UPDATEGövdede değiştirilecek alan yok
404PRODUCT_NOT_FOUNDMağazanızda böyle bir ürün yok
409PRODUCT_HAS_VARIANTSBirden çok varyantlı ürüne API ile tek fiyat verilemez; panelden düzenleyin
409PRICE_CHANGE_NOT_ALLOWEDAbonelikli dijital ürünün fiyatı yalnızca panelden değiştirilir; çünkü mevcut abonelere bildirilmelidir. Ücretsiz dijital ürünün değiştirilecek bir fiyatı yoktur
409DISCOUNT_EXCEEDS_PRICEYeni fiyat, ürünün mevcut indirimli fiyatının üzerinde değil

Fiziksel ürünün stoğunu düzenlemek bu sürümde yoktur.

Yayına alma ve yayından kaldırma

POST /products/{id}/publish ve POST /products/{id}/unpublish, ürünü yeni status değeriyle 200 olarak döner.

ÜrünYayındaYayından kaldırılmış
Fiziksel ürün ya da eski tip dijital ürünactiveinactive
Dijital ürünactive ve görünürdraft

Yayına almak için gerekenler:

  • Doğrulanmış bir mağaza; yoksa 403 STORE_NOT_VERIFIED.
  • Fiziksel üründe ya da eski tip dijital üründe sıfırdan büyük fiyat; fiziksel üründe ayrıca sıfırdan büyük stok (ya da stoksuz satışa izin) gerekir; yoksa 409 PRODUCT_NOT_READY.

Yayından kaldırmak doğrulama istemez. Bir ürünü yayından kaldırmak, ödeme alma linklerini de çalışmaz hâle getirir.

Görsel yükleme

POST /images, file alanında multipart/form-data olarak tek bir dosya alır.

curl -X POST https://api.hikie.space/v1/images \
  -H "Authorization: Bearer hks_..." \
  -H "Idempotency-Key: kupa-foto-1" \
  -F "[email protected]"
{ "url": "https://…/9f2c….jpg" }
  • JPEG, PNG ve WebP, en çok 10 MB. Tür, dosyanın adına ya da Content-Type'a değil, dosyanın kendisine bakılarak belirlenir.
  • Günde en çok 300 yükleme (Türkiye saatiyle).
  • Dönen url'yi images içinde kullanın. Ürünler yalnızca bu yolla yüklenmiş görselleri kabul eder: başka her adres 400 IMAGE_URL_NOT_ALLOWED döner ve hikie sizin için uzak bir adresten görsel çekmez.
  • Aynı görseli bir istekte iki kez vermek 400 IMAGE_DUPLICATE döner.
errorCodeNe zaman
IMAGE_REQUIREDfile alanı yok
IMAGE_TOO_LARGE10 MB'dan büyük
IMAGE_TYPE_NOT_ALLOWEDJPEG, PNG ya da WebP değil
IMAGE_URL_NOT_ALLOWEDimages içindeki bir adres bu endpoint'le yüklenmemiş
IMAGE_DUPLICATEAynı adres iki kez var

Ürünleri geri okuma

GET /products ve GET /products/{id} dijital ürünleri (eski tip dahil) döner; fiziksel ürünleri henüz döndürmez. GET /products/{id} aynı ödeme alanlarını döner. Bkz. Okuma işlemleri.

Bu sayfada