Yaptırım Taraması API

Bir kişiyi, kurumu, kripto cüzdanını, banka hesabını ya da işlemi yaptırım, PEP ve diğer risk listelerine karşı tarar. Karar döndürmez; eşleşme döndürür — ne yapacağınıza siz karar verirsiniz.

Kararı Lunixi vermez, siz verirsiniz: tarama ucu eşleşme listesi ve skor döner, "blokla" demez. Eşik (threshold) ve eşleşme tipine göre ne yapacağınız sizin politikanızdır — bu ayrım denetimde de böyle savunulur.

Kimlik doğrulama

Tarama uçları kısa ömürlü bir erişim jetonu ister. Jetonu Ed25519 imzasıyla alırsınız:

POST https://api-gateway.lunixi.com/api/v1/auth/token

Header	Zorunlu	Açıklama
`X-Key-Id`	✅	Açık anahtar kimliğiniz (kid)
`X-Signature`	✅	Ed25519 imzası (Base64)
`X-Date`	✅	ISO-8601 istek zamanı
`X-Nonce`	✅	Tekil istek nonce'u
`Digest`	—	Gövdenin SHA-256 özeti (Base64); gövde varsa zorunlu

Dönen jetonu tarama çağrılarında Authorization: Bearer … olarak gönderin.

⚠️

Anahtarınızın sanction:view_results yetkisi olmalıdır; yetkisiz anahtarla alınan jeton tarama uçlarında reddedilir. Kanonik imza string'i ve hata kodları: Kimlik Doğrulama.

Tarama uçları

Dört özne tipi, dört ayrı uç:

POST /api/v1/sanction/screening/name          # kişi veya kurum
POST /api/v1/sanction/screening/wallet        # kripto cüzdan adresi
POST /api/v1/sanction/screening/account       # banka hesabı / IBAN
POST /api/v1/sanction/screening/transaction   # işlem (taraflarıyla birlikte)

İsim, cüzdan ve işlem taramaları ile kamu ihale yasağı taraması aktif liste yayınına karşı yapılır: her tarama, o an yürürlükte olan yayını sabitler ve yanıtta hangi yayını okuduğunu söyler. Liste yayınının ne olduğu: Yaptırım Taraması.

İsim taraması gövdesi

Alan	Tip	Zorunlu	Açıklama
`name`	string	✅	Taranacak ad
`subjectType`	string	—	`person` \| `organization`
`country`	string	—	ISO 3166-1 alpha-2
`dateOfBirth`	string	—	ISO-8601; kişi taramasında yanlış-pozitifi ciddi düşürür
`identifiers`	array	—	Kimlik numarası, vergi no, pasaport gibi tekilleştiriciler
`riskDomains`	string[]	—	Taramayı bu risk alanlarıyla sınırlar: `sanctions`, `pep`, `rca`, `wanted`, `regulatory`, `debarment`, `ownership`, `vessel`, `securities`. Gönderilmezse bütün risk alanları taranır
`mode`	string	—	`sanctions_only` \| `sanctions_pep` \| `full_risk` — hazır bir risk alanı kümesi (bkz. AML Taraması). `riskDomains` ile birlikte verilirse ikisinin kesişimi taranır
`threshold`	number	—	Eşleşme skoru alt sınırı
`customerReference`	string	—	Kendi kayıt kimliğiniz (denetim izine yazılır)

curl -X POST "https://api-gateway.lunixi.com/api/v1/sanction/screening/name" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mehmet Öz",
    "subjectType": "person",
    "country": "TR",
    "dateOfBirth": "1980-04-12",
    "riskDomains": ["sanctions", "pep", "rca"],
    "threshold": 0.85,
    "customerReference": "cust_84213"
  }'

⚠️

Bilinmeyen bir mode ya da risk alanı, veya mode ile riskDomains kesişiminin boş olması sanction.screening.scope_invalid (400) ile reddedilir. Geçersiz bir alan sessizce düşürülmez; düşürülseydi hiç taranmamış bir alan "eşleşme yok" gibi görünürdü.

