22 panduan

Dokumentasi · Referensi

Referensi API

Setiap endpoint `/api/v1` dengan izin, parameter, bentuk body, dan contoh panggilan — dibangkitkan dari kontrak OpenAPI yang sama dengan server.

18 operasi8 grup9 izinUnduh OpenAPI 3.1

Sebelum memanggil endpoint

Semua permintaan memakai Authorization: Bearer <API key>. Kunci dibuat administrator di /admin/integrasi dan hanya ditampilkan sekali.
Setiap kunci terikat pada satu klien integrasi. Data klien lain dijawab 404, bukan 403, agar keberadaannya tidak bocor.
Izin efektif adalah irisan izin klien dan izin kunci. Mencabut izin di klien langsung mempersempit semua kunci di bawahnya.
Daftar memakai cursor: kirim ?cursor= dari meta.cursor. Jangan menyusun cursor sendiri.

Identitas

Informasi klien dan konfigurasi

GET/api/v1/mecukup API key

Identitas integrasi

Klien, scope efektif, katalog event webhook, dan batas laju.

Respons

200 · Identitas klien
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/me \  -H "Authorization: Bearer $SIKOTES_API_KEY"

Katalog

Instrumen yang tersedia

GET/api/v1/instrumentscatalog:read

Daftar instrumen terbit

Parameter

Parameter GET /instruments
Field	Tipe	Keterangan
`limit (query)`	integer	—

Respons

200 · Katalog
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/instruments \  -H "Authorization: Bearer $SIKOTES_API_KEY"

Peserta

Kelola peserta milik klien

GET/api/v1/participantsparticipants:read

Daftar peserta

Parameter

Parameter GET /participants
Field	Tipe	Keterangan
`limit (query)`	integer	—
`cursor (query)`	string	—
`q (query)`	string	Cari nama atau email

Respons

200 · Daftar peserta
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/participants \  -H "Authorization: Bearer $SIKOTES_API_KEY"

POST/api/v1/participantsparticipants:write

Buat peserta

Idempoten terhadap email: permintaan ulang mengembalikan peserta yang sama dengan `created: false`.

Body (wajib)

Body POST /participants
Field	Tipe	Keterangan
`name`wajib	string	—
`email`wajib	string	—
`phone`	string \| null	—
`city`	string \| null	—
`organization`	string \| null	—
`occupation`	string \| null	—

Respons

200 · Peserta sudah ada (idempoten)
201 · Peserta dibuat
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/participants \  -H "Authorization: Bearer $SIKOTES_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "name": "…",  "email": "…",  "phone": "…",  "city": "…",  "organization": "…",  "occupation": "…"}'

GET/api/v1/participants/{participantId}participants:read

Detail peserta

Parameter

Parameter GET /participants/{participantId}
Field	Tipe	Keterangan
`participantId (path)`wajib	string	—

Respons

200 · Peserta
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/participants/<participantId> \  -H "Authorization: Bearer $SIKOTES_API_KEY"

PATCH/api/v1/participants/{participantId}participants:write

Perbarui peserta

Parameter

Parameter PATCH /participants/{participantId}
Field	Tipe	Keterangan
`participantId (path)`wajib	string	—

Body (wajib)

Body PATCH /participants/{participantId}
Field	Tipe	Keterangan
`name`	string	—
`phone`	string \| null	—
`city`	string \| null	—
`organization`	string \| null	—
`occupation`	string \| null	—
`active`	boolean	—

Respons

200 · Diperbarui
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/participants/<participantId> \  -H "Authorization: Bearer $SIKOTES_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "name": "…",  "phone": "…",  "city": "…",  "organization": "…",  "occupation": "…",  "active": 0}'

Hasil

Hasil tes dan skala

GET/api/v1/resultsresults:read

Daftar hasil tes

Parameter

Parameter GET /results
Field	Tipe	Keterangan
`limit (query)`	integer	—
`cursor (query)`	string	—
`participantId (query)`	string	—
`instrumentId (query)`	string	—

Respons

200 · Daftar hasil
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/results \  -H "Authorization: Bearer $SIKOTES_API_KEY"

GET/api/v1/results/{resultId}results:read

Detail hasil dan skala

Parameter

Parameter GET /results/{resultId}
Field	Tipe	Keterangan
`resultId (path)`wajib	string	—

Respons

200 · Hasil
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/results/<resultId> \  -H "Authorization: Bearer $SIKOTES_API_KEY"

Pesanan

Pesanan dan status pembayaran

GET/api/v1/ordersorders:read

Daftar pesanan

Parameter

Parameter GET /orders
Field	Tipe	Keterangan
`limit (query)`	integer	—
`cursor (query)`	string	—

Respons

200 · Daftar pesanan
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/orders \  -H "Authorization: Bearer $SIKOTES_API_KEY"

Room

Proyek/kelompok peserta

GET/api/v1/roomsrooms:read

Daftar room

Respons

200 · Daftar room
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/rooms \  -H "Authorization: Bearer $SIKOTES_API_KEY"

POST/api/v1/roomsrooms:write

Buat room

Body (wajib)

