Realtime Service API Kullanım Kılavuzu

POS sistemlerinden finansal ve muhasebe sistemlerine gerçek zamanlı veri aktarımı için kapsamlı entegrasyon çözümü

Realtime Service API Kullanım Kılavuzu

1. Genel Bakış

Realtime Service API, satış noktası (POS) sistemlerinden finans ve muhasebe sistemlerine veri aktarımı sağlamak amacıyla geliştirilmiş kurumsal düzeyde bir entegrasyon çözümüdür. Bu API, çeşitli rapor türlerini çekmek için tek bir endpoint kullanır ve istenilen rapor türü Type parametresi ile belirtilir.

API sayesinde işletmeler:

• Satış verilerini anlık olarak muhasebe sistemlerine aktarabilir
• Stok hareketlerini merkezi sistemden takip edebilir
• Şubeler ve depolar arasında veri entegrasyonu sağlayabilir
• Detaylı finansal raporlar oluşturabilir
• Satın alma ve satış faturalarını merkezi sistemde yönetebilir

2. Kimlik Doğrulama

Her API isteği için kimlik doğrulama zorunludur. API anahtarı (API Key) Authorization başlığında Bearer token formatında gönderilmelidir:

Authorization: Bearer your_api_key

Örnek:

Authorization: Bearer fdg5bc23-fg45-4603-4f65-f2437de3fcd0

Güvenlik Notu: API anahtarınızı güvenli bir şekilde saklayın ve asla istemci tarafı kodunda (örn. JavaScript) bulundurmayın. API çağrılarını her zaman güvenli bir sunucu üzerinden gerçekleştirin.

API Anahtarı Nasıl Alınır

1. robotPOS müşteri portalına giriş yapın
2. “Entegrasyonlar” bölümüne gidin
3. “API Anahtarı Oluştur” butonuna tıklayın
4. Oluşturulan anahtarı güvenli bir yerde saklayın

3. API Endpoint

POST https://pos-integration.robotpos.com/realtimeapi/api/salesdata

Realtime Service API, tüm rapor türleri için tek bir endpoint kullanır. İstenen rapor türü, istek gövdesindeki Type parametresi ile belirtilir.

4. İstek Formatı

API istekleri JSON formatında gönderilmelidir ve Content-Type başlığı application/json olarak ayarlanmalıdır.

{
  "Type": 101,        // Rapor Tipi Kodu (zorunlu)
  "StartDate": "2025-05-04 00:00:00",   // Başlangıç tarihi
  "EndDate": "2025-05-04 23:59:59",     // Bitiş tarihi
  "BranchCode": "0"   // Şube kodu: Tümü için "0", birden fazla şubeler için "222,111" tek şube "12"
  // Diğer parametreler rapor tipine göre değişebilir
}

5. Parametreler

API isteklerinde kullanılan ana parametreler aşağıda listelenmiştir. Rapor tipine göre zorunlu parametreler değişebilir.

Parametre	Tip	Zorunluluk	Açıklama
Type	Integer	Zorunlu	Çekilecek rapor türünün kodu (101-255 arası değerler)
StartDate	String	Zorunlu*	Rapor başlangıç tarihi (YYYY-MM-DD HH:MM:SS formatında) - *Bazı rapor tipleri için zorunludur
EndDate	String	Zorunlu*	Rapor bitiş tarihi (YYYY-MM-DD HH:MM:SS formatında) - *Bazı rapor tipleri için zorunludur
BranchCode	String	Zorunlu*	Şube kodu veya kodları. Üç farklı format kabul edilir: “0”: Tüm şubeler için veri çekilir ”222,111,555”: Virgülle ayrılmış şube kodları için veri çekilir ”3333”: Tek bir şube kodu için veri çekilir *Bazı rapor tipleri için zorunludur
All	Integer	Opsiyonel	Bazı rapor tipleri için, tüm verilerin çekilip çekilmeyeceğini belirtir. 1 = Tüm veriler, 0 = Sadece belirtilen şubeler
BranchCodeString	String	Opsiyonel	Bazı rapor tipleri için, BranchCode ile aynı formatta şube kodlarını belirtir
WarehouseCodeString	String	Opsiyonel	Stok sayım raporları için, depo kodlarını belirtir

6. Rapor Tipleri

Aşağıdaki tabloda tüm rapor tipleri ve gerektirdikleri parametreler listelenmiştir. İhtiyacınıza uygun rapor tipini seçerek API’yi daha verimli kullanabilirsiniz.

