TurkPII Engine Referansı | REST Dokümantasyonu

KURULUM

Tek konteyner, tek anahtar.

Engine müşterinin ağında çalışır. Lisans anahtarı konteyner başlangıcında okunur; istek başına ayrı kimlik doğrulama yoktur.

docker

docker run --rm \
  -e LICENSE_KEY="<lisans-anahtarı>" \
  -p 8080:8080 \
  bahadorr/turkpii:1.1.1

# konteyner açıldıktan sonra
curl http://localhost:8080/health

# { "status": "ok", "version": "1.1.1" }

Başlangıç değişkenleri

Değişken	Zorunlu	Ne yapar
`LICENSE_KEY`	Evet	Lisans konteyner başlangıcında doğrulanır. Anahtar eksik veya geçersizse konteyner açılmaz; bu bir HTTP hatası değildir.
`8080` (port)	Evet	REST arayüzü konteyner içinde 8080 portunu dinler. Örnekler bu portu kullanır.

Çevrimiçi aktivasyon, zorunlu dış bağlantı ve bulut taraması yoktur. Lisans çevrimdışı doğrulanır; değerlendirme lisansında süre ve istek limitleri bulunur.

Anahtarı verinLICENSE_KEY ile konteyner başlar; geçersiz anahtar başlangıçta durur.
Sağlığı kontrol edinGET /health çalışan sürümü döner.
İlk isteği gönderinPOST /mask metni ve ayarları JSON olarak alır.

GENEL BAKIŞ

Dört uç nokta.

İstek ve yanıt gövdeleri JSON'dur. Metin, çalışma zamanınızdan çıkmadan maskelenir.

POST/mask

Metindeki PII'yi maskeler; maskelenmiş metni, token haritasını ve tespitleri döner.

POST/unmask

Token haritasıyla maskelenmiş metni geri açar. Geri dönüş yalnız pseudonymize modunda mümkündür.

GET/health

Servis ayakta mı ve hangi sürüm çalışıyor? Gövde yok, yanıt iki alan.

GET/license/info

Lisans durumu, süre, açık özellikler, limitler ve runtime modu.

Ortak kurallar

Base URL örnektir. Belgelerde http://localhost:8080 kullanılır; kendi ağınızda servis adı farklı olabilir.
Kimlik doğrulama başlangıçta. LICENSE_KEY konteyner açılışında doğrulanır; her istekte anahtar başlığı taşınmaz.
UTF-8 ve byte ofseti. start / end değerleri özgün metnin UTF-8 byte ofsetleridir.
Sürüm imajla gelir. /health yanıtındaki version çalışan imajın sürümünü gösterir; imaj etiketiyle aynı olmalıdır.
Örneklerde gerçek veri yok. Metin [metin], değerler {{TC_1}} gibi yer tutuculardır.

UÇ NOKTA 01

Metni maskele.

POST /mask

Metindeki kişisel veriyi bulur, kabul edilen tespitleri token veya anonim değerle değiştirir ve kararın ayrıntısını döner.

İstek alanları

Alan	Tip	Zorunlu	Açıklama
`text`	string	Evet	Taranacak metin.
`debug`	boolean	Hayır	`true` ise yanıta her aday için `explanations[]` eklenir.
`mask_policy`	enum	Hayır	Hangi adayların maskeleneceğini belirler. Varsayılan `valid_and_suspicious`.
`options.detect`	string[]	Hayır	İstenen PII tipleri. Karşılıklı dışlama kurallarına uyulmalıdır.
`options.ner`	boolean	Hayır	Lisans varsa Türkçe NER çalıştırılır. Gerçekte çalışıp çalışmadığı `summary.ner_enabled` ile döner.
`options.min_confidence`	number	Hayır	`0.0`–`1.0`. `0.0` güven eşiğini kapatır.
`options.mode`	enum	Hayır	`pseudonymize` (varsayılan) veya `anonymize`.

/mask isteği

curl -X POST http://localhost:8080/mask \
  -H "Content-Type: application/json" \
  -d '{
    "text": "[metin]",
    "options": {
      "detect": ["TC", "IBAN", "PHONE", "EMAIL"],
      "mode": "pseudonymize"
    }
  }'

import requests

res = requests.post(
    "http://localhost:8080/mask",
    json={
        "text": "[metin]",
        "options": {
            "detect": ["TC", "IBAN", "PHONE", "EMAIL"],
            "mode": "pseudonymize",
        },
    },
)
print(res.json()["masked"])

const res = await fetch("http://localhost:8080/mask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    text: "[metin]",
    options: {
      detect: ["TC", "IBAN", "PHONE", "EMAIL"],
      mode: "pseudonymize",
    },
  }),
});

const data = await res.json();
console.log(data.masked);

Maskeleme politikası

