API başvurusu

Temel adres: https://damga.ondiso.net/api/v1. Tüm istek ve yanıtlar JSON (Content-Type: application/json), karakter kodlaması UTF-8, zamanlar ISO 8601 UTC (2026-10-01T09:15:00Z).

#Kimlik doğrulama

Her istekte platformunuzun API anahtarı:

Authorization: Bearer dmg_live_4k2m…

Anahtar yalnız sunucunuzda durur; tarayıcıya, mobil uygulamaya ya da kaynak koda koymayın. Sızdıysa panelde yenileyin (yönetimin tanımladığı platformlarda Damga yöneticisinden isteyin): eskisi hemen geçersiz olur. Panelden açılan canlı platformlarda her imza isteği 1 kredi düşer; bakiye yetmezse 402 insufficient_credits. Kurum hesabındayken açılan platformun kredisi kurumun ortak bakiyesinden düşer (Kurum hesapları).

Hız sınırı: platform başına dakikada 240 istek. Aşılırsa 429 rate_limited.

#İmza isteği açmak

POST /sign-requests

Yanıt 201 Created: imza isteği nesnesi ve ek olarak sign_url.

sign_url kullanıcıya özeldir ve yalnız bu yanıtta döner (Damga yalnız özetini saklar). Kaybederseniz yeni bağlantı alın.

#PAdES: imza PDF içinde

format: "pades" ile açılan istekte Damga uygulaması imzayı PDF'in içine ekler (PAdES-B-B, ETSI.CAdES.detached). Sonuç tek bir PDF'tir: Adobe Acrobat Reader ve diğer PDF okuyucuları imzayı ve imzalayanı gösterir, ayrıca .imz dosyası taşımanız gerekmez.

• İmza artımlı güncelleme olarak eklenir: imzalı PDF, gönderdiğiniz PDF'in baytlarıyla aynen başlar; Damga bunu ve imzanın dosyanın tamamını kapsadığını teslimden önce denetler.
• Şifreli (parola korumalı) ve "değişikliğe kapalı" onaylı PDF'lere imza eklenemez; kullanıcı sayfada açıklamayı görür.
• Aynı PDF birden çok kez imzalanabilir: imzalı PDF'i yeni bir isteğin belgesi olarak gönderin, önceki imzalar geçerli kalır.

{
  "title": "Hizmet sözleşmesi",
  "document": { "content": "<PDF, base64>", "filename": "sozlesme.pdf" },
  "format": "pades",
  "signer": { "national_id": "10000000146", "name": "Ayşe Yılmaz" },
  "appearance": { "page": "last", "position": "bottom-right", "reason": "Sözleşme onayı", "location": "Yalova" },
  "verify_url": "https://sisteminiz.ornek/dogrula/sozlesme-42"
}

İmza tamamlanınca imzalı PDF'i indirin.

#XAdES: imza XML içinde

format: "xades" ile XML belgeler imzalanır ya da mühürlenir: e-Fatura ve e-Arşiv (UBL-TR), e-İrsaliye, e-Defter ve beratı ya da herhangi bir XML. Kullanıcı e-imza USB'sindeki nitelikli e-imza (NES), mali mühür ya da e-mühürle imzalar; Damga uygulaması imzayı XML'in içine ekler ve imzalı XML'i teslim eder. GİB'e ya da özel entegratöre gönderim bu işin parçası değildir: e-Fatura ve e-Defter.

Belge iyi biçimli (well-formed) XML olmalı ve DOCTYPE / ENTITY tanımı içeremez (XXE saldırılarına karşı; Damga dış kaynak yüklemez). Zaten imzalı (ds:Signature içeren) XML kabul edilmez.

İmza XAdES-BES (ETSI EN 319 132-1, baseline B-B; XAdES 1.3.2 ad alanı):

