API

Davetler

Davet, aramadaki bir hakemden bir makaleyi değerlendirmesini ister. Scholvet daveti iletir, yanıtı toplar ve size bildirir.

Yaşam döngüsü

Davet pending olarak başlar ve tek bir son duruma geçer.

status	Anlamı
`pending`	Hakemin yanıtı bekleniyor. respondBy'da sona erer.
`accepted`	Hakem kabul etti. Kimliği artık davette yer alır ve dueAt belirlenir.
`declined`	Hakem reddetti. Nedeni declineReason'da.
`expired`	respondBy'a kadar yanıt gelmedi.
`cancelled`	Daveti siz geri çektiniz.
`completed`	Tamamlanan değerlendirmeyi siz onayladınız.

Davet oluşturma

POST /v1/invitations

Aramalarınızdan birindeki hakemi davet eder. Davetle birlikte 201 Created döner.

İstek gövdesi

Alan	Tür	Açıklama
`searchId` zorunlu	`uuid`	Hakem kodunun geldiği arama. Süresi dolmamış olmalı.
`reviewerCode` zorunlu	`string`	O aramadaki bir reviewerCode.
`externalRef`	`string`	Davetin sizdeki kimliği, en fazla 80 karakter. Her yanıtta ve webhook'ta geri gelir.
`articleTitle` zorunlu	`string`	Hakeme gösterilecek başlık, en fazla 600 karakter.
`articleAbstract`	`string`	Hakeme gösterilecek özet, en fazla 4.000 karakter.
`message`	`string`	Editörden kişisel not, en fazla 2.000 karakter.
`respondByDays`	`integer`	Hakemin yanıt süresi (gün), 1 ile 30 arası. Varsayılan 7.
`reviewDays`	`integer`	Kabulden sonra değerlendirme süresi (gün), 1 ile 90 arası. Varsayılan 21.

İstek

curl -X POST https://api.scholvet.com/v1/invitations \
  -H "X-Api-Key: $SCHOLVET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchId": "0b4f6c1e-5c1a-4a7e-9d0f-7f1c2a9e3b55",
    "reviewerCode": "SV-7KQ2MX4P",
    "externalRef": "your-invitation-881",
    "articleTitle": "Deep learning for tumour detection in brain MRI",
    "articleAbstract": "We evaluate convolutional neural networks...",
    "message": "We would value your opinion on this manuscript.",
    "respondByDays": 7,
    "reviewDays": 21
  }'

Yanıt · 201 Created

{
  "invitationId": "6d8da67a-2bc0-4c8e-b8c9-e9831c02f746",
  "externalRef": "your-invitation-881",
  "articleRef": "JMIR-2026-0104",
  "reviewerCode": "SV-7KQ2MX4P",
  "status": "pending",
  "createdAt": "2026-10-28T09:20:11Z",
  "respondBy": "2026-11-04T09:20:11Z",
  "respondedAt": null,
  "dueAt": null,
  "completedAt": null,
  "declineReason": null,
  "reviewer": null
}

Doğrulama hatalarının yanı sıra davet oluşturma şu nedenlerle başarısız olabilir:

404 search_not_found — Arama yok ya da başka bir dergiye ait.
409 search_expired — Arama 30 günden eski. Yeniden arayın.
422 reviewer_not_in_search — Hakem kodu o aramanın sonuçları arasında değil.
409 reviewer_unavailable — Hakem bu makale için zaten davet edilmiş ya da artık müsait değil (kapasite, izin ya da yeni bir çıkar çatışması).
402 overage_cap_reached — Kurumunuzun aşım üst sınırı doldu; bu dönem yeni davet gönderilemez.

Davet nesnesi

Tüm davet uç noktaları ve webhook'lar bu nesneyi döndürür.