Değer	Kapsam
`valid_only`	Yalnız doğrulamayı geçen adaylar maskelenir. Şüpheli aday `detected` içinde kalır, metinde açık bırakılır.
`valid_and_suspicious`	Varsayılan. Doğrulanan ve şüpheli adaylar maskelenir; ikisi de token üretir.
`everything`	Tespit edilen tüm adaylar için daha geniş kapsam.
`all_structured_like`	Yapısal olarak PII'ye benzeyen adaylar için en geniş yapısal kapsam.
`compliance_strict`	Uyum odaklı sıkı kapsam; yanlış pozitif yerine kaçırmamayı tercih eder.

Politika neyin maskeleneceğini değiştirir, neyin listeleneceğini değiştirmez. detected dizisi her durumda tüm kabul edilen adayları taşır. Geniş kapsamlı üç politikayı üretim öncesi kendi metinlerinizle doğrulayın.

Yanıt

200 OK · /mask

{
  "masked": "{{NAME_1}}, TC: {{TC_1}}, tel: {{PHONE_1}}",
  "tokens": {
    "NAME_1": "[özgün değer]",
    "TC_1": "[özgün değer]",
    "PHONE_1": "[özgün değer]"
  },
  "detected": [
    {
      "type": "TC",
      "start": 19,
      "end": 30,
      "confidence": 0.7231,
      "source": "regex.tc",
      "validation_state": "suspicious",
      "reason": "checksum10_failed"
    }
  ],
  "summary": {
    "detected_context": "natural",
    "total_detected": 3,
    "by_type": { "NAME": 1, "PHONE": 1, "TC": 1 }
  }
}

Metin ve değerler yer tutucudur. Örnekte tokens anahtarları token adıdır; değer yayınlanmaz.

Yanıt alanları

Alan	Tip	Açıklama
`masked`	string	Kabul edilen tespitlerin `{{TOKEN}}` ile değiştirildiği metin.
`tokens`	object	`TOKEN → özgün değer`. Pseudonymize modunda döner; anonymize modunda bulunmaz.
`detected[]`	array	Kabul edilen her aday için tip, ofset, güven, kaynak, doğrulama durumu ve skor bileşenleri.
`summary`	object	İstenen tipler, NER durumu, algılanan bağlam, toplam ve tipe göre sayılar.
`explanations[]`	array	Yalnız `debug: true` ile döner. Her aday için karar hattı.

İki kural

KARŞILIKLI DIŞLAMA

NAME ile PERSON, AGE ile AGE_RANGE aynı istekte istenemez. İkisini birlikte göndermek 400 döner.

DEBUG

debug: true her aday için pipeline adımlarını ekler: eşleşme, aday sınırı, doğrulayıcı sonucu ve politika kararı.

explanations · debug

{
  "entity": "TC",
  "validation_state": "suspicious",
  "matched_by": "regex.tc",
  "masking_applied": false,
  "pipeline": [
    "regex.tc matched",
    "bounded candidate",
    "TCValidator suspicious: checksum10_failed",
    "mask policy skipped masking"
  ]
}

Lisans kapsamı darsa istek hata vermez; summary.unlicensed_types_skipped, summary.ner_requested_but_not_licensed ve context_downgraded_to alanları neyin atlandığını söyler.

UÇ NOKTA 02

Token ile geri aç.

POST /unmask

Maskelenmiş metni, /mask yanıtındaki token haritasıyla geri açar. Yalnız pseudonymize modunda anlamlıdır.

İstek alanları

Alan	Tip	Zorunlu	Açıklama
`masked`	string	Evet	`{{TOKEN}}` yer tutucularını içeren metin.
`tokens`	object	Hayır	`TOKEN → değer` haritası. Boş veya eksikse yer tutucular olduğu gibi kalır.

/unmask isteği

curl -X POST http://localhost:8080/unmask \
  -H "Content-Type: application/json" \
  -d '{
    "masked": "{{NAME_1}} toplantıya katıldı",
    "tokens": { "NAME_1": "[özgün değer]" }
  }'

{
  "masked": "{{NAME_1}} toplantıya katıldı",
  "tokens": {
    "NAME_1": "[özgün değer]"
  }
}

Yanıt

Alan	Tip	Açıklama
`text`	string	Yer tutucuların token değerleriyle değiştirildiği metin.

200 OK · /unmask

{ "text": "[özgün değer] toplantıya katıldı" }

Token haritası istemcide tutulur; Engine token saklamaz. Anonymize modunda harita üretilmediği için geri açma yapılamaz.

UÇ NOKTA 03

Sağlığı sor.

GET /health

Konteynerin ayakta olup olmadığını ve çalışan sürümü döner. Gövde ve parametre yoktur.

200 OK · /health

{ "status": "ok", "version": "1.1.1" }

