# PavoPay Cloud API - Restoran Entegrasyon Dokümantasyonu

**Versiyon:** 1.0  
**Tarih:** 21 Mayıs 2026  
**API Base URL:** `https://pavo.sirrusyazilim.com/api.php`  
**Pavo Cloud API:** `https://overpaywsdemo.overtech.com.tr`  
**Admin Panel:** `https://pavo.sirrusyazilim.com/admin/`

---

## 1. Genel Bakış

Bu dokümantasyon, restoran yazılımlarının PavoPay POS cihazları ile Cloud API üzerinden entegre olmasını açıklar. Entegrasyon sayesinde restoran yazılımından satış gönderilir, POS cihazında ödeme alınır ve sonuç sorgulanır.

### Temel Akış

```
Restoran Yazılımı → API Sunucusu → PavoPay Cloud → POS Cihazı
                                                       ↓
                                                   Ödeme Alınır
                                                       ↓
Restoran Yazılımı ← API Sunucusu ← PavoPay Cloud ← Sonuç Döner
```

### Desteklenen İşlemler

- Satış gönderme (masa bazlı)
- Ödeme tipi seçimi (nakit, kredi kartı, yemek kartı vb.)
- Satış sorgulama
- Satış iptal etme
- Ürün/kategori/stok yönetimi
- Terminal bildirim gönderme
- X/Z Raporları

---

## 2. Ön Gereksinimler

### 2.1 Kimlik Bilgileri

Pavo'dan alınacak bilgiler:

| Bilgi | Açıklama | Örnek |
|-------|----------|-------|
| `appToken` | Sabit uygulama token'ı | `97b7a056881768d5a5eccac57402166b3024b798` |
| `apiKey` | Üye işyerine özel API anahtarı | `808d9ac24d7ac2fed...` |
| `terminalSerial` | POS cihaz seri numarası | `PAV860030343` |

### 2.2 Terminal Eşleşme (Bir Kez Yapılır)

Cloud API kullanmadan önce POS cihazı ile eşleşme yapılması **zorunludur**. Bu işlem sadece bir kez yapılır.

**Adım 1 — Eşleşme İsteği:**

```
POST /api.php?action=pairingRequest
Content-Type: application/json

{
    "sourceFingerPrint": "RESTORAN_ADI",
    "sourceReference": "Restoran_Entegrasyon",
    "targetSerialNo": "PAV860030343"
}
```

Yanıt:
```json
{
    "Data": {
        "Id": 7735,
        "PairingCode": "053636",
        "IsApproved": false
    },
    "Success": true
}
```

> POS cihazında eşleşme isteği çıkacak — cihazdan **onaylayın**.

**Adım 2 — Eşleşme Kontrol:**

```
POST /api.php?action=checkPairing
Content-Type: application/json

{
    "pairingId": 7735,
    "targetSerialNo": "PAV860030343"
}
```

Yanıt:
```json
{
    "Data": {
        "IsApproved": true,
        "TargetFingerPrint": "SPRD/sl8541e_1h10_oversea/sl8541e_1h10:9/PPR1..."
    },
    "Success": true
}
```

> `TargetFingerPrint` değerini **kaydedin** — her satış gönderiminde kullanılacak.

---

## 3. Satış Gönderme (PaymentLinkRequest)

Restoran yazılımından POS cihazına satış göndermek için `PaymentLinkRequest` endpoint'i kullanılır.

### 3.1 Temel Satış

```
POST /api.php?action=paymentLinkRequest
Content-Type: application/json
```

