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.
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ış
| Konu | Değer |
|---|---|
| Yöntem | POST — tüm parametreler JSON gövdede gönderilir |
| Gövde | Content-Type: application/json, UTF-8, en fazla 2 MB |
| Kimlik doğrulama | HTTP başlıkları: branch_id, api_key, secret_key |
| İşlem seçimi | Gövdedeki processType alanı (ör. "list", "create") |
| Uç noktalar | products.php, sales.php, customers.php, firms.php, categories.php, paymentTypes.php |
| Yanıt | JSON; her yanıtta status (true/false) ve message |
| Tarih / saat biçimi | YYYY-MM-DD ve HH:MM:SS (24 saat) |
API anahtarlarını alma
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.
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.
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ç nokta | processType | Ne yapar |
|---|---|---|
products.php | list | Ürünleri stok, fiyat, kategori, varyant ve (isteğe bağlı) şube stoklarıyla listeler |
products.php | add | Yeni ürün ekler (en fazla 1000 / istek), isteğe bağlı açılış stoğuyla |
products.php | update | Ürün bilgilerini ve fiyatları günceller (barkoda göre) |
products.php | updateQuantity | Stok miktarını verilen değere eşitler |
products.php | delete | Ürünleri siler (barkoda göre) |
products.php | purchaseInvoices | Alış faturalarını satırlarıyla listeler |
products.php | purchaseMovements | Alış faturası satırlarını (ürün bazında giriş hareketleri) listeler |
sales.php | list | İki tarih-saat arasındaki satışları ürün ve ödeme ayrıntısıyla listeler |
sales.php | create | Yeni satış kaydeder |
sales.php | cancel | Satışı iptal eder |
sales.php | pavoInvoice | Pavo N86 cihazından kesilen satışın e-arşiv / e-fatura belge bilgisini verir |
customers.php | list | Müşterileri borç / ödeme özetiyle listeler, arar |
customers.php | getCustomerTransactions | Bir müşterinin satış ve ödeme hareketlerini (ekstre) verir |
customers.php | create | Müşteri oluşturur; müşteri varsa gönderilen alanları günceller |
customers.php | addPayment | Müşteriye ödeme (tahsilat) ekler |
firms.php | list | Firmaları (tedarikçileri) borç / ödeme özetiyle listeler |
firms.php | getFirmTransactions | Bir firmanın hesap ekstresini yürüyen bakiyeyle verir |
categories.php | list | Ürün gruplarını (kategorileri) listeler |
paymentTypes.php | list | Aktif özel ödeme tiplerini listeler |
Kimlik doğrulama başlıkları
| Başlık | Değer |
|---|---|
branch_id | API Entegrasyon Bilgileriniz penceresindeki Branch ID |
api_key | Api Key |
secret_key | Secret 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\u0131gibi) 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.,processTypeyoksa404 İşlem türü boş olamaz., tanınmayan işlemde400 Geçersiz işlem tipi.döner.
Sayfalama ve sıralama
page1'den başlar.limitsayfa 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şdatadöner. orderByTypeyalnı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
| Parametre | Tür | Açıklama |
|---|---|---|
page | sayı | Sayfa (varsayılan 1) |
limit | sayı | Sayfa başına kayıt; en fazla 1000 (includeBranches açıkken en fazla 200) |
orderByColumn | metin | barcode (varsayılan), name, salePrice1, salePrice2, buyingPrice |
orderByType | metin | ASC ya da DESC |
onlineProducts | true/false | Yalnız online satışa açık ürünler |
variantProducts | true/false | Yalnız varyantlı ürünler |
inStockProducts | true/false | Yalnız stoğu 0'dan büyük ürünler (tüm stok hesaplandığı için daha pahalıdır) |
includeBranches | true/false | Her ü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 }
]
}
]
}| Alan | Açıklama |
|---|---|
salePrice1 / salePrice2 | Fiyat 1 ve Fiyat 2; para birimleri salePrice1Currency / salePrice2Currency |
buyingPrice | Alış fiyatı (buyingPriceCurrency) |
quantity | Güncel stok (metin, 3 ondalık). Stok = alışlar − alış iadeleri − satışlar |
taxRate | KDV oranı (%) |
categoryID / categoryName | Ürün grubu; grupsuz ürünlerde 0 ve boş |
criticalQuantity | Kritik stok seviyesi |
unitValue | Birim (Adet, Kg…) |
updatedDate | Fiyatın son değiştiği tarih |
lastQuantityChangeDate / Time | Son stok hareketinin (alış ya da satış) tarihi ve saati |
isOnline | Ürün kartında online satışa açık mı |
variantCode / variants | Varyant 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.
| Parametre | Tür | Açıklama |
|---|---|---|
salePrice2, buyingPrice | sayı | Varsayılan 0 |
salePrice1Currency, salePrice2Currency, buyingPriceCurrency | metin | Varsayılan TRY |
quantity | sayı | Açılış stoğu; 0'dan büyükse “Servis ile stok arttırma işlemi” açıklamalı bir stok girişi oluşur |
taxRate | tam sayı | KDV; varsayılan 20 |
stockCode, origin, note | metin | Stok kodu, menşei, ürün açıklaması |
image | metin | Ürün görselinin adresi (URL) |
criticalQuantity | sayı | Kritik stok |
isOnline | true/false | Online 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ı
| Parametre | Tür | Açıklama |
|---|---|---|
page | sayı | Sayfa; sayfa başına 100 fatura (sabit) |
startDate, endDate | YYYY-MM-DD | Fatura tarihi aralığı (isteğe bağlı) |
supplierID | metin | Yalnız bu firmanın faturaları (firms.php › firmID) |
invoiceNo | metin | Fatura numarası |
includeItems | true/false | Fatura satırlarını da döndür (varsayılan true) |
includeReturns | true/false | İade faturalarını da döndür (varsayılan false) |
orderByType | metin | Fatura 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
| Parametre | Tür | Açıklama |
|---|---|---|
page | sayı | Sayfa; sayfa başına 1000 satır (sabit) |
barcode | metin | Yalnız bu ürünün hareketleri |
startDate, endDate | YYYY-MM-DD | Fatura tarihi aralığı |
supplierID | metin | Firma filtresi |
includeReturns | true/false | İade satırlarını da döndür (varsayılan false) |
orderByType | metin | Varsayı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
| Parametre | Tür | Açıklama |
|---|---|---|
startDate, startTime | zorunlu | Başlangıç: YYYY-MM-DD ve HH:MM:SS |
endDate, endTime | zorunlu | Bitiş: YYYY-MM-DD ve HH:MM:SS (gün sonu için 23:59:59) |
page | sayı | Sayfa |
limit | sayı | 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": []
}
]
}| Alan | Açıklama |
|---|---|
saleCode | Satış kodu (iptal ve ekstre işlemlerinde kullanılır) |
customerCode | Açık hesap / müşterili satışta müşteri kodu; boşsa müşterisiz |
paymentTypeID / paymentTypeName | Nakit, Pos, Açık Hesap, Parçalı ya da özel ödeme tipinin kimliği ve adı |
staffID / staffName | Satışı yapan personel; ana hesap için “Yönetici” |
quantity, amount | Toplam miktar ve iskontolar düşülmüş satış tutarı |
discountAmount | Satış altı iskonto oranı (%) — alan adına rağmen yüzde değeridir |
serviceFee | Hizmet bedeli / POS komisyonu |
profit | Alış fiyatı tanımlı ürünlerden hesaplanan kâr |
application | Satışı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şproductsolan 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
| Parametre | Tür | Açıklama |
|---|---|---|
data.products[] | zorunlu | En 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.paymentType | metin | CASH / Nakit (varsayılan), CREDITCARD / Pos, OPENACCOUNT / Açık Hesap ya da paymentTypes.php'den bir paymentTypeID |
data.date, data.time | metin | Satış tarihi ve saati; gönderilmezse şimdiki zaman |
data.customerCode | metin | Müşteri kodu; gönderilirse hesapta kayıtlı olmalı. Açık hesap satışlarda gönderin |
data.discountRate | sayı | Satış altı iskonto oranı, 0–100 |
data.note | metin | Satış notu |
data.externalRef | metin | Sizin 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ıttaX-BP-Idempotent: replaybaşlığı gelir. - Başarısız istekte
400 Satış kaydedilemedi.döner; yanıt başlıklarındakiX-BP-Refdeğ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
| Parametre | Tür | Açıklama |
|---|---|---|
page, limit | sayı | Sayfalama; en fazla 1000 |
keyword | metin | Müşteri kodu, ad, soyad, unvan ya da telefonda arar (en fazla 100 karakter) |
onlyDebtCustomers | true/false | Yalnız kalan borcu olan müşteriler (daha pahalıdır) |
orderByColumn | metin | customerName (varsayılan), shoppingCount, debt, paymentAmount, remainingDebt |
orderByType | metin | ASC 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
| Parametre | Tür | Açıklama |
|---|---|---|
customerCode | zorunlu | Müşteri kodu (adı). Büyük harfe çevrilerek kaydedilir; tırnak gibi bazı özel karakterler değiştirilir |
customerType | metin | Bireysel ya da Kurumsal |
name, surname, title | metin | Ad, soyad, unvan |
phone | metin | En fazla 11 karakter |
email, address, country, city, district, postalCode | metin | İletişim ve adres |
taxOffice, taxNo | metin | Vergi dairesi ve VKN / TCKN |
debtLimit | sayı | Veresiye limiti |
discountRate | sayı | Müşteri iskonto oranı (yalnız yeni müşteride) |
priceType | sayı | 1 = Fiyat 1, 2 = Fiyat 2 |
note | metin | Müş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
| Parametre | Tür | Açıklama |
|---|---|---|
data.firmID | zorunlu | Firma kimliği (list › firmID) |
data.startDate, data.endDate | YYYY-MM-DD | Varsayılan: tüm geçmiş ile bugün |
page, limit | sayı | 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": "" }
]
}transactionType | Anlamı | Bakiyeye etkisi |
|---|---|---|
openAccountInvoice | Açık hesap alış faturası | Borç artar |
openAccountReturnInvoice | Açık hesap iade faturası | Borç azalır |
paidInvoice / returnInvoice | Peşin ödenmiş alış / iade faturası | Etkilemez (bilgi amaçlı) |
debt | Elle eklenen borç | Borç artar |
payment | Firmaya yapılan ödeme | Borç 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
| Parametre | Tür | Açıklama |
|---|---|---|
page, limit | sayı | En fazla 1000 |
orderByColumn | metin | name (varsayılan) ya da categoryID |
orderByType | metin | ASC ya da DESC |
onlyActive | true/false | Yalnız aktif gruplar |
onlyOnline | true/false | Yalnız online mağazaya açık gruplar |
onlyRoot | true/false | Yalnız üst gruplar |
parentCategoryID | sayı | 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ı
| HTTP | message | Ne yapmalı? |
|---|---|---|
| 500 | Branch 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. |
| 401 | Mağ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. |
| 403 | API 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. |
| 429 | Dakikalık kullanım limitiniz doldu. | Retry-After kadar (dakikanın sonuna) bekleyin. |
| 429 | Gü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. |
| 429 | Bu 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. |
| 429 | Aşı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. |
| 400 | Geç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. |
| 400 | Doğ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. |
| 503 | Servis 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 / saniye | Puan / dakika | Puan / gün |
|---|---|---|---|
| Standart (varsayılan) | 10 | 3.000 | 800.000 |
| Pro | 20 | 8.000 | 800.000 |
| Partner | 40 | 20.000 | 3.000.000 |
| İşlem | Puan |
|---|---|
paymentTypes list | 1 |
categories list | 3 |
firms list | 10 |
firms getFirmTransactions | 30 |
products list | 15 |
products list + inStockProducts | 60 |
products list + includeBranches | 90 |
products purchaseInvoices / purchaseMovements | 45 |
products add / update / updateQuantity / delete | 15 |
sales list | 30 |
sales create / cancel / pavoInvoice | 15 |
customers list | 25 |
customers list + onlyDebtCustomers | 75 |
customers getCustomerTransactions | 50 |
customers create / addPayment | 25 |
Ö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-Limit | Dakikalık puan sınırınız |
X-RateLimit-Remaining | Bu dakika kalan puan |
X-RateLimit-Reset | Dakikalık sayacın sıfırlanmasına kalan saniye |
X-RateLimit-Cost | Bu isteğin puanı |
Retry-After | 429 yanıtlarında tekrar denemeden önce beklenecek saniye |
X-Cache | HIT: yanıt önbellekten geldi, MISS: yeni hesaplandı |
ETag | Yanı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
ETagdeğerini saklayıp sonraki istekteIf-None-Matchbaşlığıyla gönderirseniz, veri değişmediyse gövdesiz304 Not Modifieddö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:
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ısaleCodeile tekilleştirin (upsert).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.
İ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.Ü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;304dönen sayfayı atlayın. Değişen sayfalardaupdatedDate(fiyat) velastQuantityChangeDate/Time(stok) alanlarını kendi kayıtlarınızla karşılaştırın.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.Siparişleri güvenle yazın
Sitenizdeki her siparişi
sales.php › createile kendi sipariş numaranızıexternalRefolarak göndererek yazın; ağ hatasından sonra tekrar denemek mükerrer satış oluşturmaz.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-Afterkadar 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.