Type Kodu	Rapor Adı	Açıklama	Gerekli Parametreler
101	Şube Listesi	Tüm şubelerin detaylı listesi ve bilgileri (Branches_json)	-
102	Grup Satışları	Ürün gruplarına göre satış analizleri (GroupSales)	BranchCode, StartDate, EndDate
103	Ödemeler	Ödeme yöntemlerine göre detaylı ödeme raporları (Payments)	BranchCode, StartDate, EndDate, All
104	Tüketim Belgeleri	Tüketim belgelerinin detaylı listesi (PosFinansConsumptionDocuments_json)	BranchCodeString, StartDate, EndDate
105	Cari Listesi	Tüm cari hesapların kapsamlı listesi (PosFinansCurrents_json)	-
106	Stok Sayım Belgeleri	Stok sayım belgeleri ve sonuçları (PosFinansInventoryCountDocuments_json)	WarehouseCodeString, StartDate, EndDate
107	Üretim Formülleri	Üretim formüllerinin detaylı listesi (PosFinansManafactureFormulas_json)	-
108	Manuel Tüketim Belgeleri	Manuel olarak girilen tüketim belgeleri (PosFinansManuelConsumptionDocuments_json)	BranchCodeString, StartDate, EndDate
109	Ürün Listesi	Tüm ürünlerin detaylı listesi (PosFinansProductList_json)	-
110	Satın Alma Faturaları	Tedarikçilerden alınan fatura belgeleri (PosFinansPurchaseInvoiceDocuments_json)	StartDate, EndDate
111	Satın Alma İade Faturaları	Tedarikçilere yapılan iade faturaları (PosFinansPurchaseInvoiceReturnDocuments_json)	StartDate, EndDate
112	Satış Faturaları	Müşterilere kesilen satış faturaları (PosFinansSaleInvoiceDocuments_json)	StartDate, EndDate
113	Yarı Mamül Belgeleri	Yarı mamül üretim ve tüketim belgeleri (PosFinansSemiFinishedDocuments_json)	StartDate, EndDate
114	Stok Giriş Fişleri	Stok giriş hareketlerini gösteren belgeler (PosFinansStockRecordEntryDocuments_json)	StartDate, EndDate
115	Stok Çıkış Fişleri	Stok çıkış hareketlerini gösteren belgeler (PosFinansStockRecordIssueDocuments_json)	StartDate, EndDate
116	Depo Listesi	Tüm depoların detaylı listesi ve bilgileri (PosFinansWarehouses_json)	-
117	Depo Transfer Belgeleri	Depolar arası stok transferlerini gösteren belgeler (PosFinansWarehouseTransferDocuments_json)	BranchCodeString, StartDate, EndDate
118	Ürün Satış Detayları	Ürün bazında detaylı satış analizleri (ProductSales_json)	BranchCode, StartDate, EndDate, All
119	İptal Edilen Satışlar	İptal edilmiş satışların detaylı listesi (Voids_json)	BranchCode, StartDate, EndDate
255	Ürün Detaylı Satışlar	Ürün bazında kapsamlı satış analizleri	BranchCode, StartDate, EndDate

7. Özel Parametre Davranışları

API, bazı özel parametre değerlerini otomatik olarak işler:

BranchCode Parametresi

• BranchCode=“0”: Tüm şubeleri kapsar, sorgu içindeki şube filtreleme koşulu kaldırılır.
• BranchCode=“222,111,555”: Virgülle ayrılmış şube kodları için, SQL’de IN ifadesi otomatik olarak oluşturulur.
• BranchCode=“3333”: Tek bir şube kodu normal parametre olarak kullanılır.

BranchCodeString Parametresi

BranchCode ile aynı mantıkta çalışır ancak belirli rapor türleri için kullanılır. Tüketim belgeleri, manuel tüketim belgeleri ve depo transfer belgeleri için gereklidir.

WarehouseCodeString Parametresi

Stok sayım belgeleri için gereklidir ve depo kodlarını belirtmek için kullanılır. BranchCode ile aynı formatta kullanılır: “0” (tüm depolar), “111,222,333” (belirli depolar) veya “444” (tek depo)

8. Örnek İstekler

Aşağıdaki örnekler, API’nin farklı senaryolarda nasıl kullanılacağını göstermektedir. Kendi ihtiyaçlarınıza göre bu örnekleri uyarlayabilirsiniz.

Örnek 1: Şube Listesi Çekme

{
  "Type": 101
}

Örnek 2: Belirli Şubeler İçin Grup Satışları

{
  "Type": 102,
  "BranchCode": "222,111,555",
  "StartDate": "2025-05-04 00:00:00",
  "EndDate": "2025-05-04 23:59:59"
}

Örnek 3: Tüm Şubeler İçin Ürün Satış Detayları

{
  "Type": 118,
  "BranchCode": "0",
  "StartDate": "2025-05-04 00:00:00",
  "EndDate": "2025-05-04 23:59:59",
  "All": 1
}

Örnek 4: Belirli Bir Şube İçin Ürün Detaylı Satışlar

