Geliştiriciler

Sade bir REST API, imzalı webhooklar

Panelde yapabildiğiniz her şeyi API ile de yapabilirsiniz. Uç noktalar /v1 altında, istek ve yanıtlar JSON, hatalar tek bir biçimde ve Türkçe açıklamalı.

API referansı Test anahtarı isteyin

Tipik bir entegrasyon

1. Belgeyi yükleyin. Yükleme adresini alın, PDF'yi PUT ile gönderin, yüklemeyi tamamlayın.
2. Zarfı oluşturun. Alıcıları, sırayı ve her alıcının işlem türünü tanımlayın.
3. Gönderin. Belge dondurulur, ilk sıradaki alıcılara davet gider.
4. Olayları dinleyin. envelope.completed geldiğinde delil paketini indirin.

Kimlik doğrulama: Authorization: Bearer pk_live_... Anahtarlar kurum panelinden, izin kapsamıyla oluşturulur.

Sayfalama: imleç tabanlı, ?limit=20&cursor=...

Hız sınırı: aşıldığında 429 ve Retry-After başlığı.

Zarf oluşturma ve göndermebash

curl -X POST https://api.yepp.tr/v1/dispatches \
  -H "Authorization: Bearer pk_live_..." \
  -H "Idempotency-Key: 7d1f0c2e-ise-alim-4411" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "İş sözleşmesi - Ayşe Demir",
    "kind": "JOINT",
    "documentMode": "SAME",
    "documentId": "0192c7a4-...",
    "method": "OTP",
    "otpPolicy": "SMS",
    "dueAt": "2026-11-05T17:00:00Z",
    "recipients": [
      { "name": "Can Yılmaz", "email": "can@ornek.com.tr", "phone": "+905321234567" },
      { "name": "Ayşe Demir", "phone": "+905321234568", "inviteChannel": "SMS" }
    ]
  }'

# Taslağı gönderin. Bu adımda PDF dondurulur, doğrulama kodu basılır.
curl -X POST https://api.yepp.tr/v1/dispatches/{id}/send \
  -H "Authorization: Bearer pk_live_..." \
  -H "Idempotency-Key: 7d1f0c2e-ise-alim-4411-send"

Başlıca uç noktalar

Tam liste ve şemalar API referansında. Temel adres: https://api.yepp.tr/v1

API uç noktaları
Yöntem	Yol	Ne işe yarar
POST	/documents/uploads	Yükleme adresi alın, PDF'yi doğrudan depolamaya gönderin
POST	/documents/:id/complete-upload	Yüklemeyi tamamlayın, kontrol ve işleme başlasın
POST	/templates/:id/render	Şablondan değişkenlerle belge üretin
POST	/dispatches	Seri gönderim ya da ortak imza taslağı oluşturun
POST	/dispatches/:id/send	Gönderin; seri gönderimde her alıcıya ayrı zarf açılır
GET	/envelopes/:id	Zarfın ve alıcıların durumunu sorgulayın
GET	/envelopes/:id/timeline	Olay geçmişini alın
POST	/envelopes/:id/remind	Bekleyen alıcılara hatırlatma gönderin
POST	/envelopes/:id/cancel	Zarfı gerekçesiyle iptal edin
GET	/evidence/:packageId/download-url	Delil paketi için süreli indirme adresi alın
POST	/webhooks	Webhook uç noktası tanımlayın

Webhook olayları

Olaylar HMAC-SHA256 ile imzalanır. 2xx dışında bir yanıt ya da 10 saniyelik zaman aşımı yeniden denemeye yol açar. Aynı zarfın olayları sırasıyla teslim edilir.

envelope.sentenvelope.viewedenvelope.completedenvelope.declinedenvelope.expiredenvelope.cancelledrecipient.notifiedrecipient.viewedrecipient.verifiedrecipient.approvedrecipient.signedrecipient.declinedsignature.faileddocument.readydocument.failedevidence.ready

Örnek olay gövdesijson

{
  "id": "evt_000000000123",
  "type": "recipient.approved",
  "createdAt": "2026-10-21T08:15:00.000Z",
  "tenantId": "0192...",
  "data": {
    "envelopeId": "0192...",
    "envelopeCode": "PK-2026-000123",
    "recipientId": "0192...",
    "status": "APPROVED"
  }
}

İmza doğrulama (Node.js)ts

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyYeppWebhook(rawBody: string, headers: Headers, secret: string) {
  const timestamp = headers.get("Yepp-Timestamp") ?? "";
  const signature = (headers.get("Yepp-Signature") ?? "").replace(/^v1=/, "");

  // 5 dakikadan eski olayları reddedin
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Idempotency-Key

Zarf oluşturma, gönderme ve yükleme isteklerinde 24 saat boyunca aynı anahtar aynı sonucu döner.

Hata biçimi

Her hata { error: { code, message, details, requestId } } biçimindedir. requestId'yi destek talebinize ekleyin.

Sürümleme

Kırıcı değişiklikler /v2 ile gelir. Mevcut sürüm, yenisi çıktıktan sonra da bir süre desteklenir.

Entegrasyonunuzu birlikte planlayalım

Hangi sistemden hangi belgeyi göndereceğinizi anlatın, size test anahtarı ve örnek akış hazırlayalım.

Demo isteyin Ücretsiz hesap açın