Barındırılan belge verme API'si

Kurumun, Tamga'nın barındırılan belge verme servisine belge teklif ettirmek, bilet sattırmak ya da belge iptal ettirmek için çağırdığı API.

Gerçek ağ

https://issuer.tamga.network/{slug}/api/v1

Sandbox (deneme ağı)

https://issuer.sandbox.tamga.network/{slug}/api/v1

Kimlik doğrulama

Bearer

Tanım

OpenAPI 3.1 dosyası · Rehber

Tamga Network operatörü işletir (ADR-0016, ADR-0020). Bağımlılıksız Node istemcisi @tamga-network/issuer/client.

Teklifler. İki tür:

• Kimliğe bağlı (önerilen; ADR-0020): bind gönderin. PIN yok. Kişi bağlantıyı cüzdanında açar ve Tamga kimlik belgesini sunar; belge yalnızca sunulan kimlik numarası ve doğum tarihi eşleşirse verilir. Bu anahtarların yalnızca anahtarlı özeti saklanır. 7 gün geçerli, tek kullanımlık. Bağlantıyı kişiye siz kendi kanalınızdan (e-posta, öğrenci portalı) iletirsiniz; Tamga iletişim bilgisi almaz.
• PIN'li ön yetkili (kimlik belgesi olmayanlar için yedek yol): yanıtta tx_code gelir. PIN'i asla bağlantıyla aynı kanaldan göndermeyin.

Belge verisi teklifle gönderilmez: barındırılan servis onu belge verme anında kurumunuzun sorgu ucundan okur (kurum sorgu ucu sayfasına bakın).

Hatalar RFC 9457 problem ayrıntısı biçimindedir (title, status). Her anahtarın dakikalık sınırı vardır (Retry-After ile 429).

Uç noktalar

Uç nokta	Açıklama
POST /offers	Belge teklif et
GET /tickets	Satılan biletleri listele
POST /tickets	Bilet sat
POST /revocations	Belgeyi iptal et, askıya al ya da geri al

Kimlik doğrulama

Bearer

Authorization: Bearer tmg_<slug>_… — Kurum Konsolu'nda kurum başına verilen, kapsamlı bir API anahtarı; 90 gün geçerlidir, yenisi verilerek döndürülür. Yalnız sunucunuzda tutun.

Teklifler

Kayıtlarınızdaki bir kişiye belge teklif edin.

Belge teklif et

POST/offers

Kapsam offers:write. Kişi kurumunuzun sorgu ucunda bulunmalıdır.

Kimlik doğrulama Bearer

İstek gövdesi

application/json

Alan	Tür	Açıklama
subject_id zorunlu	string	Kişiye verdiğiniz opak referans (sorgu ucunuzdaki SubjectRecord.id).
vct zorunlu	string	Belge türü; güven listesinde kurumunuza yetkilendirilmiş olmalıdır.
klass	string	Ön yetkili teklifte PIN'in iletim biçimi; bind varsa yok sayılır. Değerler: on-screen · out-of-band
bind	object	Teklifi kimliğe bağlar (ADR-0020). Yalnızca anahtarlı özet saklanır.
bind.personal_administrative_number zorunlu	string
bind.birth_date zorunlu	string (date)

Yanıtlar

Durum	Açıklama
200	Teklif oluşturuldu.
400	RFC 9457 problem ayrıntısı. Döner: Problem
401	Anahtar yok, süresi dolmuş ya da kapsamı yetmiyor. Döner: Problem
404	Kişi kurumunuzun kaynağında yok.
429	Anahtar başına sınır aşıldı. Retry-After saniye bekleyin. Döner: Problem Başlıklar: Retry-After
503	Sorgu ucunuza ulaşılamadı.

Örnek

İstek · curl

curl -X POST "https://issuer.tamga.network/your-institution/api/v1/offers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject_id":"stu_8c41f2","vct":"urn:tamga:edu:DiplomaCredential:1","bind":{"personal_administrative_number":"10000000146","birth_date":"2001-04-17"}}'

Yanıt · 200

