NeroCart ile geliştirin
Mağazanızı muhasebe, ERP, kargo, pazaryeri ve kendi yazılımlarınızla bağlayın. Sürümlü REST API, imzalı webhook'lar ve OAuth 2.0 uygulamalarıyla güvenli, öngörülebilir ve kalıcı entegrasyonlar kurun.
Siparişler ve faturalar
Siparişleri çekin, durumlarını izleyin, kargoya verin, faturalarını alın.
Ürünler ve stok
Ürün, varyant, kategori ve görselleri yönetin; stoku depolar arasında eşitleyin.
Müşteriler
Müşteri kayıtlarını ve gruplarını CRM'inizle senkron tutun.
Webhook'lar
Yeni sipariş, ödeme, kargo, stok gibi 50'yi aşkın olayı anında, imzalı olarak alın.
Uygulamalar (OAuth)
Birçok mağazaya kurulan uygulamalar için OAuth 2.0 + PKCE ile izin akışı.
Vitrin API'si
Ürün listesi, sepet ve ödeme adımı için anahtarsız, herkese açık API.
Başlarken
- Anahtar oluşturun. Mağaza panelinde Ayarlar › Gelişmiş › API anahtarları sayfasında Yeni anahtar'a basın, bir ad verin ve her alan için Okuma, Yazma ya da Okuma ve yazma seçin.
- Anahtarı kopyalayın. Anahtar (
nck_…) yalnız bir kez gösterilir; programınızın gizli ayarlarına kaydedin. - İlk isteği gönderin. Her mağaza API'yi kendi alan adında yanıtlar:
curl https://magazaniz.com/api/v1/admin/orders?limit=10 \ -H "Authorization: Bearer nck_XXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
{
"data": [ { "id": 17217, "number": "GC-000003", "status": "confirmed", "total": { "amount_minor": 65000, "currency": "TRY" }, … } ],
"meta": { "total": 128, "limit": 10, "offset": 0, "page": 1, "total_pages": 13, "has_more": true }
}
Tutarlar her zaman para biriminin en küçük biriminde tam sayıdır (65000 = 650,00 TL); ondalık sayı kullanılmaz.
Test mağazası
Entegrasyonunuzu canlı bir mağazaya dokunmadan denemek için NeroCart size bir geliştirici test mağazası açar: ödemeler her zaman test modundadır (gerçek para alınmaz, siparişler test siparişidir, faturaya ve kargoya gitmez) ve sayfaları arama motorlarına kapalıdır. API, webhook'lar ve panel canlı mağazayla birebir aynıdır. İstemek için bize yazın.
Kimlik doğrulama ve güvenlik
Yönetim API'si (/api/v1/admin) her istekte Authorization: Bearer <anahtar> ister. Vitrin API'si (/api/v1/store) anahtarsızdır.
| Özellik | Nasıl çalışır |
|---|---|
| En az yetki | Her anahtar yalnız seçilen alanlara erişir: siparişler, ürünler, stok, müşteriler, indirim ve fiyatlar, kargo, raporlar. İade ve mağaza ayarları hiçbir anahtara açılmaz. |
| Saklama | Anahtar yalnız oluşturulurken gösterilir; sistemde yalnız SHA-256 izi tutulur. nck_ öneki ve anahtarın son yedi karakteri (CRC32 kontrol toplamı), sızan anahtarların yanlış alarm olmadan tanınmasını sağlar. |
| Süre | Anahtar 30 gün, 90 gün, 1 yıl sonra kendiliğinden kapanacak şekilde oluşturulabilir. |
| IP kısıtı | Anahtar yalnız belirtilen IP adreslerinden ya da CIDR aralıklarından (IPv4/IPv6) kabul edilebilir. |
| Mağaza kısıtı | Birden çok mağazası olan hesapta anahtar tek mağazaya bağlanabilir. |
| İz | Son kullanım zamanı tutulur; oluşturma, iptal ve silme işlem kayıtlarına yazılır. |
| Uygulamalar | Birçok mağazaya kurulan uygulamalar OAuth 2.0 yetkilendirme kodu akışını PKCE (RFC 7636) ile kullanır; mağaza sahibi izinleri onay ekranında görür. |
Anahtar sızarsa
NeroCart, GitHub'ın gizli anahtar tarama (secret scanning) programının ortağıdır. Bir NeroCart API anahtarı (nck_…) herkese açık bir GitHub deposuna, gist'e, issue'ya ya da pakete yüklenirse GitHub bize bildirir ve anahtar anında iptal edilir; o andan sonra anahtarla yapılan her çağrı reddedilir. İptal, mağazanın işlem kayıtlarına (Ayarlar › İşlem kayıtları) yazılır.
Anahtarı GitHub da bulsa siz de fark etseniz yapılacaklar:
- Yeni bir anahtar oluşturun: Ayarlar › API anahtarları'ndan, yalnız programınızın ihtiyaç duyduğu alanlarla; programın gizli ayarlarına (ortam değişkeni ya da gizli bilgi yöneticisi) koyun, koda asla yazmayın.
- Sızan anahtarı iptal edin: iptal edilmemişse Ayarlar › API anahtarları'ndan iptal edip silin.
- Anahtarı koddan ve geçmişten çıkarın: dosyayı silmek yetmez; geçmişi yeniden yazın (örneğin
git filter-repoile) ya da depoyu açığa çıkmış sayın. - Anahtarın ne yaptığına bakın: her anahtarın istek kaydı (Ayarlar › API anahtarları › anahtar) son 30 günün çağrılarını, işlem kayıtları yapılan değişiklikleri gösterir.
- Sonraki anahtarları daraltın: her programa ayrı anahtar, gereken en az alan, bir bitiş tarihi ve mümkünse IP izin listesi verin.
Size ait olmayan bir anahtar mı buldunuz ya da yardım mı gerekiyor? info@nerocart.com adresine yazın.
Webhook'lar
Panelde Ayarlar › Gelişmiş › Geliştirici sayfasından bir adres ekleyin ve olayları seçin. Her olay JSON olarak POST edilir:
{ "id": "…", "name": "order.paid", "v": 1, "at": "2026-11-09T10:53:37Z",
"aggregate_type": "order", "aggregate_id": 17217, "data": { … } }
| Başlık | Anlamı |
|---|---|
X-NeroCart-Signature | t=<unix>,v1=<HMAC-SHA256>; imza "<t>.<gövde>" üzerine, uç noktanın gizli anahtarıyla. Anahtar yenilenirken ikinci bir v1= eski anahtarla gelir; herhangi biri eşleşirse kabul edin. |
X-NeroCart-Event | Olayın adı, ör. order.paid |
X-NeroCart-Event-Id | Olayın kimliği: aynı olay iki kez gelirse bir kez işleyin. |
X-NeroCart-Event-Version | Gövdenin şema sürümü (v). |
X-NeroCart-Delivery-Id | Bu gönderimin kaydı; yeniden denemelerde aynıdır. |
2xx dışında bir yanıt ya da zaman aşımı olursa gönderim 12 kez, artan aralıklarla yeniden denenir; panelde her gönderimin kaydı ve Yeniden gönder düğmesi vardır.
İmzayı doğrulama
import crypto from "node:crypto";
export function verify(header, rawBody, secret, toleranceSec = 300) {
const parts = header.split(",").map((p) => p.trim().split("="));
const t = parts.find(([k]) => k === "t")?.[1];
const sigs = parts.filter(([k]) => k === "v1").map(([, v]) => v);
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
const want = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return sigs.some((s) => s.length === want.length &&
crypto.timingSafeEqual(Buffer.from(s), Buffer.from(want)));
}
function nerocart_verify(string $header, string $rawBody, string $secret, int $tolerance = 300): bool {
$t = null; $sigs = [];
foreach (explode(',', $header) as $part) {
[$k, $v] = array_pad(explode('=', trim($part), 2), 2, '');
if ($k === 't') $t = $v; elseif ($k === 'v1') $sigs[] = $v;
}
if ($t === null || abs(time() - (int)$t) > $tolerance) return false;
$want = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
foreach ($sigs as $s) if (hash_equals($want, $s)) return true;
return false;
}
import hashlib, hmac, time
def verify(header: str, raw_body: bytes, secret: str, tolerance: int = 300) -> bool:
parts = [p.strip().split("=", 1) for p in header.split(",")]
t = next((v for k, v in parts if k == "t"), None)
sigs = [v for k, v in parts if k == "v1"]
if t is None or abs(time.time() - int(t)) > tolerance:
return False
want = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(want, s) for s in sigs)
Olaylar
order.created, order.paid, order.shipped, order.delivered, order.cancelled, order.refunded, order.edited, fulfillment.tracking_updated, fulfillment.delivered, return.requested, return.closed, product.created, product.updated, product.deleted, price.changed, inventory.level_changed, cart.abandoned, category.updated, collection.updated, promotion.changed ve daha fazlası — tam liste ve her olayın gövde şeması API referansında.
Kurallar
Yanıtlar ve hatalar
Başarılı yanıt {"data": …}, hata {"error": {"code", "message", "details"}} biçimindedir. Her yanıtta X-Request-Id bulunur; destek isterken bu kimliği verin.
| Durum | Ne zaman |
|---|---|
400 | Eksik ya da hatalı alan (validation); details.field hangi alan olduğunu söyler. |
401 | Anahtar yok, yanlış, iptal edilmiş, süresi dolmuş ya da izin verilmeyen bir IP'den. |
403 | Anahtarın bu alana izni yok. |
404 | Kayıt yok ya da bu mağazanın değil. |
409 | Durum çakışması (ör. aynı istek hâlâ işleniyor). |
422 | Aynı Idempotency-Key farklı bir istekle kullanıldı. |
429 | Hız sınırı; Retry-After kadar bekleyip yeniden deneyin. |
Sayfalama
Listeler limit (en çok 200, varsayılan 50) ile offset ya da page alır. Yanıttaki meta toplamı ve has_more bilgisini verir; Link başlığı (RFC 8288) ilk, önceki, sonraki ve son sayfaları gösterir. rel="next" kalmayana kadar izleyin:
Link: </api/v1/admin/orders?limit=50&offset=0>; rel="first", </api/v1/admin/orders?limit=50&offset=100>; rel="next", </api/v1/admin/orders?limit=50&offset=1250>; rel="last"
Tekrarlanan istekler (Idempotency-Key)
Her POST, PUT, PATCH ve DELETE isteğine benzersiz bir Idempotency-Key ekleyin. Bağlantı kopup istek yeniden gönderilirse ilk yanıt aynen döner (Idempotent-Replayed: true) ve işlem ikinci kez yapılmaz. Anahtar 24 saat saklanır.
curl -X POST https://magazaniz.com/api/v1/admin/products \
-H "Authorization: Bearer nck_…" -H "Idempotency-Key: 6f1c2b7e-urun-aktarim-001" \
-H "Content-Type: application/json" -d '{"title":"Yeşil Çay 100 g", …}'
Hız sınırları
| Kapsam | Sınır |
|---|---|
| API anahtarı başına | dakikada 600 istek (anlık 120) |
| IP adresi başına | dakikada 1.200 istek (anlık 300) |
Her yanıt RateLimit-Limit ve RateLimit-Remaining başlıklarını taşır; sınır aşılınca 429 ve Retry-After gelir.
Sürümler
API /api/v1 altındadır ve bu sürüm içinde yalnız büyür: alan ya da adres kaldırılmaz, anlamı değiştirilmez; bu kural her yayında otomatik sözleşme denetimiyle korunur. Kırıcı bir değişiklik ancak yeni bir sürümle (/api/v2) ve önceden duyurulan bir geçiş süresiyle yapılır.
Postman ve kod üretme
API'nin tamamı OpenAPI 3 sözleşmesiyle tanımlı; istemci kodu ve deneme koleksiyonu ondan üretilir.
Postman
Postman'de Import › Link ile https://nerocart.com/developers/postman.json adresini verin. Koleksiyonun değişkenlerinde baseUrl mağazanızın adresi, apiKey anahtarınız olsun.
TypeScript / JavaScript
npx openapi-typescript https://nerocart.com/doc -o nerocart.d.ts npm i openapi-fetch
import createClient from "openapi-fetch";
import type { paths } from "./nerocart";
const api = createClient<paths>({ baseUrl: "https://magazaniz.com", headers: { Authorization: `Bearer ${process.env.NEROCART_KEY}` } });
const { data } = await api.GET("/api/v1/admin/orders", { params: { query: { limit: 50 } } });
PHP, Python, Java, C#, Go
npx @openapitools/openapi-generator-cli generate -i https://nerocart.com/doc -g php -o nerocart-php # -g python | java | csharp | go
Değişiklik günlüğü
API'deki her değişiklik burada tarihiyle yazılır. /api/v1 içinde değişiklikler yalnız eklemedir; mevcut entegrasyonlar bozulmaz. Canlı durum: durum sayfası.
| Tarih | Değişiklik |
|---|---|
| 11 Kasım 2026 | Anahtar kontrol toplamı: yeni anahtarlar yedi karakterlik CRC32 kontrol toplamıyla biter (nck_<8>_<39>); önceki anahtarlar çalışmaya devam eder. |
| 10 Kasım 2026 | Anahtar alanları: Stok yazma artık depo konumlarını (locations.write), Ürünler yazma medya silmeyi (media.delete) kapsıyor. |
| 10 Kasım 2026 | Kargo firması bilgisi sorgusu: GET /api/v1/admin/shipping/carrier-profiles/lookup kargo firmasının unvanını, VKN'sini ve vergi dairesini bulur; faturalar kargo firması kaydını kullanır. |
| 9 Kasım 2026 | Geliştirici rehberi ve tam API referansı yayında; yönetim API'si (/api/v1/admin) artık referansta. |
| 9 Kasım 2026 | NeroCart adları: webhook başlıkları X-NeroCart-*, yeni anahtarlar nck_ ile başlar. |
| 9 Kasım 2026 | Anahtar güvenliği: 21 alanda okuma/yazma izni, son kullanma tarihi, IP kısıtı, yenileme, iptal edilen ve süresi dolan anahtarı silme. |
| 9 Kasım 2026 | Idempotency-Key bütün yönetim yazma isteklerinde; tekrar eden istek ilk yanıtı alır. |
| 9 Kasım 2026 | Sayfalama: her listede Link başlığı (RFC 8288) ve meta.has_more. |
| 9 Kasım 2026 | İstek kayıtları: panelde her anahtarın son çağrıları, sonuçları ve süreleri (30 gün). |
| 9 Kasım 2026 | Webhook deneme gönderimi: POST /api/v1/admin/x/webhooks/endpoints/{id}/test ve panelde Test gönder. |
| 9 Kasım 2026 | Geliştirici test mağazası, durum sayfası ve Postman koleksiyonu. |
| 9 Kasım 2026 | Sızan anahtar koruması: GitHub'da herkese açık bulunan nck_ anahtarları otomatik iptal edilir. |