```json
{
    "LinkType": "P",
    "SourceFingerPrint": "RESTORAN_ADI",
    "SourceTerminalReference": "Masa-5",
    "TargetFingerPrint": "SPRD/sl8541e_1h10_oversea/...",
    "TargetSerialNo": "PAV860030343",
    "PushNow": true,
    "PaymentLinkReference": "SRS260521143000",
    "PaymentAmount": 150.00,
    "CurrencyCode": "TRY",
    "RequestedMethod": "P",
    "ApplicationName": "Satış",
    "Request": {
        "Sale": {
            "RefererApp": "Harici Uygulama",
            "RefererAppVersion": "1.0.0",
            "SendEMailNotification": false,
            "SendPhoneNotification": false,
            "SaleReason": "Masa-5 Hesabı",
            "TotalAmount": 150.00,
            "IntegrationSaleType": 1,
            "OrderNo": "MS005-001",
            "TotalPrice": 150.00,
            "GrossPrice": 150.00,
            "CurrencyCode": "TRY",
            "ExchangeRate": 1.0,
            "MainDocumentType": 1,
            "ShowCreditCardMenu": true,
            "AddedSaleItems": [
                {
                    "IsGeneric": false,
                    "ItemQuantity": 2,
                    "Name": "Adana Kebap",
                    "TaxGroupCode": "KDV20",
                    "UnitCode": "C62",
                    "UnitPriceAmount": 50.00,
                    "GrossPriceAmount": 100.00,
                    "TotalPriceAmount": 100.00
                },
                {
                    "IsGeneric": false,
                    "ItemQuantity": 2,
                    "Name": "Ayran",
                    "TaxGroupCode": "KDV10",
                    "UnitCode": "C62",
                    "UnitPriceAmount": 25.00,
                    "GrossPriceAmount": 50.00,
                    "TotalPriceAmount": 50.00
                }
            ]
        }
    }
}
```

### 3.2 Yanıt

```json
{
    "Data": {
        "Id": 72626,
        "StatusId": 1,
        "PaymentLinkReference": "SRS260521143000",
        "PaymentAmount": 150.0,
        "RequestTime": "2026-05-21T14:30:00.123"
    },
    "Success": true
}
```

> `Data.Id` değerini kaydedin — satış durumu sorgulamak için kullanılacak.

---

## 4. Parametre Açıklamaları

### 4.1 Ana Parametreler

| Parametre | Zorunlu | Açıklama |
|-----------|---------|----------|
| `LinkType` | Evet | `"P"` (Paired — eşleşmiş cihaz) |
| `SourceFingerPrint` | Evet | Kaynak uygulama kimliği (eşleşmede kullanılan) |
| `SourceTerminalReference` | Evet | Masa adı / kaynak bilgisi (cihazda görünür) |
| `TargetFingerPrint` | Evet | Eşleşme sonrası alınan cihaz fingerprint'i |
| `TargetSerialNo` | Evet | POS cihaz seri numarası |
| `PushNow` | Evet | `true` — cihaza anında gönder |
| `PaymentLinkReference` | Evet | Benzersiz referans numarası (sorgulama için) |
| `PaymentAmount` | Evet | Toplam tutar |
| `CurrencyCode` | Evet | Para birimi: `"TRY"`, `"USD"`, `"EUR"` |
| `RequestedMethod` | Evet | `"P"` (Payment), `"C"` (Cancel/İptal) |
| `ApplicationName` | Evet | Uygulama adı: `"Satış"` |

### 4.2 Sale (Satış) Parametreleri

| Parametre | Zorunlu | Açıklama |
|-----------|---------|----------|
| `RefererApp` | Evet | `"Harici Uygulama"` (sabit) |
| `RefererAppVersion` | Evet | `"1.0.0"` |
| `TotalAmount` | Evet | Toplam tutar |
| `TotalPrice` | Evet | Toplam fiyat (TotalAmount ile aynı) |
| `GrossPrice` | Evet | Brüt fiyat (TotalAmount ile aynı) |
| `IntegrationSaleType` | Evet | Satış tipi (bkz. aşağıda) |
| `OrderNo` | Hayır | Sipariş numarası (kendi sisteminizden) |
| `MainDocumentType` | Hayır | 1: E-Arşiv, 9: Gider Pusulası, 10: Cari Tahsilat |
| `ShowCreditCardMenu` | Hayır | `true`: cihazda ödeme tipi seçimi çıkar |
| `SaleReason` | Hayır | Satış açıklaması |
| `AddedSaleItems` | Evet | Satış kalemleri dizisi |
| `PaymentInformations` | Hayır | Boş bırakılırsa cihazda ödeme tipi seçilir |

