Entegrasyonlar Ücretsiz! E-Fatura ve Yazarkasa Entegrasyonları Self-Servis Model ile Ücretsiz! Aktif edin, kurun, kullanmaya başlayın!

BenimPOS API dokümanı

Geliştiriciler için BenimPOS API: anahtarlar, kimlik doğrulama, ürün, satış, müşteri, firma, kategori ve ödeme tipi uç noktaları, hata kodları, limitler.

15 dk okumaGüncelleme: Ekim 2026

BenimPOS API'si, hesabınızdaki verilere kendi yazılımınızdan erişmenizi sağlar: e-ticaret sitenize ürün, stok ve fiyat aktarabilir, sitedeki siparişleri BenimPOS'a satış olarak yazabilir, muhasebe ya da raporlama sisteminize satış, müşteri, tedarikçi ve alış faturası verilerini çekebilirsiniz. Bu sayfa geliştiriciler için hazırlanmıştır ve API'nin güncel davranışını anlatır.

API modülü yıllık 1.800,00 TL ücretlidir ve Entegrasyonlar › API Entegrasyonu sekmesinden satın alınır. Deneme süresi ve ayrı bir test ortamı yoktur. API ile yazarkasaya fiş gönderilemez; yazarkasa entegrasyonları yalnız BenimPOS uygulamaları içinde çalışır.

Hızlı bakış

KonuDeğer
YöntemPOST — tüm parametreler JSON gövdede gönderilir
GövdeContent-Type: application/json, UTF-8, en fazla 2 MB
Kimlik doğrulamaHTTP başlıkları: branch_id, api_key, secret_key
İşlem seçimiGövdedeki processType alanı (ör. "list", "create")
Uç noktalarproducts.php, sales.php, customers.php, firms.php, categories.php, paymentTypes.php
YanıtJSON; her yanıtta status (true/false) ve message
Tarih / saat biçimiYYYY-MM-DD ve HH:MM:SS (24 saat)

API anahtarlarını alma

  1. Modülü satın alın

    Web panelinde sol menünün en altındaki Entegrasyonlar sayfasında API Entegrasyonu sekmesini açın ve karttaki Satın Al ile satın almayı tamamlayın.

  2. Bilgilerinizi açın

    Satın almadan sonra sayfanın üstündeki tabloda API Entegrasyonu satırı görünür. Satırdaki kalem simgesine basın; API Entegrasyon Bilgileriniz penceresi açılır.

  3. Değerleri kopyalayın

    Pencerede üç değer vardır: Branch ID (hesabınızın / şubenizin kodu), Api Key ve Secret Key. Kopyala simgesiyle alıp uygulamanızın ayarlarına girin.

Anahtarlar hesabınıza tam erişim sağlar: kod deposuna, tarayıcıda çalışan koda (JavaScript) ya da mesajlara yazmayın; yalnız sunucu tarafında saklayın. Anahtarın ele geçtiğini düşünüyorsanız penceredeki yenile simgesiyle yeni anahtar üretin; eski anahtar hemen geçersiz olur, uygulamanızdaki değeri güncellemeyi unutmayın.

  • Her şube ayrı bir hesaptır ve kendi Branch ID'si ile anahtarlarına sahiptir. Verisine erişeceğiniz her şube hesabında API modülü ayrıca etkinleştirilir.
  • Modülün süresi dolduğunda istekler kimlik hatası alır. Süreyi Entegrasyonlar sayfasından yenileyin; seçenek görünmüyorsa WhatsApp destek hattımıza yazın.
  • Önceki sürüm PDF dokümanına Entegrasyonlar › API Entegrasyonu kartındaki bağlantıdan da ulaşabilirsiniz; alan adları ve davranış için bu sayfa günceldir.

Adresler ve istek yapısı

Her veri türü ayrı bir uç noktadır ve aynı uç noktada farklı işlemler processType ile seçilir. Servis adresinin kökü https://www.benimpos.com/api şeklindedir; örneğin ürünler için https://www.benimpos.com/api/products.php.

Uç noktaprocessTypeNe yapar
products.phplistÜrünleri stok, fiyat, kategori, varyant ve (isteğe bağlı) şube stoklarıyla listeler
products.phpaddYeni ürün ekler (en fazla 1000 / istek), isteğe bağlı açılış stoğuyla
products.phpupdateÜrün bilgilerini ve fiyatları günceller (barkoda göre)
products.phpupdateQuantityStok miktarını verilen değere eşitler
products.phpdeleteÜrünleri siler (barkoda göre)
products.phppurchaseInvoicesAlış faturalarını satırlarıyla listeler
products.phppurchaseMovementsAlış faturası satırlarını (ürün bazında giriş hareketleri) listeler
sales.phplistİki tarih-saat arasındaki satışları ürün ve ödeme ayrıntısıyla listeler
sales.phpcreateYeni satış kaydeder
sales.phpcancelSatışı iptal eder
sales.phppavoInvoicePavo N86 cihazından kesilen satışın e-arşiv / e-fatura belge bilgisini verir
customers.phplistMüşterileri borç / ödeme özetiyle listeler, arar
customers.phpgetCustomerTransactionsBir müşterinin satış ve ödeme hareketlerini (ekstre) verir
customers.phpcreateMüşteri oluşturur; müşteri varsa gönderilen alanları günceller
customers.phpaddPaymentMüşteriye ödeme (tahsilat) ekler
firms.phplistFirmaları (tedarikçileri) borç / ödeme özetiyle listeler
firms.phpgetFirmTransactionsBir firmanın hesap ekstresini yürüyen bakiyeyle verir
categories.phplistÜrün gruplarını (kategorileri) listeler
paymentTypes.phplistAktif özel ödeme tiplerini listeler

