# Yalnız maskeleme

Siper /mask ucunun doğrudan kullanımı. Dönüşüm seçenekleri, toplu istek, kategori filtreleme ve desen listeleri.

Maskelemeyi dil modeli olmadan, kendi akışınızın bir adımı olarak da kullanabilirsiniz. `/mask` ucu metni alır; maskeli metinle birlikte hangi aralıkta ne bulunduğunu gösteren bir tespit raporu döndürür.

Diyagram: girdi metni /mask uç noktasına gider; yanıt maskeli metin ve tespit raporunu birlikte döner.

İstekleri, panelden ürettiğiniz sanal anahtarla `Authorization: Bearer` başlığında yetkilendirirsiniz; Gateway çağrılarında kullandığınız anahtarın aynısıdır. `/mask` çağrıları da istek limitlerine ve denetim izine tabidir.

Gövde hataları (eksik veya bozuk istek) ve kimlik hataları Gateway’in hata biçimiyle döner; alan doğrulama ayrıntıları ise maskeleme servisinin kendi biçimiyle gelebilir.

## İlk çağrı

```bash
curl https://gw-tr.gurubase.io/mask \
  -H "Authorization: Bearer $SANAL_ANAHTAR" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ahmet Yılmaz, TCKN 10000000382, İstanbul'\''da yaşıyor."}'
```

```json
{
  "masked_text": "<PERSON_1>, TCKN <TCKN_1>, İstanbul'da yaşıyor.",
  "transform": "placeholder",
  "spans": [
    { "category": "person", "start": 0, "end": 12, "score": 0.85 },
    { "category": "tckn", "start": 19, "end": 30, "score": 1.0 }
  ],
  "timings_ms": { "total": 27.58 }
}
```

`masked_text` maskeli metindir; doğrudan maskeleme uçlarında yer tutucular ham kategori adlarını kullanır ([Kavramlar](/docs/concepts/)). `spans` listesi her tespit için kategoriyi, girdi metnindeki karakter aralığını (`start`, `end`) ve güven puanını (`score`) verir. `timings_ms.total` toplam işleme süresidir.

## Dönüşüm seçenekleri

`transform` alanı maskeli metnin biçimini belirler; varsayılan `placeholder`.

| Değer | Davranış |
| --- | --- |
| `placeholder` | Değeri `<PERSON_1>` gibi numaralı bir yer tutucuyla değiştirir; hangi kategoriden kaç değer geçtiği görünür kalır. |
| `mask` | Karakterleri dolgu karakteriyle örter; uzunluk korunur. Dolgu karakterini `mask_char` ile seçersiniz, varsayılan `#`. |

## Toplu istek

Birden çok metni `/mask/batch` ucuna tek istekte gönderirsiniz; `results` dizisi girdiyle aynı sırada döner. Uzunluk sınırını aşan metin için `/mask` 413 döndürür. `/mask/batch`’te bu sınır, birleştirilmiş toplam metin üzerinden uygulanır.

```bash
curl https://gw-tr.gurubase.io/mask/batch \
  -H "Authorization: Bearer $SANAL_ANAHTAR" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "Ahmet Yılmaz aradı.",
      "IBAN: TR12 0001 0000 0000 0000 0000 01"
    ]
  }'
```

## Kategori filtreleme

Varsayılan davranış 26 kategorinin tamamını maskelemektir. `categories` alanıyla kapsamı daraltırsınız: bir `preset` seçersiniz, gerekirse `enable` listesi kümeye kategori ekler, `disable` çıkarır. Kategori anahtarları, rapordaki `category` değerleriyle aynıdır (`person`, `tckn`, `saglik` gibi).

| Preset | Kapsam |
| --- | --- |
| `ALL` | Tüm kategoriler; varsayılan davranışla aynı. |
| `KVKK` | Tüm KVKK kapsamı; `ALL` ile aynı küme. |
| `KVKK_SENSITIVE` | Yalnız m.6 özel nitelikli dokuz kategori. |
| `IDENTITY` | Yalnız kişi ve adres. |
| `IDENTIFIERS` | Yalnız numara ve kod türü tanımlayıcılar (TCKN, IBAN, telefon gibi). |

```json
{
  "text": "...",
  "categories": { "preset": "KVKK_SENSITIVE" }
}
```

Kategorilerin tam listesi ve m.6 ayrımı için [Kategoriler](/docs/categories/).

## Desen listeleri

İki liste alanıyla maskeleme kararına kendi kurallarınızı eklersiniz. İkisi de düzenli ifade (regular expression, Python `re` sözdizimi) listesi alır; geçersiz bir desen 422 döndürür.

- `allow_patterns`: tespit edilen bir alanın yüzey metni desenle eşleşiyorsa o alan maskelenmez. Kişisel veri olmayan sabit değerler için kullanışlıdır; örneğin ortak destek adresinizin veya kurum adınızın maskelenmesini istemezsiniz.
- `block_patterns`: desenle eşleşen her metin parçası, model tespit etmemiş olsa bile maskelenir. Kuruma özgü sicil, dosya veya müşteri numarası biçimlerini garantiye almak için. Düz dize verirseniz kategori `custom` olur; `{"pattern": ..., "category": ...}` nesnesiyle kategori atarsınız. Mevcut bir tespitle çakışan eşleşme atlanır; tespit kazanır.

```json
{
  "text": "...",
  "allow_patterns": ["destek@kurum\\.example", "\\bDemo Kurum\\b"],
  "block_patterns": [
    "\\bMST-\\d{6}\\b",
    { "pattern": "\\bSICIL-\\d{6}\\b", "category": "custom" }
  ]
}
```

Yer tutucu biçimi ve dil ayrımı için [Kavramlar](/docs/concepts/). Aynı maskelemeyi sohbet akışının içinde kullanmak için [Gateway entegrasyonu](/docs/guides/gateway-integration/).