CEPA Test API

CEPA Test Entegrasyonu Genel Bilgiler
Bu adımda CEPA Test entegrasyonuna ilişkin genel bilgileri bulabilirsiniz.
Giriş
CEPA Test’s API, üretilmiş test token'larına ulaşabilmenize, adayların test sonuçlarını ve diğer bilgilerine ulaşabilmenizi ve frame olarak test ekranı oluşturabilmenizi sağlar. Bu web servis, REST / JSON tabanl olup, yakın zamanda XML (Soap) desteği ile de yayında olacaktır.
CEPA Test API v1 desteği 1 Aralık 2023 tarihinde sonlandırılacaktır. CEPA Test API v2'ye göz atmak için tıklayınız.
Güvenlik
Entegrasyon Rest yapısına " Basic Auth " güvenlik kontrol yapısı ile kolayca bağlanılıp veri çekilebilmektedir. Her test token'ı üretebilen kurum için kullanıcı adı ve parola tanımlanmaktadır. Örneğin: A şirketi için veri okuma işlemi yapılırken "login" ve "password" bu kurum için tanımlanan benzersiz şifreyi gerekli kılmaktadır.
CEPA Test Security
API Hangi Platformlarda Kullanabilirsiniz?
CEPA Test API'ı Web ve Mobile Web platformlarında entegre olabilirsiniz.
RestAPI/JSON Veri akış şeması
API
Entegrasyon Adımları
Aşağıdaki demo bağlantı bilgileri ile Postman uygulamasıyla API sistemine bağlantı kurun:
Login : api
Password : api
GET https://britishside.org/CEPATest/Integration/RestAPI/GetTokens
Bu bağlantının GET metoduyla yapılması gerekmektedir. Farklı bir uygulamadan bağlantı kurabilmek için "Header" ile login ve parola tanımlanarak/göndererek bağlantı kurulması gerekmektedir. Aksi takdirde bağlantı istekleri "Not authorized" yanıtı alacaktır.

Bağlantı işlemini sorunsuz bir şekilde gerçekleştirdiğinizde, sağ tarafta konsolda görüntülediğiniz gibi bir çıktı verecektir.

