API Referansı

Base URL: https://heptacert.com/api

Tüm istekler HTTPS üzerinden yapılmalı ve Authorization: Bearer hc_live_... başlığı içermelidir. İstek/yanıt gövdeleri JSON'dur (Content-Type: application/json).

Tam, makine-okunur OpenAPI spesifikasyonu https://heptacert.com/api/openapi.json adresinde yayınlanır. Postman/Insomnia'ya içe aktarabilir veya ChatGPT Actions ile kullanabilirsiniz.

Konvansiyonlar

Sayfalama (Pagination)

Liste döndüren endpoint'ler page ve limit sorgu parametrelerini destekler:

Parametre	Tip	Varsayılan	Açıklama
`page`	int	`1`	1'den başlayan sayfa numarası
`limit`	int	`20`	Sayfa başına kayıt (üst sınır genellikle `200`)
`search`	string	—	Destekleyen endpoint'lerde isim/e-posta filtresi

limit üst sınırı aşan değerler sınıra çekilir. Çok sayıda kayıt çekerken limit'i yükseltip sayfa sayısını azaltmak daha verimlidir.

Tarih/Saat

Tüm zaman damgaları ISO 8601 formatındadır. Yazma işlemlerinde naive (saat dilimsiz) ISO değeri gönderebilirsiniz (2026-09-15T09:00:00); okuma yanıtlarında zaman damgaları UTC olarak döner.

İdempotanlık

POST ile kaynak oluşturmada, çakışan benzersiz alanlar (örn. bir etkinlikte aynı e-posta) 409 Conflict döner — tekrar denemek yeni kayıt oluşturmaz. Yeniden deneme mantığı yazarken bu davranışa güvenebilirsiniz.

Hata Modeli

Hatalar uygun HTTP durum kodu ve JSON gövdesiyle döner:

{ "detail": "Bu etkinliğe ait kayıt bulunamadı." }

HTTP	Anlamı
`400`	Geçersiz istek — eksik/hatalı alan
`401`	Kimlik doğrulama başarısız — geçersiz/eksik anahtar
`402`	Yetersiz bakiye (örn. toplu üretim için HeptaCoin)
`403`	Yetkisiz — gerekli scope eksik
`404`	Kayıt bulunamadı
`409`	Çakışma — kayıt zaten var
`413`	Yük çok büyük (örn. 5 MB üstü Excel)
`422`	Doğrulama hatası — alan tipleri/kuralları
`429`	Hız sınırı aşıldı
`500`	Sunucu hatası

422 doğrulama hataları, hatalı alanların listesini içerir:

{
  "detail": [
    { "loc": ["body", "email"], "msg": "value is not a valid email", "type": "value_error.email" }
  ]
}

Etkinlikler

`GET /admin/events`

Hesabınızdaki tüm etkinlikleri listeler.

Parametre	Tip	Açıklama
`search`	string	İsim filtresi

Yanıt:

[
  {
    "id": 42,
    "name": "Python Summit 2026",
    "event_date": "2026-09-15T09:00:00",
    "event_type": "conference",
    "visibility": "public",
    "certificate_enabled": true,
    "registration_enabled": true,
    "registration_closed": false,
    "checkin_enabled": true,
    "attendee_count": 150
  }
]

`GET /admin/events/{id}`

Tek etkinliğin tam detayını getirir. Bulunamazsa 404.

`POST /admin/events`

Yeni etkinlik oluşturur.

İstek gövdesi:

{
  "name": "React Workshop",
  "template_image_url": "placeholder",
  "event_type": "workshop",
  "event_date": "2026-10-01T10:00:00",
  "event_location": "İstanbul",
  "event_description": "İleri seviye React eğitimi.",
  "certificate_enabled": true,
  "registration_enabled": true,
  "checkin_enabled": true,
  "visibility": "private"
}

name zorunludur. template_image_url zorunludur; gerçek şablonu editörden sonra ayarlayacaksanız geçici "placeholder" değeri verebilirsiniz.

`PATCH /admin/events/{id}`

Etkinliği günceller. Yalnızca gönderilen alanlar değişir (partial update).

`DELETE /admin/events/{id}`

Etkinliği kalıcı olarak siler. Geri alınamaz — ilişkili katılımcılar, sertifikalar ve oturumlar da silinir.

`POST /admin/events/{id}/close-registration` · `.../open-registration`

Kayıt formunu kapatır/açar (registration_closed bayrağını değiştirir).

Gerekli scope: okuma için events:read, yazma/silme için events:write.

Katılımcılar