### 4.3 Satış Kalemleri (AddedSaleItems)

| Parametre | Zorunlu | Açıklama |
|-----------|---------|----------|
| `Name` | Evet | Ürün adı |
| `IsGeneric` | Evet | `false` (tanımlı ürün) |
| `ItemQuantity` | Evet | Miktar |
| `UnitCode` | Evet | `"C62"` (Adet), `"KGM"` (Kg), `"LTR"` (Lt) |
| `UnitPriceAmount` | Evet | Birim fiyat |
| `GrossPriceAmount` | Evet | Brüt tutar (miktar × birim fiyat) |
| `TotalPriceAmount` | Evet | Toplam tutar |
| `TaxGroupCode` | Evet | KDV kodu (bkz. aşağıda) |

### 4.4 Ödeme Bilgileri (PaymentInformations) — Opsiyonel

Eğer ödeme tipi önceden belirlenmişse:

```json
"PaymentInformations": [
    {
        "Mediator": 1,
        "Amount": 150.00,
        "CurrencyCode": "TRY",
        "ExchangeRate": 1.0
    }
]
```

**Cihazda ödeme tipi seçilsin istiyorsanız:** `PaymentInformations` göndermeyin ve `ShowCreditCardMenu: true` yapın.

---

## 5. Ödeme Tipi Seçenekleri

### 5.1 Cihazda Seçim (Önerilen)

`PaymentInformations` göndermezseniz ve `ShowCreditCardMenu: true` yaparsanız, cihaz ekranında tüm ödeme seçenekleri görünür. Garson veya müşteri cihazdan seçer.

### 5.2 Sabit Ödeme Tipi

| Mediator ID | Ödeme Tipi |
|-------------|-----------|
| 1 | Nakit |
| 2 | Kredi Kartı (BKM TechPos) |
| 4 | Multinet |
| 10 | Harici Yemek Kartı |
| 13 | Metropol |
| 27 | Ödemesiz |
| 28 | Havale / EFT |
| 29 | Açık Hesap |

---

## 6. Referans Kodları

### 6.1 KDV Kodları (TaxGroupCode)

| Kod | Oran | Açıklama |
|-----|------|----------|
| `KDV20` | %20 | Standart KDV |
| `KDV10` | %10 | İndirimli KDV |
| `KDV1` | %1 | Düşük KDV |
| `KDV0-351` | %0 | KDV İstisna |

### 6.2 Satış Tipleri (IntegrationSaleType)

| Tip | Ad |
|-----|----|
| 1 | Normal Satış |
| 2 | Avans Satış |
| 3 | Cari Satış |
| 4 | Kuyum Satış |
| 6 | Kısmi İade |
| 7 | Avans Kısmi İade |

### 6.3 Satış Durumları (StatusId)

| ID | Durum |
|----|-------|
| 1 | Initial (Başlatıldı) |
| 2 | InProgress (İşleniyor) |
| 3 | Completed (Tamamlandı) |
| 4 | Abandoned (Vazgeçildi) |
| 5 | Aborted (İptal Edildi) |

### 6.4 Birim Kodları (UnitCode)

| Kod | Birim |
|-----|-------|
| `C62` | Adet |
| `KGM` | Kilogram |
| `LTR` | Litre |
| `MTR` | Metre |

---

## 7. Satış Durumu Sorgulama

### 7.1 PaymentLinkId ile Sorgulama

```
POST /api.php?action=checkLinkRequest
Content-Type: application/json

{
    "paymentLinkId": 72626,
    "paymentLinkReference": ""
}
```

### 7.2 PaymentLinkReference ile Sorgulama

```
POST /api.php?action=checkLinkRequest
Content-Type: application/json

{
    "paymentLinkId": 0,
    "paymentLinkReference": "SRS260521143000"
}
```

### 7.3 OrderNo ile Sorgulama

```
GET /api.php?action=getCompletedSale&orderNo=MS005-001
```

