# Yardım Makaleleri

https://dev.wisecp.com/tr/yardim-makaleleri

Yardım makalelerini yazan, okuyan, güncelleyen ve kaldıran beş uç.

## Genel Bakış

Yardım makalesi iki katmanda yaşar: **yapısal veri** (kategori, durum, görünürlük, sıra) ve **dil başına içerik** (başlık, adres parçası, gövde, etiketler, arama motoru alanları).

Başlık her etkin dilde zorunludur. Adres parçası ise isteğe bağlıdır ve boş bırakılırsa başlıktan türetilir; benzersizliği **dil başına** denetlenir.

Güncelleme adı düzeltme çağrıştırsa da davranışı tam yazımdır: çeviri seti her dil için yeniden kaydedilir. Bu yüzden değişiklik yapmadan önce mevcut hâli okumak gerekir.

## Referans

### Makaleleri Listeleme

get/api/v1/admin/knowledgebase/articles

`Knowledgebase/GetKnowledgebaseArticles` admin

Yardım makalelerini okunma ve oy sayılarıyla döndürür.

Sorgu 3

searchstringNumara, başlık ve etiketlerde arar.

pageintKaçıncı sayfa.

limitintSayfa başına kayıt. En çok 100.

Dönen alanlar data[] — 10 + meta — 3

idintMakalenin numarası.

titlestringBaşlık. Panelin geçerli dilinde gelir.

routestringAdres parçası.

categorystringKategorinin adı.

statusstringYayında mı taslak mı.

privateboolYalnız giriş yapmış müşterilere mi görünür.

viewsintKaç kez okundu.

usefulintFaydalı oyu.

uselessintFaydasız oyu.

created_atstringYazıldığı an.

totalintToplam makale. Meta altında döner.

pageintBulunulan sayfa.

limitintSayfa boyutu.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

```bash
curl 'https://panel.ornek.com/api/v1/admin/knowledgebase/articles?search=password' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/knowledgebase/articles', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
const poor = data.filter((a) => a.useless > a.useful);
```

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

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

```php
// Baslik TEK dilde gelir; ceviri karsilastirmasi icin detayi okumak gerekir.
$rows = Api::Knowledgebase()->GetKnowledgebaseArticles()['data'];
$weak = array_filter($rows, fn ($a) => $a['useless'] > $a['useful']);
```

### Makale Yazma

post/api/v1/admin/knowledgebase/articles

`Knowledgebase/CreateKnowledgebaseArticle` admin her dil gerekir

Yeni bir yardım makalesi açar.

Gövde 6

translationsobjectreq translations.Dil başına içerik. Her etkin dilde başlık gerekir.

titlestringMakale başlığı. Her etkin dilde gerekir.

routestringAdres parçası. Boş bırakılırsa başlıktan türetilir.

contentstringMakale gövdesi. İşaretleme kabul eder.

tagsstringEtiketler.

seo_titlestringArama motoru başlığı.

seo_keywordsstringArama motoru anahtar kelimeleri.

seo_descriptionstringArama motoru açıklaması.

category_idintBağlı kategorinin numarası. Sıfır kategorisiz demektir.

statusstringYayında mı taslak mı.

privateboolYalnız giriş yapmış müşterilere görünsün mü.

sidebarboolYan sütun görünsün mü.

rankintListedeki sırası.

Dönen alanlar 201 — data — 11

dataobjectOluşan makale. Okuma ucuyla aynı şekildedir; yeni numara meta altında da gelir.

Hatalar 4

title_required422Etkin dillerden birinde başlık eksik.

route_in_use422Adres parçası o dilde başka bir makalede kullanılıyor.

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/knowledgebase/articles' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"category_id":3,"translations":{"en":{"title":"How to reset your password","content":"<p>Open the account page.</p>"}}}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/knowledgebase/articles', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    category_id: 3,
    status: 'published',
    translations: {
      en: { title: 'How to reset your password', route: 'reset-password', content: html },
    },
  }),
});

const { data, meta } = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/knowledgebase/articles');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'category_id'  => 3,
        'translations' => ['en' => ['title' => $title, 'content' => $html]],
    ]),
]);

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

```php
// HER etkin dilde baslik ister; eksik dil tum cagriyi reddeder, kismi kayit olmaz.
$langs = array_column(Api::Reference()->GetLanguages()['data'], 'code');
foreach ($langs as $l) $t[$l] = ['title' => $titles[$l] ?? $titles['en']];

Api::Knowledgebase()->CreateKnowledgebaseArticle(['translations' => $t]);
```

### Makaleyi Okuma

get/api/v1/admin/knowledgebase/articles/{id}

`Knowledgebase/GetKnowledgebaseArticle` admin

Makaleyi bütün dilleriyle döndürür.

Dönen alanlar data — 11

idintMakalenin numarası.

category_idintBağlı kategorinin numarası.

statusstringYayında mı taslak mı.

privateboolYalnız giriş yapmış müşterilere mi görünür.

sidebarboolYan sütun görünür mü.

rankintListedeki sırası.

viewsintKaç kez okundu.

usefulintFaydalı oyu.

uselessintFaydasız oyu.

created_atstringYazıldığı an.

translationsobject translations.Dil başına içerik.

titlestringMakale başlığı. Her etkin dilde gerekir.

routestringAdres parçası. Boş bırakılırsa başlıktan türetilir.

contentstringMakale gövdesi. İşaretleme kabul eder.

tagsstringEtiketler.

seo_titlestringArama motoru başlığı.

seo_keywordsstringArama motoru anahtar kelimeleri.

seo_descriptionstringArama motoru açıklaması.

Hatalar 2

not_found404Makale bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