• ds:SignedInfo: C14N 1.0 (inclusive, yorumsuz: REC-xml-c14n-20010315), RSA-SHA256 ya da ECDSA-SHA256;
• belge başvurusu URI="", tek dönüşüm enveloped-signature (UBL-TR şematronu en fazla bir dönüşüme izin verir; düğüm kümesi C14N 1.0 ile kanonikleşir), SHA-256;
• xades:SignedProperties başvurusu (Type="http://uri.etsi.org/01903#SignedProperties"): SigningTime (UTC), SigningCertificateV2 (sertifikanın SHA-256 özeti), DataObjectFormat (text/xml);
• ds:KeyInfo/ds:X509Data: imzalayan sertifika (ve e-imza USB'sinde varsa zincir).

Damga, imzalı XML'i teslim almadan önce doğrular: başvuru özetleri, imza değeri, sertifika özeti, sertifikanın geçerliliği, beklenen kişi / kurum (signer.*, allowed_kinds) ve imza çıkarıldığında XML'in gönderdiğiniz belgeyle kanonik olarak aynı olduğu (yalnız imza ve UBL profilinde gerekirse boş uzantı sarmalayıcısı eklenmiş olabilir).

{
  "title": "Satış faturası DMG2026000000001",
  "document": { "content": "<UBL-TR fatura XML, base64>", "filename": "DMG2026000000001.xml" },
  "format": "xades",
  "xades": { "profile": "ubl" },
  "signer": { "tax_id": "1234567890" },
  "allowed_kinds": ["mali_muhur"]
}

Yanıttaki xades nesnesi Damga'nın belgeyi nasıl tanıdığını söyler: {"profile": "ubl", "type": "ubl", "label": "e-Fatura (UBL-TR)", "signature_id": "Signature_DMG2026000000001", "vkn_tckn": "1234567890"}. İmza sayfası XML'i girintili, salt okunur önizler ve "e-Fatura (UBL-TR) · mali mühürle imzalanacak" gibi bir etiket gösterir. İmza tamamlanınca imzalı XML'i indirin.

#Görünür imza kutusu

Kutuda Damga işareti, "Elektronik olarak imzalanmıştır" (mühürlerde "mühürlenmiştir"), imzalayanın adı, maskeli T.C. kimlik no ya da VKN, imza zamanı (Türkiye saati), sertifikayı veren kurum ve varsa verify_url yazar. Yazı tipi PDF'e gömülür (IBM Plex Sans, Türkçe karakterler dahil).

#Zaman damgası ve uzun süreli doğrulama

level ile imzanın düzeyi seçilir (ETSI baseline düzeyleri):

• Zaman damgasını Damga sunucusu kendi tanımlı zaman damgası sunucusundan (TSA) alır; TSA kimlik bilgileri kullanıcının bilgisayarına hiç gitmez. Damga uygulaması imzayı atınca imza değerinin SHA-256'sını sunucuya gönderir, belirteci alır ve imzaya ekler; sunucu teslimde imzalı çıktıdaki damgaların bu istek için kendi verdiği damgalar olduğunu denetler.
• LT / LTA için OCSP / CRL bilgisini de sunucu getirir (sertifikadaki AIA / CRL dağıtım noktası adreslerinden; önbelleğe alır). Canlı platformda iptal bilgisi alınamazsa imza tamamlanmaz; sertifika iptal edilmişse imza reddedilir (certificate_revoked).
• CAdES ve XAdES için en çok T desteklenir (uzun süreli doğrulama bilgisinin bu biçimlere gömülmesi — CAdES-LT / XAdES-LT — henüz yok).
• Zaman damgası sunucusu tanımlı değilse level T ve üstü 422 döner. Damga'nın kendi panelinde PDF'ler LT, XML'ler T düzeyinde imzalanır (TSA tanımlı değilse B).

İstek nesnesinde level istenen düzeydir; tamamlanan isteğin signature nesnesinde gerçekleşen düzey ve damga bulunur:

"signature": {
  "format": "PAdES-B-LT",
  "level": "LT",
  "timestamp": { "time": "2026-10-01T09:02:32Z", "tsa": "Kamu SM Zaman Damgası Sunucusu", "valid": true, "serial": "4A1F…", "policy": "2.16.792.1.2.1.1.5.7.3.1" },
  "document_timestamp": null,
  "dss": { "certs": 5, "ocsps": 3, "crls": 0, "vri": 1 },
  …
}

#Sertifika türleri

Damga her sertifikanın türünü sertifikanın kendisinden çıkarır; imza sayfası türü etiketler, allowed_kinds dışındakileri seçtirmez ve nedenini yazar. İmzadan sonra sunucu türü ve VKN'yi imzadaki sertifikadan yeniden belirler.

Sınıflama bilinçli olarak temkinlidir: emin olunamayan sertifika other olur. allowed_kinds kullanıyorsanız ilk canlı imzalarda sonucu (signature.signer.kind) kontrol edin.

Mühür örneği (yalnız belirli kurumun mali mührü ya da e-mührü):

{
  "title": "Fatura onayı",
  "document": { "content": "<PDF, base64>" },
  "format": "pades",
  "signer": { "tax_id": "1234567890", "name": "Örnek Bilişim A.Ş." },
  "allowed_kinds": ["mali_muhur", "e_muhur"]
}

#İmza isteğini okumak

GET /sign-requests/{id}

Süresi dolan istek bu çağrıda expired olarak döner. Sonuç için bildirim beklemek istemezseniz kullanıcı dönüş adresinize geldiğinde bu çağrıyı yapın.

#İmza isteği nesnesi

{
  "id": "sr_7kq2m9x4pd8e3hwa5tbn6cjy",
  "object": "sign_request",
  "status": "completed",
  "format": "cades",
  "title": "Proje öneri formu — GEN-2026-003",
  "reference": "oneri-3",
  "document": {
    "filename": "proje-oneri-formu.pdf",
    "size": 81918,
    "sha256": "46ef847f83bd1dc9413b654f2983a48c2cc20b8efba6141db6968ef21db1882f"
  },
  "expected_signer": { "national_id": "10000000146", "name": "Ayşe Yılmaz", "tax_id": null },
  "allowed_kinds": null,
  "metadata": null,
  "created_at": "2026-10-01T09:00:00Z",
  "expires_at": "2026-10-01T09:15:00Z",
  "finished_at": "2026-10-01T09:02:31Z",
  "cancel_reason": null,
  "signature": {
    "format": "CAdES-BES",
    "encoding": "DER",
    "signed_at": "2026-10-01T09:02:31Z",
    "content": "MIIN…",
    "download_url": "https://damga.ondiso.net/api/v1/sign-requests/sr_7kq2m9x4pd8e3hwa5tbn6cjy/signature",
    "signer": {
      "name": "AYŞE YILMAZ",
      "national_id": "10000000146",
      "tax_id": null,
      "kind": "nes",
      "certificate": {
        "issuer": "Kamu SM Nitelikli Elektronik Sertifika Hizmet Sağlayıcısı - Sürüm 6",
        "issuer_org": "Kamu Sertifikasyon Merkezi",
        "serial": "9EE28F2485A45880",
        "subject": "C=TR, CN=AYŞE YILMAZ, serialNumber=10000000146",
        "valid_from": "2025-03-12T08:00:00Z",
        "valid_to": "2028-03-12T08:00:00Z",
        "qualified": true,
        "pem": "-----BEGIN CERTIFICATE-----…"
      }
    }
  }
}

signature yalnız status = completed iken doludur. signer.national_id tam numaradır: kendi kullanıcınızla eşleştirmeniz için. Kişisel veridir; kaydederken ve gösterirken buna göre davranın. Mühürlerde signer.tax_id (VKN) dolu, national_id boştur (şahıs işletmesinin mali mührü hariç). signer.kind: sertifika türü.

PAdES isteğinde signature şöyledir (content yoktur; imza PDF'in içindedir):

"signature": {
  "format": "PAdES-B-B",
  "encoding": "PDF",
  "signed_at": "2026-10-01T09:02:31Z",
  "download_url": "https://damga.ondiso.net/api/v1/sign-requests/sr_7kq2m9x4pd8e3hwa5tbn6cjy/document/signed",
  "document": { "filename": "sozlesme-imzali.pdf", "size": 132841, "sha256": "9c1e…" },
  "signer": { "name": "AYŞE YILMAZ", "national_id": "10000000146", "tax_id": null, "kind": "nes", "certificate": { … } }
}

XAdES isteğinde de content yoktur; imza XML'in içindedir:

"signature": {
  "format": "XAdES-BES",
  "encoding": "XML",
  "signed_at": "2026-10-01T09:02:31Z",
  "download_url": "https://damga.ondiso.net/api/v1/sign-requests/sr_7kq2m9x4pd8e3hwa5tbn6cjy/document/signed",
  "document": { "filename": "DMG2026000000001-imzali.xml", "size": 18342, "sha256": "4b0d…" },
  "signer": { "name": "ÖRNEK BİLİŞİM ANONİM ŞİRKETİ", "national_id": null, "tax_id": "1234567890", "kind": "mali_muhur", "certificate": { … } }
}

Bildirimlerde (sign_request.completed) aynı nesne gelir; format alanından isteğin biçimini anlarsınız.

#İmzayı indirmek

GET /sign-requests/{id}/signature → application/pkcs7-signature, dosya adı <belge>.imz. Yalnız CAdES isteklerinde: ayrık (detached) CMS imzasıdır; PDF'in kendisi içinde değildir. PAdES ve XAdES isteklerinde 404.

GET /sign-requests/{id}/document → imzalanması için gönderdiğiniz belgenin aynısı (application/pdf ya da XAdES'te application/xml; sonuçlanmasından 30 gün sonrasına kadar).

#İmzalı PDF indirmek

GET /sign-requests/{id}/document/signed → PAdES'te application/pdf (<belge>-imzali.pdf), XAdES'te application/xml (<belge>-imzali.xml). CAdES isteklerinde 404, imza henüz yoksa 409 not_signed. İmzalı belge sonuçlanmasından 30 gün sonrasına kadar saklanır: bildirim ya da dönüş geldiğinde indirip kendi arşivinize koyun.

#İptal etmek

POST /sign-requests/{id}/cancel — gövde (isteğe bağlı): {"reason": "Başvuru geri çekildi"}

Açık imza sayfası "İmza isteği iptal edildi" der, Damga uygulaması kapanır. Yalnız pending istekler iptal edilebilir; diğerleri 409.

#Yeni imza sayfası bağlantısı

POST /sign-requests/{id}/link → {"sign_url": "…"}

Önceki bağlantı geçersiz olur. Kullanıcı sayfayı kapatıp e-postadaki bağlantıyı kaybettiğinde ya da imzayı başka bir cihazda sürdürmek istediğinde kullanın.

#İmza doğrulamak

POST /verify — Damga'da atılmamış imzalar da olabilir.

{ "document": "<PDF, base64>", "signature": "<.imz, base64>" }

İmza PDF'in içindeyse (PAdES) signature alanını göndermeyin: { "document": "<imzalı PDF, base64>" }. Son imza doğrulanır; yanıtta ayrıca format (PAdES-B-B), signatures (PDF'teki imza sayısı) ve geçersizse code (no_signature, byte_range_invalid — imzadan sonra belgeye ekleme yapılmış, signature_invalid) bulunur.

Yanıtta ayrıca level (B, T, LT, LTA), timestamp ({time, tsa, valid}; imza zaman damgası), PAdES'te document_timestamp ve dss (DSS'teki sertifika / OCSP / CRL sayıları) bulunur. İmzanın ardından eklenen artımlı güncellemelerde yalnız DSS ve belge zaman damgası kabul edilir; başka her ekleme byte_range_invalid ile reddedilir. İptal durumunun doğrulama anında ayrıca sorgulanması yapılmaz.

İmzalı XML (XAdES) de aynı biçimde, signature olmadan gönderilir: { "document": "<imzalı XML, base64>" }. Yanıtta format (XAdES-BES), signing_time, signature_id, UBL belgelerinde ubl (vkn_tckn, signature_id, signature_id_matches) ve geçersizse code (no_signature, signature_invalid, certificate_mismatch, not_xades, xml_unsafe — DOCTYPE / ENTITY içeriyor, unsupported_algorithm) bulunur. XML'de tek bir ds:Signature olmalı; belgenin tamamını (URI="") kapsamayan imzalar geçersiz sayılır.

{
  "valid": true,
  "chain_checked": true,
  "document_sha256": "46ef…",
  "signer": { "name": "AYŞE YILMAZ", "national_id": "10000000146", "tax_id": null, "kind": "nes", "certificate": { …, "test": false } }
}

chain_checked Damga sunucusuna Kamu SM / ESHS kök sertifikaları yüklüyse true olur; o zaman sertifikanın güvenilir bir sağlayıcıdan geldiği de denetlenmiştir. Ayrıntı: İmzayı doğrulamak.

#E-posta mühürlemek

POST /email-seals — göndermeden önce bir e-postayı mühürler. Gövde ya iletinin tamamı ({"eml": "<base64>"}) ya da özetidir (from, to[], cc[], subject, date, message_id, body_sha256 ya da text, attachments[{name, sha256}]). From alan adı platformun hesabında DNS ile doğrulanmış olmalı (403 domain_not_verified). Canlı anahtarla 1 kredi düşer.

{
  "id": "es_k2m4n6p8q9r2s3t4u5v6w7x8",
  "mode": "live",
  "sealed_at": "2026-10-01T09:15:02Z",
  "from_domain": "ornek.com.tr",
  "canonical_sha256": "d66c…",
  "verify_url": "https://damga.ondiso.net/dogrula/eposta/es_k2m4n6p8q9r2s3t4u5v6w7x8",
  "header": "X-Damga-Seal: es_k2m4n6p8q9r2s3t4u5v6w7x8",
  "footer_html": "<!--damga-muhur-->…<!--/damga-muhur-->",
  "footer_text": "[damga-muhur]…[/damga-muhur]",
  "credits_charged": 1
}

GET /email-seals/{id} aynı nesneyi döner (yalnız mühürü atan platform). Kanonik biçim, alt bilginin eklenmesi ve doğrulama: E-posta mühürleme.

#Bağlantıyı denemek

GET /ping → {"platform": "Sisteminizin adı", "mode": "live"}

#Hatalar

Hata yanıtları hep aynı biçimdedir:

{ "error": { "code": "validation_failed", "message": "İstek alanları geçersiz.", "fields": { "title": "Belge başlığı 1-250 karakter olmalı." } } }

code değişmez ve programınız ona göre karar verir; message kullanıcıya gösterilebilir Türkçe açıklamadır. Tam liste: Hata kodları.

PAdES ve mühürlerle gelen, kullanıcının imza sayfasında görebileceği kodlar: