Referensi API
Create Widget Session
Membuat session SSO dan mengembalikan widgetUrl yang siap di-embed ke
<iframe> di frontend partner.
Endpoint
POST {BASE_URL}/api/v2/partner/{partnerId}/sessions| Environment | Base URL |
|---|---|
| Development / Staging | https://dev-app.psikologiehub.com |
| Production | https://app.psikologiehub.com |
Path Parameters
| Field | Tipe | Wajib | Deskripsi |
|---|---|---|---|
partnerId | string | Ya | Partner ID aktif yang diberikan oleh PsikologieHub |
Headers
{ "Content-Type": "application/json" }Request Body
| Field | Tipe | Wajib | Deskripsi |
|---|---|---|---|
user.user_id | string | Ya | ID eksternal HR/rekruiter di sistem partner |
user.email | string | Ya | Email HR/rekruiter |
user.name | string | Ya | Nama lengkap HR/rekruiter |
user.username | string | Tidak | Username HR/rekruiter (tidak ikut signature) |
user.company.company_id | string | Tidak | ID eksternal perusahaan |
user.company.name | string | Tidak | Nama perusahaan (tidak ikut signature) |
user.company.email | string | Tidak | Email perusahaan (tidak ikut signature) |
user.candidates[].candidate_id | string | Ya | ID eksternal kandidat |
user.candidates[].nama | string | Ya | Nama kandidat (key Bahasa Indonesia) |
user.candidates[].email | string | Ya | Email kandidat |
signature | string | Ya | Signature HMAC-SHA256 (hex lowercase) |
⚠️
Field nama kandidat memakai nama (Bahasa Indonesia), bukan name.
Ini sumber error integrasi yang sering terjadi.
Contoh Request Body
{
"user": {
"user_id": "USR-001",
"email": "[email protected]",
"name": "John Doe",
"username": "johndoe",
"company": {
"company_id": "COMP-001",
"name": "Acme Corp",
"email": "[email protected]"
},
"candidates": [
{ "candidate_id": "CND-001", "nama": "Jane Doe", "email": "[email protected]" },
{ "candidate_id": "CND-002", "nama": "Bob Doe", "email": "[email protected]" }
]
},
"signature": "ac689886217ce7c1002102d1327dfe741ecfeb3912426eac1777e80db427a1c2"
}Response Sukses (200)
{
"success": true,
"sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"widgetUrl": "https://dev-app.psikologiehub.com/api/v2/partner/widget?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"partnerId": "psikologihub",
"expiresIn": 1778760077
}| Field | Tipe | Deskripsi |
|---|---|---|
success | boolean | Selalu true saat response sukses |
sessionToken | string | JWT session token (dipakai widget secara internal) |
widgetUrl | string | URL yang di-embed ke iframe (sudah include ?token=) |
partnerId | string | Partner ID yang membuat session ini |
expiresIn | integer | UNIX timestamp (detik) kapan session expired |
Response Error
401 Invalid signature
{
"success": false,
"message": "Invalid signature",
"errors": null
}404 Partner not found or inactive
{
"success": false,
"message": "Partner not found or inactive",
"errors": null
}422 Validation failed
{
"success": false,
"message": "Validation failed",
"errors": {
"signature": ["Signature is required."]
}
}Lihat halaman Penanganan Error untuk daftar lengkap status code dan strategi retry yang disarankan.
Contoh Implementasi End-to-End
Contoh di bawah mencakup generate signature sekaligus memanggil endpoint.
<?php
function generateSignature(
string $partnerId, string $userId, string $userEmail, string $userName,
string $companyId, string $candidateIdsCsv, string $secretKey
): string {
$canonical = implode('|', [
$partnerId, $userId, $userEmail, $userName, $companyId, $candidateIdsCsv,
]);
return hash_hmac('sha256', $canonical, $secretKey);
}
$baseUrl = 'https://dev-app.psikologiehub.com';
$partnerId = 'psikologihub-1024';
$secretKey = getenv('PSIKOLOGIE_SECRET_KEY');
$signature = generateSignature(
$partnerId, 'USR-001', '[email protected]', 'John Doe',
'COMP-001', 'CND-001,CND-002', $secretKey
);
$payload = [
'user' => [
'user_id' => 'USR-001',
'email' => '[email protected]',
'name' => 'John Doe',
'username' => 'johndoe',
'company' => [
'company_id' => 'COMP-001',
'name' => 'Acme Corp',
'email' => '[email protected]',
],
'candidates' => [
['candidate_id' => 'CND-001', 'nama' => 'Jane Doe', 'email' => '[email protected]'],
['candidate_id' => 'CND-002', 'nama' => 'Bob Doe', 'email' => '[email protected]'],
],
],
'signature' => $signature,
];
$ch = curl_init("$baseUrl/api/v2/partner/$partnerId/sessions");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo "status: $status\n";
echo "response: $response\n";