```bash
curl 'https://panel.ornek.com/api/v1/admin/knowledgebase/articles/12' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/knowledgebase/articles/${id}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
const missing = langs.filter((l) => ! data.translations[l]?.content);
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/knowledgebase/articles/' . $id);
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 buradan okuyun: guncelleme ceviri setinin TAMAMINI yeniden yazar.
$a = Api::Knowledgebase()->GetKnowledgebaseArticle(['id' => $id])['data'];
$a['translations']['en']['content'] = $newHtml;
```

### Makaleyi Güncelleme

patch/api/v1/admin/knowledgebase/articles/{id}

`Knowledgebase/UpdateKnowledgebaseArticle` admin tam yazım

Makalenin tamamını yeniden yazar.

Gövde 6

translationsobjectreq translations.Dil başına içerik. Set yeniden yazılır; göndermediğiniz dil kaybolur.

titlestringMakale başlığı. Her etkin dilde gerekir.

routestringAdres parçası. Boş bırakılırsa başlıktan türetilir.

contentstringMakale gövdesi. İşaretleme kabul eder.

tagsstringEtiketler.

seo_titlestringArama motoru başlığı.

seo_keywordsstringArama motoru anahtar kelimeleri.

seo_descriptionstringArama motoru açıklaması.

category_idintBağlı kategorinin numarası. Sıfır kategorisiz demektir.

statusstringYayında mı taslak mı.

privateboolYalnız giriş yapmış müşterilere görünsün mü.

sidebarboolYan sütun görünsün mü.

rankintListedeki sırası.

Dönen alanlar data — 11

dataobjectGüncel makale. Okuma ucuyla aynı şekildedir.

Hatalar 5

not_found404Makale bulunamadı.

title_required422Etkin dillerden birinde başlık eksik.

route_in_use422Adres parçası o dilde başka bir makalede kullanılıyor.

vetoed422Bir kanca kaydı reddetti.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

```bash
curl -X PATCH 'https://panel.ornek.com/api/v1/admin/knowledgebase/articles/12' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"draft","translations":{"en":{"title":"How to reset your password","content":"<p>Updated steps.</p>"}}}'
```

```javascript
const cur = await fetch(`https://panel.ornek.com/api/v1/admin/knowledgebase/articles/${id}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
}).then((r) => r.json());

cur.data.translations.en.content = html;

const res = await fetch(`https://panel.ornek.com/api/v1/admin/knowledgebase/articles/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(cur.data),
});
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/knowledgebase/articles/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($article),
]);

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

```php
// Adi PATCH ama davranisi TAM YAZIM: ceviriler her dil icin yeniden kaydedilir.
$a = Api::Knowledgebase()->GetKnowledgebaseArticle(['id' => $id])['data'];
$a['translations']['en']['content'] = $newHtml;

Api::Knowledgebase()->UpdateKnowledgebaseArticle($a + ['id' => $id]);
```

### Makaleyi Silme

delete/api/v1/admin/knowledgebase/articles/{id}

`Knowledgebase/DeleteKnowledgebaseArticle` admin

Makaleyi, bütün çevirilerini ve başlık görselini siler.

Dönen alanlar data — 2

deletedboolSilme çalıştı mı.

idintSilinen makalenin numarası.

Hatalar 3

not_found404Makale 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/knowledgebase/articles/12' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/knowledgebase/articles/${id}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/knowledgebase/articles/' . $id);
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
// Adres parcasi da gider: o adrese gelen eski baglantilar bulunamadi sayfasina duser.
Api::Knowledgebase()->UpdateKnowledgebaseArticle(['id' => $id, 'status' => 'draft'] + $article);
// silmek yerine taslaga cekmek baglantiyi korur
```

## Tuzaklar

> **Güncelleme çeviri setini yeniden yazar**
> 
> Güncelleme gövdesi **makalenin tamamıdır**. Yalnız bir dili gönderirseniz diğer dillerin içeriği yeniden kaydedilmez ve kaybolur. Önce okuma ucundan tam seti alın, üzerinde değişikliği yapın, sonra tümünü geri gönderin.

> **Eksik dil kaydı tümüyle durdurur**
> 
> Başlık her etkin dilde gerekir; biri eksikse çağrı `422` döner ve **hiçbir dil kaydedilmez**. Yeni bir dil kurulduğunda var olan makaleler o dilde başlıksızdır, yani ilk düzenlemede bu hata karşınıza çıkar. Dil listesini başvuru ucundan alıp gövdeyi ona göre kurun.

> **Adres parçası dil başına benzersizdir**
> 
> Aynı adres parçasını iki makalede kullanmak `route_in_use` verir, ama bu denetim **dil başınadır**: aynı parça İngilizcede dolu, Türkçede boş olabilir. Toplu içe aktarmada çakışma tek bir dilde çıkar ve tüm kaydı durdurur.

> **Gizli makale gizli değil, üyeye özeldir**
> 
> Gizlilik alanı makaleyi **giriş yapmış müşterilere** sınırlar; yönetim panelinde ve arama sonuçlarında görünmeye devam eder. Bir içeriği tümüyle kaldırmak istiyorsanız durumu taslağa çekin.

> **Silmek eski bağlantıları kırar**
> 
> Makale silindiğinde adres parçası da gider ve o adrese gelen dış bağlantılar bulunamadı sayfasına düşer. Arama motorunda yer etmiş bir makaleyi silmek yerine **taslağa çekmek** çoğu zaman daha iyidir; içerik gizlenir, adres yerinde kalır.

## İlgili Makaleler

- [Yardım Kategorileri](https://dev.wisecp.com/tr/yardim-kategorileri)
- [Başvuru Listeleri](https://dev.wisecp.com/tr/basvuru-listeleri)