NeroCart Geliştiriciler EN

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.

S

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

Müşteriler

Müşteri kayıtlarını ve gruplarını CRM'inizle senkron tutun.

W

Webhook'lar

Yeni sipariş, ödeme, kargo, stok gibi 50'yi aşkın olayı anında, imzalı olarak alın.

O

Uygulamalar (OAuth)

Birçok mağazaya kurulan uygulamalar için OAuth 2.0 + PKCE ile izin akışı.

V

Vitrin API'si

Ürün listesi, sepet ve ödeme adımı için anahtarsız, herkese açık API.

Başlarken

  1. 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.
  2. Anahtarı kopyalayın. Anahtar (nck_…) yalnız bir kez gösterilir; programınızın gizli ayarlarına kaydedin.
  3. İ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.

ÖzellikNasıl çalışır
En az yetkiHer 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.
SaklamaAnahtar 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üreAnahtar 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.
İzSon kullanım zamanı tutulur; oluşturma, iptal ve silme işlem kayıtlarına yazılır.
UygulamalarBirç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:

  1. 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.
  2. Sızan anahtarı iptal edin: iptal edilmemişse Ayarlar › API anahtarları'ndan iptal edip silin.
  3. Anahtarı koddan ve geçmişten çıkarın: dosyayı silmek yetmez; geçmişi yeniden yazın (örneğin git filter-repo ile) ya da depoyu açığa çıkmış sayın.
  4. 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.
  5. 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ıkAnlamı
X-NeroCart-Signaturet=<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-EventOlayın adı, ör. order.paid
X-NeroCart-Event-IdOlayın kimliği: aynı olay iki kez gelirse bir kez işleyin.
X-NeroCart-Event-VersionGövdenin şema sürümü (v).
X-NeroCart-Delivery-IdBu 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

Node.js
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)));
}
PHP
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;
}
Python
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.

DurumNe zaman
400Eksik ya da hatalı alan (validation); details.field hangi alan olduğunu söyler.
401Anahtar yok, yanlış, iptal edilmiş, süresi dolmuş ya da izin verilmeyen bir IP'den.
403Anahtarın bu alana izni yok.
404Kayıt yok ya da bu mağazanın değil.
409Durum çakışması (ör. aynı istek hâlâ işleniyor).
422Aynı Idempotency-Key farklı bir istekle kullanıldı.
429Hı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ı

KapsamSınır
API anahtarı başınadakikada 600 istek (anlık 120)
IP adresi başınadakikada 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ı.

TarihDeğişiklik
11 Kasım 2026Anahtar kontrol toplamı: yeni anahtarlar yedi karakterlik CRC32 kontrol toplamıyla biter (nck_<8>_<39>); önceki anahtarlar çalışmaya devam eder.
10 Kasım 2026Anahtar alanları: Stok yazma artık depo konumlarını (locations.write), Ürünler yazma medya silmeyi (media.delete) kapsıyor.
10 Kasım 2026Kargo 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 2026Geliştirici rehberi ve tam API referansı yayında; yönetim API'si (/api/v1/admin) artık referansta.
9 Kasım 2026NeroCart adları: webhook başlıkları X-NeroCart-*, yeni anahtarlar nck_ ile başlar.
9 Kasım 2026Anahtar 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 2026Idempotency-Key bütün yönetim yazma isteklerinde; tekrar eden istek ilk yanıtı alır.
9 Kasım 2026Sayfalama: 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 2026Webhook deneme gönderimi: POST /api/v1/admin/x/webhooks/endpoints/{id}/test ve panelde Test gönder.
9 Kasım 2026Geliştirici test mağazası, durum sayfası ve Postman koleksiyonu.
9 Kasım 2026Sızan anahtar koruması: GitHub'da herkese açık bulunan nck_ anahtarları otomatik iptal edilir.

Kaynaklar