REST API (v1)
Tüm temel kaynaklar: kuruluşlar, kullanıcılar, kurslar, yollar, kayıtlar, sertifikalar, onaylar. /api/openapi.json adresinde tipli OpenAPI 3.1 şeması. Kiracı başına hız sınırlıdır (cömert).
Geliştiriciler
Sizin altyapınızın dilini konuşan bir LMS
ColPort Hall kutudan çıktığı gibi tipli bir REST API, imzalı webhook'lar, native xAPI / Tin Can iletimi ve OIDC SSO sunar. Her uç nokta OpenAPI 3.1 ile belgelenmiştir. Her müşteri ücretsiz bir sandbox kiracı talep edebilir.
Temel API'ler
Entegre olmanın dört yolu
Webhook'lar
Her önemli olayda imzalı webhook'lar (HMAC-SHA256): enrolment.created, course.completed, certificate.issued, compliance.gap_detected. 72 saat boyunca üstel geri çekilmeyle tekrar denenir.
xAPI ifade akışı
Her öğrenme olayı gerçek zamanlı olarak xAPI ifadeleri yayar. Bunları giden webhook üzerinden kendi LRS'inize akıtın veya xAPI GET uç noktasını yoklayın. SCORM çalışma zamanı olayları da xAPI'ye çevrilir.
OIDC SSO + İK webhook'u
Microsoft Entra ID, Google Workspace ve Okta için hazır ayarlarla ya da herhangi bir OpenID Connect sağlayıcısıyla OIDC tek oturum açma. HMAC-SHA256 ile imzalanan bir İK webhook'u, employee.hired ve employee.updated olaylarını alır.
Hızlı başlangıç
İlk API çağrınız, ~60 saniye
Sandbox provizyonundan sonra bir kiracı URL'si ve kişisel bir API token'ı alırsınız. Aşağıdaki
$TOKEN ve $TENANT değerlerini değiştirin. Bu çağrı, kiracınızdaki ilk on kursu listeler.curl -X GET "https://$TENANT.hall.colport.io/api/v1/courses?limit=10" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
# Response (trimmed):
# {
# "data": [
# {
# "id": "crs_01H...",
# "title": "GDPR awareness 2026",
# "status": "PUBLISHED",
# "durationMinutes": 25,
# "enrollments_count": 184,
# "createdAt": "2026-01-14T09:42:00Z"
# }
# ],
# "pagination": { "nextCursor": null, "limit": 10 }
# }xAPI örneği
Bir öğrenme olayı nasıl görünür
Bir öğrenen bir kursu her tamamladığında Hall bir xAPI İfadesi yayar. JSON-LD tüketen her şeye, LRS'inize, veri ambarınıza veya alt analitiklerinize akıtın.
POST https://your-lrs.example.com/xapi/statements
{
"actor": {
"account": { "homePage": "https://hall.colport.io", "name": "usr_01H..." },
"name": "Jan de Vries"
},
"verb": {
"id": "http://adlnet.gov/expapi/verbs/completed",
"display": { "en": "completed" }
},
"object": {
"id": "https://hall.colport.io/courses/crs_01H...",
"definition": {
"name": { "en": "GDPR awareness 2026" },
"type": "http://adlnet.gov/expapi/activities/course"
}
},
"result": { "score": { "scaled": 0.92, "raw": 46, "max": 50 }, "completion": true, "success": true },
"timestamp": "2026-04-21T14:22:18Z"
}Sınırlar + kurallar
Hall'a karşı geliştirme yapmak için bilmeniz gerekenler
Hız sınırları
REST'te kiracı başına dakikada 1.000 istek. xAPI'de dakikada 10.000 ifade. Webhook yeniden denemeleri kotanıza dahil değildir. Enterprise seviyesi üst sınırı yükseltir.
Sürümleme
v1 stabildir. Kırıcı değişiklikler, 12 aylık paralel çalıştırma penceresiyle v2 olarak sunulur. Kullanımdan kaldırmalar bir geçiş kılavuzuyla 90 gün önceden duyurulur.
Kimlik doğrulama
Sunucudan sunucuya için Bearer token'lar. Kendi kuruluşunuz için geliştirdiğiniz entegrasyonlar için PAT (kişisel erişim token'ları). Son kullanıcı tarafından yetkilendirilmiş üçüncü taraflar için OAuth 2.0 (Enterprise).
İdempotans
Idempotency-Key başlığı yoktur. İki uç nokta güvenle tekrarlanabilir: POST /api/v1/users ve POST /api/v1/enrollments, zaten var olan üyeyi veya kaydı created: false ile döndürür. Devre dışı bırakılmış bir üye istisnadır: böyle bir üyeyi kaydetmek her seferinde 410 deactivated yanıtını verir. Webhook teslimatları sabit bir olay kimliği taşımaz: X-ColPort-Delivery, yeniden denemeler dahil her denemede yenidir.
Referans
Belgeler nerede
OpenAPI 3.1 şeması
Her kiracıda /api/openapi.json adresinde mevcuttur. openapi-generator aracılığıyla herhangi bir büyük dilde tipli bir istemci oluşturur.
Webhook olay kataloğu
Her webhook olayının yük şemalarıyla birlikte canlı düzenlenen kataloğu. Yönetici Entegrasyonlar sayfasından bağlantılıdır.
xAPI profili
ColPort Hall belgelenmiş bir xAPI profili yayar: fiil uzantıları, bağlam uzantıları, etkinlik türleri. Araçlar arasında paylaşılan bir LRS'ye standartlaştırıyorsanız faydalıdır.
Sandbox kiracılar
Talep üzerine ücretsiz sandbox kiracı (sınırsız test koltuğu, tam özellik seti, haftalık sıfırlanır). CI entegrasyon testleri için idealdir.
Geliştirmeye hazır mısınız?
Kullanım senaryonuz ve kaba bir mimariyle devs@colport.io adresine e-posta gönderin. Sandbox kimlik bilgilerini 1 iş günü içinde teslim ederiz.
Demo talep edin