GoPOS Veri API

Bu API, muhasebe programları ve diğer 3. parti uygulamaların GoPOS'tan veri okumasını sağlar. Tek bir uç vardır: istemek istediğiniz verilerin adlarını bir liste hâlinde gönderirsiniz, cevap isim: veri şeklinde tek pakette döner. Ayrı ayrı istek atmanıza gerek yoktur.

API yalnızca okuma yapar; hiçbir uç veri değiştirmez. Erişim, işletmenin size verdiği token ile sağlanır ve işletmenin API Entegrasyon modülü aktif olduğu sürece çalışır.

Hızlı Başlangıç

1. İşletme, API Entegrasyon modülünü açtırır Modül aylık ücretlidir ve GoPOS bayisi/yetkilisi tarafından işletmeye tanımlanır. Modül aktif değilse token üretilemez, üretilmiş token da çalışmaz.
2. İşletme token oluşturur İşletme kendi GoPOS panelinde Entegrasyonlar → API Entegrasyonları sayfasına girer, Ekle der ve firma adınızı yazar. Üretilen token'ı size iletir. Token süresizdir; sızarsa işletme aynı ekrandan yenileyebilir (eski token o anda geçersiz olur).
3. Token'ı isteğe ekleyin Her istekte X-Api-Key başlığında gönderin. Başka bir kimlik bilgisi (kullanıcı adı, şifre, JWT) gerekmez.
4. Hangi verileri çekebileceğinizi öğrenin Gövdede boş liste [] göndererek işletmeye açık olan bütün veri adlarını ve parametrelerini alırsınız.
5. Veriyi çekin İstediğiniz adları liste hâlinde gönderin. Aşağıdaki Canlı Test bölümünden tarayıcıdan deneyebilirsiniz.

Kimlik Doğrulama

Tüm isteklerde token X-Api-Key başlığında gönderilir:

Content-Type: application/json
X-Api-Key: cGFzdGUteW91ci10b2tlbi1oZXJl...

Token hakkında bilmeniz gerekenler:

• Token bir işletmenin tek şubesine bağlıdır. Şube bilgisi token'ın içinde şifreli taşınır; ayrıca şube parametresi göndermenize gerek yoktur.
• Süresizdir, ama işletmenin modül lisansı biterse istekler 402 ile reddedilir.
• İşletme token'ı yenilerse ya da silerse anında geçersiz olur.
• Token gizli bilgidir; istemci uygulamaya (mobil/tarayıcı) gömmeyin, sunucu tarafında saklayın.

Canlı Test

Token'ınızı girip gerçek istek atabilirsiniz. Bu bölüm tarayıcınızdan doğrudan API'ye bağlanır; araya bir sunucu girmez, veriler hiçbir yere kaydedilmez. Token yalnızca sizin tarayıcınızda (localStorage) saklanır, istersen tek tuşla silinir.

Toplu Veri Çekme

Gövde üç şekilde gönderilebilir. En basiti düz isim listesidir:

["category.getall", "paymenttype.getall"]

Parametre gerekiyorsa ya da cevapta farklı bir anahtar adı istiyorsanız nesne kullanın:

[
  {
    "name": "pos.get-orders-by-date",
    "parameters": { "startDate": "2026-08-01", "endDate": "2026-08-19" },
    "alias": "agustosSatislari"
  },
  "category.getall"
]

Aynı parametre birden fazla uca gidecekse defaults ile bir kez yazın:

{
  "defaults": { "startDate": "2026-08-01", "endDate": "2026-08-19" },
  "items": ["pos.get-orders-by-date", "pos.get-ticket-report-by-day-id-or-date"]
}

Cevap

Sonuçlar results altında, istediğiniz sırayla, isim: veri şeklinde döner. Bir uç hata verirse istek tamamen başarısız olmaz: o adın verisi null olur ve ayrıntı errors altına yazılır.

{
  "success": true,
  "storeGoId": "8f14e45f-ceea-467a-9575-28e6b1c2f0a1",
  "count": 2,
  "elapsedMs": 48,
  "results": {
    "category.getall": [ ... ],
    "paymenttype.getall": [ ... ]
  }
}

Katalog (İsim Listesi)

Gövdede boş liste gönderirseniz hiçbir uç çalıştırılmaz; bunun yerine o işletmede çekebileceğiniz bütün adlar, parametreleriyle birlikte listelenir. Entegrasyona başlarken ilk yapmanız gereken budur.

POST /v2/integration/data/fetch
X-Api-Key: ...

[]

{
  "success": true,
  "count": 18,
  "catalog": [
    {
      "name": "category.getall",
      "path": "/v2/category/getall",
      "parameters": []
    },
    {
      "name": "pos.get-orders-by-date",
      "path": "/v2/pos/get-orders-by-date",
      "parameters": [
        { "name": "StoreId", "type": "Int64", "optional": false },
        { "name": "startDate", "type": "DateTimeOffset", "optional": false }
      ]
    }
  ]
}

Çekilebilen Veriler

Aşağıdaki liste standart kurulumda açık olan adlardır. Kesin liste işletmeye göre değişebilir; her zaman katalog ucundan doğrulayın.

Hata Kodları

İstek geneli

Tek bir veri adına ait hatalar (errors içinde)

{
  "success": false,
  "count": 2,
  "results": {
    "category.getall": [ ... ],
    "olmayan.ad": null
  },
  "errors": {
    "olmayan.ad": { "status": 404, "message": "'olmayan.ad' adinda bir veri cekme ucu yok." }
  }
}

Limitler ve Öneriler

Verimli kullanım

• Sabit verileri sık çekmeyin. Ürün, kategori, vergi, ödeme tipi günde birkaç kez yeter.
• Hareketli veride tarih filtresi kullanın. pos.get-orders-by-date ile yalnızca son çekimden bu yanaki aralığı isteyin; tüm listeyi tekrar çekmeyin.
• Tek istekte toplayın. Beş ayrı istek yerine beş adı tek gövdede gönderin; sunucu sırayla çalıştırıp tek cevapta döner.
• Çok sık sormayın. Saniyeler mertebesinde sorgulama hem sizi hem işletmenin veritabanını yorar; dakikalık aralıklar çoğu senaryo için fazlasıyla yeterlidir.

Sık Sorulanlar

Token'ı ben mi oluşturuyorum?

Hayır. İşletme kendi panelinden oluşturup size iletir. Siz yalnızca kullanırsınız.

Token'ın süresi doluyor mu?

Token süresizdir. Ama işletmenin API Entegrasyon modülü aylık lisanslıdır; lisans biterse istekler 402 ile reddedilir, ödeme yapılınca aynı token çalışmaya devam eder.

Şube parametresi göndermem gerekiyor mu?

Hayır. Şube token'ın içindedir. StoreId / storeGoId gönderseniz de sunucu kendi değerini kullanır.

Veri yazabilir miyim?

Hayır. Bu API salt okunurdur; katalogda yalnızca veri çekme uçları bulunur.

Bir ad hata verirse diğerleri de mi gelmez?

Gelir. Her ad bağımsız çalışır; hatalı olanın verisi null olur, ayrıntı errors içinde döner.

Token sızarsa ne yapmalıyım?

İşletmeye haber verin; panelden Tokenı Yeniden Oluştur demesi yeterli. Eski token o anda geçersiz olur, size yeni token verilir.