Kimlik doğrulama başlıkları

BaşlıkDeğer
branch_idAPI Entegrasyon Bilgileriniz penceresindeki Branch ID
api_keyApi Key
secret_keySecret Key

Başlık adları alt çizgili (branch_id) ya da tireli (branch-id, api-key, secret-key) gönderilebilir. Bazı proxy ve HTTP kütüphaneleri alt çizgili başlıkları sessizce düşürür; “alanlar boş olamaz” hatası alıyorsanız tireli biçimi kullanın. Değerlerin başında / sonunda boşluk ya da kopyalarken araya giren görünmez karakter olmamasına dikkat edin.

Örnek istek

curl -X POST "https://www.benimpos.com/api/products.php" \
  -H "Content-Type: application/json" \
  -H "branch_id: BRANCH_ID" \
  -H "api_key: API_KEY" \
  -H "secret_key: SECRET_KEY" \
  -d '{"processType":"list","page":1,"limit":500,"orderByColumn":"name","orderByType":"ASC"}'

Ortak yanıt yapısı

Listeleme yanıtlarında page, totalPage, kayıt sayısı (totalProductsCount gibi, çoğunlukla metin olarak) ve data dizisi döner:

{
  "status": true,
  "message": "İstek başarılı",
  "page": 1,
  "totalPage": 3,
  "totalProductsCount": "2450",
  "data": [ ... ]
}

Hata yanıtları uygun HTTP durum koduyla döner:

{
  "status": false,
  "message": "Mağaza kodu ile Api ve Secret Key'ler uyuşmuyor."
}
  • Yanıtlardaki Türkçe karakterler JSON kaçışlı (\u0130stek ba\u015far\u0131l\u0131 gibi) gelebilir; standart JSON çözücüler bunu otomatik çevirir.
  • Tutarlar sayı olarak döner; bazı alanlar (ör. ürünlerde quantity, taxRate, toplam kayıt sayıları) metin olarak gelir. Kodunuzda sayıya çevirin.
  • Gövde geçerli JSON değilse 400 Geçersiz JSON., processType yoksa 404 İşlem türü boş olamaz., tanınmayan işlemde 400 Geçersiz işlem tipi. döner.

Sayfalama ve sıralama

  • page 1'den başlar. limit sayfa başına kayıt sayısıdır; her işlemin üst sınırı aşağıdaki tablolarda yazar (fazlası sınıra indirilir).
  • Yanıttaki totalPage'e kadar sayfaları sırayla isteyin. Var olmayan bir sayfa boş data döner.
  • orderByType yalnız tam olarak "ASC" (büyük harf) gönderildiğinde artan sıralar; başka her değer ("asc" dahil) azalan sıralar.

Ürünler — products.php

list — ürünleri listeleme

ParametreTürAçıklama
pagesayıSayfa (varsayılan 1)
limitsayıSayfa başına kayıt; en fazla 1000 (includeBranches açıkken en fazla 200)
orderByColumnmetinbarcode (varsayılan), name, salePrice1, salePrice2, buyingPrice
orderByTypemetinASC ya da DESC
onlineProductstrue/falseYalnız online satışa açık ürünler
variantProductstrue/falseYalnız varyantlı ürünler
inStockProductstrue/falseYalnız stoğu 0'dan büyük ürünler (tüm stok hesaplandığı için daha pahalıdır)
includeBranchestrue/falseHer ürün için quantityInBranches dizisinde şube stoklarını da döndürür
{
  "status": true,
  "message": "İstek başarılı",
  "page": 1,
  "totalPage": 1,
  "totalProductsCount": "1",
  "data": [
    {
      "barcode": "8690000000017",
      "name": "Örnek Ürün 1 L",
      "salePrice1": 49.9,
      "salePrice2": 45,
      "buyingPrice": 30.5,
      "salePrice1Currency": "TRY",
      "salePrice2Currency": "TRY",
      "buyingPriceCurrency": "TRY",
      "quantity": "12.000",
      "taxRate": "20",
      "stockCode": "STK-001",
      "categoryID": "15",
      "categoryName": "İçecekler",
      "image": "",
      "criticalQuantity": "5",
      "origin": "",
      "unitValue": "Adet",
      "updatedDate": "2026-10-01",
      "lastQuantityChangeDate": "2026-10-11",
      "lastQuantityChangeTime": "14:32:10",
      "note": "",
      "isOnline": true,
      "variantCode": "",
      "variants": [],
      "quantityInBranches": [
        { "branchID": "...", "branchName": "Merkez", "quantity": 12 }
      ]
    }
  ]
}
AlanAçıklama
salePrice1 / salePrice2Fiyat 1 ve Fiyat 2; para birimleri salePrice1Currency / salePrice2Currency
buyingPriceAlış fiyatı (buyingPriceCurrency)
quantityGüncel stok (metin, 3 ondalık). Stok = alışlar − alış iadeleri − satışlar
taxRateKDV oranı (%)
categoryID / categoryNameÜrün grubu; grupsuz ürünlerde 0 ve boş
criticalQuantityKritik stok seviyesi
unitValueBirim (Adet, Kg…)
updatedDateFiyatın son değiştiği tarih
lastQuantityChangeDate / TimeSon stok hareketinin (alış ya da satış) tarihi ve saati
isOnlineÜrün kartında online satışa açık mı
variantCode / variantsVaryant kodu ve varyant bilgileri (subVariantCode, variantName, variantValue)