Yanıt

Yanıt standart yanıt zarfı içinde döner; tarama alanları data altındadır.

{
  "status": "success",
  "code": "sanction.screen_name.completed",
  "message": "…",
  "data": {
    "latencyMs": 128,
    "screeningRequestId": "…",
    "publicationId": "…",
    "publicationRevision": 34,
    "coverageStatus": "COMPLETE",
    "evidenceRef": "…",
    "screenedRiskDomains": ["sanctions", "wanted", "regulatory", "debarment", "pep", "rca"],
    "uncoveredRiskDomains": [],
    "matches": [
      {
        "hitId": "…",
        "entityId": "…",
        "matchedName": "Mehmet Oz",
        "score": 0.91,
        "hitType": "probable",
        "listCode": "OFAC SDN",
        "sourceListName": "OFAC SDN",
        "recordType": "person",
        "riskDomains": ["sanctions"],
        "reason": "PROBABLE_MATCH",
        "explanationJson": "{…}",
        "lists": [
          {
            "datasetCode": "OFAC",
            "displayName": "OFAC SDN",
            "datasetKind": "SANCTIONS",
            "datasetVersionId": "…",
            "subLists": [],
            "programs": ["…"],
            "entityIds": ["…"],
            "listings": [
              { "subList": "", "label": "…", "program": "…", "reference": "…", "listedOn": "…" }
            ]
          },
          {
            "datasetCode": "UN",
            "displayName": "…",
            "datasetKind": "SANCTIONS",
            "datasetVersionId": "…",
            "subLists": [],
            "programs": ["…"],
            "entityIds": ["…"],
            "listings": []
          }
        ]
      }
    ],
    "datasetFreshnessJson": "{…}"
  },
  "statusCode": 200,
  "requestId": "…"
}

Alan	Anlamı
`matches`	Boş dizi, yalnız `status: "success"` iken temiz demektir — ve `coverageStatus` `COMPLETE` değilse yalnız taranan alanlar için. Ayrıntı: Tarama yapılamadığında
`score`	0–1 arası benzerlik; `threshold` altındakiler elenir
`hitType`	`exact` \| `probable` \| `possible`
`riskDomains`	Eşleşen kişi veya kurumun risk alanları (`sanctions`, `pep`, `wanted` …)
`lists`	Eşleşmenin yer aldığı her liste — liste kodu ve adı, okunan liste sürümü, program ve alt listeler, listeleme kayıtları (`listings`)
`sourceListName`	Eşleşmenin temsilci kaydının listesi. Bütün listeler için `lists` okunmalıdır
`screeningRequestId`	Taramanın kimliği; tarama geçmişinde ve rapor talebinde bu kimliği kullanın. Üst seviyedeki `requestId` HTTP isteğinin kimliğidir, taramanın değil
`publicationId` · `publicationRevision`	Taramanın okuduğu liste yayını ve yayının tarama anındaki revizyonu
`coverageStatus`	`COMPLETE` \| `PARTIAL` \| `DEGRADED` — aşağıda
`screenedRiskDomains`	Taranması istenen risk alanları
`uncoveredRiskDomains`	İstenen ama yayındaki hiçbir listenin kapsamadığı risk alanları
`evidenceRef`	Taramanın değiştirilemez kanıt kaydının kimliği; denetim ve itirazlarda bu kimliği kullanın
`datasetFreshnessJson`	Hangi tarihli veriye karşı tarandığı. Denetimde "PEP tarandı" beyanı tek başına savunulamaz

Birleşik eşleşme

Aynı kişi veya kurum birden çok listede yer alıyorsa tek eşleşme döner: skor, listelerin en yüksek skorudur ve kişinin yer aldığı listelerin tamamı lists içindedir. Aynı kişi için OFAC, BM ve AB'den üç ayrı satır almazsınız; tek satırda üç liste görürsünüz.

