Geliştirici belgeleri

BARKODOS API v1.1

Barkod (GTIN) ve iç kod üzerinden ürün, stok ve konum verisini okuyun; ERP, CRM, muhasebe, e-ticaret ve depo yazılımınızdan belge referanslı stok hareketi yazın; ERP'den ürün açın; maliyetli stok değerini ve hareket dökümünü alın; olayları webhook ya da olay kuyruğuyla izleyin. Uç noktalar JSON döner (muhasebe uçları isteğe bağlı CSV).

v1.1 geriye uyumludur: v1 için yazılmış istemciler değişmeden çalışır. Hazır ERP, CRM ya da muhasebe bağlantısı (konnektör) yoktur; bağlantı bu API ile karşı sistemde kurulur. API gerçek bir ERP ya da muhasebe yazılımıyla birlikte denenmedi; ilk kurulumda deneme ortamında doğrulayın.

Taban adres

https://<alan-adınız>/api/v1 (yerel kurulumda http://localhost:3310/api/v1)

Biçim

JSON, UTF-8. Tarihler ISO 8601 (UTC).

Barkod

GTIN-8, 12, 13 ya da 14 kabul edilir; eşleştirme GTIN-14'e tamamlanarak yapılır. İç kodlar (ör. BK-0001) da kullanılabilir.

Kimlik doğrulama

API anahtarını panelde Entegrasyonlar → API ve webhook sayfasında yönetici oluşturur. Anahtar yalnız bir kez gösterilir; sunucunuzda gizli değişken olarak saklayın. Tarayıcı kodunda kullanmayın: API sunucudan sunucuya kullanım içindir.

Authorization: Bearer bk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

okuma her anahtara eklenir. Anahtara bir kullanım amacı (ERP, CRM, muhasebe, e-ticaret, depo, diğer) verilir; yalnız etikettir, denetim izinde görünür. GET /hesap anahtarın adını, amacını ve kapsamlarını döner (bağlantı testi için).

Hatalar ve sınırlar

HTTP/1.1 400 Bad Request
{ "hata": { "kod": "dogrulama", "mesaj": "Geçersiz alanlar.", "alanlar": { "miktar": "Pozitif tam sayı." } } }

Her yanıtta X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları vardır.

Ürünler

GET /urunler

Sorgu: gtin, q (ad, marka, kod içinde arama), kategori, harici (dış sistem kodu, erp:STK-001), degisim_sonra (ISO zaman; artımlı eşitleme), durum (aktif varsayılan, pasif, tumu), limit (1–100, varsayılan 50), sayfa.

curl -H "Authorization: Bearer $BARKODOS_ANAHTAR" \
  "https://<alan-adınız>/api/v1/urunler?gtin=8691234560013"

{
  "veri": [{
    "id": "U-001", "ad": "Zeytinyağlı sabun", "netMiktar": "100 g", "marka": "Örnek Doğal",
    "kategori": "Sabun", "birim": "adet", "gtin": "8691234560013", "gtin14": "08691234560013",
    "icKod": null, "aktif": true, "satisFiyati": 49.9,
    "stok": { "toplam": 442, "konumlar": [{ "konum": "K1", "ad": "Ana depo · Raf A", "miktar": 340 }] },
    "minMiktar": 120, "harici": { "erp": "STK-001", "muhasebe": "153.01.001" },
    "guncelleme": "2026-09-01", "degisim": "2026-10-31T08:12:44.000Z"
  }],
  "sayfa": 1, "limit": 50, "toplam": 1
}

GET /urunler/{gtin | iç kod | U-001}

Tek ürün. Ürün yoksa 404 urun_yok.

Stok

GET /stok?konum=K1

Etkin ürünlerin barkod, ad ve miktarı; konum verilmezse toplam miktar. Konum kimlikleri GET /konumlar ile alınır.

Barkod doğrulama ve görsel

GET /barkod/{kod}/dogrula

Kontrol basamağı, uzunluk, GS1 öneki (numarayı veren kuruluş), firmanızın önekine düşüp düşmediği ve kayıtlı ürün.