add — ürün ekleme

data bir dizidir; tek istekte en fazla 1000 ürün. Zorunlu alanlar: barcode, name, salePrice1 (0 ya da daha büyük sayı). Barkodu hesapta zaten olan ürünler atlanır (güncellenmez; güncellemek için update kullanın). Zorunlu alanı eksik satırlar da atlanır.

ParametreTürAçıklama
salePrice2, buyingPricesayıVarsayılan 0
salePrice1Currency, salePrice2Currency, buyingPriceCurrencymetinVarsayılan TRY
quantitysayıAçılış stoğu; 0'dan büyükse “Servis ile stok arttırma işlemi” açıklamalı bir stok girişi oluşur
taxRatetam sayıKDV; varsayılan 20
stockCode, origin, notemetinStok kodu, menşei, ürün açıklaması
imagemetinÜrün görselinin adresi (URL)
criticalQuantitysayıKritik stok
isOnlinetrue/falseOnline satışa açık
{
  "processType": "add",
  "data": [
    {
      "barcode": "8690000000017",
      "name": "Örnek Ürün 1 L",
      "salePrice1": 49.9,
      "salePrice2": 45,
      "buyingPrice": 30.5,
      "taxRate": 20,
      "quantity": 12,
      "stockCode": "STK-001",
      "isOnline": true
    }
  ]
}

Yanıt: {"status":true,"totalProductsCount":1,"addedProductsCount":1}. API ile eklenen ürünler grupsuz ve birimi Adet olarak oluşur; grup ve birimi panelden atayın.

update — ürün güncelleme

data dizisindeki her satırda barcode zorunludur; yalnız gönderdiğiniz alanlar değişir. Güncellenebilen alanlar: name, salePrice1, salePrice2, buyingPrice, salePrice1Currency, salePrice2Currency, buyingPriceCurrency, criticalQuantity, taxRate, origin, stockCode, note, isOnline. Barkod, ürün grubu ve stok bu işlemle değişmez. En fazla 1000 ürün / istek.

{
  "processType": "update",
  "data": [
    { "barcode": "8690000000017", "salePrice1": 52.5, "isOnline": false }
  ]
}

Yanıt: totalProductsCount ve updatedProductsCount. Değişiklikler masaüstü uygulamalarına eşitlemeyle iner.

updateQuantity — stok eşitleme

quantity hedef stok miktarıdır, fark değildir: ürünün stoğu gönderdiğiniz değere eşitlenir. Mevcut stoktan fazlaysa aradaki fark için stok girişi, azsa stok çıkışı (“Servis ile stok arttırma / eksiltme işlemi”) kaydı oluşur. Negatif değer ya da hesapta olmayan barkod atlanır. En fazla 1000 ürün / istek.

{
  "processType": "updateQuantity",
  "data": [
    { "barcode": "8690000000017", "quantity": 8 },
    { "barcode": "8690000000024", "quantity": 0 }
  ]
}

Yanıt: totalProductsCount ve updatedQuantityProductsCount.

Stoğu sitenizden BenimPOS'a ve BenimPOS'tan sitenize iki yönlü eşitliyorsanız bu işlemi dikkatli kullanın: arada mağazada yapılan satış, eski bir değerle yazılan stokla ezilebilir. Satışları mümkünse sales.php › create ile satış olarak yazın; stok kendiliğinden düşer.

delete — ürün silme

{"processType":"delete","data":[{"barcode":"8690000000017"}]} — en fazla 1000 ürün / istek. Ürün kartı ve varyant bilgileri silinir, masaüstü uygulamalarına silme bilgisi gönderilir. Yanıt: deletedProductsCount. Geçmiş satış ve alış kayıtları silinmez.

purchaseInvoices — alış faturaları

ParametreTürAçıklama
pagesayıSayfa; sayfa başına 100 fatura (sabit)
startDate, endDateYYYY-MM-DDFatura tarihi aralığı (isteğe bağlı)
supplierIDmetinYalnız bu firmanın faturaları (firms.php › firmID)
invoiceNometinFatura numarası
includeItemstrue/falseFatura satırlarını da döndür (varsayılan true)
includeReturnstrue/falseİade faturalarını da döndür (varsayılan false)
orderByTypemetinFatura tarihine göre; varsayılan DESC, artan için ASC
{
  "processType": "purchaseInvoices",
  "page": 1,
  "startDate": "2026-10-01",
  "endDate": "2026-10-31",
  "includeItems": true
}
{
  "status": true, "message": "İstek başarılı", "page": 1, "totalPage": 1, "totalInvoicesCount": "1",
  "data": [
    {
      "invoiceNo": "A-2026-114", "invoiceDate": "2026-10-03",
      "supplierID": "27", "supplierName": "Örnek Toptan", "supplierTaxNumber": "", "supplierTaxOffice": "",
      "waybillNo": "", "documentNo": "", "shipmentDate": "", "paymentType": "Açık Hesap", "note": "",
      "discountValue": 0, "discountType": "0", "isReturn": false, "isSystemRecord": false,
      "createdDate": "2026-10-03", "createdTime": "10:12:40",
      "totalAmountWithoutTax": 1000, "totalAmountWithTax": 1200,
      "items": [
        { "barcode": "8690000000017", "productName": "Örnek Ürün 1 L", "quantity": 24, "unitPrice": 41.6667,
          "discount1": 0, "discount2": 0, "discount3": 0, "discount4": 0, "discount5": 0,
          "taxRate": 20, "netUnitCost": 41.6667, "amountWithoutTax": 1000, "amountWithTax": 1200 }
      ]
    }
  ]
}

