Ü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 yol | Sonuç |
|---|---|
POST /products | Taslak ü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:
shipmentAdressCollected | paymentType | Oluşan type | Sonuç |
|---|---|---|---|
true | one-off | physical | Tek varyantlı, verdiğiniz stock değerli ve ücretli kargolu taslak |
false | one-off, recurring ya da free | membership | Taslak, 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.
paymentType | price | Kimler kullanabilir | Tekrarlayan alanlar |
|---|---|---|---|
one-off | Zorunlu | Her ürün | Verilemez |
recurring | Zorunlu: her tahsilatın tutarı | Teslimat adresi toplanmayan ürün; dijital ürün oluşturur | Dördü de zorunlu |
free | null ya da hiç vermeyin | Teslimat adresi toplanmayan ürün; dijital ürün oluşturur | Verilemez |
Ü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.
| Durum | errorCode | Ne zaman |
|---|---|---|
400 | PAYMENT_TYPE_NOT_ALLOWED | shipmentAdressCollected: true ile birlikte recurring / free |
400 | PRICE_REQUIRED | Geçerli price olmadan one-off ya da recurring |
400 | PRICE_NOT_ALLOWED | free üründe price verilmiş |
400 | RECURRING_FIELDS_REQUIRED | recurring iken dört tekrarlayan alandan biri eksik |
400 | RECURRING_FIELDS_NOT_ALLOWED | one-off ya da free üründe tekrarlayan alan verilmiş |
400 | PAYMENT_PERIOD_NOT_SUPPORTED | weekly ya da day / week cinsinden süre |
400 | INVALID_PAYMENT_PERIOD | paymentPeriodCount, periyodun sınırını aşıyor |
400 | INVALID_DURATION | Toplam 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}'| Durum | errorCode | Ne zaman |
|---|---|---|
400 | EMPTY_UPDATE | Gövdede değiştirilecek alan yok |
404 | PRODUCT_NOT_FOUND | Mağazanızda böyle bir ürün yok |
409 | PRODUCT_HAS_VARIANTS | Birden çok varyantlı ürüne API ile tek fiyat verilemez; panelden düzenleyin |
409 | PRICE_CHANGE_NOT_ALLOWED | Abonelikli 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 |
409 | DISCOUNT_EXCEEDS_PRICE | Yeni 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ün | Yayında | Yayından kaldırılmış |
|---|---|---|
| Fiziksel ürün ya da eski tip dijital ürün | active | inactive |
| Dijital ürün | active ve görünür | draft |
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'yiimagesiçinde kullanın. Ürünler yalnızca bu yolla yüklenmiş görselleri kabul eder: başka her adres400 IMAGE_URL_NOT_ALLOWEDdöner ve hikie sizin için uzak bir adresten görsel çekmez. - Aynı görseli bir istekte iki kez vermek
400 IMAGE_DUPLICATEdöner.
errorCode | Ne zaman |
|---|---|
IMAGE_REQUIRED | file alanı yok |
IMAGE_TOO_LARGE | 10 MB'dan büyük |
IMAGE_TYPE_NOT_ALLOWED | JPEG, PNG ya da WebP değil |
IMAGE_URL_NOT_ALLOWED | images içindeki bir adres bu endpoint'le yüklenmemiş |
IMAGE_DUPLICATE | Aynı 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.