`GET /admin/events/{id}/attendees`

Parametre	Tip	Açıklama
`page`	int	Sayfa numarası
`limit`	int	Sayfa başına kayıt (maks. 200)
`search`	string	İsim veya e-posta filtresi

`POST /admin/events/{id}/attendees`

Tek katılımcı ekler. Aynı e-posta varsa 409.

{ "first_name": "Ahmet", "last_name": "Yılmaz", "email": "ahmet@example.com" }

`PATCH /admin/events/{event_id}/attendees/{attendee_id}`

Katılımcı bilgilerini günceller (first_name, last_name, email).

`DELETE /admin/events/{event_id}/attendees/{attendee_id}`

Katılımcıyı etkinlikten kaldırır.

Gerekli scope: attendees:read / attendees:write.

Sertifikalar

`GET /admin/events/{id}/certificates`

Parametre	Tip	Açıklama
`page` / `limit`	int	Sayfalama
`search`	string	İsim filtresi
`status`	string	`active` \| `revoked` \| `expired`

`POST /admin/events/{id}/certificates`

Sertifika yayımlama işlemi başlatır.

{ "attendee_ids": [1, 2, 3] }

attendee_ids boş bırakılırsa tüm uygun katılımcılar için yayımlanır. Bu işlem cert.issued webhook'unu tetikler.

`POST /admin/certificates/{cert_id}/revoke`

Sertifikayı iptal eder. Doğrulama sayfası "geçersiz" gösterir. cert.revoked webhook'unu tetikler.

`GET /admin/events/{id}/certificate-tiers/summary`

Kademe bazında sertifika dağılımını ve yüzdelerini döner.

Gerekli scope: certificates:read / certificates:write.

Toplu Sertifika Üretimi

Bir Excel listesinden yüzlerce sertifikayı asenkron olarak üretir. İşlem bir iş (job) olarak çalışır; durumu sorgulayıp tamamlanınca ZIP indirebilirsiniz.

`POST /admin/events/{id}/bulk-generate`

multipart/form-data ile bir .xlsx dosyası yükler. İlk uygun sütun (name, isim, ad soyad, full_name...) isim olarak kullanılır.

Maksimum dosya boyutu: 5 MB (aşılırsa 413)
Maksimum isim sayısı: 1000
Yetersiz HeptaCoin bakiyesi → 402

Yanıt, oluşturulan iş nesnesini (status: "pending") döner.

`GET /admin/events/{id}/bulk-generate-jobs`

Bu etkinlik için son işleri listeler (en yeni 30).

`GET /admin/events/{id}/bulk-generate-jobs/{job_id}`

Tek işin durumunu döner: pending → processing → completed / failed / cancelled.

`POST /admin/events/{id}/bulk-generate-jobs/{job_id}/cancel`

Devam eden bir işi iptal eder. Tamamlanmış işler iptal edilemez (400).

`GET /admin/events/{id}/bulk-generate-jobs/{job_id}/download`

Tamamlanmış işin ZIP'ini indirir. İş bitmemişse 409. İş tamamlandığında cert.bulk_completed webhook'u tetiklenir.

Oturumlar (Agenda)

`GET /admin/events/{id}/sessions`

Etkinliğin oturumlarını listeler.

`POST /admin/events/{id}/sessions`

{
  "title": "Keynote: Web'in Geleceği",
  "start_time": "2026-09-15T09:00:00",
  "end_time": "2026-09-15T10:00:00",
  "location": "Ana Salon",
  "speaker": "Dr. Ayşe Kaya",
  "capacity": 300
}

`PATCH /admin/events/{event_id}/sessions/{session_id}`

`DELETE /admin/events/{event_id}/sessions/{session_id}`

Check-in

Check-in oturum düzeyinde yapılır.

`GET /admin/events/{id}/checkin-lookup`

Parametre	Tip	Açıklama
`query`	string	İsim veya e-posta araması

`POST /admin/events/{event_id}/sessions/{session_id}/checkin`

Belirli bir oturuma manuel check-in yapar.

{ "email": "ahmet@example.com" }

`GET /admin/events/{id}/attendance`

Devam istatistiklerini döner: toplam, check-in yapan, oran ve oturum bazlı dağılım.

Anketler & Rozetler

`GET /admin/events/{id}/survey-responses`

Etkinlik anketine verilen yanıtları döner.

`GET /admin/badge-templates`

Tanımlı rozet şablonlarını listeler.

Bu kaynaklar otomasyon tetikleyicilerini besler (survey_not_completed, badge_earned).

Otomasyon Kuralları