{
  "offer_id": "off_3kQ9xV",
  "expires_at": 1791504000,
  "offer_uri": "https://issuer.tamga.network/your-institution/offers/off_3kQ9xV",
  "deep_link": "openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fissuer.tamga.network%2Fyour-institution%2Foffers%2Foff_3kQ9xV",
  "offer": {
    "credential_issuer": "https://issuer.tamga.network/your-institution",
    "credential_configuration_ids": [
      "urn:tamga:edu:DiplomaCredential:1"
    ],
    "grants": {
      "authorization_code": {
        "issuer_state": "off_3kQ9xV"
      }
    }
  },
  "identity_bound": true
}

Biletler

Etkinlik biletlerini belge olarak satın.

Satılan biletleri listele

GET/tickets

Kapsam tickets:read.

Kimlik doğrulama Bearer

Yanıtlar

Durum	Açıklama
200	Biletler.
401	Anahtar yok, süresi dolmuş ya da kapsamı yetmiyor. Döner: Problem
429	Anahtar başına sınır aşıldı. Retry-After saniye bekleyin. Döner: Problem Başlıklar: Retry-After

Örnek

İstek · curl

curl "https://issuer.tamga.network/your-institution/api/v1/tickets" \
  -H "Authorization: Bearer $API_KEY"

Yanıt · 200

{
  "tickets": [
    {}
  ]
}

Bilet sat

POST/tickets

Kapsam tickets:write. Satışı kaydeder ve bilet belgesini teklif eder; teklif kişisel veri taşımaz.

Kimlik doğrulama Bearer

İstek gövdesi

application/json

Alan	Tür	Açıklama
event_id zorunlu	string
ticket_class zorunlu	string
seat	string
klass	string	Değerler: on-screen · out-of-band

Yanıtlar

Durum	Açıklama
200	Bilet satıldı.
400	RFC 9457 problem ayrıntısı. Döner: Problem
401	Anahtar yok, süresi dolmuş ya da kapsamı yetmiyor. Döner: Problem
404	RFC 9457 problem ayrıntısı. Döner: Problem
429	Anahtar başına sınır aşıldı. Retry-After saniye bekleyin. Döner: Problem Başlıklar: Retry-After

Örnek

İstek · curl

curl -X POST "https://issuer.tamga.network/your-institution/api/v1/tickets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"evt_2026_konser","ticket_class":"standard","seat":"B-14"}'

Yanıt · 200

{
  "ticket_id": "…",
  "ticket_no": "…",
  "event": {
    "id": "…",
    "name": "…",
    "start": "…",
    "venue": "…"
  },
  "offer": {
    "offer_id": "…",
    "tx_code": "…",
    "expires_at": 0,
    "offer_uri": "…",
    "deep_link": "…"
  }
}

İptaller

Verilmiş bir belgenin durumunu değiştirin.

Belgeyi iptal et, askıya al ya da geri al

POST/revocations

Kapsam revocations:write. Bir sonraki sabit aralıklı durum listesi yayınında geçerli olur. İptal edilen belge iptal kalır; yalnız askıdaki belge geri alınabilir.

Kimlik doğrulama Bearer

İstek gövdesi

application/json

Alan	Tür	Açıklama
credential_id zorunlu	string
action	string	Değerler: revoke · suspend · reinstate (default revoke)
reason	string	Denetim kaydınızda tutulur; asla yayınlanmaz.

Yanıtlar

Durum	Açıklama
200	Kabul edildi.
400	RFC 9457 problem ayrıntısı. Döner: Problem
401	Anahtar yok, süresi dolmuş ya da kapsamı yetmiyor. Döner: Problem
404	RFC 9457 problem ayrıntısı. Döner: Problem
429	Anahtar başına sınır aşıldı. Retry-After saniye bekleyin. Döner: Problem Başlıklar: Retry-After

Örnek

İstek · curl

curl -X POST "https://issuer.tamga.network/your-institution/api/v1/revocations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credential_id":"crd_5Hn2Lw","action":"suspend","reason":"disciplinary review"}'

Yanıt · 200

{
  "ok": true,
  "effective_after_next_publish": true,
  "interval_sec": 3600
}

Nesneler

Problem

Alan	Tür	Açıklama
type	string
title	string
status	integer

---

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