isSystemRecord true ise kayıt bir firmaya bağlı olmayan sistem kaydıdır (ör. API ya da stok işlemleriyle oluşan stok girişleri). netUnitCost iskontolar düşülmüş KDV hariç birim maliyettir.

purchaseMovements — ürün bazında alış hareketleri

ParametreTürAçıklama
pagesayıSayfa; sayfa başına 1000 satır (sabit)
barcodemetinYalnız bu ürünün hareketleri
startDate, endDateYYYY-MM-DDFatura tarihi aralığı
supplierIDmetinFirma filtresi
includeReturnstrue/falseİade satırlarını da döndür (varsayılan false)
orderByTypemetinVarsayılan ASC, azalan için DESC

Her satırda barcode, productName, invoiceNo, invoiceDate, supplierID, supplierName, quantity, unitPrice, discount1–discount5, taxRate, netUnitCost, amountWithoutTax, amountWithTax, isReturn, isSystemRecord, createdDate, createdTime döner; sayı alanı totalMovementsCount.

Satışlar — sales.php

list — satışları listeleme

ParametreTürAçıklama
startDate, startTimezorunluBaşlangıç: YYYY-MM-DD ve HH:MM:SS
endDate, endTimezorunluBitiş: YYYY-MM-DD ve HH:MM:SS (gün sonu için 23:59:59)
pagesayıSayfa
limitsayıEn fazla 1000
{
  "processType": "list",
  "startDate": "2026-10-12", "startTime": "00:00:00",
  "endDate": "2026-10-12",   "endTime": "23:59:59",
  "page": 1, "limit": 500
}
{
  "status": true, "message": "İstek başarılı", "page": 1, "totalPage": 1, "totalSalesCount": "1",
  "data": [
    {
      "saleCode": "...", "customerCode": "", "paymentTypeID": "Pos", "paymentTypeName": "Pos",
      "date": "2026-10-12", "time": "14:05:00", "staffID": "...", "staffName": "Yönetici",
      "salesNote": "", "quantity": 2, "amount": 99.8, "discountAmount": 0, "serviceFee": 0,
      "profit": 38.8, "application": "Site",
      "products": [
        { "barcode": "8690000000017", "name": "Örnek Ürün 1 L", "quantity": 2, "price": 49.9,
          "amount": 99.8, "taxRate": "20", "notes": "", "discounts": [] }
      ],
      "paymentDetails": []
    }
  ]
}
AlanAçıklama
saleCodeSatış kodu (iptal ve ekstre işlemlerinde kullanılır)
customerCodeAçık hesap / müşterili satışta müşteri kodu; boşsa müşterisiz
paymentTypeID / paymentTypeNameNakit, Pos, Açık Hesap, Parçalı ya da özel ödeme tipinin kimliği ve adı
staffID / staffNameSatışı yapan personel; ana hesap için “Yönetici”
quantity, amountToplam miktar ve iskontolar düşülmüş satış tutarı
discountAmountSatış altı iskonto oranı (%) — alan adına rağmen yüzde değeridir
serviceFeeHizmet bedeli / POS komisyonu
profitAlış fiyatı tanımlı ürünlerden hesaplanan kâr
applicationSatışın yapıldığı uygulama
products[]barcode, name, quantity, price, amount, taxRate, notes, discounts[] (unit: percent / currency, value)
paymentDetails[]Parçalı ödemede her ödemenin paymentTypeID, paymentTypeName, paymentAmount
  • Satışlar yeniden eskiye sıralı döner.
  • Muhtelif tutar satırları “Muhtelif Ürün”, barkodsuz açık hesap borç girişleri “Veresiye borç girişi” adıyla gelir.
  • İptal edilmiş satışlar listede tutarı 0 ve ürün listesi boş olarak görünebilir; amount = 0 ve boş products olan kayıtları buna göre değerlendirin.
  • Masaüstü uygulamasında yapılan satışlar, masaüstü verileri web'e eşitlendikten sonra API'de görünür (aşağıdaki artımlı eşitleme ipuçlarına bakın).

create — satış kaydetme

