Kurum sorgu ucu

Barındırılan belge verme servisinin belge verisini verme anında okuyabilmesi için kurumun açtığı sorgu ucu.

Örnek — adresi siz seçersiniz; barındırılan servis tarafında kurumunuz için tanımlanır.

https://sis.example.edu/tamga

Kimlik doğrulama

Bearer (tamga-source-request+jwt)

Tanım

OpenAPI 3.1 dosyası · Rehber

Bu ucu Tamga değil, kurum uygular (ADR-0020, yetkili kaynak kurumda). Tamga'nın barındırılan belge verme servisi onu çağırır ve yanıtı saklamaz. İki işlem aynı adresi paylaşır; imzalı istekteki op alanı hangisi olduğunu söyler:

• lookup — kişi isteği cüzdandan başlattı ve Tamga kimlik belgesini sundu. Tamga eşleştirme anahtarlarını (kimlik numarası + doğum tarihi) gönderir. Eşleşen kişiyi ya da 404 döndürün.
• fetch — Tamga kurumunuzun opak kişi referansını zaten biliyor (kimliğe bağlı teklif, belge verme, belge yenileme). Güncel kaydı ya da 404 (kişi artık kayıtlarınızda yok) döndürün.

Gizlilik. Yalnız istenen vct için gereken alanları döndürün. Eşleştirme anahtarlarını günlüğe yazmayın. 404 dışındaki hatalarda Tamga cüzdana temporarily_unavailable yanıtı verir; belge verilmez.

Uç noktalar

Uç nokta	Açıklama
POST /	Kişi kaydını ara ya da getir

Kimlik doğrulama

Bearer (tamga-source-request+jwt)

Başlıkta değil: gövde, Tamga'nın kurumunuz için kullandığı erişim anahtarıyla imzalanmış kısa ömürlü bir JWT taşır (typ: tamga-source-request+jwt, ES256, 60 sn). x5c başlığındaki sertifikayla doğrulayın ve bu sertifikanın Tamga imzalı güven listesinde Tamga'nın barındırılan belge verme servisi için listelendiğini denetleyin; aud alanının uç adresinize eşit olduğunu ve exp alanını denetleyin, tekrar eden jti'yi reddedin. Yalnız TLS üzerinden sunun.

Kaynak

Tek işlem.

Kişi kaydını ara ya da getir

POST/

Gövde imzalı bir istek taşır; içeriği SourceRequestClaims nesnesidir (aşağıda).

Kimlik doğrulama Bearer (tamga-source-request+jwt)

İstek gövdesi

application/json

Alan	Tür	Açıklama
request zorunlu	string	Kompakt JWS; içeriği SourceRequestClaims.

Yanıtlar

Durum	Açıklama
200	Kayıt bulundu.
401	İsteğin imza, hedef (aud), süre ya da tekrar denetimi başarısız.
404	Eşleşen kayıt yok. Gövde {"subject": null} olabilir.
503	Geçici olarak kullanılamıyor. Tamga belge vermez; kişi sonra yeniden dener.

Örnek

İstek · curl

curl -X POST "https://sis.example.edu/tamga/" \
  -H "Content-Type: application/json" \
  -d '{"request":"eyJhbGciOiJFUzI1NiIsInR5cCI6InRhbWdhLXNvdXJjZS1yZXF1ZXN0K2p3dCIsIng1YyI6WyIuLi4iXX0.eyJvcCI6ImZldGNoIn0.sig"}'

Yanıt · 200

{
  "subject": {
    "id": "…",
    "student_no": "…",
    "family_name": "…",
    "given_name": "…",
    "birth_date": "2026-10-09",
    "programme_title_tr": "…",
    "study_level": 0,
    "enrollment_year": 0,
    "student_status": "ACTIVE"
  }
}

Nesneler

SourceRequestClaims

İmzalı isteğin içeriği.

Alan	Tür	Açıklama
op zorunlu	string	Değerler: lookup · fetch
iss zorunlu	string	Barındırılan servisin istemci kimliği — x509_hash: + base64url(SHA-256(erişim sertifikası)) (HAIP 1.0).
aud zorunlu	string	Uç adresiniz.
iat zorunlu	integer
exp zorunlu	integer	iat + 60
jti zorunlu	string
vct zorunlu	string	Verilen belge türü, ör. urn:tamga:edu:DiplomaCredential:1.
match	object	op = lookup ise gelir.
match.personal_administrative_number zorunlu	string
match.birth_date zorunlu	string (date)
subject_ref	string	op = fetch ise gelir. Daha önce SubjectRecord.id olarak döndürdüğünüz opak kimlik.

SubjectRecord

Eğitim profili (öğrenci ve diploma belgeleri). id sizin opak ve kalıcı kişi referansınızdır; Tamga yalnızca bu değeri tutar (iptal ve yenileme için). Diğer profiller belge türüne göre eklenir.

Alan	Tür	Açıklama
id zorunlu	string
student_no zorunlu	string
family_name zorunlu	string
given_name zorunlu	string
birth_date zorunlu	string (date)
personal_administrative_number	string	İsteğe bağlı; yalnız eşleştirmede kullanılır, eğitim belgelerine asla yazılmaz.
programme_title_tr zorunlu	string
programme_title_en	string
faculty_tr	string
isced_f_code	string | null
study_level zorunlu	integer	EQF/ISCED düzeyi
enrollment_year zorunlu	integer
student_status zorunlu	string	Değerler: ACTIVE · ON_LEAVE
expected_graduation_year	integer
programme_credit_points	number	Programın AKTS yükü (AB kayıt belgesi, EUHEPOE). İsteğe bağlı.
enrollment_date	string (date)	Kayıt tarihi (AB kayıt belgesi, EUHEPOE). İsteğe bağlı; enrollment_year zorunlu kalır.
graduate	object	Yalnız mezunlarda; DiplomaCredential için zorunlu.
graduate.qualification_tr zorunlu	string
graduate.qualification_en	string
graduate.eqf_level zorunlu	integer
graduate.awarding_date zorunlu	string (date)
graduate.grade	string
graduate.thesis_title_tr	string
graduate.mode_of_study	string	Değerler: FULL_TIME · PART_TIME · DISTANCE · BLENDED

---

Makine okur tanımı herhangi bir OpenAPI aracına aktararak istemci üretebilir ya da deneme isteği gönderebilirsiniz: institution-source.openapi.yaml.