### 7.4 Yanıt Örneği

```json
{
    "Data": {
        "Id": 72626,
        "StatusId": 3,
        "PaymentLinkReference": "SRS260521143000",
        "PaymentAmount": 150.0,
        "RequestTime": "2026-05-21T14:30:00.123",
        "ResponseTime": "2026-05-21T14:30:15.456",
        "Response": "{...satış detayları...}"
    },
    "Success": true
}
```

> `StatusId: 3` = Tamamlandı. `Response` alanında satış detayları (SaleNumber, ödeme bilgileri vb.) JSON olarak yer alır.

---

## 8. Satış İptal Etme

### 8.1 Link İptali

Henüz tamamlanmamış bir satış linkini iptal etmek için:

```
POST /api.php?action=cancelLinkRequest
Content-Type: application/json

{
    "paymentLinkId": 72626,
    "paymentLinkReference": ""
}
```

### 8.2 Tamamlanmış Satış İptali

Tamamlanmış bir satışı iptal etmek için `RequestedMethod: "C"` ile PaymentLinkRequest gönderilir:

```json
{
    "LinkType": "P",
    "SourceFingerPrint": "RESTORAN_ADI",
    "SourceTerminalReference": "Masa-5",
    "TargetFingerPrint": "...",
    "TargetSerialNo": "PAV860030343",
    "PaymentLinkReference": "CANCEL001",
    "PaymentAmount": 150.00,
    "CurrencyCode": "TRY",
    "RequestedMethod": "C",
    "ApplicationName": "Satış",
    "Request": {
        "Sale": {
            "SaleNumber": "rjQz55XXwC",
            "ReceiptInformation": {
                "PrintCustomerReceipt": true,
                "PrintMerchantReceipt": false,
                "ReceiptWidth": "80mm"
            }
        }
    }
}
```

---

## 9. Restoran Entegrasyon Senaryosu

### 9.1 Masa Açma ve Sipariş

```
1. Restoran yazılımında masa açılır (Masa-5)
2. Siparişler girilir (Adana Kebap x2, Ayran x2)
3. Hesap istenir
```

### 9.2 Ödeme Gönderme

```
4. Restoran yazılımı PaymentLinkRequest gönderir:
   - SourceTerminalReference: "Masa-5"
   - OrderNo: "MS005-001" (masa no + sipariş no)
   - PaymentLinkReference: "SRS260521143000" (benzersiz)
   - AddedSaleItems: [ürünler]
   - ShowCreditCardMenu: true (garson cihazda ödeme tipi seçer)
```

### 9.3 Cihazda Ödeme

```
5. POS cihazına satış düşer
6. Cihaz ekranında:
   - "Masa-5" görünür
   - Ürünler ve tutar listelenir
   - Ödeme tipi seçilir (Nakit/Kart/Yemek Kartı)
7. Ödeme alınır, fiş basılır
```

### 9.4 Sonuç Sorgulama

```
8. Restoran yazılımı CheckLinkRequest ile durumu sorgular
9. StatusId: 3 (Completed) ise masa kapatılır
10. Response içinden SaleNumber, fiş bilgileri alınır
```

### 9.5 Örnek Polling Kodu (PHP)

```php
function waitForCompletion($apiUrl, $linkId, $maxWait = 120) {
    $start = time();
    while (time() - $start < $maxWait) {
        $ch = curl_init($apiUrl . '?action=checkLinkRequest');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode([
                'paymentLinkId' => $linkId,
                'paymentLinkReference' => ''
            ]),
            CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        ]);
        $response = json_decode(curl_exec($ch), true);
        curl_close($ch);

        $status = $response['Data']['StatusId'] ?? 0;

        if ($status === 3) return ['success' => true, 'data' => $response['Data']];
        if ($status >= 4) return ['success' => false, 'status' => $status];

        sleep(3); // 3 saniye bekle, tekrar sorgula
    }
    return ['success' => false, 'status' => 'timeout'];
}
```

---

## 10. Tüm API Endpoint'leri