{ "veri": { "girdi": "8691234560019", "gecerli": false, "tur": "GTIN-13", "hata": "Kontrol basamağı hatalı: son hane 3 olmalı.",
  "beklenenKontrol": 3, "onek": null, "firmaOneki": null, "kayitli": false, "urun": null } }

GET /barkod/{kod}.svg

Baskıya hazır SVG. Sorgu: tur = ean13 (varsayılan), itf14 (koli; gosterge 1–8), code128 (iç kod), qr (GS1 Digital Link); olcek 1–10. Görseli sunucunuzda alıp önbelleğe koyun; anahtarı görsel adresine yazmayın.

Stok hareketi yazma

POST /stok/hareketler

Kapsam stok-yazma. tur: giris, cikis, sayim (konumdaki miktarı verilen değere çeker) ya da transfer (kaynak → hedef). Aynı isteği tekrar göndermeye karşı Idempotency-Key başlığı kullanın (24 saat geçerli); tekrarda ilk yanıt "tekrar": true ile döner, stok ikinci kez değişmez.

ERP ve muhasebe için referans nesnesi: belgeTuru (fatura, irsaliye, siparis, uretim, iade, sayim, diger), belgeNo, cari ve haricId. haricId kalıcı tekrar korumasıdır: aynı anahtarla aynı haricId ikinci kez gelirse yeni hareket açılmaz, ilk hareket 200 ve "tekrar": true ile döner.

curl -X POST "https://<alan-adınız>/api/v1/stok/hareketler" \
  -H "Authorization: Bearer $BARKODOS_ANAHTAR" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: siparis-1001" \
  -d '{ "kod": "8691234560013", "tur": "cikis", "miktar": 2, "konum": "K4", "aciklama": "Web siparişi #1001" }'

# ERP: satın alma faturasıyla mal kabul
curl -X POST "https://<alan-adınız>/api/v1/stok/hareketler" \
  -H "Authorization: Bearer $BARKODOS_ANAHTAR" -H "Content-Type: application/json" \
  -d '{ "kod": "8691234560013", "tur": "giris", "miktar": 120, "konum": "K1",
        "referans": { "belgeTuru": "fatura", "belgeNo": "A-2026-0042", "cari": "Tedarikçi A.Ş.", "haricId": "erp-grn-42" } }'

HTTP/1.1 201 Created
{ "veri": { "hareket": { "id": "H-00445", "tur": "cikis", "miktar": 2, "kaynak": "K4", ... },
            "urun": { "gtin": "8691234560013", "stok": { "toplam": 440, ... } } } }

Hareket geçmişi

GET /hareketler

Kapsam okuma. Eskiden yeniye sıralı. Artımlı çekim için sonra imleci (hareket kimliği) kullanın: yanıttaki sonraki doluysa devamı vardır. Sorgu: sonra, baslangic ve bitis (Türkiye günü, YYYY-AA-GG), tur, urun (kod), konum, limit (en çok 500).

{ "veri": [{ "id": "H-00445", "tarih": "2026-10-31T08:12:44.000Z", "tur": "giris", "miktar": 120, "etki": 120,
    "kaynak": null, "hedef": "K1", "kullanici": "BARKODOS API · ERP",
    "urun": { "id": "U-001", "gtin": "8691234560013", "icKod": null, "ad": "Zeytinyağlı sabun", "birim": "adet", "harici": { "erp": "STK-001" } },
    "referans": { "belgeTuru": "fatura", "belgeNo": "A-2026-0042", "cari": "Tedarikçi A.Ş.", "haricId": "erp-grn-42" } }],
  "toplam": 1, "sonraki": null }

miktar giriş, çıkış ve aktarımda pozitiftir; sayımda farktır (eksi olabilir). etki toplam stoğa işaretli etkidir (aktarımda 0). GET /hareketler/{id} tek hareketi döner.

Ürün yazma (ERP ana verisi)

POST /urunler

Kapsam urun-yazma. Alanlar: ad, kategori, birim (zorunlu), marka, netMiktar, minMiktar, satisFiyati, webAdresi, gorselAdresi, harici ve barkod: ic (varsayılan; iç kod verilir), yeni (firma önekinizden sıradaki GTIN), mevcut (gtin alanındaki numara), rezerve. birimMaliyet yalnız muhasebe kapsamıyla yazılır. GS1 kuralları paneldekiyle aynıdır: pasife alınmış ya da başka üründeki GTIN verilemez.