`GET /admin/events/{id}/automations`

`POST /admin/events/{id}/automations`

{
  "name": "Sertifika Sonrası E-posta",
  "trigger": "certificate_issued",
  "actions": [
    { "type": "send_email", "template_id": 5, "delay_hours": 0 }
  ],
  "enabled": true
}

`PATCH /admin/events/{event_id}/automations/{rule_id}`

`DELETE /admin/events/{event_id}/automations/{rule_id}`

Trigger tipleri: attended_event, registered_no_show, certificate_issued, survey_not_completed, badge_earned, lms_course_completed, compliance_overdue

Analitik

`GET /admin/events/{id}/analytics`

Tek etkinlik için detaylı metrikler.

Organizasyon düzeyi raporlar

Endpoint	İçerik
`GET /admin/analytics/org/overview`	Genel bakış metrikleri
`GET /admin/analytics/org/cert-timeline`	Sertifika yayımlama zaman çizelgesi
`GET /admin/analytics/org/crm`	CRM özet metrikleri
`GET /admin/analytics/org/training-compliance`	Eğitim uyum durumu

Gerekli scope: analytics:read.

CRM

Etkinliklerden bağımsız kişi/şirket katmanı (bkz. Temel Kavramlar).

Endpoint	İşlem
`GET /admin/crm/accounts`	Hesapları (şirketleri) listele
`GET /admin/crm/accounts/{id}/contacts`	Hesabın kişilerini listele
`GET /admin/crm/accounts/{id}/deals`	Hesabın fırsatlarını listele
`POST /admin/crm/import-csv`	CSV ile toplu kişi içe aktar
`POST /admin/crm/lead-scores/recalculate`	Lead skorlarını yeniden hesapla
`GET /admin/crm/duplicates`	Olası mükerrer kayıtları bul
`POST /admin/crm/merge`	Mükerrer kayıtları birleştir

Gerekli scope: crm:read / crm:write.

API Anahtarı Yönetimi

Endpoint	İşlem
`GET /admin/api-keys`	Anahtarları listele (yalnızca prefix görünür)
`POST /admin/api-keys`	Yeni anahtar oluştur (tam değer bir kez döner)
`GET /admin/api-keys/scopes`	Geçerli scope listesini al
`PATCH /admin/api-keys/{id}`	İsim/scope/aktiflik güncelle
`DELETE /admin/api-keys/{id}`	Anahtarı sil

Webhook Yönetimi

Endpoint	İşlem
`GET /admin/webhooks`	Endpoint'leri listele
`POST /admin/webhooks`	Endpoint oluştur (secret üretilir)
`DELETE /admin/webhooks/{id}`	Endpoint sil

Payload formatı, imza doğrulama ve yeniden deneme politikası için Webhooks sayfasına bakın.

Halka Açık Sertifika Doğrulama

Sertifika doğrulama herkese açıktır ve kimlik doğrulama gerektirmez:

https://heptacert.com/verify/{cert_uuid}

Bu sayfa sertifikanın geçerli (active), iptal edilmiş (revoked) veya bulunamadığını gösterir. Üçüncü taraflar (işverenler, kurumlar) bir sertifikanın gerçekliğini bu link üzerinden doğrulayabilir. MCP üzerinden get_certificate_by_public_id aracıyla da programatik doğrulama yapılabilir.

SSO / OAuth2 Kimlik Doğrulama

API Referansı

Konvansiyonlar

Sayfalama (Pagination)

Tarih/Saat

İdempotanlık

Hata Modeli

Etkinlikler

GET /admin/events

GET /admin/events/{id}

POST /admin/events

PATCH /admin/events/{id}

DELETE /admin/events/{id}

POST /admin/events/{id}/close-registration · .../open-registration

Katılımcılar

GET /admin/events/{id}/attendees

POST /admin/events/{id}/attendees

PATCH /admin/events/{event_id}/attendees/{attendee_id}

DELETE /admin/events/{event_id}/attendees/{attendee_id}

Sertifikalar

GET /admin/events/{id}/certificates

POST /admin/events/{id}/certificates

POST /admin/certificates/{cert_id}/revoke

GET /admin/events/{id}/certificate-tiers/summary

Toplu Sertifika Üretimi

POST /admin/events/{id}/bulk-generate

GET /admin/events/{id}/bulk-generate-jobs

GET /admin/events/{id}/bulk-generate-jobs/{job_id}

POST /admin/events/{id}/bulk-generate-jobs/{job_id}/cancel

GET /admin/events/{id}/bulk-generate-jobs/{job_id}/download