# PosCloud Entegrasyonu - Kurulum ve Kullanım Kılavuzu

## ✅ Tamamlanan İşlemler

### 1. Oluşturulan Dosyalar

- ✅ `app/Services/PosCloudService.php` - PosCloud API servis sınıfı
- ✅ `docs/POSCLOUD_INTEGRATION.md` - Detaylı teknik dokümantasyon (İngilizce)
- ✅ `docs/POSCLOUD_KURULUM.md` - Bu dosya (Türkçe kurulum kılavuzu)

### 2. Güncellenen Dosyalar

- ✅ `config/services.php` - PosCloud URL konfigürasyonu eklendi
- ✅ `.env.example` - PosCloud environment değişkenleri eklendi
- ✅ `app/Livewire/CustomerTransactions.php` - API entegrasyonu yapıldı

---

## 🔧 Kurulum Adımları

### Adım 1: Integration Kaydı Oluştur

Veritabanında PosCloud entegrasyon kaydı oluşturmanız gerekiyor:

```php
// Tinker ile veya seed dosyası ile:
Integration::create([
    'slug' => 'bulutadisyon',
    'title' => 'PosCloud Entegrasyonu',
    'account_id' => 123, // selected_pos_service_id ile eşleşmeli
    'api_key' => 'YOUR_API_KEY_HERE', // PosCloud dashboard'dan alın
    'is_active' => true,
    'type' => 'pos',
]);
```

**API Key Nasıl Alınır?**
1. PosCloud (Bulut Adisyon) dashboard'a giriş yapın
2. Firma ayarlarına gidin
3. API anahtarı bölümünden key'i kopyalayın
4. Yukarıdaki Integration kaydına yapıştırın

### Adım 2: Environment Kontrolü

`.env` dosyanızda şu satırlar varsa kontrol edin (opsiyonel, default değerler zaten var):

```env
POSCLOUD_PROD_URL=https://api.bulutadisyon.com
POSCLOUD_DEV_URL=https://dev.api.bulutadisyon.com
POSCLOUD_BETA_URL=https://beta.api.bulutadisyon.com
```

### Adım 3: Cache Temizle

```bash
php artisan cache:clear
php artisan config:clear
```

---

## 🎯 Nasıl Çalışır?

### Senaryo 1: Yeni Hareket Ekleme

```
1. Müşteri detay sayfasında "Yeni Hareket Ekle" butonuna tıkla
2. Modal açılır
3. Form doldur:
   - Tutar: 150.00
   - İndirim: 0 (opsiyonel)
   - Ödeme Tipi: Nakit
   - Açıklama: "Müşteriden tahsilat"
   - Tarih: 13.05.2026 14:30
4. "Kaydet" butonuna tıkla
5. Sistem PosCloud API'ye istek gönderir
6. API başarılı → Remote DB'ye yazılır → Liste güncellenir → Başarı mesajı
7. API başarısız → Hata mesajı → Kayıt oluşmaz → Modal açık kalır
```

### Senaryo 2: Vadeli Satış Tahsilatı

```
1. Müşteri detay sayfasında vadeli satışlar listelenir
2. Bir satışın yanındaki "Tahsil Et" butonuna tıkla
3. Modal açılır (tutar otomatik doldurulur)
4. Ödeme tipi ve tarih seç
5. "Tahsil Et" butonuna tıkla
6. Sistem PosCloud API'ye istek gönderir
7. API başarılı → Remote DB'ye yazılır → Liste güncellenir → Başarı mesajı
8. API başarısız → Hata mesajı → Kayıt oluşmaz
```

---

## 📊 Veri Akışı

```
┌─────────────────┐
│  Kullanıcı UI   │
│  (Livewire)     │
└────────┬────────┘
         │ Form Submit
         ↓
┌─────────────────┐
│  Validation     │
│  (Laravel)      │
└────────┬────────┘
         │ Valid
         ↓
┌──────────────────────┐
│  PosCloudService     │
│  createCustomer      │
│  Transaction()       │
└────────┬─────────────┘
         │ HTTP POST
         ↓
┌──────────────────────────┐
│  PosCloud API            │
│  api.bulutadisyon.com    │
└────────┬─────────────────┘
         │
    ┌────┴─────┐
    │ Success? │
    └────┬─────┘
     Yes │      │ No
         ↓      ↓
    ┌────────┐  ┌──────────────┐
    │PosCloud│  │ Hata Mesajı  │
    │Backend │  │ Göster       │
    │        │  └──────────────┘
    │Remote  │
    │DB'ye   │
    │Yazar   │
    └───┬────┘
        │
        ↓
    ┌──────────────┐
    │ refreshData()│
    │ Remote DB'den│
    │ güncel veri  │
    │ çek          │
    └───┬──────────┘
        │
        ↓
    ┌──────────────┐
    │ UI Güncelle  │
    │ Başarı Mesajı│
    └──────────────┘
```