harici dış sistem kodlarıdır: { "erp": "STK-001", "muhasebe": "153.01.001", "crm": "PRD-77" }. Sistem adı küçük harf, 2–20 karakter; kod sistem içinde tekildir. Aynı dış kodla tekrar gelen POST yeni ürün açmaz, var olanı "tekrar": true ile döner.

curl -X POST "https://<alan-adınız>/api/v1/urunler" \
  -H "Authorization: Bearer $BARKODOS_ANAHTAR" -H "Content-Type: application/json" \
  -d '{ "ad": "Lavanta sabunu", "netMiktar": "150 g", "kategori": "Sabun", "birim": "adet",
        "barkod": "yeni", "minMiktar": 20, "harici": { "erp": "STK-900" } }'

PATCH /urunler/{kod}

Yalnız gönderilen alanlar değişir. gtin, icKod ve id değişmez (400 gtin_degismez); içerik ya da net miktar değiştiyse yeni ürün açın. Dış kodlar birleştirilir; { "harici": { "muhasebe": null } } o kodu siler.

Muhasebe

Kapsam muhasebe. Maliyet bilgisi yalnız bu uçlarda döner. format=csv ile dosya iner: ; ayraçlı, ondalık virgüllü, UTF-8 BOM'lu (Excel ve muhasebe yazılımlarının içe aktarımı için); ürünlerde geçen dış sistem kodları ayrı sütun olur.

GET /muhasebe/stok-degeri

Her etkin ürün için miktar × ürün kartındaki birim maliyet ve toplam. Sorgu: konum, format. Değerleme yöntemi kart maliyetidir ("yontem": "kart-maliyeti"); FIFO ya da ağırlıklı ortalama hesaplanmaz, bunlar muhasebe yazılımınızda yapılır.

GET /muhasebe/hareketler

Maliyetli hareket dökümü: tutar = etki × birimMaliyet. birimMaliyet hareket anındaki kart maliyetidir ("maliyetKaynagi": "hareket"); bu özellikten önceki kayıtlarda güncel kart maliyeti kullanılır ("kart"). baslangic ya da sonra zorunlu; en çok 5000 satır, devamı sonraki imleciyle.

curl -H "Authorization: Bearer $BARKODOS_ANAHTAR" \
  "https://<alan-adınız>/api/v1/muhasebe/hareketler?baslangic=2026-10-01&bitis=2026-10-31&format=csv" -o hareketler.csv

Olay kuyruğu

GET /olaylar

Webhook alamayan sistemler (güvenlik duvarı arkasındaki ERP, masaüstü muhasebe yazılımı) için çekme yöntemi. Son 1000 olay saklanır; kimlikler artan sıralıdır (evt_000000123). Sorgu: sonra, olay (virgülle), limit (en çok 500). Yanıtta devami doluysa hemen yeniden çekin; eksik: true ise imleciniz saklama süresinin dışına düşmüştür, ürün ve hareketleri yeniden eşitleyin. Webhook gövdesi kuyruktakiyle aynı olay kimliğini taşır.

ERP, CRM ve muhasebe ile çalışmak

Eşitleme sırası: önce ürünler (degisim_sonra), sonra hareketler (sonra imleci). İmleçleri kendi tarafınızda saklayın; bir istek yarıda kalırsa aynı imleçle yeniden çekin.

OpenAPI tanımı

GET /api/v1/openapi.json anahtarsız açılır (OpenAPI 3.0). Postman, Insomnia ya da istemci üreticilerine (openapi-generator) verilebilir. Tanımdaki her uç, otomatik testte gerçek sunucuya karşı denenir.

Webhook'lar

Panelde bir https adresi ve olay seçin: stok.degisti, hareket.olusturuldu, stok.asgari_alti, urun.olusturuldu, urun.guncellendi, sayim.tamamlandi (açıklamalar olay kuyruğunda). Her olay adresinize JSON olarak POST edilir. 2xx dönmezseniz 2 sn ve 10 sn sonra iki kez yeniden denenir; zaman aşımı 8 sn.