Alan	Tip	Açıklama
`status`	string	Sağlıklı serviste `ok`.
`version`	string	Çalışan imajın sürümü. Örnek `1.1.1`; imaj etiketiyle eşleşmelidir.

Eski referanstaki 1.0.2 örneği güncel değildir. Bu sayfa imaj etiketiyle aynı sürümü kullanır; kendi kurulumunuzda /health yanıtını doğrulayın.

UÇ NOKTA 04

Lisansı oku.

GET /license/info

Lisans süresi, tier, açık özellikler, limitler ve runtime modu. Ham lisans anahtarı yanıtta dönmez.

200 OK · /license/info

{
  "customer_name": "[müşteri adı]",
  "tier": "evaluation",
  "status": "valid",
  "expires_at": "2026-08-12T00:00:00Z",
  "days_remaining": 30,
  "features": {
    "contexts": ["natural", "json", "xml", "sql", "logfmt", "markdown",
                 "csv", "ocr", "chat", "yaml"],
    "ner": true,
    "ocr": true,
    "anonymize": true,
    "pseudonymize": true
  },
  "limits": { "max_req_per_sec": 25, "max_req_per_day": 50000 },
  "runtime": { "mode": "cpu", "ner_available": true }
}

Değerlendirme lisansı örneğidir. Süre, limit ve tier lisans dosyasından gelir.

Alan	Tip	Açıklama
`customer_name`	string	Lisanslı müşteri adı.
`tier`	string	`evaluation`, `starter`, `professional`, `enterprise`.
`status`	string	`valid`; süre 30 günün altına indiğinde `expiring_soon`.
`expires_at` · `days_remaining`	string · number	RFC 3339 bitiş zamanı ve kalan tam gün.
`features.*`	array · boolean	Lisanslı bağlamlar, tipler ve `ner`, `ocr`, `anonymize`, `pseudonymize` bayrakları.
`limits.max_req_per_sec`	number	Saniye başına istek limiti.
`limits.max_req_per_day`	number · null	Günlük limit; `null` ise günlük sınır yok.
`runtime.mode` · `runtime.ner_available`	string · boolean	Genel sürümde `cpu`; NER modeli yüklü mü.

HATALAR

Ne zaman durur, ne zaman devam eder?

Lisans hatası konteyneri başlatmaz. İstek hataları JSON gövdesiyle 400 döner.

BAŞLANGIÇ

Lisans anahtarı yok veya geçersiz

HTTP hatası değildir; konteyner çıkar ve loglar. Uygulama ayağa kalkmaz, istek kabul edilmez.

400

Bozuk istek gövdesi

/mask ve /unmask için geçersiz JSON veya zorunlu alan eksikliği.

400

Bilinmeyen PII tipi

options.detect içinde tanımsız bir tip adı. Yanıt geçerli tiplerin listesini döner.

konteyner logu · lisans yok

{"time":"2026-07-05T14:24:18Z","level":"ERROR","msg":"application init failed",
 "error":"[LICENSE] invalid license: LICENSE_KEY is required"}

400 · bilinmeyen tip

{
  "error": "unknown PII type: NATIONAL_ID",
  "valid_types": ["TC", "IBAN", "CREDIT_CARD", "PASSPORT", "VIN", "IP", "PORT",
                  "PHONE", "EMAIL", "NAME", "PERSON", "ADDRESS", "TAX", "PLATE",
                  "AGE", "AGE_RANGE"]
}

401, 403, 429 ve 5xx yanıtları önceki referansta belgelenmemiştir. Lisans limitleri sert hata yerine yumuşak daralma ile bildirilir; farklı bir durum görürseniz yayın öncesi servis ekibiyle doğrulayın.

SÜRÜM NOTLARI

1.1.1 · CPU runtime.

Bu referans, bahadorr/turkpii:1.1.1 imajındaki davranışı temel alır.

v1.1.1 CPU runtime · güncel

16 PII tipi: TC, TAX, IBAN, CREDIT_CARD, PLATE, PASSPORT, PHONE, EMAIL, NAME, PERSON, ADDRESS, VIN, IP, PORT, AGE, AGE_RANGE.
İki mod: pseudonymize ve anonymize.
On metin bağlamı: natural, json, xml, sql, logfmt, markdown, csv, ocr, chat, yaml.
/health yanıtındaki sürüm artık imaj etiketiyle aynı kaynaktan gelir.
Karşılıklı dışlama ve lisans daralması alanları örneklerde açıkça gösterilir.

Makine okunur OpenAPI/JSON Schema bu sürümde yayımlanmıyor. Alan tabloları ve örnekler API'nin gözlenen çıktısından türetilmiştir; entegrasyon öncesi kendi kurulumunuzda doğrulayın.

Başa dön