# Entegrasyonlar

cxg-tattoos, satın alma ücretlerini almak ve yönetici izinlerini denetlemek için farklı framework'lere bağlanabilir. Görünüm entegrasyonu, karakter yüklendiğinde veya skin değiştiğinde kaydedilmiş dövmeleri yeniden uygular. Her bölüm ayrı yapılandırılır.

[Giriş](https://docs.cxgstudios.com/docs/tr/01-cxg-tattoos/01-introduccion.md), [Kurulum](https://docs.cxgstudios.com/docs/tr/01-cxg-tattoos/02-instalacion.md), [Yapılandırma](https://docs.cxgstudios.com/docs/tr/01-cxg-tattoos/03-configuracion.md), [Katalog](https://docs.cxgstudios.com/docs/tr/01-cxg-tattoos/04-catalogo.md) ve [Arayüz](https://docs.cxgstudios.com/docs/tr/01-cxg-tattoos/06-interfaz.md) bölümlerine de bakın.

## Kullanılabilir framework'ler

| Sistem | Yapılandırma tanımlayıcısı | Varsayılan kaynak | Ödemeler | İzinler |
| --- | --- | --- | --- | --- |
| Qbox | `qbx` | `qbx_core` | Evet | Evet |
| QBCore | `qbcore` | `qb-core` | Evet | Evet |
| ESX | `esx` | `es_extended` | Evet | Evet |
| Framework yok | `standalone` | Uygulanamaz | Özel callback veya ücretsiz satın alma | ACE veya özel denetim |

`auto` ile kaynak, başlatılmış Qbox, QBCore veya ESX'i algılar; hiçbirini bulamazsa `standalone` kullanır. Sunucuda birden fazla framework etkinse veya kaynak adı varsayılandan farklıysa framework'i belirtebilirsiniz:

```lua
Config.Purchases.framework = 'qbx' -- auto | qbx | qbcore | esx | standalone
Config.Purchases.resources.qbx = 'qbx_core'
Config.Purchases.accounts = { 'cash', 'bank' }
Config.Purchases.esxAccountMap.cash = 'money'
Config.Purchases.esxAccountMap.bank = 'bank'
Config.Purchases.allowFreePurchases = false
```

Hesaplar belirtilen sırayla denenir. Ücret tek bir hesaptan tahsil edilir; bakiyesi yetmezse sıradaki hesap denenir. ESX'te `esxAccountMap`, `cash` değerini `money` hesap adına eşler.

`Config.Purchases.reason` ve `refundReason`, destekleyen provider'larda işlemlerin nedenini belirtir. Başlangıç değerleri `tattoo-purchase` ve `tattoo-purchase-refund` şeklindedir. `allowFreePurchases` seçeneği standalone adaptöründe tahsilatı atlamaya izin verir; diğer framework'lerdeki satın almaları ücretsiz yapmaz.

## Framework olmadan ödeme

`standalone` modunda `tryCharge` ve `refund` callback'lerini sunucunuzun ekonomi kaynağına bağlayın. Satın almaları kabul etmek için iki callback de gereklidir: dövme kaydı başarısız olursa tahsilatı iade etmek gerekir.

```lua
Config.Purchases.framework = 'standalone'
Config.Purchases.standalone.tryCharge = function(source, totalAmount, context)
    -- Sustituye esta llamada por la API de economía de tu servidor.
    local charged, receipt = MyEconomy.charge(source, totalAmount, context)
    if charged then
        return true, receipt
    end
    return false, 'No tienes saldo suficiente.'
end

Config.Purchases.standalone.refund = function(source, totalAmount, context, receiptData)
    -- Usa receiptData para devolver el mismo cobro aprobado.
    return MyEconomy.refund(source, totalAmount, receiptData) == true
end
```

`MyEconomy`, sunucunuzun API'sini temsil eder; bunu gerçek ad ve çağrılarla değiştirin. Ücretsiz satın almaya özellikle izin vermek için `allowFreePurchases = true` ayarlayın.

Ödeme adaptörleri `isAvailable(settings)`, `charge(source, amount, context, settings)` ve `refund(source, amount, context, settings)` işlevlerini sunar. Onaylanan bir ödeme makbuzunu `context.paymentReceipt` içinde korumalıdır; cxg-tattoos, olası iadeyi aynı ödeme sistemine yönlendirmek için bunu kullanır. Kendi ekonominiz için doğrudan yapılandırma yolu, `standalone` içindeki `tryCharge` ve `refund` callback'leridir.

## Yönetici izinleri

Yönetici panelini açma ve kullanma izinleri sunucuda doğrulanır. İstemci arayüzünü gizlemek veya değiştirmek erişim yetkisi vermez.

Başlangıç yapılandırması algılanan framework'i ve yedek olarak ACE'i kullanır:

```lua
Config.Permissions = {
    framework = 'auto', -- auto | qbx | qbcore | esx | standalone
    mode = 'hybrid',    -- framework | ace | hybrid | custom
    acePrefix = 'cxg-tattoos.',
    resources = {
        qbx = 'qbx_core',
        qbcore = 'qb-core',
        esx = 'es_extended',
    },
    bindings = {
        admin = {
            ace = { 'cxg-tattoos.admin', 'group.admin', 'admin' },
            qbx = { 'god', 'admin', 'group.admin' },
            qbcore = { 'god', 'admin', 'group.admin' },
            esx = { 'superadmin', 'admin' },
        },
    },
}
```

`framework` modu framework rollerini denetler. `ace`, binding içindeki ACE girdilerini kullanır. `hybrid`, bu iki yöntemden herhangi biriyle erişime izin verir. `standalone` modunda framework yetkilendirmesi kullanılamaz; ACE'i veya özel bir denetimi yapılandırın.

Örneğin, `group.admin` ACE principal grubunun üyelerine izin vermek için:

```cfg
add_ace group.admin cxg-tattoos.admin allow
```

Kararı kendi sisteminize devretmek için `mode = 'custom'` kullanın. Callback oyuncu kimliğini, izni, işlem bağlamını ve yapılandırılmış binding'i alır; yalnızca boolean `true` değeri erişim verir:

```lua
Config.Permissions.mode = 'custom'
Config.Permissions.custom = {
    hasPermission = function(source, permission, context, binding)
        return exports.my_permissions:hasPermission(source, permission) == true
    end,
}
```

`my_permissions` değerini sunucunuzda kurulu API'ye göre uyarlayın. Callback eksikse, hata verirse veya başka bir değer döndürürse erişim reddedilir.

Paneli açan komut da yapılandırılır. `permission`, `Config.Permissions.bindings` içindeki bir anahtarla eşleşmelidir:

```lua
Config.AdminCommand.enabled = true
Config.AdminCommand.name = 'tattooadmin'
Config.AdminCommand.permission = 'admin'
```

Bu değerlerle `admin` izni `/tattooadmin` komutunu ve yönetim işlemlerini korur. Komutu devre dışı bırakmak için `enabled = false` yapın; diğer yönetim yollarında izin denetimi sürer.

### Düzenlenebilir entegrasyon dosyaları

Düzenlenebilir bridge'ler harici sistem bağlantılarını bir araya getirir. Özel bir izin veya ödeme için yukarıda açıklanan callback'leri yapılandırmak tercih edilir. Mevcut bir bridge'i uyarlayacaksanız sözleşmesini koruyun:

| Dosya veya grup | Kullanım | Adaptör sözleşmesi |
| --- | --- | --- |
| `bridge/permissions/server.lua` | Framework seçimi ve `framework`, `ace`, `hybrid` veya `custom` modunun uygulanması | `TattooPermissions.Has(source, permission, context)`, yalnızca izin verildiğinde `true` döndürür |
| `bridge/permissions/registry.lua` | İzinlerin ortak kaydı ve yardımcı araçları | `TattooPermissionBridge.register(name, adapter)` |
| `bridge/permissions/qbx.lua`, `qbcore.lua`, `esx.lua`, `standalone.lua` | Her framework veya frameworksüz mod için denetimler | `isAvailable(settings)` ve `hasPermission(source, binding, settings, permission)`; uyarlanırsa ek `context` kabul eder |
| `bridge/payments/server.lua` | Provider seçimi, tahsilat ve iade | `Config.TryChargePlayer(source, totalAmount, context)` ve `Config.RefundPlayer(source, totalAmount, context)` |
| `bridge/payments/registry.lua` | Ödemelerin ortak kaydı ve yardımcı araçları | `TattooPaymentBridge.register(name, adapter)` ve makbuz yardımcıları |
| `bridge/payments/qbx.lua`, `qbcore.lua`, `esx.lua`, `standalone.lua` | Framework veya özel callback'lerle ödeme işlemleri | `isAvailable(settings)`, `charge(...)` ve `refund(...)` |
| `bridge/appearance.lua` | Skin yükleme olayları ve kaydedilmiş dövmeleri isteme | Karakterin dövme listesini ister ve görünüm yüklemesi tamamlandığında uygular |

Bridge çağırdığında izin callback'i beşinci argüman olarak `context` değerini de alır. Kayıt, dahil edilen provider'ları (`qbx`, `qbcore`, `esx`, `standalone`) içerir; özel seçenekler için başka bir provider eklemek gerekmez.

Ödeme adaptöründe `TattooPaymentBridge.setReceipt(context, provider, account, amount, identifier, data)` ile makbuz kaydını koruyun. İade, `getReceipt(context, provider, amount)` ile aynı provider'ı ve tutarı doğrulamalı; iade onaylandıktan sonra makbuzu iade edilmiş olarak işaretlemelidir. Kullandığınız provider'ın dosyasını uyarlayın; adaptörleri değiştirmeden kendi entegrasyonunuzu kurmak için standalone callback'lerini kullanın.

## Görünüm ve karakterin yüklenmesi

Kaynak, `illenium-appearance`, `fivem-appearance`, QBCore, ESX ve `spawnmanager` için yaygın olayları dinler; ardından kaydedilmiş dövmeleri alıp yeniden uygular. Qbox'ta multicharacter önizleme yapılandırması, karakter seçiminde kaydedilmiş dövmeleri göstermek için `playerskins.skin` değerini kullanır.

Görünüm sisteminiz farklı bir olay kullanıyorsa skin yüklemesi tamamlandıktan sonra uygulamayı isteyin:

```lua
TriggerServerEvent('cxg-tattoos:fetchMyTattoos')
```

Olay, geçerli karakterin dövmelerini istemciye gönderir. Listeyi oyuncunun seçtiği bir kaynaktan göndermeyin: sahiplik sunucuda çözülür ve doğrulanır.

Qbox multicharacter önizlemesi şu alanlarla ayarlanır:

```lua
Config.QbxMulticharacterPreview.enabled = true
Config.QbxMulticharacterPreview.resource = 'qbx_core'
Config.QbxMulticharacterPreview.playerskinsTable = 'playerskins'
Config.QbxMulticharacterPreview.playersTable = 'players'
Config.QbxMulticharacterPreview.syncExistingOnStart = true
```

`enabled` entegrasyonu açar; `resource` kurulu Qbox kaynağının adını belirtir. `playerskinsTable` ve `playersTable`, bu kurulumun kullandığı görünüm ve karakter tablolarını gösterir. `syncExistingOnStart`, cxg-tattoos başlatılırken önceden kaydedilmiş dövmelerin eşitlenmesini sağlar; böylece multicharacter seçiminde de görünürler. Sunucunuz tabloları yeniden adlandırdıysa bu iki alanı güncelleyin. `qbx_core` kaynağını değiştirmeniz gerekmez.