Metotlar
GetTokens
GET https://britishside.org/CEPATest/Integration/RestAPI/GetTokens
Bu metotla header'a gönderilen login bilgilerine ait kurumun/şirkete tanımlanmış tüm test kodları listelenmektedir. Response ile döndürülen verilerin detaylı tablosu aşağıdaki gibidir:
Parametre Veri Türü Açıklama
Rank integer Döngüdeki kaydın sırasını ifade eder.
UserID integer Adayın veritabanına kayıtlı unique (benzersiz) kullanıcı Id'sini ifade eder.
TestID integer Adayın aldığı testin CEPA Test sistemindeki Id karşılığını ifade eder.
TestName string Adayın aldığı/tamamladığı testin CEPA Test sistemindei tam adını ifade eder.
Issuer string Adaya test için token üretmiş ve tanımlamış kurumun bilgisini ifade eder.
Name string Testi alan/tamamlayan adayın kimliğinde/pasaportunda yer aldığı gibi adını ifade eder.
Lastname string Testi alan/tamamlayan adayın kimliğinde/pasaportunda yer aldığı gibi soyadını ifade eder.
Email string Adayın test token'ı tanımlanan e-posta adresini ifade eder.
CompleteDate datetime Adayın test(ler)'ini tamamladığı tarihi ve saati ifade eder.
OverallScore integer Adayın tamamladığı testin skor bazında sonucunu ifade eder.
CefrLevel string Adayın tamamladığı testin CEFR standartları karşılığı seviyesini ifade eder.
CefrDescription string Adayın tamamladığı testin CEFR standartları karşılığını ifade eder.
Demo boolean Tanımlanan token'ın demo/test olup olmadığı ifade eder. Eğer test demo ise "true" değil ise "false" değeri döndürür.
CreateDate datetime Kurum için üretilmiş boş token'ların veritabanına kayıt tarihini ifade eder.
GetCandidates
GET https://britishside.org/CEPATest/Integration/RestAPI/GetCandidates
Bu metotla header'a gönderilen login bilgilerine ait kurumun/şirket adına teste katılan/tamamlayan tüm adayların bilgisi çekilebilmektedir. Response ile döndürülen verilerin detaylı tablosu aşağıdaki gibidir:
Parametre Veri Türü Açıklama
Rank integer Döngüdeki kaydın sırasını ifade eder.
Email string Adayın test token'ı tanımlanan e-posta adresini ifade eder.
Issuer string Adaya test için token üretmiş ve tanımlamış kurumun bilgisini ifade eder.
Tokens array Adayın aldığı/tamamladığı tüm testleri listeler.
TestName string Adayın aldığı/tamamladığı testin CEPA Test sistemindei tam adını ifade eder.
CompleteDate datetime Adayın test(ler)'ini tamamladığı tarihi ve saati ifade eder.
OverallScore integer Adayın tamamladığı testin skor bazında sonucunu ifade eder.
CefrLevel string Adayın tamamladığı testin CEFR standartları karşılığı seviyesini ifade eder.
CefrDescription string Adayın tamamladığı testin CEFR standartları karşılığını ifade eder.
Demo boolean Tanımlanan token'ın demo/test olup olmadığı ifade eder. Eğer test demo ise "true" değil ise "false" değeri döndürür.
CreateDate datetime Kurum için üretilmiş boş token'ların veritabanına kayıt tarihini ifade eder.
GetCandidateByEmail
GET https://britishside.org/CEPATest/Integration/RestAPI/GetCandidateByEmail/email@email.com
Bu metotla e-mail adresi ile aday bazlı veri çekilebilmektedir. Response ile döndürülen verilerin detaylı tablosu aşağıdaki gibidir:
Parametre Veri Türü Açıklama
Rank integer Döngüdeki kaydın sırasını ifade eder.
Email string Adayın test token'ı tanımlanan e-posta adresini ifade eder.
Issuer string Adaya test için token üretmiş ve tanımlamış kurumun bilgisini ifade eder.
Tokens array Adayın aldığı/tamamladığı tüm testleri listeler.
TestID integer Adayın aldığı testin CEPA Test sistemindeki Id karşılığını ifade eder.
TestName string Adayın aldığı/tamamladığı testin CEPA Test sistemindei tam adını ifade eder.
TestStatus string Aday testi tamamladığında Completed henüz tamamlamadığında ise Incomplete olarak görünür.
CompleteDate datetime Adayın test(ler)'ini tamamladığı tarihi ve saati ifade eder.
OverallScore integer Adayın tamamladığı testin skor bazında sonucunu ifade eder.
CefrLevel string Adayın tamamladığı testin CEFR standartları karşılığı seviyesini ifade eder.
CefrDescription string Adayın tamamladığı testin CEFR standartları karşılığını ifade eder.
Assessment string Assessor değerlendirmesine giren testlerin değerlendirme durumunu ifade eder. Test değerlendirmesi tamamladığında Completed henüz tamamlamadığında ise Incomplete olarak görünür.
AssessmentDeadline datetime Assessor değerlendirmesine giren testlerin değerlendirme süresini ifade eder. Değerlendirmeler en geç bu tarihe kadar tamamlanmaktadır. Değerlendirme süresi testin tamamlanmasından itibaren 48 saattir.
SecurityChecks boolean Adayın tamamlanan testinin video/ses güvenlik kontrolü ve onayının durumunu ifade eder. Kontrol tamamlandığında true henüz tamamlanmadığında ise false olarak görünür.
Photo string Adayın teste giriş yapmadan önce kayıt esnasında sisteme kayıt ettiği kimlik belge ibrazlı fotoğrafını gösterir.
Demo boolean Tanımlanan token'ın demo/test olup olmadığı ifade eder. Eğer test demo ise "true" değil ise "false" değeri döndürür.
CreateDate datetime Kurum için üretilmiş boş token'ların veritabanına kayıt tarihini ifade eder.
TestsOverallResult array Adaya test için token üretmiş ve tanımlamış kurumun bilgisini ifade eder.
OverallScore integer Reading & Listening ve Speakig test sonuçlarının overall sonucunu ifade eder.
CefrLevel string Overall sonucun Common European Framework of Reference for Languages (CEFR) sonucunu ifade eder.
CefrDescription string Overall sonucun Common European Framework of Reference for Languages (CEFR) sonucunu seviye olarak ifade eder.
Status boolean Overall score başarıyla oluşturulduysa status değeri "true" olarak, oluşturulamamış ise "false" olarak dönecektir.
StatusDescription string Overal score sonuç durumunun açıklama metni.
GetTestResultsByToken