{
  "Type": 255,
  "BranchCode": "3333",
  "StartDate": "2025-05-04 00:00:00",
  "EndDate": "2025-05-04 23:59:59"
}

Örnek 5: Belirli Depolar İçin Stok Sayım Belgeleri

{
  "Type": 106,
  "WarehouseCodeString": "100,200,300",
  "StartDate": "2025-05-01 00:00:00",
  "EndDate": "2025-05-04 23:59:59"
}

Örnek 6: Belirli Şubeler İçin Depo Transfer Belgeleri

{
  "Type": 117,
  "BranchCodeString": "222,111",
  "StartDate": "2025-05-01 00:00:00",
  "EndDate": "2025-05-04 23:59:59"
}

Örnek 7: cURL İle İstek Örneği

curl --location 'https://pos-integration.robotpos.com/realtimeapi/api/salesdata' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 2c5f4710-83c3-427f-87fc-c247ab5babf4' \
--data '{
    "BranchCode": "0",
    "StartDate": "2025-05-04 00:00:00",
    "EndDate": "2025-05-04 23:59:59",
    "Type": 101
}'

9. Hata Kodları

API isteklerinizde aşağıdaki hata kodlarıyla karşılaşabilirsiniz. Hata mesajları, sorunun kaynağını belirlemenize yardımcı olacaktır.

HTTP Kodu	Hata Mesajı	Açıklama
400	Type parametresi gereklidir	İstek gövdesinde Type parametresi bulunmamaktadır
400	Geçersiz Type değeri	Desteklenmeyen bir Type değeri gönderilmiştir
400	StartDate parametresi gereklidir	Type kodu için gerekli olan StartDate parametresi eksik
400	EndDate parametresi gereklidir	Type kodu için gerekli olan EndDate parametresi eksik
400	BranchCode parametresi gereklidir	Type kodu için gerekli olan BranchCode parametresi eksik
401	Geçersiz API anahtarı	Kimlik doğrulama başarısız oldu
403	Yetkisiz erişim	API anahtarı bu rapor türüne erişim izni vermiyor
404	Type [kod] için rapor sorgu dosyası bulunamadı	Belirtilen Type kodu için SQL sorgu dosyası bulunamadı
429	İstek limiti aşıldı	Çok fazla istek gönderildi, lütfen daha sonra tekrar deneyin
500	İç sunucu hatası	Sunucu tarafında bir hata oluştu
503	Servis kullanılamıyor	API bakım modunda veya geçici olarak kullanılamıyor

10. Yanıt Formatı

API, JSON formatında yanıt döndürür. Başarılı yanıtların genel yapısı aşağıdaki gibidir:

{
  "data": [...], // Rapor verileri
  "totalRows": 123, // Toplam satır sayısı
  "affectedRows": 0, // Etkilenen satır sayısı (sorgu değişiklik yapmadığında 0)
  "timestamp": "2025-05-04T14:30:45.123Z", // Yanıt zamanı
  "execution_time": 0.235 // Sorgunun yürütülme süresi (saniye)
}

Veri Formatları

• Bazı rapor türleri için data alanı bir JSON dizisi olarak döndürülür.

Örnek Yanıt:

{
  "data": [
    {
      "BranchID": 222,
      "BranchName": "Merkez Şube",
      "Address": "Ankara Cad. No:1",
      "Phone": "0212 555 1234",
      "IsActive": 1
    },
    {
      "BranchID": 111,
      "BranchName": "Kadıköy Şube",
      "Address": "Bağdat Cad. No:42",
      "Phone": "0216 333 5678",
      "IsActive": 1
    }
  ],
  "totalRows": 2,
  "affectedRows": 0,
  "timestamp": "2025-05-04T14:30:45.123Z",
  "execution_time": 0.021
}

11. Önemli Notlar

• Tarih Formatı: Tarih parametreleri her zaman “YYYY-MM-DD HH:MM:SS” formatında gönderilmelidir.
• API Çağrı Logları: Tüm API çağrıları güvenlik ve izleme amaçlı olarak günlüğe (log) kaydedilir.
• Rate Limiting: Her tanımlayıcı (IP adresi/API anahtarı) için 1 dakikalık süre içinde maksimum 30 istek yapılabilir. Bu limit aşıldığında 429 hata kodu döndürülür.
• Timeout Değeri: API istekleri 60 saniye içinde yanıt vermediğinde otomatik olarak timeout olur.

• Veri Güvenliği: Tüm API trafiği SSL üzerinden şifrelenmiş olarak iletilir.
• Teknik Destek: API kullanımıyla ilgili sorularınız için [e-mail] adresine e-posta gönderebilir veya teknik destek portalımızı ziyaret edebilirsiniz.

---

2025 RobotPOS. Tüm hakları saklıdır.

API Versiyon: 2.5.0