POST /barkodos-webhook
Content-Type: application/json
X-Barkodos-Olay: stok.degisti
X-Barkodos-Zaman: 1793430000
X-Barkodos-Imza: sha256=5f1c…

{ "id": "evt_000000123", "olay": "stok.degisti", "zaman": "2026-10-31T09:40:00.000Z",
  "veri": { "urun": { "id": "U-001", "gtin": "8691234560013", "ad": "Zeytinyağlı sabun" },
            "hareket": { "id": "H-00446", "tur": "cikis", "miktar": 2, "kaynak": "K4", "hedef": null },
            "stok": { "toplam": 438, "konumlar": { "K1": 340, "K3": 60, "K4": 38 } } } }

İmza: HMAC-SHA256(sır, X-Barkodos-Zaman + "." + ham gövde), onaltılık. Sabit zamanlı karşılaştırın ve 5 dakikadan eski zaman damgalarını reddedin.

// Node.js (Express): ham gövdeyle doğrulama
import crypto from 'node:crypto';
app.post('/barkodos-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const zaman = req.get('X-Barkodos-Zaman');
  const beklenen = 'sha256=' + crypto.createHmac('sha256', process.env.BARKODOS_WEBHOOK_SIRRI)
    .update(`${zaman}.${req.body}`).digest('hex');
  const gelen = req.get('X-Barkodos-Imza') ?? '';
  const gecerli = gelen.length === beklenen.length && crypto.timingSafeEqual(Buffer.from(gelen), Buffer.from(beklenen));
  if (!gecerli || Math.abs(Date.now() / 1000 - Number(zaman)) > 300) return res.sendStatus(401);
  const olay = JSON.parse(req.body);
  // olay.veri.urun.gtin, olay.veri.stok.toplam …
  res.sendStatus(204);
});

<?php // PHP
$govde = file_get_contents('php://input');
$zaman = $_SERVER['HTTP_X_BARKODOS_ZAMAN'] ?? '';
$beklenen = 'sha256=' . hash_hmac('sha256', $zaman . '.' . $govde, getenv('BARKODOS_WEBHOOK_SIRRI'));
if (!hash_equals($beklenen, $_SERVER['HTTP_X_BARKODOS_IMZA'] ?? '') || abs(time() - (int)$zaman) > 300) { http_response_code(401); exit; }
$olay = json_decode($govde, true);
http_response_code(204);

Ürün akışları

API bağlantısı kurmadan katalog paylaşmak için. Adresleri yönetici panelde görür; adresler gizli belirteç içerir ve yenilenebilir. Yalnız etkin ve GTIN'li ürünler Google ve Meta akışına girer.

Örnek: WooCommerce sipariş tamamlanınca stok düşmek

<?php // functions.php — WooCommerce
add_action('woocommerce_order_status_completed', function ($siparis_id) {
  $siparis = wc_get_order($siparis_id);
  foreach ($siparis->get_items() as $kalem) {
    $urun = $kalem->get_product();
    $gtin = $urun ? $urun->get_global_unique_id() : '';   // WooCommerce 9.2+ GTIN alanı
    if (!$gtin) continue;
    wp_remote_post('https://<alan-adınız>/api/v1/stok/hareketler', [
      'headers' => [
        'Authorization' => 'Bearer ' . BARKODOS_ANAHTAR,
        'Content-Type' => 'application/json',
        'Idempotency-Key' => "woo-$siparis_id-" . $kalem->get_id(),
      ],
      'body' => wp_json_encode(['kod' => $gtin, 'tur' => 'cikis', 'miktar' => $kalem->get_quantity(), 'konum' => 'K3', 'aciklama' => "Web siparişi #$siparis_id"]),
      'timeout' => 10,
    ]);
  }
});

Pazaryerleri ve mağaza altyapıları

Trendyol, Hepsiburada, Amazon, Shopify, WooCommerce ve diğer platformlara bağlantı panelde Entegrasyonlar → Pazaryeri ve mağazalar sayfasından kurulur. Ürünler platformdaki ilanlarla barkodla eşleştirilir, stok ve fiyat barkodla gönderilir. Her platform önce simülasyonda çalışır; gönderilecek istek birebir gösterilir. Platform adları sahiplerinin markalarıdır; BARKODOS bu platformların resmî iş ortağı değildir.