ATS Entegrasyon API

Aday Takip Sisteminizi Maatrics'e bağlayın: basit bir REST API üzerinden aday ekleyin, sonuçları alın ve raporları çekin.

Dış işe alım sistemleri bu API ile Maatrics değerlendirmelerine aday gönderir, ardından sonuçlarını takip edip alır. Adaylar sistemler arasında remote_id ile eşleşir — bu, ATS'inizin atadığı benzersiz kimliktir. Aday eklerken siz belirlersiniz; Maatrics her yanıt ve webhook'ta onu geri döndürür.

1.  ATS       ──GET   /assessments                ──▶  değerlendirmeleri keşfet
2.  ATS       ──POST  /assessments/:id/applicants ──▶  aday ekle → invite_url
3.  Aday      ── Maatrics üzerinde değerlendirmeyi tamamlar
4.  Maatrics  ──POST  webhook_url                 ──▶  sonuç (applicant.analyzed)
5.  ATS       ──GET   /applicants/:remote_id      ──▶  durum / sonuç sorgula
6.  ATS       ──GET   /api/ats/file/:remote_id    ──▶  PDF raporu indir

Kimlik Doğrulama

Her /api/v1/ats/* isteği bir Bearer token içermelidir. Token'lar entegrasyon başına üretilir; ats_ önekiyle başlar ve ardından 48 karakter gelir. Bir token yalnızca entegrasyonu aktif olduğu sürece geçerlidir.

Authorization: Bearer ats_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token'ınızı Maatrics panelinden (ATS Entegrasyonları) alın veya yenileyin. /api/ats/file/:remoteId tek herkese açık uç noktadır — remote_id UUID'si erişim anahtarı işlevi görür; bu nedenle rapor URL'lerini gizli tutun.

Uç Noktalar

curl -X GET "https://api.maatrics.com/api/v1/ats/assessments" \
  -H "Authorization: Bearer ats_xxx"

curl -X GET "https://api.maatrics.com/api/v1/ats/assessments/9bk2f1a7c3" \
  -H "Authorization: Bearer ats_xxx"

curl -X GET "https://api.maatrics.com/api/v1/ats/assessments/9bk2f1a7c3/applicants" \
  -H "Authorization: Bearer ats_xxx"

curl -X POST "https://api.maatrics.com/api/v1/ats/assessments/9bk2f1a7c3/applicants" \
  -H "Authorization: Bearer ats_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "applicants": [
      {
        "remote_id": "cand-3f2a9b7c",
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]"
      }
    ]
  }'

curl -X GET "https://api.maatrics.com/api/v1/ats/applicants/cand-3f2a9b7c" \
  -H "Authorization: Bearer ats_xxx"

curl -X GET "https://api.maatrics.com/api/ats/file/cand-3f2a9b7c" -o report.pdf

Sonuç Webhook'u

Bir adayın analizi yayınlandığında Maatrics, aşağıdaki payload'ı entegrasyonunuzun webhook_url adresine POST eder. Hızlıca 2xx dönün, remote_id ile yinelenenleri eleyin, ardından report_url'den PDF'i çekin ve/veya yapılandırılmış sonuçlar için aday durumu uç noktasını çağırın. Payload, değerlendirme tipine göre değişen bir report_data taşır; aşağıda üç tip için birer örnek payload verilmiştir.

Sonuçların yapısı değerlendirme tipine (type) göre değişir. Bir sonucu işlemeden önce type alanına bakın ve report_data'yı buna göre ayrıştırın — aşağıdaki Kullanım sekmesi tam olarak bunu gösterir.

// On a result webhook — or the candidate status response —
// branch on `type` to parse report_data / results correctly:
function handleResult(payload) {
  switch (payload.type) {
    case "language":
      // word_accuracy, speaking_fluency, vocabulary, grammar, general_level
      return renderLanguageReport(payload.report_data);

    case "proficiency":
      // proficiencies[] — each with nested actions[]
      return renderProficiencyReport(payload.report_data);

    case "technical":
    case "technical_code":
      // proficiencies[] + skills[]
      return renderTechnicalReport(payload.report_data);

    default:
      return; // unknown type — ignore
  }
}

Hatalar

Standart HTTP durum kodları kullanılır. Doğrulama hataları, alan-bazlı bir errors nesnesiyle 422 döner. Her istek denetim ve hata ayıklama için sunucu tarafında loglanır.