Aynı listedeki iki kayıt ise adları aynı olsa da ayrı eşleşmelerdir: bir yayıncının aynı adla listelediği iki kayıt iki ayrı kişi veya kurumdur.

Kapsam durumu

`coverageStatus`	Anlamı	Eşleşme yoksa
`COMPLETE`	İstenen bütün risk alanları tarandı	Temiz sonuç
`PARTIAL`	İstenen risk alanlarından en az biri için yayında liste yok; bu alanlar `uncoveredRiskDomains` içindedir	Yalnız taranan alanlar için temiz. `uncoveredRiskDomains` için temiz değildir
`DEGRADED`	Yazım farkı olan adları bulan aday araması kullanılamadı ya da çok yaygın bir ad nedeniyle aday penceresi doldu; benzer yazılmış adlar kaçmış olabilir	Tam bir tarama gibi değerlendirmeyin; taramayı yeniden çalıştırın

Liste yayınına geçişten önce yapılmış bir taramanın aynı idempotency anahtarıyla tekrarında publicationId, publicationRevision, coverageStatus ve evidenceRef null döner.

⚠️

datasetFreshnessJson boş dönerse tazelik manifestosu üretilememiş demektir. Bu durumda uyum beyanınızı muhafazakâr kurun — "şu tarihli listeye karşı tarandı" diyemezsiniz.

Tarama yapılamadığında

Aktif bir liste yayını sabitlenemezse tarama yapılmaz ve eski verilere geri düşülmez. Yanıt status: "failure" ve HTTP 503 ile döner:

Uç	`code`
İsim taraması	`sanction.screen_name.failed`
Cüzdan taraması	`sanction.wallet.failed`
İşlem taraması	`sanction.transaction.failed`
Kamu ihale yasağı taraması	`sanction.public_procurement.failed`

🚫

Başarısız bir tarama hiçbir koşulda "eşleşme yok" olarak değerlendirilmemelidir. Müşteri kaydını veya işlemi "taranmadı" durumunda bekletin; taramayı tekrarlayın ya da incelemeye alın. Boş matches listesi yalnız status: "success" iken anlam taşır.

Cüzdan taraması

POST /api/v1/sanction/screening/wallet

Alan	Tip	Zorunlu	Açıklama
`walletAddress`	string	✅	Taranacak adres
`chain`	string	—	Ağ (ör. `ethereum`, `bitcoin`, `tron`, `solana`)
`mode`	string	—	`wallet_sanctions` (varsayılan) \| `wallet_risk` \| `wallet_full_aml` — geniş modlar maruziyet ve kripto istihbaratı isabetlerini de ekler
`customerReference`	string	—	Kendi kayıt kimliğiniz

Adres, aktif yayındaki listelerde yer alan kripto cüzdan adresleriyle tam eşleşmeyle aranır; benzerlik araması yapılmaz. Harf büyüklüğü yalnız bilgi taşımadığı biçimlerde yok sayılır:

Adres biçimi	Karşılaştırma
EVM onaltılık (`0x…`)	Harf büyüklüğüne duyarsız
Önekli bech32 (`bc1…`, `ltc1…` vb.)	Harf büyüklüğüne duyarsız
Önekli CashAddr	Harf büyüklüğüne duyarsız
Diğerleri (ör. Bitcoin legacy, Tron, Solana)	Harf büyüklüğüne duyarlı — adresi verildiği gibi gönderin

Eşleşme ağ etiketine değil adrese göre yapılır: aynı EVM adresi farklı EVM ağlarında aynı adrestir. Listenin belirttiği ağ ayrıca listedChains alanında döner.

