# Talep Özel Alan Tanımları

https://dev.wisecp.com/tr/talep-ozel-alan-tanimlari

Talep formundaki özel alanların tanımını kuran ve değiştiren beş uç.

## Genel Bakış

Bu beş uç, müşterinin destek talebi açarken doldurduğu **ek form alanlarını** tanımlar. Alan tipi, zorunluluğu, sırası ve hangi departmanda görüneceği yapısal kayıtta; etiketi, açıklaması ve seçenek adları ise **dil başına** tutulur.

Buradaki kayıtlar **tanımlardır**, cevaplar değil. Müşterinin yazdığı değerler talebin kendi kaydında şifreli durur ve talep detayında görünür; bu uçlar onlara dokunmaz.

Yazma sözleşmesi alışılmışın dışında kalır: güncelleme, adına rağmen **tanımın tamamını** ister. Çeviriler ve seçenekler her dil için baştan kaydedilir.

## Referans

### Alanları Listeleme

get/api/v1/admin/tickets/custom-fields

`Tickets/GetTicketCustomFields` admin

Talep formundaki özel alanları sırasıyla döndürür.

Sorgu 2

department_idintDepartmana göre süzer. Sıfır, her departmana açık alanları verir.

statusstringEtkin ya da kapalı olanları süzer.

Dönen alanlar data[] — 8 + meta

idintAlanın numarası.

department_idintGörüneceği departman.

departmentstringDepartmanın adı. Tüm departmanlara açık alanda boş kalır.

statusstringAlan etkin mi.

rankintFormdaki sırası.

typestringAlanın tipi: `text`, `textarea`, `password`, `select`, `radio`, `checkbox`.

namestringAlanın etiketi. Yalnız panelin geçerli dilinde gelir.

requiredboolDoldurulması zorunlu mu.

totalintToplam alan sayısı. Meta altında döner.

Hatalar 2

invalid_status422Durum süzgeci tanınmıyor.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/tickets/custom-fields?status=active' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const url = new URL('https://panel.ornek.com/api/v1/admin/tickets/custom-fields');
url.searchParams.set('status', 'active');

const res  = await fetch(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tickets/custom-fields?' . http_build_query(['status' => 'active']));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Liste TEK DIL verir; tum cevirileri gormek icin alani tek tek okuyun.
$fields = Api::Tickets()->GetTicketCustomFields([], ['status' => 'active'])['data'];
```

### Alan Oluşturma

post/api/v1/admin/tickets/custom-fields

`Tickets/CreateTicketCustomField` admin her dil gerekir

Talep formuna yeni bir alan ekler ve çevirilerini yazar.

Gövde 7

typestringreqAlanın tipi: `text`, `textarea`, `password`, `select`, `radio`, `checkbox`.

department_idintAlanın görüneceği departman. Sıfır, tüm departmanlar demektir.

statusstringAlan etkin mi. Öntanımlı olarak etkin.

requiredboolMüşterinin doldurması zorunlu mu.

rankintFormdaki sırası. Sıfır, alanı sona ekler.

translationsobjectreqDil başına etiket ve açıklama. Etiket her etkin dilde gerekir.

optionsobjectDil başına seçenek etiketleri. Seçim tipli alanlarda gerekir ve etiketler diller arasında konuma göre eşleşir.

Dönen alanlar 201 — data + meta

dataobjectOluşan alan. Detay ucuyla aynı şekildedir.

created_idintYeni alanın numarası. Meta altında döner.

Hatalar 6

invalid_type422Alan tipi tanınmıyor.

name_required422Etkin dillerden birinde etiket eksik.

option_label_required422Bir seçenek satırı bir dilde dolu, başka dilde boş.

options_required422Seçim tipli alanın hiç seçeneği yok.

vetoed422Bir kanca kaydı reddetti.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tickets/custom-fields' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"select","required":true,"translations":{"tr":{"name":"Sunucu bolgesi"}},"options":{"tr":["Avrupa","Kuzey Amerika"]}}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tickets/custom-fields', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'select',
    required: true,
    translations: { en: { name: 'Server location', description: '' } },
    options: { en: ['Europe', 'North America'] },
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tickets/custom-fields');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'type'         => 'select',
        'required'     => true,
        'translations' => ['en' => ['name' => 'Server location', 'description' => '']],
        'options'      => ['en' => ['Europe', 'North America']],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Seceneklerin SIRASI kimliktir: her dilde ayni siraya ayni secenegi yazin.
Api::Tickets()->CreateTicketCustomField([
    'type'         => 'select',
    'translations' => [
        'en' => ['name' => 'Server location'],
        'tr' => ['name' => 'Sunucu bolgesi'],
    ],
    'options' => [
        'en' => ['Europe', 'North America'],
        'tr' => ['Avrupa', 'Kuzey Amerika'],
    ],
]);
```

### Alan Detayı

get/api/v1/admin/tickets/custom-fields/{fid}

`Tickets/GetTicketCustomField` admin

Bir alanı bütün çevirileriyle döndürür.

Dönen alanlar data — 8

idintAlanın numarası.

department_idintGörüneceği departman.

statusstringAlan etkin mi.

rankintFormdaki sırası.

typestringAlanın tipi: `text`, `textarea`, `password`, `select`, `radio`, `checkbox`.

requiredboolDoldurulması zorunlu mu.

has_optionsboolSeçenekli bir tip mi.

translationsobjectDil başına etiket, açıklama ve seçenekler. Seçenekler kendi numaraları ve adlarıyla gelir.

Hatalar 2

not_found404Alan bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/tickets/custom-fields/4' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch(`https://panel.ornek.com/api/v1/admin/tickets/custom-fields/${fid}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tickets/custom-fields/' . $fid);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Guncellemeden ONCE burayi okuyun: yazma cagrisi tanimin TAMAMINI ister.
$field = Api::Tickets()->GetTicketCustomField(['fid' => $fid])['data'];
```

### Alanı Güncelleme

patch/api/v1/admin/tickets/custom-fields/{fid}

`Tickets/UpdateTicketCustomField` admin tam tanım ister

Alanın tanımını yeniden yazar.

Gövde 7

typestringreqAlanın tipi: `text`, `textarea`, `password`, `select`, `radio`, `checkbox`.

department_idintAlanın görüneceği departman. Sıfır, tüm departmanlar demektir.

statusstringAlan etkin mi. Öntanımlı olarak etkin.

requiredboolMüşterinin doldurması zorunlu mu.

rankintFormdaki sırası. Sıfır, alanı sona ekler.

translationsobjectreqDil başına etiket ve açıklama. Etiket her etkin dilde gerekir.

optionsobjectDil başına seçenek etiketleri. Seçim tipli alanlarda gerekir ve etiketler diller arasında konuma göre eşleşir.

Dönen alanlar data — 8

dataobjectGüncel alan. Detay ucuyla aynı şekildedir.

Hatalar 6

not_found404Alan bulunamadı.

invalid_type422Alan tipi tanınmıyor.

name_required422Etkin dillerden birinde etiket eksik.

option_label_required422Bir seçenek satırı bir dilde dolu, başka dilde boş.

options_required422Seçim tipli alanın hiç seçeneği yok.

vetoed422Bir kanca kaydı reddetti.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X PATCH 'https://panel.ornek.com/api/v1/admin/tickets/custom-fields/4' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"select","status":"inactive","translations":{"tr":{"name":"Sunucu bolgesi"}},"options":{"tr":["AB","ABD","Asya"]}}'
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/tickets/custom-fields/${fid}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'select',
    status: 'inactive',
    translations: { en: { name: 'Server region', description: '' } },
    options: { en: ['EU', 'US', 'Asia'] },
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tickets/custom-fields/' . $fid);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'type'         => 'select',
        'status'       => 'inactive',
        'translations' => ['en' => ['name' => 'Server region', 'description' => '']],
        'options'      => ['en' => ['EU', 'US', 'Asia']],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Tek bir bayragi degistirmek icin bile TUM tanimi gonderin; eksik birakilan silinir.
$cur = Api::Tickets()->GetTicketCustomField(['fid' => $fid])['data'];
$cur['fid']    = $fid;
$cur['status'] = 'inactive';

Api::Tickets()->UpdateTicketCustomField($cur);
```