---

## ⚠️ Önemli Notlar

### 1. Yerel Kayıt YOK
- ❌ API başarısız olursa hiçbir kayıt oluşmaz
- ❌ Fallback mekanizması yok
- ✅ Ya hep ya hiç mantığıyla çalışır

### 2. Remote Database
- `PosCustomerTransactions` modeli `mysql-remote` connection kullanır
- API başarılı olduktan sonra remote DB'den güncel veriler çekilir
- PosCloud backend, remote DB'ye yazmaktan sorumludur

### 3. Yön Parametresi
- Tüm manuel işlemler `direction='collection'` kullanır
- Bu, müşteriden para tahsil edildiği anlamına gelir
- `payment` yönü şu an kullanılmıyor (müşteriye ödeme)

### 4. Tarih Formatı
- Laravel formatı: `Y-m-d\TH:i` (örn: `2026-05-13T14:30`)
- PosCloud formatı: `DD.MM.YYYY HH:mm` (örn: `13.05.2026 14:30`)
- Servis otomatik dönüşüm yapar

---

## 🐛 Sorun Giderme

### Problem: "API anahtarı yapılandırılmamış"

**Çözüm:**
```sql
-- Integration tablosunu kontrol et
SELECT * FROM integrations WHERE slug = 'bulutadisyon';

-- Eğer kayıt yoksa ekle:
INSERT INTO integrations (slug, title, account_id, api_key, is_active, type, created_at, updated_at)
VALUES ('bulutadisyon', 'PosCloud', 123, 'YOUR_API_KEY', 1, 'pos', NOW(), NOW());
```

### Problem: "Bağlanılamadı" hatası

**Çözüm:**
1. Sunucu internet bağlantısını kontrol et
2. Firewall outbound HTTPS trafiğine izin veriyor mu kontrol et
3. PosCloud API ayakta mı kontrol et

### Problem: Transaction oluştu ama listede görünmüyor

**Çözüm:**
```php
// Remote DB'den manuel sorgu yap
$transactions = PosCustomerTransactions::where('account_id', 123)
    ->where('second_party_type', 'customer')
    ->where('second_party_id', 45)
    ->orderBy('paid_at', 'desc')
    ->get();

dd($transactions);
```

Eğer kayıt DB'de var ama UI'da görünmüyorsa:
- `refreshData()` metodunun çağrıldığından emin olun
- Browser console'da JavaScript hatası var mı kontrol edin
- Livewire component'in doğru render edildiğini kontrol edin

---

## 🧪 Test Checklist

Kurulum sonrası test edin:

- [ ] Integration kaydı oluşturuldu mu?
- [ ] API key doğru girildi mi?
- [ ] Manuel transaction ekleme çalışıyor mu?
- [ ] Vadeli satış tahsilatı çalışıyor mu?
- [ ] API başarısız olduğunda hata mesajı gösteriliyor mu?
- [ ] Başarılı işlem sonrası liste güncelleniyor mu?
- [ ] Bakiye doğru hesaplanıyor mu?
- [ ] Log dosyasında API çağrıları görünüyor mu?

---

## 📝 Log Kontrolü

API çağrılarını izlemek için:

```bash
tail -f storage/logs/laravel.log | grep "PosCloud"
```

Örnek log çıktıları:

```
[2026-05-13 14:30:00] local.INFO: PosCloud API: Transaction oluşturuluyor
[2026-05-13 14:30:01] local.INFO: PosCloud API: Transaction başarıyla oluşturuldu
[2026-05-13 14:30:01] local.INFO: Manuel transaction başarıyla oluşturuldu
```

---

## 🚀 Sonraki Adımlar

Entegrasyon çalıştıktan sonra şunları düşünebilirsiniz:

1. **Retry Mekanizması**: Başarısız API çağrıları için otomatik yeniden deneme
2. **Background Queue**: Uzun süren API çağrıları için queue kullanımı
3. **Reconciliation**: PosCloud ve remote DB arasındaki tutarsızlıkları tespit etme
4. **Webhook Desteği**: Gerçek zamanlı senkronizasyon onayı
5. **Bulk Operations**: Toplu transaction oluşturma

---

## 📞 Destek

Sorun yaşarsanız:

1. Log dosyalarını kontrol edin: `storage/logs/laravel.log`
2. Integration kaydını doğrulayın
3. PosCloud API documentation'ı inceleyin: `docs/API_GUIDE.md`
4. Teknik dokümantasyon: `docs/POSCLOUD_INTEGRATION.md`

---

**Son Güncelleme:** 2026-05-14
**Versiyon:** 1.0.0