{
  "status": "success",
  "code": "sanction.wallet.completed",
  "data": {
    "address": "0x…",
    "chain": "ethereum",
    "isSanctioned": true,
    "riskScore": 100,
    "riskLevel": "…",
    "publicationId": "…",
    "publicationRevision": 34,
    "coverageStatus": "COMPLETE",
    "evidenceRef": "…",
    "publicationHits": [
      {
        "hitId": "…",
        "entityId": "…",
        "entityName": "…",
        "entityType": "ORGANIZATION",
        "hitType": "exact",
        "score": 100,
        "riskCategory": "sanctions",
        "riskDomains": ["sanctions"],
        "sourceListName": "OFAC SDN",
        "lists": [ { "datasetCode": "OFAC", "displayName": "OFAC SDN", "…": "…" } ],
        "listedAddress": "0x…",
        "listedChains": ["ETH"],
        "caseRule": "EVM_HEX"
      }
    ],
    "hits": []
  },
  "statusCode": 200
}

Alan	Anlamı
`publicationHits`	Liste yayınında adresi tutan listelenmiş taraflar. Aynı taraf birden çok listedeyse tek isabettir ve bütün listeleri `lists` içindedir
`riskCategory`	Tarafın en katı risk alanı
`listedAddress` · `listedChains`	Adresin listedeki yazımı ve listenin belirttiği ağ veya para birimi
`caseRule`	Uygulanan karşılaştırma kuralı: `EVM_HEX` \| `BECH32` \| `CASHADDR` \| `CASE_SENSITIVE`
`hits`	Kendi cüzdan listeniz, maruziyet kayıtları ve kripto istihbaratı. Liste yayınının isabetleri bu alanda yer almaz
`isSanctioned`	Yaptırım alanındaki bir taraf adresi tutuyorsa `true`

Yaptırım alanındaki bir taraf adresi tutuyorsa isSanctioned: true olur ve skor 100'dür. Diğer risk alanlarındaki (ör. wanted, regulatory) bir taraf skor 90 ile döner ve inceleme gerektiren bir isabettir. Liste yayını sabitlenemezse cüzdan taraması da yapılmaz (503, yukarıda).

Hesap taraması

POST /api/v1/sanction/screening/account

Yaptırım listeleri IBAN veya banka hesap numarası yayımlamaz. Hesap taraması bu nedenle liste yayınını değil, kendi hesap listenizi (kara liste) ve hesap risk bilgisini tarar; yanıtında yayın alanları yoktur. Hesap sahibinin adını ayrıca isim taramasından geçirin.

İşlem taraması

POST /api/v1/sanction/screening/transaction

İşlemin bütün tarafları aynı liste yayınında taranır. Yanıta publicationId, publicationRevision ve coverageStatus eklenmiştir; coverageStatus tarafların en zayıf kapsam durumudur. Taraf başına kanıt, kapsam ve liste ayrıntısı resultsJson içindedir. Hiçbir taraf taranmadıysa bu alanlar boştur.

Kamu ihale yasağı taraması

POST /api/v1/sanction/intelligence/public-procurement-ban

Kişi veya kurumu, aktif liste yayınındaki yasaklılar (debarment) listelerinde ad ve TCKN/VKN ile tarar.

Alan	Tip	Zorunlu	Açıklama
`entityName`	string	—	Kişi veya kurum adı
`tckn` · `vkn`	string	—	Birebir aranır; eşit bir TCKN/VKN, ad farklı olsa da eşleşme üretir
`entityType`	string	—	Kişi mi kurum mu
`onlyActive`	boolean	—	Yalnız yürürlükteki yasaklar
`limit`	number	—	Dönecek en fazla isabet
`customerReference`	string	—	Kendi kayıt kimliğiniz
`productChannel`	string	—	Hangi üründen geldiği (raporlama)

entityName, tckn ve vkn'den en az biri verilmelidir; hiçbiri yoksa istek sanction.screening.subject_invalid (400) ile reddedilir.

