Kod örnekleri

Aşağıdaki örneklerin hepsi aynı üç işi yapar: isteği açar, kullanıcıyı gönderir, sonucu okur. API anahtarını ortam değişkeninden (DAMGA_API_KEY) alırlar.

#PHP

Ek paket gerekmez. Depodaki sdk/php/DamgaClient.php aynı işi yapan tek dosyalık istemcidir; aşağıdaki özünü gösterir.

<?php
final class Damga
{
    public function __construct(private string $key, private string $base = 'https://damga.ondiso.net/api/v1') {}

    public function create(string $pdf, string $title, ?string $tc, string $returnUrl, ?string $reference = null): array
    {
        return $this->call('POST', '/sign-requests', array_filter([
            'title' => $title,
            'reference' => $reference,
            'document' => ['content' => base64_encode($pdf), 'filename' => 'belge.pdf'],
            'signer' => $tc ? ['national_id' => $tc] : null,
            'return_url' => $returnUrl,
        ], fn ($v) => $v !== null));
    }

    public function get(string $id): array
    {
        return $this->call('GET', '/sign-requests/' . rawurlencode($id));
    }

    private function call(string $method, string $path, ?array $body = null): array
    {
        $context = stream_context_create(['http' => [
            'method' => $method,
            'header' => "Authorization: Bearer {$this->key}\r\nContent-Type: application/json\r\nAccept: application/json",
            'content' => $body === null ? '' : json_encode($body),
            'timeout' => 30,
            'ignore_errors' => true, // 4xx gövdesini de oku
        ]]);
        $raw = file_get_contents($this->base . $path, false, $context);
        preg_match('#HTTP/\S+ (\d{3})#', $http_response_header[0] ?? '', $m);
        $data = json_decode((string) $raw, true) ?? [];
        if ((int) ($m[1] ?? 0) >= 400) {
            throw new RuntimeException(($data['error']['code'] ?? 'http') . ': ' . ($data['error']['message'] ?? ''));
        }
        return $data;
    }
}

// 1) başlat
$damga = new Damga(getenv('DAMGA_API_KEY'));
$req = $damga->create(file_get_contents('oneri.pdf'), 'Proje öneri formu', '10000000146',
    'https://sisteminiz.ornek/imza-dondu', 'oneri-3');
$_SESSION['damga'] = $req['id'];
header('Location: ' . $req['sign_url'], true, 303);

// 2) dönüş sayfası (imza-dondu)
$r = $damga->get($_GET['damga_request']);
if ($r['status'] === 'completed' && $r['id'] === $_SESSION['damga']) {
    file_put_contents('arsiv/oneri-3.imz', base64_decode($r['signature']['content']));
}

PAdES (imza PDF'in içinde): isteğe 'format' => 'pades' ekleyin; dönüşte .imz yerine imzalı PDF'i indirin.

// create(): 'format' => 'pades', 'appearance' => ['position' => 'bottom-right']
if ($r['status'] === 'completed' && $r['format'] === 'pades') {
    // ikili yanıt (PDF), JSON değil
    $pdf = file_get_contents($r['signature']['download_url'], false, stream_context_create(['http' => [
        'header' => 'Authorization: Bearer ' . getenv('DAMGA_API_KEY'),
    ]]));
    file_put_contents('arsiv/oneri-3-imzali.pdf', $pdf);
}
// sdk/php/DamgaClient.php: $client->downloadSignedDocument($id)

#Node.js (18+)

const BASE = "https://damga.ondiso.net/api/v1";
const headers = { Authorization: `Bearer ${process.env.DAMGA_API_KEY}`, "Content-Type": "application/json" };

async function damga(method, path, body) {
  const res = await fetch(BASE + path, { method, headers, body: body && JSON.stringify(body) });
  const data = await res.json();
  if (!res.ok) throw Object.assign(new Error(data.error.message), { code: data.error.code, status: res.status });
  return data;
}

// Express örneği
app.post("/imza-baslat", async (req, res) => {
  const pdf = await fs.readFile("oneri.pdf");
  const r = await damga("POST", "/sign-requests", {
    title: "Proje öneri formu",
    document: { content: pdf.toString("base64"), filename: "oneri.pdf" },
    signer: { national_id: req.user.tcNo },
    return_url: "https://sisteminiz.ornek/imza-dondu",
    reference: "oneri-3",
  });
  req.session.damga = r.id;
  res.redirect(303, r.sign_url);
});

app.get("/imza-dondu", async (req, res) => {
  const r = await damga("GET", `/sign-requests/${encodeURIComponent(req.query.damga_request)}`);
  if (r.status === "completed" && r.id === req.session.damga) {
    await fs.writeFile("arsiv/oneri-3.imz", Buffer.from(r.signature.content, "base64"));
  }
  res.render("sonuc", { durum: r.status });
});

Bildirim doğrulama:

const crypto = require("node:crypto");
app.post("/damga-bildirim", express.raw({ type: "application/json" }), (req, res) => {
  const { t, v1 } = Object.fromEntries(req.get("Damga-Signature").split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", process.env.DAMGA_WEBHOOK_SECRET).update(`${t}.${req.body}`).digest("hex");
  const ok = v1 && expected.length === v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
  if (!ok || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  // … event.type, event.data.id
  res.sendStatus(200);
});

#Python

import base64, hashlib, hmac, os, time, requests

BASE = "https://damga.ondiso.net/api/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['DAMGA_API_KEY']}"

def create(pdf: bytes, title: str, tc: str, return_url: str) -> dict:
    r = S.post(f"{BASE}/sign-requests", json={
        "title": title,
        "document": {"content": base64.b64encode(pdf).decode(), "filename": "belge.pdf"},
        "signer": {"national_id": tc},
        "return_url": return_url,
    }, timeout=30)
    r.raise_for_status()
    return r.json()

def get(request_id: str) -> dict:
    r = S.get(f"{BASE}/sign-requests/{request_id}", timeout=30)
    r.raise_for_status()
    return r.json()

def webhook_ok(raw_body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    mac = hmac.new(os.environ["DAMGA_WEBHOOK_SECRET"].encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts.get("v1", "")) and abs(time.time() - int(parts["t"])) <= 300

#C# (.NET 6+)

using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient { BaseAddress = new Uri("https://damga.ondiso.net/api/v1/") };
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("DAMGA_API_KEY"));

var created = await http.PostAsJsonAsync("sign-requests", new {
    title = "Proje öneri formu",
    document = new { content = Convert.ToBase64String(await File.ReadAllBytesAsync("oneri.pdf")), filename = "oneri.pdf" },
    signer = new { national_id = "10000000146" },
    return_url = "https://sisteminiz.ornek/imza-dondu"
});
created.EnsureSuccessStatusCode();
var req = await created.Content.ReadFromJsonAsync<JsonElement>();
string signUrl = req.GetProperty("sign_url").GetString()!;

#cURL ile deneme

PDF=$(base64 -w0 oneri.pdf)
curl https://damga.ondiso.net/api/v1/sign-requests -H "Authorization: Bearer $DAMGA_API_KEY" -H "Content-Type: application/json" \
  -d "{\"title\":\"Deneme\",\"document\":{\"content\":\"$PDF\"}}"