ParametreTürAçıklama
data.products[]zorunluEn az 1, en fazla 500 satır. Her satırda barcode (zorunlu), price (> 0), quantity (> 0), taxRate (0–39), buyingPrice (≥ 0, kâr hesabı için)
data.paymentTypemetinCASH / Nakit (varsayılan), CREDITCARD / Pos, OPENACCOUNT / Açık Hesap ya da paymentTypes.php'den bir paymentTypeID
data.date, data.timemetinSatış tarihi ve saati; gönderilmezse şimdiki zaman
data.customerCodemetinMüşteri kodu; gönderilirse hesapta kayıtlı olmalı. Açık hesap satışlarda gönderin
data.discountRatesayıSatış altı iskonto oranı, 0–100
data.notemetinSatış notu
data.externalRefmetinSizin sipariş numaranız (en fazla 100 karakter). Aynı değerle gelen ikinci istek yeni satış oluşturmaz, ilk satışın kodunu döner
{
  "processType": "create",
  "data": {
    "externalRef": "WEB-100245",
    "paymentType": "CREDITCARD",
    "date": "2026-10-12",
    "time": "14:05:00",
    "customerCode": "",
    "discountRate": 0,
    "note": "Web sipariş 100245",
    "products": [
      { "barcode": "8690000000017", "price": 49.9, "quantity": 2, "taxRate": 20, "buyingPrice": 30.5 }
    ]
  }
}
{ "status": true, "message": "İstek başarılı", "salesCode": "..." }
  • Satış tek parça kaydedilir: bir hata olursa hiçbir kayıt oluşmaz, yarım satış kalmaz.
  • Stok, satırdaki barkodla düşer; barkodların BenimPOS'taki ürünlerle birebir aynı olmasına dikkat edin.
  • Ağ hatasından sonra tekrar denerken aynı externalRef'i gönderin; satış ikinci kez oluşmaz ve yanıtta X-BP-Idempotent: replay başlığı gelir.
  • Başarısız istekte 400 Satış kaydedilemedi. döner; yanıt başlıklarındaki X-BP-Ref değerini destek talebinize ekleyin.
  • API ile oluşturulan satışlar yazarkasaya gönderilmez ve e-faturaya otomatik dönüşmez.

cancel — satış iptali

{ "processType": "cancel", "data": { "salesCode": "..." } }

Satışın başlığı, satırları ve satışa bağlı ödemeler birlikte iptal edilir; yanıt Satış başarıyla iptal edildi. Bulunamayan kodda 400 Gönderilen satış koduna ait bir satış bulunamadı, beklenmeyen bir hatada 500 Satış iptal edilemedi, hiçbir değişiklik yapılmadı. döner. Not: bu işlemde alan adı salesCode, listede saleCode'dur.

pavoInvoice — Pavo belge bilgisi

Pavo N86 cihazıyla tamamlanan bir satışın e-arşiv / e-fatura belgesini verir. salesCode bu işlemde gövdenin en üst düzeyinde gönderilir: {"processType":"pavoInvoice","salesCode":"..."}.

{
  "status": true, "message": "İstek başarılı", "salesCode": "...", "hasInvoice": true,
  "ettn": "...", "invoiceNo": "...", "documentType": "...", "downloadUrl": "https://...",
  "documents": [ { "ettn": "...", "invoiceNo": "...", "documentType": "...", "downloadUrl": "https://..." } ]
}

Belge yoksa hasInvoice: false ve Bu satış koduna ait Pavo fatura bilgisi bulunamadı. mesajı döner.

Müşteriler — customers.php

Müşteriler müşteri koduyla (customerCode) tanımlanır; bu, BenimPOS'taki müşteri adıdır ve satış, ödeme ve ekstre işlemlerinde anahtar olarak kullanılır.

list — müşterileri listeleme

ParametreTürAçıklama
page, limitsayıSayfalama; en fazla 1000
keywordmetinMüşteri kodu, ad, soyad, unvan ya da telefonda arar (en fazla 100 karakter)
onlyDebtCustomerstrue/falseYalnız kalan borcu olan müşteriler (daha pahalıdır)
orderByColumnmetincustomerName (varsayılan), shoppingCount, debt, paymentAmount, remainingDebt
orderByTypemetinASC ya da DESC
{
  "status": true, "message": "İstek başarılı", "page": 1, "totalPage": 1, "totalCustomersCount": "1",
  "data": [
    { "customerID": "5531", "customerCode": "ÖRNEK MÜŞTERİ", "name": "", "surname": "", "title": "",
      "customerType": "Bireysel", "shoppingCount": "14", "debt": 2500, "payment": 1800, "remainingDebt": 700,
      "phone": "5xxxxxxxxx", "address": "", "note": "" }
  ]
}

debt açık hesap satışlarının toplamı, payment yapılan ödemeler, remainingDebt kalan borçtur.

getCustomerTransactions — müşteri ekstresi

Gövde: {"processType":"getCustomerTransactions","data":{"customerCode":"ÖRNEK MÜŞTERİ"},"page":1}. limit en fazla 1000. Müşterinin satışları (Sales) ve ödemeleri (Payment) eskiden yeniye tek listede döner.

{
  "status": true, "message": "İstek başarılı", "page": 1, "totalPage": 1, "totalTransactionsCount": 2,
  "data": [
    { "transactionType": "Sales", "salesCode": "...", "quantity": 3, "amount": 2500, "discount": 0,
      "staffID": "...", "staffName": "Yönetici", "date": "2026-10-02", "time": "11:05:12",
      "note": "", "paymentTypeID": "", "paymentTypeName": "Açık Hesap" },
    { "transactionType": "Payment", "salesCode": "Ödeme", "quantity": 0, "amount": 1800, "discount": 0,
      "staffID": "...", "staffName": "Yönetici", "date": "2026-10-09", "time": "17:20:00",
      "note": "", "paymentTypeID": "...", "paymentTypeName": "Nakit" }
  ]
}

create — müşteri oluşturma / güncelleme

ParametreTürAçıklama
customerCodezorunluMüşteri kodu (adı). Büyük harfe çevrilerek kaydedilir; tırnak gibi bazı özel karakterler değiştirilir
customerTypemetinBireysel ya da Kurumsal
name, surname, titlemetinAd, soyad, unvan
phonemetinEn fazla 11 karakter
email, address, country, city, district, postalCodemetinİletişim ve adres
taxOffice, taxNometinVergi dairesi ve VKN / TCKN
debtLimitsayıVeresiye limiti
discountRatesayıMüşteri iskonto oranı (yalnız yeni müşteride)
priceTypesayı1 = Fiyat 1, 2 = Fiyat 2
notemetinMüşteri notu
{
  "processType": "create",
  "data": {
    "customerCode": "ÖRNEK MÜŞTERİ",
    "customerType": "Kurumsal",
    "title": "Örnek Ticaret Ltd. Şti.",
    "taxOffice": "Örnek VD",
    "taxNo": "1234567890",
    "phone": "5xxxxxxxxx",
    "city": "İstanbul",
    "district": "Kadıköy",
    "debtLimit": 5000,
    "priceType": 1
  }
}

Kod hesapta yoksa müşteri oluşturulur (Yeni müşteri başarıyla oluşturuldu); varsa yalnız gönderilen alanlar güncellenir (Müşteri kaydı başarıyla güncellendi). Güncellemede hiç alan gönderilmezse 400 Güncellenecek bir parametre bulunamadı. döner. Sonraki isteklerde müşteri kodunu listede döndüğü (büyük harfli) biçimiyle kullanın.

addPayment — müşteriye ödeme ekleme

{
  "processType": "addPayment",
  "data": {
    "customerCode": "ÖRNEK MÜŞTERİ",
    "amount": 750,
    "paymentTypeID": "CASH",
    "date": "2026-10-12",
    "time": "15:40:00",
    "note": "Online tahsilat"
  }
}

customerCode ve 0'dan büyük amount zorunludur. paymentTypeID: CASH / Nakit (varsayılan), CREDITCARD / Pos ya da özel ödeme tipi kimliği. Ödeme müşterinin kalan borcundan düşer. Hata mesajları: Müşteri kodu boş olamaz., Gönderilen müşteri kodu ile örtüşen bir müşteri bulunamadı, Tutar 0 veya 0'dan küçük olamaz., Ödeme tipi bulunamadı.

Firmalar (tedarikçiler) — firms.php

list — firmaları listeleme

Parametreler: page, limit (en fazla 1000). Aktif firmalar ada göre sıralı döner.

{
  "status": true, "message": "İstek başarılı", "page": 1, "totalPage": 1, "totalFirmsCount": "1",
  "data": [
    { "firmID": "27", "firmName": "Örnek Toptan", "personName": "", "phone": "", "gsm": "",
      "address": "", "taxOffice": "", "taxNo": "", "debt": 12000, "payment": 9000, "remainingDebt": 3000 }
  ]
}

getFirmTransactions — firma ekstresi

ParametreTürAçıklama
data.firmIDzorunluFirma kimliği (list › firmID)
data.startDate, data.endDateYYYY-MM-DDVarsayılan: tüm geçmiş ile bugün
page, limitsayıVarsayılan 500, en fazla 1000
{
  "status": true, "message": "İstek başarılı", "page": 1, "totalPage": 1, "totalTransactionsCount": 2,
  "summary": {
    "firmID": "27", "firmName": "Örnek Toptan", "startDate": "2026-10-01", "endDate": "2026-10-31",
    "currency": "TRY", "openingBalance": 1800, "closingBalance": 3000, "totalDebit": 1200, "totalCredit": 0
  },
  "data": [
    { "transactionType": "openAccountInvoice", "source": "invoice", "date": "2026-10-03", "time": "10:12:40",
      "description": "", "paymentTypeName": "Açık Hesap", "invoiceNo": "A-2026-114", "waybillNo": "",
      "documentNo": "", "dispatchDate": "", "dueDate": "2026-11-02", "productCount": 24,
      "amount": 1200, "balanceEffect": 1200, "balanceAfter": 3000, "documentImage": "", "transactionRef": "" }
  ]
}
transactionTypeAnlamıBakiyeye etkisi
openAccountInvoiceAçık hesap alış faturasıBorç artar
openAccountReturnInvoiceAçık hesap iade faturasıBorç azalır
paidInvoice / returnInvoicePeşin ödenmiş alış / iade faturasıEtkilemez (bilgi amaçlı)
debtElle eklenen borçBorç artar
paymentFirmaya yapılan ödemeBorç azalır

openingBalance başlangıç tarihinden önceki kalan borç, closingBalance bitiş tarihindeki kalan borçtur; balanceAfter her satırdan sonraki yürüyen bakiyedir.

Ürün grupları — categories.php

ParametreTürAçıklama
page, limitsayıEn fazla 1000
orderByColumnmetinname (varsayılan) ya da categoryID
orderByTypemetinASC ya da DESC
onlyActivetrue/falseYalnız aktif gruplar
onlyOnlinetrue/falseYalnız online mağazaya açık gruplar
onlyRoottrue/falseYalnız üst gruplar
parentCategoryIDsayıBu üst grubun alt grupları
{
  "status": true, "message": "İstek başarılı", "page": 1, "totalPage": 1, "totalCategoryCount": "1",
  "data": [
    { "categoryID": "15", "name": "İçecekler", "parentCategoryID": "0", "parentCategoryName": "",
      "showOnSalesPage": true, "isOnline": false, "isActive": true, "productCount": 42 }
  ]
}

Ödeme tipleri — paymentTypes.php

Hesaptaki aktif özel ödeme tiplerini (yemek kartı, havale vb.) ada göre listeler; parametre olarak yalnız page alır. Nakit, Pos ve Açık Hesap bu listede yoktur; satış ve ödeme isteklerinde bunlar için CASH, CREDITCARD, OPENACCOUNT kullanın. mainPaymentType tipin kasada hangi gruba yazıldığını gösterir: Nakit, Pos ya da Harici Kasa.

{
  "status": true, "message": "İstek başarılı", "page": 1, "totalPage": 1, "totalPaymentTypesCount": "2",
  "data": [
    { "paymentTypeID": "112", "paymentTypeName": "Yemek Kartı", "mainPaymentType": "Pos" },
    { "paymentTypeID": "113", "paymentTypeName": "Havale", "mainPaymentType": "Harici Kasa" }
  ]
}

Hata kodları

HTTPmessageNe yapmalı?
500Branch ID, Api Key ve Secret Key alanları boş olamaz.Üç başlığı da gönderin. X-BP-Missing yanıt başlığı hangisinin ulaşmadığını yazar; alt çizgili başlıklar düşüyorsa tireli biçimi deneyin.
401Mağaza kodu ile Api ve Secret Key'ler uyuşmuyor.Değerleri yeniden kopyalayın. X-BP-Auth başlığı ipucu verir: api_key-eslesmiyor, secret_key-eslesmiyor, bu-firma_id-bu-veritabaninda-yok. Hatalı denenen anahtar 60 sn hatalı sayılır; düzelttikten sonra 60 sn bekleyin. Anahtarı yenilediyseniz yenisini kullanın; modül süresini kontrol edin.
403API erişiminiz askıya alınmıştır. Lütfen destek ile iletişime geçin.WhatsApp destek hattımıza yazın.
429Çok fazla istek. Lütfen yavaşlayın.Saniyelik sınırı aştınız; 1 sn bekleyip tekrar deneyin, paralel istekleri azaltın.
429Dakikalık kullanım limitiniz doldu.Retry-After kadar (dakikanın sonuna) bekleyin.
429Günlük kullanım kotanız doldu.Kota gece yarısı (Türkiye saati) sıfırlanır; X-RateLimit-Reset-At başlığına bakın.
429Bu IP adresinden gelen istekler geçici olarak durduruldu. / Bu IP adresi için dakikalık limit aşıldı.Çok sayıda hatalı anahtar denemesi (5 dakikada 30) ya da IP limiti aşımı. Retry-After süresi (15–30 dk) bitene kadar bekleyin, anahtarlarınızı düzeltin.
429Aşırı kullanım nedeniyle erişiminiz geçici olarak durduruldu. / Erişiminiz geçici olarak durdurulmuştur.Uygulamanızda sonsuz döngü ya da sürekli tekrarlanan hatalı istek olup olmadığını kontrol edin ve WhatsApp destek hattımıza yazın.
413İstek gövdesi çok büyük.Gövde 2 MB'ı aşmamalı; veriyi parçalara bölün.
400Geçersiz JSON. / Geçersiz işlem tipi.Gövdenin geçerli JSON olduğunu ve processType değerini kontrol edin.
404İşlem türü boş olamaz.processType gönderin.
400Doğrulama mesajları (ör. “Başlangıç tarihi geçersiz. Format: YYYY-MM-DD”, “Ödeme tipi bulunamadı”, “Tek istekte en fazla 1000 ürün gönderebilirsiniz.”)Mesajda yazan alanı düzeltin.
503Servis geçici olarak yanıt veremiyor. Lütfen birazdan tekrar deneyin.Retry-After (30 sn) sonra tekrar deneyin.

Kullanım limitleri

Her istek, uç noktanın ağırlığına göre puan harcar. Hesabınızın planına göre saniyelik istek sayısı, dakikalık puan ve günlük puan sınırı vardır:

Planİstek / saniyePuan / dakikaPuan / gün
Standart (varsayılan)103.000800.000
Pro208.000800.000
Partner4020.0003.000.000
İşlemPuan
paymentTypes list1
categories list3
firms list10
firms getFirmTransactions30
products list15
products list + inStockProducts60
products list + includeBranches90
products purchaseInvoices / purchaseMovements45
products add / update / updateQuantity / delete15
sales list30
sales create / cancel / pavoInvoice15
customers list25
customers list + onlyDebtCustomers75
customers getCustomerTransactions50
customers create / addPayment25

Örnek: Standart planda dakikada 3.000 puanla yaklaşık 200 ürün listesi ya da 100 satış listesi isteği yapılabilir. Ayrıca tek bir IP adresinden gelen tüm istekler için dakikalık bir üst sınır uygulanır. Limitler değişebilir; her yanıttaki başlıkları esas alın:

Yanıt başlığıAnlamı
X-RateLimit-LimitDakikalık puan sınırınız
X-RateLimit-RemainingBu dakika kalan puan
X-RateLimit-ResetDakikalık sayacın sıfırlanmasına kalan saniye
X-RateLimit-CostBu isteğin puanı
Retry-After429 yanıtlarında tekrar denemeden önce beklenecek saniye
X-CacheHIT: yanıt önbellekten geldi, MISS: yeni hesaplandı
ETagYanıtın parmak izi (aşağıya bakın)

Daha yüksek limite ihtiyacınız varsa kullanım senaryonuzla birlikte WhatsApp destek hattımıza yazın.

Önbellek ve ETag

  • Okuma işlemlerinin yanıtları kısa süre önbellekte tutulur: satış listesi 30 sn; ürün, müşteri listesi ve ekstreleri 60 sn; firma listesi, alış faturaları ve alış hareketleri 120 sn; ürün grupları, ödeme tipleri ve Pavo belgeleri 300 sn.
  • Aynı gövdeyle bu süre içinde gelen istek önbellekten döner (X-Cache: HIT); veri değişmemiş olsa da puan harcar. Bu nedenle aynı sorguyu önbellek süresinden sık tekrarlamanın faydası yoktur.
  • Aynı uç noktada bir yazma işlemi (ekleme, güncelleme, satış, iptal, ödeme) yaptığınızda o hesabın ilgili önbelleği temizlenir; sonraki liste güncel veriyi getirir.
  • Yanıttaki ETag değerini saklayıp sonraki istekte If-None-Match başlığıyla gönderirseniz, veri değişmediyse gövdesiz 304 Not Modified döner; bant genişliğinden tasarruf edersiniz.

Artımlı eşitleme ipuçları

API'de “şu tarihten sonra değişenler” filtresi ve webhook (anlık bildirim) yoktur; değişiklikleri periyodik sorguyla alırsınız. Önerilen düzen:

  1. Satışları zaman penceresiyle çekin

    Son başarılı çekimin zamanını saklayın ve sales.php › list'i o zamandan şimdiye kadar isteyin. Kayıtları saleCode ile tekilleştirin (upsert).

  2. Pencereyi geriye örtüştürün

    Masaüstü uygulamasında yapılan satışlar satış saatiyle kaydedilir ama web'e eşitlendikten sonra API'de görünür. Bu yüzden her çekimde pencerenin başını geriye kaydırın (ör. son 1–2 saat) ve gün sonunda o günü bir kez daha baştan çekin; geç gelen satışları kaçırmazsınız.

  3. İptalleri yakalayın

    Örtüşen pencerede daha önce aldığınız bir satış amount = 0 ve boş ürün listesiyle gelirse iptal edilmiştir; kendi tarafınızda da iptal edin.

  4. Ürünleri sayfa sayfa karşılaştırın

    Ürün listesinde değişiklik filtresi yoktur. Sayfaları belirli aralıklarla çekip her sayfanın ETag'ini saklayın; 304 dönen sayfayı atlayın. Değişen sayfalarda updatedDate (fiyat) ve lastQuantityChangeDate/Time (stok) alanlarını kendi kayıtlarınızla karşılaştırın.

  5. Yalnız gerekeni isteyin

    Sitenize yalnız online ürünleri aktarıyorsanız onlineProducts: true kullanın; şube stoklarına (includeBranches) ve stok filtresine (inStockProducts) yalnız gerçekten gerektiğinde başvurun, puanları yüksektir.

  6. Siparişleri güvenle yazın

    Sitenizdeki her siparişi sales.php › create ile kendi sipariş numaranızı externalRef olarak göndererek yazın; ağ hatasından sonra tekrar denemek mükerrer satış oluşturmaz.

  7. Limitlere saygı gösterin

    İstekleri sıralı ve aralıklı gönderin, saniyede 10'dan fazla eşzamanlı istek açmayın. 429 aldığınızda Retry-After kadar bekleyin; hatalı anahtarla döngü halinde tekrar denemeyin (IP'niz geçici olarak engellenir).

Sık sorulan sorular

API ile alış faturası oluşturabilir miyim?

Hayır. Alış faturalarını purchaseInvoices ve purchaseMovements ile okuyabilirsiniz; oluşturma servisi yoktur. Stok eklemek için add (açılış stoğu) ya da updateQuantity kullanılır.

Ürüne API ile grup (kategori) atayabilir miyim?

Hayır, ürün ekleme ve güncellemede grup alanı yoktur. Grupları categories.php ile okuyabilir, ürünlere grubu web panelinden ya da Excel ile atayabilirsiniz.

Masaüstünde yaptığım satış API'de ne zaman görünür?

Masaüstü uygulaması verileri web'e gönderdikten (eşitleme) sonra. Masaüstünde ana sayfadaki Veri entegrasyonu kartından eşitlemeyi hemen başlatabilirsiniz. Web ve mobil uygulamadaki satışlar anında görünür.

Teknik destek nasıl alırım?

Sorunuzu istek gövdesi (anahtarlar hariç), HTTP durum kodu, yanıt mesajı, isteğin saati ve varsa X-BP-Ref / X-BP-Auth başlıklarıyla birlikte WhatsApp destek hattımıza yazılı iletin. API anahtarlarınızı mesajla paylaşmayın. Destek yazılıdır; telefonla görüşme yapılmaz.

İlgili makaleler

Takıldığınız bir yer mi var? WhatsApp'tan yazın, destek ekibimiz yardımcı olsun.
Destek al