Alan	Tür	Açıklama
`invitationId` zorunlu	`uuid`	Davetin kimliği.
`externalRef`	`string \| null`	Gönderdiyseniz sizin externalRef değeriniz.
`articleRef` zorunlu	`string`	Aramanın articleRef değeri.
`reviewerCode` zorunlu	`string`	Hakemin derginize özel kodu.
`status` zorunlu	`string`	pending, accepted, declined, expired, cancelled ya da completed.
`createdAt` zorunlu	`date-time`	Davetin gönderildiği zaman.
`respondBy` zorunlu	`date-time`	Yanıt için son zaman.
`respondedAt`	`date-time \| null`	Hakemin yanıt verdiği zaman.
`dueAt`	`date-time \| null`	Değerlendirme için son zaman: yanıt zamanı artı reviewDays.
`completedAt`	`date-time \| null`	Onayladığınız biçimiyle değerlendirmenin tamamlandığı zaman.
`declineReason`	`string \| null`	Ret nedeni.
`reviewer`	`object \| null`	fullName, email, orcid, academicTitle ve institution. Yalnızca durum accepted ya da completed olduğunda bulunur.

Örnek · kabul edildi

{
  "invitationId": "6d8da67a-2bc0-4c8e-b8c9-e9831c02f746",
  "externalRef": "your-invitation-881",
  "articleRef": "JMIR-2026-0104",
  "reviewerCode": "SV-7KQ2MX4P",
  "status": "accepted",
  "createdAt": "2026-10-28T09:20:11Z",
  "respondBy": "2026-11-04T09:20:11Z",
  "respondedAt": "2026-10-29T07:02:45Z",
  "dueAt": "2026-11-19T07:02:45Z",
  "completedAt": null,
  "declineReason": null,
  "reviewer": {
    "fullName": "Ayşe Demir",
    "email": "[email protected]",
    "orcid": "0000-0001-5109-3700",
    "academicTitle": "Prof. Dr.",
    "institution": "Ankara University"
  }
}

declineReason değerleri:

busy — Şu anda yoğunum
out_of_scope — Uzmanlık alanım dışında
conflict_of_interest — Çıkar çatışması var
other — Diğer

Bir makalenin davetlerini listeleme

GET /v1/invitations?articleRef={articleRef}

Bir articleRef için davetlerinizi en yeniden başlayarak döndürür (en fazla 100). Kaçırılan bir webhook'tan sonra durumu yeniden kurmak için kullanışlıdır.

İstek

curl "https://api.scholvet.com/v1/invitations?articleRef=JMIR-2026-0104" \
  -H "X-Api-Key: $SCHOLVET_API_KEY"

Daveti sorgulama

GET /v1/invitations/{invitationId}

Tek bir daveti döndürür. Davet yoksa ya da başka bir dergiye aitse 404 invitation_not_found.

İstek

curl https://api.scholvet.com/v1/invitations/6d8da67a-2bc0-4c8e-b8c9-e9831c02f746 \
  -H "X-Api-Key: $SCHOLVET_API_KEY"

Daveti geri çekme

POST /v1/invitations/{invitationId}/cancel

Bekleyen ya da kabul edilmiş bir daveti geri çeker ve hakeme bildirir. Diğer durumlarda 409 invalid_status döner.

İstek

curl -X POST https://api.scholvet.com/v1/invitations/6d8da67a-2bc0-4c8e-b8c9-e9831c02f746/cancel \
  -H "X-Api-Key: $SCHOLVET_API_KEY"

Tamamlanan değerlendirmeyi onaylama

POST /v1/invitations/{invitationId}/completion

Kabul edilmiş bir daveti tamamlandı olarak işaretler. Diğer durumlarda 409 invalid_status döner.

İstek gövdesi

Alan	Tür	Açıklama
`accepted` zorunlu	`boolean`	Değerlendirme kabul edilebilirse true; kullanılamazsa false.
`qualityRating`	`integer`	Editörün değerlendirmeye verdiği puan, 1 ile 5 arası.
`completedAt`	`date-time`	Değerlendirmenin gönderildiği zaman. Verilmezse şimdiki zaman; gelecekteki ya da kabulden önceki bir değer yok sayılır.

İstek

curl -X POST https://api.scholvet.com/v1/invitations/6d8da67a-2bc0-4c8e-b8c9-e9831c02f746/completion \
  -H "X-Api-Key: $SCHOLVET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accepted": true, "qualityRating": 4, "completedAt": "2026-11-15T16:40:00Z" }'

Hakemler puanı yalnızca bu çağrıyla kazanır, kendi beyanlarıyla asla. Puan zamanlamaya ve verdiğiniz değerlendirmeye bağlıdır, 30 gün bekletilir; hakemin kendi kurumunun dergisine ve bir yılda aynı dergiden altıyı aşan hakemliklere verilmez.

Sonraki: Hakem kaydetme →