Doğrulama Raporları API
| HTTP yöntemi | Yol | İşlev |
|---|---|---|
GET | /api/v1/verification-reports | Mevcut doğrulama çalışmalarını listeler |
GET | /api/v1/verification-reports/:id | Tek çalışmanın detayını okur |
Bu uçlar çalışma başlatmaz veya dosya üretmez. Organizasyon kimliği sunucuda
kimlik doğrulama bağlamından çözülür. Başka organizasyonun veya bulunmayan
çalışmanın detayı 404 döner. Liste createdAt azalan sıralanır.
Kimlik Doğrulama ve Yetki
| Kimlik doğrulama | Kural |
|---|---|
| API anahtarı | x-api-key; verification:read izni gerekir. Bu izin anahtar oluşturma veya izin güncelleme sırasında yalnız ENTERPRISE planına verilir |
| JWT | Authorization: Bearer <JWT>; compliance sayfası için okuma izni denetlenir |
| Plan ve kota | Anahtar çağrısında publicApi özelliği ve planın hız sınırı; hem JWT hem anahtar çağrısında genel API kullanım kotası denetlenir |
JWT yolunda ayrıca bir ENTERPRISE plan veya ADMIN/EDITOR rol listesi
tanımlı değildir. Bu, API anahtarı izin verme politikasıyla aynı kural değildir.
Yanıt kimliksiz erişime açık değildir ve organizasyona ait rapor verisi içerir.
Sorgu ve Yol Parametreleri
Liste sorgusunun bütün alanları isteğe bağlıdır:
| Parametre | Tip ve doğrulama | Uygulanan davranış |
|---|---|---|
page | Tam sayı, en az 1; varsayılan 1 | Sayfalama |
limit | Tam sayı, 1–100; varsayılan 20 | Sayfalama |
status | QUEUED, PROCESSING, PAUSED, REVIEW_REQUIRED, COMPLETED, FAILED, CANCELLED | Durum filtresi |
sourceType | DOCUMENT, WEBSITE, REKLAM | Kaynak türü filtresi |
profileId | Kırpılmış metin, en fazla 80 karakter | Profil kimliği filtresi |
analysisDepth | STANDARD, DEEP | DTO kabul eder; bu genel API okuma servisinde filtrelemeye uygulanmaz |
search | Kırpılmış metin, en fazla 160 karakter | DTO kabul eder; filtrelemeye uygulanmaz |
regulatorCode | Kırpılmış metin, en fazla 40 karakter | DTO kabul eder; filtrelemeye uygulanmaz |
scenarioKey | Kırpılmış metin, en fazla 120 karakter | DTO kabul eder; filtrelemeye uygulanmaz |
Son dört alanı göndermek listeyi daraltmaz. Kırpılan metin alanlarında boş
veya yalnız boşluk içeren değer verilmemiş sayılır. Tanımlanmamış liste
sorgusu alanları 400 döner.
Detay yolundaki id, çalışmanın metin kimliğidir. Controller UUID biçimi
zorunlu tutmaz; kimlik ve organizasyon birlikte sorgulanır.
Yanıt
Her iki işlem başarıda 200 döner. Liste sayfalaması data.meta içindedir:
{
"success": true,
"data": {
"items": [],
"meta": {
"total": 0,
"page": 1,
"limit": 20,
"totalPages": 1
}
}
}totalPages, en az 1 olmak üzere ceil(total / limit) olur.
Liste Satırı
| Alanlar | İçerik |
|---|---|
id, sourceType, status, analysisDepth | Kimlik, kaynak türü, çalışma durumu ve analiz derinliği |
createdAt, updatedAt, queuedAt | ISO 8601 tarih-saat |
startedAt, completedAt, failedAt, reviewRequiredAt | ISO 8601 tarih-saat veya null |
currentStep, statusReason, sensitivityClass | Metin veya null |
etaSeconds | Sayı veya null |
processedPageCount, totalPageCount | İşlenen ve hedeflerdeki toplam sayfa sayısı |
profile | { id, name, regulatorCode, scenarioKey, slug } |
profileVersion | { id, name, sourceType, status, versionNumber } |
counts | { exportRecords, results, reviews } sayıları |
results | Sonuç özetleri; aşağıdaki alanları taşır |
latestReview | { id, status, requestedAt, decidedAt, decisionNote, reviewReason } veya null |
reviewStatus | { latestStatus, pendingCount, total } |
exportHistory | { items, latestStatus, total }; dışa aktarma kayıtları |
rerunOf, reusedFrom | İlişkili çalışmanın kimlik, kaynak, durum ve tarih özeti veya null |
sourceDescriptor | { displayName, documentName, label, primary, secondary, sourceType, sourceUrl, textSummary, title, valueLabel } kaynak özeti |
advisory | isLegalAdvice: false, provenanceLabel, disclaimer |
Sonuç özeti alanları: id, title, status, summary, confidenceScore,
decisionCode, evidenceCount, isOverall, latestReviewStatus,
manualReviewRequired, provenance, scorecard, trustBadge.
title, summary, decisionCode, latestReviewStatus ve scorecard
gibi alanlar null olabilir. Sonuç durumu COMPLIANT, NON_COMPLIANT,
OUT_OF_SCOPE, INSUFFICIENT_DATA; güven rozeti HIGH_TRUST, PROVISIONAL,
REVIEW_REQUIRED, OVERRIDDEN değerlerinden biridir.
Dışa aktarma kaydı; id, format, status, createdAt, checksum,
fileUrl, manifestLabel, boardReportId, complianceEvidencePackId,
trustWorkspaceHref, attestation alanlarını içerir. Dosya veya onay alanı
null olabilir. Bu uçlar ayrıca imzalı downloadUrl üretmez. attestation doluysa
attestedAt, boardReportId, complianceEvidencePackId, statement, status
alanlarını taşır. rerunOf ve reusedFrom doluysa id, sourceType, status,
createdAt, completedAt, failedAt içerir.
Detay Nesnesi
Detay yanıtında data, liste satırını ve şu ek alanları içerir:
| Alan | İçerik |
|---|---|
modelExecutions | Sonuç kimliği, sağlayıcı/model, sürüm, politika, girdi/çıktı özeti ve çalışma metadata kayıtları |
recommendations | id, resultId, title, description, status, metadata, createdAt, updatedAt |
decisionTrace | id, resultId, stepKey, stepLabel, outcome, rationale, createdAt |
evidenceChain | Kanıt kimliği, sonuç kimliği, tür, başlık, alıntı, konum, sayfa, checksum, metadata ve kaynak dosya özeti |
reviews | İnceleme kimliği, durumu, talep/karar tarihi, karar notu ve gerekçesi |
targets | Hedef kimliği, kaynak türü/URL’si, belge adı, MIME türü, sayfa sayısı, checksum, metadata ve dosyalar |
timeline | id, eventType, message, stepKey, metadata, createdAt |
Detay results[] öğeleri özet alanlarına ek olarak boardReportId,
complianceEvidencePackId, verificationControlCode, verificationControlId,
verificationControlTitle, decisionTraces, sourceLinks, evidences,
modelExecutions, recommendations taşır. sourceLinks.local uygulama içi
mevzuat yollarını; sourceLinks.source dış kaynak bağlantılarını içerir.
Boş ilişkiler dizi olarak döner; eksik isteğe bağlı alanlar null olabilir.
Detaydaki alt kayıtların alan adları:
modelExecutions[]:id,resultId,createdAt,provider,model,modelVersion,servedModel,inputHash,outputHash,metadata,phase,promptVersion,ruleSetVersion,chunkingVersion,ocrPipelineVersion,retrievalVersion,retrievalPolicyVersion,scoringVersion,deterministicPolicyVersion,executionFingerprint,fallbackReason,contextPackStrategy,corpusSnapshotId,freshnessStatus,requestedLane,resolvedLane,policyVersion,billingFeatureKey. Sonuç altındakimodelExecutions[]aynı alanlarıresultIdolmadan taşır.evidenceChain[]:id,resultId,createdAt,evidenceType,title,excerpt,locator,pageNumber,checksum,metadata,artifact. Sonuç altındakievidences[]aynı alanlarıresultIdolmadan taşır.- Kanıt
artifactnesnesi:id,artifactType,byteSize,checksum,metadata,mimeType,pageCount,sourceUrl,storageKey; yoksanull. targets[]:id,sourceType,sourceUrl,displayName,documentName,mimeType,pageCount,checksum,metadata,artifacts. Hedef dosyaları yukarıdaki kaynak dosya alanlarına ek olarakcreatedAttaşır.sourceLinks.local[]vesourceLinks.source[]:{ href, kind, label }. Sonuç altındaki öneriler ve karar izleri, üsttekirecommendationsvedecisionTracekayıtlarınıresultIdolmadan taşır.
advisory.disclaimer değeri “Nihai hukuki görüş değildir.” olur. Bir
çalışmanın COMPLETED olması, bütün sonuçların uygun bulunduğu anlamına gelmez;
sonuç durumu ve inceleme ihtiyacı ayrıca değerlendirilir.
Hata Kodları
| HTTP durumu | Anlam |
|---|---|
400 | Geçersiz liste sorgusu, enum veya sayfalama |
401 | JWT/API anahtarı eksik veya geçersiz |
402 | Genel API kotası çözülürken abonelik bağlamı bulunamıyor |
403 | Anahtar/IP izni, JWT sayfa izni, plan özelliği veya kullanım kotası yetersiz |
404 | Detay çalışması bulunamadı veya organizasyon kapsamında değil |
429 | İstek hızı aşıldı; mevcutsa Retry-After süresine uyulur |
503 | API anahtarının hız sınırı denetimi kullanılamıyor |
Hatalar application/problem+json türünde döner. Ortak alanlar
Ortak API Kuralları sayfasındadır.
Örnekler
curl --fail-with-body --get 'https://api.mevzuatradar.com/api/v1/verification-reports' \
--data-urlencode 'status=COMPLETED' \
--data-urlencode 'limit=20' \
-H "x-api-key: $MEVZUATRADAR_API_KEY"Listedeki id değeri VERIFICATION_RUN_ID olarak kullanılır:
curl --fail-with-body "https://api.mevzuatradar.com/api/v1/verification-reports/$VERIFICATION_RUN_ID" \
-H "x-api-key: $MEVZUATRADAR_API_KEY"