Ne işe yarar?

E-ticaret sitenizi GhNCoDe paneline bağlar. Siteniz siparişlerini panele gönderir; siparişler Siparişler sayfasına E-Ticaret etiketiyle düşer, sesli bildirim çalar ve stoktan kendiliğinden düşülür. Siteniz stok ve fiyatı da panelden okur.

Adres: https://app.ghncode.com/api/v1 · Biçim: JSON · Karakter seti: UTF-8

1. Anahtar alma

1. app.ghncode.com'a girin → Entegrasyonlar → E-Ticaret kartı → API anahtarı oluştur.
2. Anahtar (ghn_live_ ile başlar) yalnız bir kez gösterilir; kopyalayıp sitenizin sunucu ayarlarına kaydedin.
3. Siparişlerin kabul edilmesi için kartta Siparişleri al açık olmalı.

Her istekte anahtarı başlıkta gönderin:

Authorization: Bearer ghn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Ürün, stok ve fiyat okuma

GET /products - ürünleri değişme sırasına göre parça parça verir (her yanıtta en çok 500).

Parametre	Açıklama
updated_since	İsteğe bağlı. Bu andan itibaren (bu an dahil) değişen ürünler (ISO 8601, ör. 2026-10-20T10:00:00Z). Stok bir siparişle düşünce de ürün "değişmiş" sayılır.
cursor	İsteğe bağlı. Bir önceki yanıttaki next_cursor değeri; aynen gönderin.
per_page	Yanıt başına ürün, en çok ve varsayılan 500.

curl -H "Authorization: Bearer $GHN_API_KEY" \
  "https://app.ghncode.com/api/v1/products?updated_since=2026-10-20T10:00:00Z"

{
  "data": [
    { "sku": "ABC1", "barcode": "8690000000001", "name": "Kedi Maması 1 kg", "unit": "adet",
      "stock": 12, "price": 149.9, "vat_rate": 20, "updated_at": "2026-10-20T11:30:00.000Z" }
  ],
  "per_page": 500, "has_more": true, "next_cursor": "eyJ0IjoiMjAyNi0xMC0yMFQxMTozMDowMCJ9..."
}

price ürünün E-Ticaret fiyatıdır; girilmemişse satış fiyatı verilir. barcode alanında birden çok barkod ; ile ayrılmış olabilir.

has_more true ise aynı isteği cursor=<next_cursor> ekleyerek tekrarlayın; next_cursor null gelene kadar devam edin.

Öneri: stok ve fiyatı 5-15 dakikada bir okuyun. updated_since olarak kendi saatinizi değil, bir önceki okumada aldığınız en büyük updated_at değerinin 5 dakika öncesini verin; böylece hiçbir değişiklik atlanmaz (aynı ürünün iki kez gelmesi sorun değildir).

GET /products/{sku} - tek ürün, aynı biçimde.

3. Sipariş gönderme

POST /orders

curl -X POST "https://app.ghncode.com/api/v1/orders" \
  -H "Authorization: Bearer $GHN_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "order_id": "WEB-1001",
    "placed_at": "2026-10-20T14:30:00+03:00",
    "customer": { "name": "Ayşe Yılmaz", "phone": "05551112233", "address": "Çankaya / Ankara" },
    "items": [
      { "sku": "ABC1", "barcode": "8690000000001", "name": "Kedi Maması 1 kg", "quantity": 2, "unit_price": 150 }
    ],
    "total": 300
  }'

Alan	Kural
order_id	Zorunlu. Sitenizdeki sipariş numarası; 1-100 karakter, harf, rakam, . - _
placed_at	Zorunlu. Sipariş tarihi (ISO 8601).
items	Zorunlu, 1-100 kalem. Her kalemde name, quantity (0'dan büyük, en çok 1000), unit_price ve sku ya da barcode'dan en az biri.
total	Zorunlu. Sipariş toplamı (TL).
customer	İsteğe bağlı: name, phone, address (en çok 500 karakter).

• Kalem önce stok koduyla (sku), bulunamazsa barkodla panel ürününe bağlanır ve stoktan düşülür. Hiçbiriyle bulunamayan kalem kaydedilir ama stoktan düşmez.
• Cevap 201: { "order_id": "WEB-1001", "status": "new", "created": true }
• Aynı order_id tekrar gönderilirse sipariş yeniden yazılmaz; 200 ve "created": false ile paneldeki güncel durum döner. Bağlantı koptuğunda gönül rahatlığıyla tekrar deneyebilirsiniz.
• Kontörle çalışan hesaplarda her sipariş kontör düşer; kontör biterse 402 döner, kontör yüklendikten sonra tekrar gönderin.

4. Sipariş durumu

GET /orders/{order_id} - siparişin paneldeki durumu:

{ "order_id": "WEB-1001", "status": "preparing", "placed_at": "2026-10-20T11:30:00.000Z" }

Durumlar: new yeni · accepted kabul edildi · preparing hazırlanıyor · ready_for_pickup hazır · shipped yola çıktı · delivered teslim edildi · cancelled iptal · returned iade.

POST /orders/{order_id}/status - siteden iptal ya da teslim bildirimi:

curl -X POST "https://app.ghncode.com/api/v1/orders/WEB-1001/status" \
  -H "Authorization: Bearer $GHN_API_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "cancelled" }'

Yalnız cancelled ve delivered gönderilebilir. İptalde düşülen stok geri eklenir. İptal edilmiş sipariş yeniden açılamaz. Hazırlanıyor / yola çıktı gibi adımları satıcı panelden ilerletir.

5. Hatalar

Bütün hatalar aynı biçimde döner: { "error": { "code": "...", "message": "..." } }

HTTP	code	Anlamı
401	invalid_key	Anahtar yok, hatalı ya da iptal edilmiş.
402	insufficient_credit	Kontör yetersiz, sipariş kaydedilmedi.
403	orders_disabled	Panelde "Siparişleri al" kapalı.
403	business_inactive	İşletme hesabı aktif değil.
404	not_found	Ürün ya da sipariş bulunamadı.
422	validation_error	Eksik ya da hatalı alan; message hangi alan olduğunu söyler.
429	rate_limited	Sınır aşıldı (aşağıda).
500	internal_error	Beklenmeyen hata; biraz sonra tekrar deneyin.
503	api_disabled	API geçici olarak kapalı.

6. Sınırlar

• Anahtar başına dakikada en çok 120 istek.
• Saatte en çok 200, günde en çok 1000 sipariş.
• İstek gövdesi en çok 256 KB.
• Hatalı anahtarla aynı adresten dakikada 30'dan fazla deneme yapılırsa o adres bir dakika bekletilir.

Sorularınız için: info@ghncode.com · WhatsApp 0532 409 76 61

← Ana sayfaya dön