{
  "status": "success",
  "code": "sanction.public_procurement.completed",
  "data": {
    "matched": false,
    "riskScore": 0,
    "decision": "…",
    "hits": [],
    "publicationId": "…",
    "publicationRevision": 34,
    "coverageStatus": "PARTIAL",
    "evidenceRef": "…",
    "screenedRiskDomains": ["debarment"],
    "searchedLists": [
      { "datasetCode": "…", "displayName": "…", "datasetVersionId": "…" }
    ],
    "uncoveredSources": [
      { "datasetCode": "TR_PUBLIC_PROCUREMENT_BAN", "displayName": "…", "reason": "NOT_PUBLISHED" }
    ]
  },
  "statusCode": 200
}

Alan	Anlamı
`searchedLists`	Taramanın okuduğu yasaklı listeleri
`uncoveredSources`	Taranması beklenen ancak yayında bulunmayan kaynaklar
`coverageStatus`	Kapsanmayan bir kaynak varken `PARTIAL`
`hits[].matchBasis`	Eşleşmenin dayanağı (ör. `tckn`, `vkn`, ad)
`hits[].lists`	İsabetin yer aldığı listeler (isim taramasındaki yapı)

⚠️

Türkiye kamu ihale yasaklıları (KİK) bu taramada yoktur. Bu liste için makine tarafından okunabilir resmî bir kaynak bulunmadığından taranmaz; yanıt uncoveredSources içinde TR_PUBLIC_PROCUREMENT_BAN ile PARTIAL kapsam bildirir. Eşleşme olmaması, Türkiye'deki kamu ihale yasakları bakımından temiz sonuç değildir — bu kontrolü EKAP üzerinden ayrıca yapmanız gerekir.

Tarama geçmişi

GET /api/v1/sanction/screening/history

Daha önce yapılan taramaları döndürür. Denetimde "bu müşteriyi ne zaman, hangi modda taradık" sorusunun cevabıdır — customerReference alanını doldurursanız burada bulursunuz.

Sürekli izleme

Tek seferlik tarama, listeler güncellendiğinde sizi uyarmaz. Bunun için özneyi izlemeye kaydedin:

POST /api/v1/sanction/monitoring/register     # özneyi izlemeye al
GET  /api/v1/sanction/monitoring/alerts       # yeni eşleşme uyarıları
GET  /api/v1/sanction/monitoring/entities     # izlenen özneler
GET  /api/v1/sanction/monitoring/matches      # izleme kaynaklı eşleşmeler
GET  /api/v1/sanction/monitoring/dataset-freshness   # veri seti tazeliği

Müşteri kabulünde tarama yapıp izlemeye kaydetmezseniz, o müşteri ertesi gün listeye eklendiğinde haberiniz olmaz. Kabul taraması ile sürekli izleme iki ayrı yükümlülüktür.

İzlemeye alma gövdesi

{
  "externalCustomerId": "cust_9001",
  "subjectType": "person",
  "profileJson": "{\"name\":\"Ahmet Yılmaz\",\"countryCode\":\"TR\",\"dateOfBirth\":\"1980-01-31\",\"identifiers\":[{\"type\":\"tckn\",\"value\":\"12345678901\"}]}",
  "frequency": "DAILY",
  "riskDomainScope": ["sanctions", "pep"]
}

Alan	Anlamı
`externalCustomerId`	Müşterinin sizdeki referansı. Uyarı ve webhook'ta geri döner; aynı referansla yeniden kayıt profili günceller.
`subjectType`	`person` veya `organization`.
`profileJson`	Öznenin profili, JSON metni olarak: `name` (zorunlu), `countryCode`, `dateOfBirth`, `identifiers[]` (`type`, `value`). Yeniden taramalar bu profille yapılır; tanımlayıcı vermek isabeti artırır.
`frequency`	`DAILY`, `WEEKLY` veya `MONTHLY`. Boş bırakılırsa günlük. Liste yayını değiştiğinde ise sıklıktan bağımsız olarak etkilenen özneler yeniden taranır.
`riskDomainScope`	İzlenecek risk alanları (`sanctions`, `pep`, `rca`, `wanted`, `regulatory`, `debarment`). Boş bırakılırsa yaptırım alanı.