Body POST /rooms
Field	Tipe	Keterangan
`name`wajib	string	—
`description`	string \| null	—
`organization`	string \| null	—
`pacing`	string (free · sequential)	—
`members`	array	—
`instruments`	array	—

Respons

201 · Room dibuat
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/rooms \  -H "Authorization: Bearer $SIKOTES_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "name": "…",  "description": "…",  "organization": "…",  "pacing": "…",  "members": 0,  "instruments": 0}'

GET/api/v1/rooms/{roomId}rooms:read

Detail room

Parameter

Parameter GET /rooms/{roomId}
Field	Tipe	Keterangan
`roomId (path)`wajib	string	—

Respons

200 · Room
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/rooms/<roomId> \  -H "Authorization: Bearer $SIKOTES_API_KEY"

Webhook

Endpoint notifikasi keluar

GET/api/v1/webhookswebhooks:manage

Daftar endpoint webhook

Respons

200 · Endpoint
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/webhooks \  -H "Authorization: Bearer $SIKOTES_API_KEY"

POST/api/v1/webhookswebhooks:manage

Buat endpoint webhook

Rahasia tanda tangan dikembalikan **sekali** pada respons ini.

Body (wajib)

Body POST /webhooks
Field	Tipe	Keterangan
`url`wajib	string	HTTPS publik
`description`	string	—
`events`wajib	array	—

Respons

201 · Endpoint dibuat beserta secret
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/webhooks \  -H "Authorization: Bearer $SIKOTES_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "url": "…",  "description": "…",  "events": 0}'

GET/api/v1/webhooks/{endpointId}webhooks:manage

Detail endpoint

Parameter

Parameter GET /webhooks/{endpointId}
Field	Tipe	Keterangan
`endpointId (path)`wajib	string	—

Respons

200 · Endpoint
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/webhooks/<endpointId> \  -H "Authorization: Bearer $SIKOTES_API_KEY"

PATCH/api/v1/webhooks/{endpointId}webhooks:manage

Perbarui endpoint atau rotasi rahasia

Parameter

Parameter PATCH /webhooks/{endpointId}
Field	Tipe	Keterangan
`endpointId (path)`wajib	string	—

Respons

200 · Diperbarui
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/webhooks/<endpointId> \  -H "Authorization: Bearer $SIKOTES_API_KEY"

DELETE/api/v1/webhooks/{endpointId}webhooks:manage

Hapus endpoint

Parameter

Parameter DELETE /webhooks/{endpointId}
Field	Tipe	Keterangan
`endpointId (path)`wajib	string	—

Respons

200 · Dihapus
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/webhooks/<endpointId> \  -H "Authorization: Bearer $SIKOTES_API_KEY"

Pemakaian

Kuota dan kesehatan antrean

GET/api/v1/usagecukup API key

Pemakaian API dan antrean webhook

Respons

200 · Pemakaian
400 · Input tidak valid
401 · API key tidak ada atau tidak sah
403 · Scope tidak mencukupi atau IP ditolak
404 · Sumber daya tidak ditemukan
409 · Konflik data
429 · Batas laju atau kuota tercapai

Contoh panggilanbashReady

curl -s https://sikotes.id/api/v1/usage \  -H "Authorization: Bearer $SIKOTES_API_KEY"

Izin

Minta izin sekecil yang cukup. Izin berisiko tinggi membuka data hasil atau memungkinkan perubahan data peserta.

Katalog izin API
Izin	Risiko	Kegunaan
`catalog:read` Baca katalog instrumen	low	Daftar instrumen yang terbit beserta slug, durasi, dan tingkat akses.
`participants:read` Baca peserta	medium	Daftar dan detail peserta yang dibuat oleh klien ini.
`participants:write` Kelola peserta	high	Membuat, memperbarui, dan menonaktifkan peserta milik klien ini.
`results:read` Baca hasil tes	high	Ringkasan skor dan status hasil peserta milik klien ini.
`reports:read` Baca laporan	high	Status laporan, kode verifikasi, dan tautan unduhan PDF.
`orders:read` Baca pesanan	medium	Pesanan dan status pembayaran peserta milik klien ini.
`rooms:read` Baca room	medium	Room/proyek yang dibuat klien ini beserta anggotanya.
`rooms:write` Kelola room	high	Membuat room, menambah anggota, dan menugaskan tes.
`webhooks:manage` Kelola webhook	high	Membuat dan mengubah endpoint webhook milik klien ini.

Batas pemakaian

Batas pemakaian API
Batas	Bawaan	Catatan
Permintaan per menit	120	Dapat dinaikkan sampai 6000 per klien. Dihitung per klien, bukan per IP.
Kuota harian	Tanpa batas	Bila diaktifkan, kelebihan dijawab `429`.
Ukuran halaman	25 (maks 100)	Atur lewat `?limit=`; nilai di atas maksimum dipotong.
Ukuran body	16–64 KB	Bergantung endpoint; body lebih besar dijawab `413`.

Saat menerima 429, hormati header Retry-After dan gunakan backoff dengan jitter. Sertakan requestId dari amplop galat bila melapor.