### 10.1 Kimlik Doğrulama

| Endpoint | Method | Açıklama |
|----------|--------|----------|
| `?action=auth` | GET | Token al (otomatik cache'lenir) |
| `?action=authenticate` | GET | Yeni token oluştur |

### 10.2 Satış İşlemleri

| Endpoint | Method | Açıklama |
|----------|--------|----------|
| `?action=paymentLinkRequest` | POST | Satış/İptal gönder |
| `?action=checkLinkRequest` | POST | Satış durumu sorgula |
| `?action=cancelLinkRequest` | POST | Link iptal |
| `?action=getCompletedSale` | GET | Satış detay (orderNo/saleId/saleUID/saleNumber) |
| `?action=listCompletedSales` | GET | Tamamlanan satış listesi |
| `?action=listSales` | GET | Satış listesi |

### 10.3 Terminal Eşleşme

| Endpoint | Method | Açıklama |
|----------|--------|----------|
| `?action=pairingRequest` | POST | Eşleşme isteği |
| `?action=checkPairing` | POST | Eşleşme kontrol |

### 10.4 Ürün Yönetimi

| Endpoint | Method | Açıklama |
|----------|--------|----------|
| `?action=listProducts` | GET | Ürün listesi |
| `?action=getProduct` | GET | Ürün detay |
| `?action=uploadProduct` | POST | Ürün ekle/güncelle |
| `?action=uploadCategory` | POST | Kategori ekle |
| `?action=uploadProperty` | POST | Özellik ekle |
| `?action=uploadProductStock` | POST | Stok güncelle |
| `?action=addStockTransaction` | POST | Stok hareketi |
| `?action=deleteProductImages` | POST | Ürün resimleri sil |
| `?action=listBranches` | GET | Şube listesi |

### 10.5 Bildirim

| Endpoint | Method | Açıklama |
|----------|--------|----------|
| `?action=sendNotification` | POST | Firebase push bildirim |

---

## 11. Hata Yönetimi

### 11.1 API Yanıt Yapısı

Başarılı:
```json
{
    "Success": true,
    "Data": { ... },
    "Message": null
}
```

Hatalı:
```json
{
    "Success": false,
    "Message": "Hata açıklaması"
}
```

### 11.2 Yaygın Hatalar

| Hata | Çözüm |
|------|-------|
| `Authentication failed` | appToken veya apiKey hatalı |
| `SourceFingerPrint cannot be empty` | Eşleşme bilgileri eksik |
| `Undefined request method type` | TargetFingerPrint boş — eşleşme yapılmamış |
| `Payment link not found` | Geçersiz PaymentLinkId veya Reference |
| `Cihaz Meşgul` | POS cihazında başka işlem devam ediyor |

### 11.3 Öneriler

- Her satış için **benzersiz** `PaymentLinkReference` kullanın
- Satış sonucunu **polling** ile sorgulayın (3-5 saniye aralıklarla)
- Token otomatik cache'lenir (60 dk), süre dolunca yenilenir
- Hata durumunda **retry** mekanizması kurun

---

## 12. Güvenlik

- API iletişimi **HTTPS** üzerinden yapılır
- Token **60 dakika** geçerlidir, otomatik yenilenir
- `TargetFingerPrint` eşleşme onayı olmadan satış gönderilemez
- Her satış **loglanır** (sale_logs tablosu)
- Admin panel **şifre korumalı** (session timeout: 1 saat)

---

## 13. Test Ortamı

| Bilgi | Değer |
|-------|-------|
| API Base URL | `https://overpaywsdemo.overtech.com.tr` |
| appToken | `97b7a056881768d5a5eccac57402166b3024b798` |
| Admin Panel | `https://pavo.sirrusyazilim.com/admin/` |
| Admin Giriş | admin / admin123 |
| Terminal | PAV860030343 (ID: 76295) |

---

## 14. İletişim

- **Pavo Destek:** gmudestek@pavo.com.tr / 0850 611 0 444
- **Sirrus Yazılım:** admin@sirrusyazilim.com