Bu metotla belirtilen Token'a ait test durumu bilgileri gelir. Testin anlık durumunu, adayın bilgileri ve test sonucuyla ilgili durum kontrolünü yapmak için bu metot kullanılabilir. Response ile döndürülen verilerin detaylı tablosu aşağıdaki gibidir:

GET https://britishside.org/CEPATest/Integration/RestAPI/GetTestResultsByToken / { Token }
Parametre Veri Türü Açıklama
Rank integer Döngüdeki kaydın sırasını ifade eder.
UserID integer Adayın veritabanına kayıtlı unique (benzersiz) kullanıcı Id'sini ifade eder.
TestID integer Adayın aldığı testin CEPA Test sistemindeki Id karşılığını ifade eder.
TestName string Adayın aldığı/tamamladığı testin CEPA Test sistemindei tam adını ifade eder.
Issuer string Adaya test için token üretmiş ve tanımlamış kurumun bilgisini ifade eder.
Name string Testi alan/tamamlayan adayın kimliğinde/pasaportunda yer aldığı gibi adını ifade eder.
Lastname string Testi alan/tamamlayan adayın kimliğinde/pasaportunda yer aldığı gibi soyadını ifade eder.
Email string Adayın test token'ı tanımlanan e-posta adresini ifade eder.
Photo string Adayın teste giriş yapmadan önce kayıt esnasında sisteme kayıt ettiği kimlik belge ibrazlı fotoğrafını gösterir.
TestStatus string Aday testi tamamladığında Completed henüz tamamlamadığında ise Incomplete olarak görünür.
CompleteDate datetime Adayın test(ler)'ini tamamladığı tarihi ve saati ifade eder.
OverallScore integer Adayın tamamladığı testin skor bazında sonucunu ifade eder.
CefrLevel string Adayın tamamladığı testin CEFR standartları karşılığı seviyesini ifade eder.
CefrDescription string Adayın tamamladığı testin CEFR standartları karşılığını ifade eder.
Assessment string Assessor değerlendirmesine giren testlerin değerlendirme durumunu ifade eder. Test değerlendirmesi tamamladığında Completed henüz tamamlamadığında ise Incomplete olarak görünür.
AssessmentDeadline datetime Assessor değerlendirmesine giren testlerin değerlendirme süresini ifade eder. Değerlendirmeler en geç bu tarihe kadar tamamlanmaktadır. Değerlendirme süresi testin tamamlanmasından itibaren 48 saattir.
SecurityChecks boolean Adayın tamamlanan testinin video/ses güvenlik kontrolü ve onayının durumunu ifade eder. Kontrol tamamlandığında true henüz tamamlanmadığında ise false olarak görünür.
Demo boolean Tanımlanan token'ın demo/test olup olmadığı ifade eder. Eğer test demo ise "true" değil ise "false" değeri döndürür.
CreateDate datetime Kurum için üretilmiş boş token'ların veritabanına kayıt tarihini ifade eder.
GetPDFTestReportByToken

Bu metotla seçilen Token testini tamamladıysa global ve assessment raporlarını PDF dosyası oluşturacak şekilde base64 encoded olarak getirmekteir. Response ile döndürülen verilerin detaylı tablosu aşağıdaki gibidir:

GET https://britishside.org/CEPATest/Integration/RestAPI/GetPDFTestReportByToken / { Token }
Parametre Veri Türü Açıklama
TestTaker string Test adayının ad ve soyadını ifade eder.
TestName string Adayın tamamladığı testin tam adını ifade eder.
base64 base64 Adayın test sonucunun PDF dosyası oluşturacak şekilde base64 encode edilmiş içerik getirilir.
GetTestReportsByToken

Bu metotla seçilen Token testini tamamladıysa global ve assessment raporlarını getirmekteir. Response ile döndürülen verilerin detaylı tablosu aşağıdaki gibidir:

GET https://britishside.org/CEPATest/Integration/RestAPI/GetTestReportsByToken / { Token }
Parametre Veri Türü Açıklama
TestTaker string Test adayının ad ve soyadını ifade eder.
TestName string Adayın tamamladığı testin tam adını ifade eder.
Reports array Test rapor içeriğini belirtir.
AssessmentRationale string Yalnızca değerlendirme yapılan testler için rapor içermektedir. (Örn. Speaking, Writing) testleri.
GlobalDescriptions array Adayın test sonucu ve CEFR seviyesine göre otomatik oluşturulan raporlar.
UnderstandingTheResults array Adayın test sonucu ve CEFR seviyesine göre otomatik oluşturulan raporlar.
GetTests
Bu metotla CEPA Testlerini listeleyebilirsiniz. Response ile döndürülen verilerin detaylı tablosu aşağıdaki gibidir:
Parametre Veri Türü Açıklama
TestID integer Testin CEPA Test veritabanındaki unique (benzersiz) Id'sini ifade eder.
Duration string Testin yaklaşık süresini ifade eder.
AvailableTokens integer Kurumun üretebileceği test token'ı sayısını ifade eder.
UsedTokens integer Kurumun daha önce üretip kullanmış olduğu test token sayısını ifade eder.
CreateTokenByTestId
POST https://britishside.org/CEPATest/Integration/RestAPI/CreateTokenByTestId / { testId }

Bu metotla kurum/şirket adına eğer test üretebilecek token kredisi var ise test token'ı oluşturulabilmektedir. GetTests metodu ile token üretilebilecek testler listelenebilir, mevcut üretilebilecek test kredisi görüntülenebilir.

Token üretebilmek için body içeriğinde form-data olarak aşağıdaki tablodaki parametre ve metotlarla request işlemi yapmanız gerekmektedir.

Key Value Require Description
email string YES Token üretilecek adayın e-mail adresi. Bu e-mail adresine davet e-maili gönderilecektir.
emailsend integer Optional Üretilecek token için adaya davet e-maili gönderilip gönderilmeyeceğini belirler. Gönderim yapılacak ise değeri "1" olmalıdır, yapılmayacak ise boş bırakılabilir.
client integer YES Üretilecek token'ın hangi API Client tarafından üretildiğini ifade eder.
test_version integer Optional Üretilecek token'ın hangi test versiyonu iletıleceğini belirtir. Default Test değeri '0'. Short Test versiyonu için bu değeri '2' gönderilmelidir.
name string Optional Token üretilecek adayın adı.
lastname string Optional Token üretilecek adayın soyadı.
deadline_start datetime Optional Token üretilecek adayın teste en erken girebileceği tarihi ve saati ifade eder. Format: YYYY-mm-dd H:i:s
deadline_end datetime Optional Token üretilecek adayın testi tamamlaması gereken en geç tarihi ve saati ifade eder. Format: YYYY-mm-dd H:i:s

Postman uygulamasıyla örnek post ekranı aşağıdaki gibi olacaktır.

Post sonucunda JSON çıktısı aşağıdaki gibi olacaktır:
Parametre Veri Türü Açıklama
TestID integer Testin CEPA Test veritabanındaki unique (benzersiz) Id'sini ifade eder.
TestName string Adaya tanımlanan testin CEPA Test sistemindei tam adını ifade eder.
Name string Adaya tanımlanan kimliğinde/pasaportunda yer aldığı gibi adını ifade eder.
Lastname string Adaya tanımlanan kimliğinde/pasaportunda yer aldığı gibi soyadını ifade eder.
Email string Adayın test token'a tanımlanan e-posta adresini ifade eder.
Issuer string Adaya test için token üretmiş ve tanımlamış kurumun bilgisini ifade eder.
StartDeadline datetime Token üretilecek adayın teste en erken girebileceği tarihi ve saati ifade eder. Format: YYYY-mm-dd H:i:s
EndDeadline datetime Token üretilecek adayın testi tamamlaması gereken en geç tarihi ve saati ifade eder. Format: YYYY-mm-dd H:i:s
AvailableToken integer Adaya test için tanımlanmış token'ı ifade eder. Her bir Request işleminde yeni bir token tanımlanacaktır.
CreateDate datetime Adaya test için tanımlanan token'ın veritabanında oluşturulma tarihini ifade eder.
Status string İşlemin sonucunu ifade eder. Success döndürülen her işlemin sonucu başarılı şekilde tamamlandığını ifade eder.
CreateTestFrameByToken
HTTP https://www.cepatest.org/Online?TokenID= { token }
Sisteme tanımlamış olan Secure URL üzerinden gelen iFrame ekran talepleri otomatik sınav oturumunu oluşturacaktır. Secure URL tanımlamaları için cepa@britishside.com adresine e-mail atmanız gerekmektedir. Örnek ekran oluşturma linki: iFrame ekranının güvenli bir biçimde oluşturabilmesi için aşağıdaki verilerle Request yapılması gerekmektedir.

