Dokümantasyon

API — beş dakikada ilk isteğiniz.

REST, JSON, tek anahtar. Aşağıdaki her uç canlıdır ve örnekler gerçek yanıt biçimini gösterir.

Bir çağrı hangi kapılardan geçer?src/app.ts’teki gerçek sıra

Kapılar bu sırayla çalışır: kimliği çözülemeyen istek kotaya hiç dokunmaz, kotası yetmeyen istek doğrulamaya hiç girmez. Kısmi sonuç yoktur — 100 kalemlik iş 40 kalem kaldıysa tamamen reddedilir; yarım sonucu tam sonuç gibi vermek en kötüsü olurdu.

1 · Anahtar alın

Panele girin, API Anahtarları ekranından üretin. Ham anahtar yalnız bir kez gösterilir; veritabanında sadece SHA-256 özeti durur, kaybedilirse yenisi üretilir.

Anahtar üretmek yönetici yetkisi ister. Bir API anahtarıyla yeni anahtar üretilemez — sızan tek bir anahtar sonsuz sayıda kalıcı anahtara dönüşmesin diye.

2 · Kimlik doğrulama

Anahtarı iki başlıktan biriyle gönderin.

HTTPİstek başlığı

x-api-key: gtin_live_XXXXXXXXXXXX
— ya da —
Authorization: Bearer gtin_live_XXXXXXXXXXXX

Anahtarsız istek 401 döner. Panelden gelen istekler oturum çerezini kullanır; anahtar gerekmez.

3 · Tek numara

Bir numara nasıl çözümlenir?tek istekte

Yanıttaki issuer alanı bu öneki karşılar. Dikkat: önek menşe ülke değildir; numarayı kimin verdiğini gösterir.

Kontrol basamağı nasıl bulunur?GS1 mod-10

Sayfadaki bu hesap elle yazılmadı; ürünün kullandığı aynı kuralla üretildi. Geçersiz bir numarada size “geçersiz” demekle kalmayıp olması gereken rakamı söylememizin sebebi bu.

GET/v1/gtins/{gtin}

{
  "input": "4006381333931",
  "compact": "4006381333931",
  "valid": true,
  "type": "GTIN-13",
  "gtin14": "04006381333931",
  "checkDigit": "1",
  "expectedCheckDigit": "1",
  "issues": [],
  "issuer": {
    "prefix": "400-440",
    "issuer": "GS1 Germany",
    "countryCode": "DE",
    "kind": "company"
  },
  "product": null
}

Alan	Ne
`valid`	Kontrol basamağı GS1 mod-10 kuralına uyuyor mu.
`type`	`GTIN-8`, `GTIN-12`, `GTIN-13`, `GTIN-14`.
`gtin14`	14 haneli karşılığı — eşleştirme için bunu kullanın.
`expectedCheckDigit`	Geçersizse olması gereken rakam.
`issues`	Sorun kodları; geçerliyse boş dizi.
`issuer`	Numarayı veren GS1 kuruluşu, ülke ve önek. Tahsis edilmemiş önekte `null`.
`product`	Sizin kataloğunuzdan ad, marka, kategori, görsel. Kataloğunuzda yoksa `null`.

4 · Toplu doğrulama

JSON listesi ya da doğrudan CSV gövdesi. Tek işte 10.000 numaraya kadar.

POST/v1/batches

Content-Type: application/json

{ "gtins": ["4006381333931", "8690504045618"] }

— ya da CSV gövdesi (text/csv): GTIN sütunu otomatik bulunur —

Uç	Ne yapar
`POST /v1/batches`	İşi başlatır, `202` ve iş kimliği döner.
`GET /v1/batches`	Son işleri listeler.
`GET /v1/batches/{id}`	Durum ve ilerleme.
`GET /v1/batches/{id}/results`	Sonuçlar; `offset` ve `limit` ile sayfalanır.
`GET /v1/batches/{id}/result.csv`	Tamamını CSV olarak indirir.

Sonuçlar kalıcıdır — servis yeniden başlasa bile kaybolmaz. 60 dakika saklanır.

5 · Kendi kataloğunuz

Yüklediğiniz alanlar her sorguda product içinde döner. Katalog yüklemek kotadan düşmez.

CSVBeklenen sütunlar

gtin,urun_adi,marka,kategori,gorsel_url
4006381333931,STABILO BOSS Fosforlu Kalem,STABILO,Kırtasiye,https://...
8690504045618,Çikolatalı Gofret 36 g,Örnek Marka,Gıda,

Sütun	Zorunlu	Not
`gtin`	evet	Herhangi bir GTIN biçimi; 14 haneye normalleştirilir.
`urun_adi`	hayır	En fazla 300 karakter.
`marka`	hayır
`kategori`	hayır	Serbest metin.
`gorsel_url`	hayır	Yalnız `https` kabul edilir.

6 · Kullanım ve kota

GET/v1/usage

{ "requests": 128, "items": 4210 }

GET /v1/usage/daily günlük kırılımı verir. İstek ile kalem farklıdır: 100 numaralık bir toplu iş 1 istek ama 100 kalemdir; faturalama kalem üzerinden yapılır.

Yanıt kodları

Altı kod. Hepsi gövdede bir error anahtarıyla gelir; hiçbiri sessizce boş sonuç döndürmez.

Ne zaman hangi kod?geçersiz numara da 200’dür

Kafa karıştıran nokta: geçersiz bir numara hata değildir. Çağrı başarılıdır, yanıt valid: false der. 400 ancak numara hiç okunamadığında döner.

Kotanızı yanıttan okuyun

Sormanıza gerek yok; her yanıt kalan hakkınızı taşır. Kotanın bittiğini 402 ile öğrenmek zorunda değilsiniz.

Her yanıtta dönen başlıklarsürpriz kesinti olmasın diye

7 · Sınırlar ve hatalar

Kod	Ne zaman	Ne yapmalı
`400`	Gövde ya da CSV okunamadı.	Alan adlarını ve biçimi kontrol edin.
`401`	Anahtar yok, yanlış ya da iptal edilmiş.	Panelden yeni anahtar üretin.
`403`	Yetki yetersiz (ör. üye anahtar üretemez).	Yönetici yetkisi gerekir.
`413`	Toplu iş 10.000 kalemi aştı.	Listeyi bölün.
`429`	Dakikalık istek ya da kalem sınırı aşıldı.	`retry-after` başlığındaki süre kadar bekleyin.
`kota_doldu`	Aylık kalem hakkınız bitti.	Paketi yükseltin ya da dönem başını bekleyin.
`503`	Aynı anda çok fazla açık toplu iş.	Kısa süre sonra tekrar deneyin.

Yanıt başlıklarında kalan hakkınız gelir: x-ratelimit-remaining, x-item-ratelimit-remaining.

Anahtarınızı alın

Panele girin, API Anahtarları ekranından üretin. Hesabınız yoksa kurum yöneticiniz açar.

Panele giriş