Geliştiriciler için personel.net API

İşverenler kendi işe alım sistemlerini (ATS), kariyer sayfalarını ve iş akışlarını personel.net'e bağlayabilir: ilan oluşturma ve kapatma, başvuruları alma, yeni başvuru ve durum değişikliklerinde anında bildirim. İş ilanı toplayıcı siteler herkese açık beslemeyi kullanabilir.

1. API anahtarı

Şirket sahibi veya yöneticisi İşveren paneli → Entegrasyonlar sayfasından anahtar oluşturur. Anahtar yalnızca bir kez gösterilir; biz yalnızca özetini saklarız. Her istekte X-API-Key başlığıyla gönderin. Anahtar başına dakikada 120 istek sınırı vardır; ilan ve başvuru okuma işlemleri denetim kaydına yazılır. Kullanılmayan anahtarı iptal edin.

• jobs:read — İlanları okuma
• jobs:write — İlan oluşturma ve yayından kaldırma
• applications:read — Başvuruları ve aday bilgilerini okuma

2. Uçlar

Temel adres: https://api.personel.net/api/v1. Hatalar { error, code } biçimindedir. Tüm şemalar: OpenAPI belgesi.

• GET /partner/jobs — şirketinizin ilanları (jobs:read)
• POST /partner/jobs — ilan oluştur; moderasyon, kredi ve güvenlik kuralları paneldeki gibi uygulanır (jobs:write)
• PATCH /partner/jobs/:id/status — {"status":"CLOSED"} veya ACTIVE (jobs:write)
• GET /partner/jobs/:id/applications, GET /partner/applications/:id — başvurular ve aday iletişim bilgileri (applications:read)

curl -H "X-API-Key: pk_live_..." https://api.personel.net/api/v1/partner/jobs

3. Webhook'lar

Entegrasyonlar sayfasından bir https adresi ekleyin. Olaylar: application.created (yeni başvuru), application.status_changed (başvuru durumu değişti), job.status_changed (ilan durumu değişti). Gövde {"event", "occurredAt", "data": { applicationId, jobId, … } } biçimindedir ve kişisel veri içermez; ayrıntıyı API anahtarınızla çekersiniz. 2xx dışındaki yanıtlar 1, 5, 30 dakika, 2 ve 12 saat sonra tekrar denenir; çok sayıda başarısız gönderimden sonra webhook kapatılır.

Her istekte X-Personel-Event, X-Personel-Delivery, X-Personel-Timestamp ve X-Personel-Signature başlıkları bulunur. İmza, zaman.gövde metninin webhook imza anahtarıyla HMAC-SHA256 özetidir:

import crypto from "node:crypto";

// Express örneği: gövdeyi ham haliyle okuyun (express.raw).
app.post("/personel-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-Personel-Timestamp");
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.PERSONEL_WEBHOOK_SECRET)
    .update(`${timestamp}.${req.body}`)
    .digest("hex");
  const given = req.get("X-Personel-Signature") ?? "";
  const ok = given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
  // 5 dakikadan eski istekleri reddedin (tekrar oynatma saldırısı).
  if (!ok || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  // event.data.applicationId → GET /partner/applications/:id ile ayrıntıyı alın
  res.sendStatus(200);
});

4. İlan beslemesi

Yayındaki ilanlar herkese açık olarak JSON ve XML biçiminde sunulur (15 dakikada bir yenilenir). Beslemede yalnızca ilan sayfasında herkese açık olan bilgiler vardır; işverenin gizlediği maaş yer almaz. Her ilanın bağlantısını kaynak göstererek kullanın.

Test etme

Ayrı bir deneme ortamı henüz yok: entegrasyonu geliştirirken yalnızca jobs:read izinli bir anahtarla başlayın, webhook'u "Dene" düğmesiyle sınayın. Sorularınız için yardım merkezi.