Aşağıdaki linkten demo test bağlantısını inceleyebilirsiniz:

DEMO http://britishside.com/CEPADemo
Parametre Veri Türü Açıklama
Token integer Test oturumu oluşturulacak token değerini ifade eder.
ApiKey string Size özel oluşturulan key ile bağlantı isteği oluşturulur. Aksi takdirde oturum açılmaz. Bu keyi cepa@britishside.com adresine e-mail atarak talep etmeniz gerekmektedir.
Bu işlem için ayrıca Auth işlemine gerek yoktur. ApiKey ile doğrulama yapılmaktadır.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

JSON başarılı yanıt çıktısı: 
{
    "495830": {
        "Rank": "1",
        "UserID": "1936",
        "TestID": "1",
        "TestName": "Reading & Listening Comprehension Assessment",
        "Issuer": "TEST COMPANY",
        "Name": "Test",
        "LastName": "Candidate",
        "Email": "test.candidate@cepatest.org",
        "CompleteDate": "2020-01-28T17:36:46.000Z",
        "OverallScore": "50",
        "CefrLevel": "B2",
        "CefrDescription": "Upper Intermediate",
        "Demo": "false",
        "CreateDate": "2020-01-28T17:32:58.000Z"
    }
}
JSON başarılı yanıt çıktısı: 
{
    "Test Adayı": {
        "Rank": "1",
        "Email": "test.candidate@cepatest.org",
        "Issuer": "TEST COMPANY",
        "Tokens": [
            {
                "495830": [
                    {
                        "TestID": 1,
                        "TestName": "Reading & Listening Comprehension Assessment",
                        "CompleteDate": "2019-01-01T10:00:00",
                        "OverallScore": "36",
                        "CefrLevel": "B1+",
                        "CefrDescription": "Intermediate",
                        "Demo": "false",
                        "CreateDate": "2019-01-01T10:00:00"
                    }
                ],
                "200000": [
                    {
                        "TestID": 3,
                        "TestName": "Oral Proficiency Assessment",
                        "CompleteDate": "2019-01-01T10:00:00",
                        "OverallScore": "68",
                        "CefrLevel": "C1",
                        "CefrDescription": "Advanced",
                        "Demo": "false",
                        "CreateDate": "2019-01-01T10:00:00"
                    }
                ]
            }
        ]
    },
JSON başarılı yanıt çıktısı: 
{
    "Reading & Listening Comprehension Assessment": {
        "TestID": "1",
        "Duration": "About 85 minutes",
        "AvailableTokens": 50,
        "UsedTokens": 100
    },
    "Oral Proficiency Assessment": {
        "TestID": "3",
        "Duration": "About 25 minutes",
        "AvailableTokens": 50,
        "UsedTokens": 100
    },
    "Written Communication Assessment": {
        "TestID": "4",
        "Duration": "About 30 minutes",
        "AvailableTokens": 5,
        "UsedTokens": 100
    }
}
JSON başarılı yanıt çıktısı: 
{
    "Result": {
        "TestID": "1",
        "TestName": "Reading & Listening Comprehension Assessment",
        "Name": "Test",
        "Lastname": "Aday",
        "Email": "test.candidate@cepatest.org",
        "Issuer": "TEST COMPANY",
        "StartDeadline": "2024-10-09 09:37:00",
        "EndDeadline": "2024-10-09 09:37:00",
        "AvailableToken": 495830,
        "CreateDate": "2024-10-09+0309:37:27",
		"SendInvitationEmail": "true",
		"SendInvitationDescription": "Invitation e-mail has sent successfuly",
        "Status": "Success"
    }
}
JSON başarılı yanıt çıktısı: 
{
    "495830": {
        "Rank": "1",
        "UserID": "9999",
        "TestID": "1",
        "TestName": "Reading & Listening Comprehension Assessment",
        "Issuer": "TEST COMPANY",
        "Name": "Test",
        "Lastname": "Aday",
        "Email": "test.candidate@cepatest.org",
        "Photo": "https://cepatest.org/candidate_avatar.jpg",
        "TestStatus": "Completed",
        "CompleteDate": "2020-02-10T23:10:10",
        "OverallScore": "60",
        "CefrLevel": "B2+",
        "CefrDescription": "Advance Low",
        "Assessment": null,
        "AssessmentDeadline": null,
        "SecurityChecks": "true",
        "Demo": "false",
        "CreateDate": "2020-01-08T16:10:50"
    }
}