### Alanı Silme

delete/api/v1/admin/tickets/custom-fields/{fid}

`Tickets/DeleteTicketCustomField` admin

Alanı ve bütün dil kayıtlarını kaldırır.

Dönen alanlar data — 2

deletedboolSilme çalıştı mı.

idintSilinen alanın numarası.

Hatalar 3

not_found404Alan bulunamadı.

vetoed422Bir kanca silmeyi reddetti.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/tickets/custom-fields/4' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/tickets/custom-fields/${fid}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tickets/custom-fields/' . $fid);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Formdan kaldirmak icin silmek yerine KAPATIN: eski yanitlar etiketini boyle korur.
Api::Tickets()->UpdateTicketCustomField($cur + ['status' => 'inactive']);
```

## Tuzaklar

> **Güncelleme kısmi değildir**
> 
> Yöntem adı kısmi güncelleme ima etse de gövde **tanımın tamamıdır**. Çeviriler ve seçenekler her dil için yeniden yazılır, yani göndermediğiniz dil ya da seçenek düşer. Tek bir anahtarı değiştirecekseniz önce detayı okuyun, üzerinde değişikliği yapın ve tümünü geri gönderin.

> **Seçenekler konuma göre eşleşir**
> 
> Bir seçeneği **listedeki sırası** tanımlar: her dildeki birinci etiket aynı seçeneği anlatır. Bir dilde sıralamayı değiştirmek, o dilde başka bir seçeneğe başka bir ad vermek demektir ve uyarı çıkmaz. Bir satır bir dilde dolu, başka dilde boşsa kayıt reddedilir.

> **Etiket her etkin dilde gerekir**
> 
> Kayıt, kurulumdaki **her etkin dilde** bir etiket bekler. Yalnız kendi dilinizi gönderen bir betik, kuruluma ikinci bir dil eklendiği gün çalışmayı bırakır. Diller değişebildiği için listeyi koda gömmek yerine ayarlardan okuyun.

> **İki sıfır, iki ayrı anlam**
> 
> Departman alanındaki sıfır **tüm departmanlar** demektir; alan her talep formunda çıkar. Sıra alanındaki sıfır ise "başa koy" değil **sona ekle** anlamına gelir. İkisini karıştırmak, herkese görünen ve listenin dibinde duran bir alan üretir.

> **Tanımı silmek verilmiş cevapları silmez**
> 
> Silme yalnız tanımı ve çevirilerini kaldırır. Müşterilerin daha önce doldurduğu değerler taleplerin kendi kayıtlarında **kalmaya devam eder**, ama artık onları adlandıracak bir etiket yoktur. Alanı formdan çekmek istiyorsanız silmek yerine kapatın: geçmiş talepler böyle okunur kalır.

## İlgili Makaleler

- [Talep Yönetimi](https://dev.wisecp.com/tr/talep-yonetimi)
- [Talep Referans Listeleri](https://dev.wisecp.com/tr/talep-referans-listeleri)
- [Dahili Notlar ve Gizli Bilgiler](https://dev.wisecp.com/tr/dahili-notlar-ve-gizli-bilgiler)