Yanıt: { "success": true, "monitoredEntityId": "<uuid>" }. Aynı çağrı API anahtarıyla (sanction:monitoring kapsamı) ya da panel oturumuyla yapılabilir; panelde Yaptırım → İzleme → İzlemeye Al kartı aynı ucu kullanır.

İzleme webhook'ları

Yeni bir eşleşme bulunduğunda endpoint'inize sanction.monitoring.match_found olayı gönderilir; olumsuz medya izlemesi için sanction.monitoring.adverse_media_found olayı vardır. Zarf, imza ve yeniden deneme kuralları bütün ürünlerde ortaktır — bkz. Webhook'lar. Olaya abone olmak için webhook endpoint'inizde ilgili olay tipini seçin.

{
  "type": "sanction.monitoring.match_found",
  "data": {
    "monitoredEntityId": "0b5d6a51-…",
    "externalCustomerId": "cust_9001",
    "subjectName": "Ahmet Yılmaz",
    "matchedName": "Ahmet YILMAZ",
    "sourceListName": "OFAC SDN",
    "riskDomains": ["sanctions"],
    "score": 93.4,
    "canonicalEntityId": "d5990c41-…",
    "datasetGeneration": "2026-10-19",
    "detectedAt": "2026-10-19T06:12:40.000Z",
    "caseId": null,
    "screeningRequestId": "…",
    "publicationId": "…",
    "publicationRevision": 40,
    "entityIds": ["d5990c41-…", "f89dd795-…"],
    "lists": [{ "datasetCode": "OFAC", "displayName": "OFAC SDN" }]
  }
}

Alan	Anlamı
`monitoredEntityId`, `externalCustomerId`	Hangi izleme kaydı ve hangi müşteriniz.
`subjectName`, `matchedName`, `score`, `riskDomains`	İzlenen profil, eşleşen listelenmiş ad, skor (0–100) ve risk alanları.
`sourceListName`, `lists[]`	Eşleşmeyi sunan liste ve eşleşmenin yer aldığı bütün listeler.
`canonicalEntityId`, `entityIds[]`	Listelenmiş taraf ve eşleşmede birleşen bütün kayıtlar; varlık profili ucuyla okunur.
`publicationId`, `publicationRevision`, `datasetGeneration`, `detectedAt`	Eşleşmenin hangi liste yayınına karşı, ne zaman bulunduğu. Denetim kaydınız için saklayın.
`caseId`	Otomatik vaka açıldıysa vaka kimliği.

Aynı eşleşme için olay bir kez üretilir; teslimat yeniden denense de ikinci bildirim gelmez. Olayı GET /api/v1/sanction/monitoring/matches ile de görebilirsiniz.

İlgili uçlar

Uç	Ne yapar
`POST /api/v1/sanction/intelligence/adverse-media`	Olumsuz medya taraması
`POST /api/v1/sanction/intelligence/public-procurement-ban`	Kamu ihalelerinden yasaklılık (yukarıda)
`GET /api/v1/sanction/intelligence/entity-search`	Varlık arama
`GET /api/v1/sanction/intelligence/entity-profiles/:entityId`	Varlık profili
`GET /api/v1/sanction/intelligence/entity-graph/:entityId`	İlişki grafiği
`GET /api/v1/sanction/intelligence/indirect-exposure/:entityId`	Dolaylı maruziyet
`GET /api/v1/sanction/intelligence/ownership-aggregation/:entityId`	Ortaklık toplamı (%50 kuralı)
`POST /api/v1/sanction/blacklist`	Kendi kara listenize kayıt ekler. Anahtarınızın `sanction:add_list_entry` yetkisi olmalıdır; kayıt yalnız sizin listenize yazılır
`GET /api/v1/sanction/blacklist`	Kendi kara listenizi listeler (`sanction:view_results`)

Panelden Tarama Tarama Geçmişi