Multi-posting (ATS)

Solution API Technical Guide

ATS Integration Documentation.

This document will guide you through the ATS API integration details and implementation process. WhatJobs provides an easy to use API allowing job posters to send the requests to REST interface. The API accepts POST requests which means that any software you write to interact with ATS API must make POST request.

  Форматы запросов и ответов  


Вы можете использовать как JSON, так и XML. В зависимости от Вашего выбора конечной точки, предоставляемые данные должны быть такого же формата. Формат возвращаемых данных будет таким же

Доступные конечные точки:

XML endpoint https://uk.whatjobs.com/api/v1/ats/{ats-name} /xml
JSON endpoint https://uk.whatjobs.com/api/v1/ats/{ats-name} /json
Example https://uk.whatjobs.com/api/v1/ats/your-company-name/xml
 

  Аутентификация на основе маркера  


Доступ к API ограничен маркерами доступа. Данный маркер должен быть внесен в настраеваемый заголовок HTTP X-API-Token.

Для того, чтобы восстановить имя ATS и Аутентификационного маркера, пожалуйста,свяжитесь с нами.

 

  Параметры запроса HTTP  


Запрос к тестовой версии API может быть осуществлен при условии наличия следующих параметров в запросе GET.

Имя Необходим Описание
sandbox-mode Нет При установке данного булева параметра как верного, API будет работать в тестовом режиме. Например, sandbox-mode=true

Необходим только один параметр HTTP POST.

Имя Необходим Описание
data ДА Привязка параметра к телу входящего запроса XML или JSON. Убедитесь в том, что данные в теле POST соответствуют конечным точкам, к которым Вы отправляете запрос.
Представленная ниже таблица содержит более подробную информацию о том, что соответствует требованиям.
 

  Поля данных XML/JSON  


Ниже представлены поля, которые могут быть использованы при запросе, когда команда установлена на add.

Название поля Необходим Тип Дополнительная информация
команда ДА Исправление Ожидаемое значение: add
имэйл_компании ДА Имэйл Должно отображаться с данным маркеромимэйл Админа на странице настроек сайта по поиску работы.
название_компании ДА Строка символов Должно отображаться с данным маркеромНазвание Компании на странице настроек сайта по поиску работы.
компания_Хэш ДА Строка символов Должно отображаться с данным маркеромХэш (не обязательно) на странице настроек сайта по поиску работы.
заголовок ДА Строка символов Свободный текст, заголовок вакансии. Минимум 3 символа. Максимум 255 символов.
описание ДА Строка символов Свободный текст, от 100 до 65 тысяч символов, подробное описание вакансии.
Данное поле может содержать следующие HTML тэги: p, br, b, strong, i, u, ul, li, ol
тип_работы ДА УСТАНОВКА Допустимые значения: постоянная, временная, контракт
job_status ДА УСТАНОВКА Допустимые значения: полная занятость, частичная занятость
заявка-имэйл Да, если Вам URL пустой Имэйл Необходимо, если URL заявки пустой
заявка_url Да, если письмо пустое URL Необходимо, если письмо заявки пустое
индустрия Нет УСТАНОВКА Применимые значения: индустрия, доступные значения в таблице ниже.
weeks_to_advertise Нет УСТАНОВКА Допустимые значения: 1, 2, 3, 4, 6, 8, 10, 12
тип заработной платы Нет УСТАНОВКА Допустимые значения: Год, Месяц, Неделя, День, Час
заработная_плата_от Нет Числа Плавающее значение для меньшей заработной платы.
Зарплата Нет Числа Плавающее значение для большей заработной платы.
заработная_плата_валюта Нет УСТАНОВКА Допустимые значения: фунтов стерлингов, Доллра США, Евро
salary_benefits Нет Строка символов Свободный текст, дополнительная информация о заработной плате.
месторасположения Нет Строка символов Свободный текст, предлагаемый формат: страна, регион, округ, город
почтовый индекс Нет Строка символов Действительный почтовый индекс России.
ссылка Нет Строка символов Свободный текст, вакансия со ссылкой, которая которая прикреплена к объявлению рекрутером.
 

Таблица, размещенная ниже, описывает поля, которые могут использоваться в запросе, когда подается команда для delete.

Название поля Необходим Тип Дополнительная информация
команда ДА Исправление Ожидаемое значение: удалить
имэйл_компании ДА Имэйл Должно отображаться с данным маркеромимэйл Админа на странице настроек сайта по поиску работы.
название_компании ДА Строка символов Должно отображаться с данным маркеромНазвание Компании на странице настроек сайта по поиску работы.
компания_Хэш ДА Строка символов Должно отображаться с данным маркеромХэш (не обязательно) на странице настроек сайта по поиску работы.
код вакансии ДА Строка символов Это то же значение, которое будет возвращено в ответе add команды в следующем формате: целое-целое
 

  Допустимые значение сферы  


Таблица ниже содержит все допустимые для индустрии значения.

Industries
  • Бухгалтерское дело
  • Администрирование и Секретариат
  • Аэрокосмические системы и Авиация
  • Сельское хозяйство, рыбная ловля, лесное хозяйство и охрана природы
  • Автомобилестроительный
  • Банковские и финансовые услуги
  • Общественное питание и гостевой бизнес
  • Волонтерство и благотворительность
  • Строительство и частная собственность
  • Служба поддержки
  • Оборона и военное дело
  • Транспорт и управление транспортным средством
  • Образование и подготовка
  • Электроника
  • Энергетика, средства инженерного обеспечения, нефть и газ
  • Инженерное дело
  • Мода и искусство
  • Товары повседневного спроса
  • Выпускники и стажеры
  • Здоровье, охрана и защита
  • Здравоохранение и Медицина
  • Человеческие ресурсы и персонал
  • Информационные технологии
  • Страхование
  • Журналистика, издательское дело и перевод
  • Юриспруденция
  • Отдых, туризм и развлечения
  • Склад и логистика
  • Консультирование и управление
  • Изготовление и производство
  • Маркетинг, реклама и PR
  • СМИ, дизайн и творческая работа
  • Личный ассистент
  • Фармацея
  • Бюджетные сектор
  • Закупка и снабжение
  • Подбор кадров
  • Оптовая и розничная торговля
  • Продажи
  • Наука
  • Социальная защита
  • Телекоммуникации
 

  Пример XML запорса 


 
пример XML для Команды Добавить
          <?xml version="1.0" encoding="UTF-8"?>
          <job>
          <command><![CDATA[add]]></command>
          <company_email><![CDATA[[email protected]]]></company_email>
          <company_name><![CDATA[Sample Company Name]]></company_name>
          <company_hash><![CDATA[]]></company_hash>
          <title><![CDATA[Sample Account Manager]]></title>
          <description><![CDATA[Sample Description ...with html tag support]]></description>
          <industry><![CDATA[Accountancy]]></industry>
          <job_type><![CDATA[permanent]]></job_type>
          <job_status><![CDATA[full-time]]></job_status>
          <weeks_to_advertise><![CDATA[1]]></weeks_to_advertise>
          <application_email><![CDATA[[email protected]]]></application_email>
          <application_url><![CDATA[https://wwww.company.com/valid-url]]></application_url>
          <salary_type><![CDATA[annum]]></salary_type>
          <salary_from><![CDATA[20000]]></salary_from>
          <salary_to><![CDATA[40000]]></salary_to>
          <salary_currency><![CDATA[gbp]]></salary_currency>
          <salary_benefits><![CDATA[Bonus payments]]></salary_benefits>
          <location><![CDATA[England, Yorkshire and the Humber, Yorkshire, Hull]]></location>
          <postcode><![CDATA[]]></postcode>
          <reference><![CDATA[ref-123-xu]]></reference>
          </job>
 
пример XML cURL для команды Добавить
            curl https://uk.whatjobs.com/api/v1/ats/{ats-name} /xml?sandbox-mode=true \
            -X POST \
            -H 'x-api-token: {Authentication-Token}' \
            -d 'data=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%3Cjob%3E%3Ccommand%3E%3C!%5BCDATA%5Badd%5D%5D%3E%3C%2Fcommand%3E%3Ccompany_email%3E%3C!%5BCDATA%5Bsample%40email.com%5D%5D%3E%3C%2Fcompany_email%3E%3Ccompany_name%3E%3C!%5BCDATA%5BSample%20Company%20Name%5D%5D%3E%3C%2Fcompany_name%3E%3Ccompany_hash%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Fcompany_hash%3E%3Ctitle%3E%3C!%5BCDATA%5BSample%20Account%20Manager%5D%5D%3E%3C%2Ftitle%3E%3Cdescription%3E%3C!%5BCDATA%5BSample%20Description%20...with%20html%20tag%20support%5D%5D%3E%3C%2Fdescription%3E%3Cindustry%3E%3C!%5BCDATA%5BAccountancy%5D%5D%3E%3C%2Findustry%3E%3Cjob_type%3E%3C!%5BCDATA%5Bpermanent%5D%5D%3E%3C%2Fjob_type%3E%3Cjob_status%3E%3C!%5BCDATA%5Bfull-time%5D%5D%3E%3C%2Fjob_status%3E%3Cweeks_to_advertise%3E%3C!%5BCDATA%5B1%5D%5D%3E%3C%2Fweeks_to_advertise%3E%3Capplication_email%3E%3C!%5BCDATA%5Bvalid-email-address%40company.com%5D%5D%3E%3C%2Fapplication_email%3E%3Capplication_url%3E%3C!%5BCDATA%5Bhttps%3A%2F%2Fwwww.company.com%2Fvalid-url%5D%5D%3E%3C%2Fapplication_url%3E%3Csalary_type%3E%3C!%5BCDATA%5Bannum%5D%5D%3E%3C%2Fsalary_type%3E%3Csalary_from%3E%3C!%5BCDATA%5B20000%5D%5D%3E%3C%2Fsalary_from%3E%3Csalary_to%3E%3C!%5BCDATA%5B40000%5D%5D%3E%3C%2Fsalary_to%3E%3Csalary_currency%3E%3C!%5BCDATA%5Bgbp%5D%5D%3E%3C%2Fsalary_currency%3E%3Csalary_benefits%3E%3C!%5BCDATA%5BBonus%20payments%5D%5D%3E%3C%2Fsalary_benefits%3E%3Clocation%3E%3C!%5BCDATA%5BEngland%2C%20Yorkshire%20and%20the%20Humber%2C%20Yorkshire%2C%20Hull%5D%5D%3E%3C%2Flocation%3E%3Cpostcode%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Fpostcode%3E%3Creference%3E%3C!%5BCDATA%5Bref-123-xu%5D%5D%3E%3C%2Freference%3E%3C%2Fjob%3E'
          
 
пример XML для команды Удалить
            <?xml version="1.0" encoding="UTF-8"?>
            <job>
            <command><![CDATA[delete]]></command>
            <company_email><![CDATA[[email protected]]]></company_email>
            <company_name><![CDATA[Sample Company Name]]></company_name>
            <company_hash><![CDATA[]]></company_hash>
            <job_id><![CDATA[185394403-1508429206]]></job_id>
            </job>
          
 
пример XML cURL Sample для команды Удалить
            curl https://uk.whatjobs.com/api/v1/ats/{ats-name}/xml?sandbox-mode=true \
            -X POST \
            -H 'x-api-token: {Authentication-Token}' \
            -d 'data=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%3Cjob%3E%3Ccommand%3E%3C!%5BCDATA%5Bdelete%5D%5D%3E%3C%2Fcommand%3E%3Ccompany_email%3E%3C!%5BCDATA%5Bsample%40email.com%5D%5D%3E%3C%2Fcompany_email%3E%3Ccompany_name%3E%3C!%5BCDATA%5BSample%20Company%20Name%5D%5D%3E%3C%2Fcompany_name%3E%3Ccompany_hash%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Fcompany_hash%3E%3Cjob_id%3E%3C!%5BCDATA%5B185394403-1508429206%5D%5D%3E%3C%2Fjob_id%3E%3C%2Fjob%3E'
          
 
пример JSON для команды Объявление
            {
              "команда": "добавить",
              "имейл_компании": "[email protected]",
              "имя_компании": "Пример Имя Компании",
              "компания_хэш": "",
              "заголовок": "Пример Аккаунт-Менеджер",
              "описание": "Пример описания ...с поддержкой html тэга",
              "индустрия": "Бухгалтерское дело",
              "тип _занятости": "постоянная",
              "Статус": "Полный рабочий день",
              "реклама недели": "1",
              "имэйл_заявки": "действительный-имейл[email protected]",
              "url_заявки": "https://wwww.company.com/valid-url",
              "тип_заработной_платы": "ежегодно",
              "зарплата_от": "20000",
              "зарплата_до": "40000",
              "зарплата_валюта": "Фунт Стерлинг",
              "зарплата_бонусы": "Выплата бонусов",
              "месторасположения": "Англия, Йоркшир и Хамбер, Йоркшир, Халл",
              "ссылка": "сыылка-123-xu"
            }
 
пример JSON cURL для команды Добавить
              curl https://uk.whatjobs.com/api/v1/ats/{ats-name}/json?sandbox-mode=true \
              -X POST \
              -H 'x-api-token: {Authentication-Token}' \
              -d 'data=%7B%22command%22%3A%22add%22%2C%22company_email%22%3A%22sample%40email.com%22%2C%22company_name%22%3A%22Sample%20Company%20Name%22%2C%22company_hash%22%3A%22%22%2C%22title%22%3A%22Sample%20Account%20Manager%22%2C%22description%22%3A%22Sample%20Description%20...with%20html%20tag%20support%22%2C%22industry%22%3A%22Accountancy%22%2C%22job_type%22%3A%22permanent%22%2C%22job_status%22%3A%22full-time%22%2C%22weeks_to_advertise%22%3A%221%22%2C%22application_email%22%3A%22valid-email-address%40company.com%22%2C%22application_url%22%3A%22https%3A%2F%2Fwwww.company.com%2Fvalid-url%22%2C%22salary_type%22%3A%22annum%22%2C%22salary_from%22%3A%2220000%22%2C%22salary_to%22%3A%2240000%22%2C%22salary_currency%22%3A%22gbp%22%2C%22salary_benefits%22%3A%22Bonus%20payments%22%2C%22location%22%3A%22England%2C%20Yorkshire%20and%20the%20Humber%2C%20Yorkshire%2C%20Hull%22%2C%22reference%22%3A%22ref-123-xu%22%7D'
            
 
пример JSON для команды Удалить
              {
                "команда": "удалить",
                "имейл_компании": "[email protected]",
                "имя_компании": "Пример Имя Компании",
                "компания_хэш": "",
                "код_вакансии": "185394403-1508429206"
              }
 
пример JSON cURL для команды Удалить
                curl https://uk.whatjobs.com/api/v1/ats/{ats-name}/json?sandbox-mode=true \
                -X POST \
                -H 'x-api-token: {Authentication-Token}' \
                -d 'data=%7B%22command%22%3A%20%22delete%22%2C%20%22company_email%22%3A%20%22sample%40email.com%22%2C%20%22company_name%22%3A%20%22Sample%20Company%20Name%22%2C%20%22company_hash%22%3A%20%22%22%2C%20%22job_id%22%3A%20%22185394403-1508429206%22%7D'
              
 

 Коды Статусов Ответа HTTP 


В зависимости от результатов действия возвратный код статуса HTTP может быть одним из нижеуказанных значений.

Код Статуса Причина Ответное сообщение адресата Описание
200 успешно Конечный Пользователь Это результат успешного действия. Окончательное значение переменной ответного сообщения должно быть отображено для конечного пользователя
203 Ошибка в данных конечного пользователя Конечный Пользователь Такое происходит каждый раз, когда конечный пользователь вводит некорректную информацию. Ответное сообщение должно отображаться для пользователя. Например, если пользователь вводит некорректный адрес электронной почты или не имеет достаточно средств на счете.
400 Баг в конфигурации ATS ATS Это означает наличие ошибки в структуре предоставляемых данных. Это случается при наличии бага в конфигурации ATS. Например, значение параметра команды отличается отadd или удалить, или значение недель_для_рекламы Причиной может быть переменная в ответном сообщении.
503 Ошибка API ATS API временно недоступен и временно не может принять запрос. Ответное сообщение содержит более подробную информацию. В таком случае, ответный результат может быть HTML.
 

  Формат Ответа  


Обратный ответ будет XML или JSON в зависимости от выбранной конечной точки. Все ответы будут содержать следующие переменные

Данный код должен быть предоставлен при выполнении команды удаления.
Имя Описание
успешно Логическое значение указывает на статус обратного ответа, которые может быть Верным (с HTTP кодом 200) или Неверным (с HTTP кодом 203, 400 or 503).
сообщение Ответное сообщение должно быть отображено для конечного пользователя в случае, если код HTTO 200 или 203.
url_вакансии содержит URL вакансии при успешном выполнении команды добавитьлибо ноль
код вакансии содержит код вакансии при успешном выполнении команды addлибо ноль
 

  Пример Ответа  


 
сообщение об успешном выполнении XML с кодом HTTP 200
                <?xml version="1.0" encoding="UTF-8" ?>
                <response>
                <success><![CDATA[true]]></success>
                <message><![CDATA[The job has been added successfully.]]></message>
                <job_url><![CDATA[https://uk.whatjobs.com/job/sample-job-example-url]]></job_url>
                <job_id><![CDATA[185394449-1508749660]]></job_id>
                </response>
              
 
сообщение об успешном выполнении XML с кодом HTTP 200
                <?xml version="1.0" encoding="UTF-8" ?>
                <response>
                <success><![CDATA[true]]></success>
                <message><![CDATA[The job has been deleted successfully.]]></message>
                <job_url><![CDATA[]]></job_url>
                <job_id><![CDATA[]]></job_id>
                </response>
 
XML error response with HTTP code of 203
                  <?xml version="1.0" encoding="UTF-8" ?>
                  <response>
                  <success><![CDATA[false]]></success>
                  <message><![CDATA[The company email must be a valid email address.]]></message>
                  <job_url><![CDATA[]]></job_url>
                  <job_id><![CDATA[]]></job_id>
                  </response>
                
 
Сообщение об ошибке XML с кодом HTTP 400
                  <?xml version="1.0" encoding="UTF-8" ?>
                  <response>
                  <success><![CDATA[false]]></success>
                  <message><![CDATA[The submitted data is corrupted.]]></message>
                  <job_url><![CDATA[]]></job_url>
                  <job_id><![CDATA[]]></job_id>
                  </response>
 
сообщение об успешном выполнении JSON с кодом HTTP 200
                    {
                      "успешно": верно,
                      "message": "The job has been added successfully.",
                      "job_url": "https://uk.whatjobs.com/job/sample-job-example-url",
                      "job_id": "185394449-1508749660"
                    }
 
сообщение об успешном выполнении JSON с кодом HTTP 200
                      {
                        "успешно": верно,
                        "сообщение": "Данная вакансия была успешно удалена.",
                        "url_вакансии": нет,
                        "код_вакансии": нет
                      }
 
сообщение об ошибке JSON с кодом HTTP 203
                        {
                          "успешно": неверно,
                          "сообщение": "Имэйлом компании должен быть действительный имэйл.",
                          "url_вакансии": нет,
                          "код_вакансии": нет
                        }
 
сообщение об ошибке JSON с кодом HTTP 400
                          {
                            "успешно": неверно,
                            "сообщение": "Предоставленные данные повреждены.",
                            "url_вакансии": нет,
                            "код_вакансии": нет
                          }
 

  Заявка  


В зависимости от метода заявки на вакансиюapplication_email или application_url отправить ATS данные заявителя по имэйлу или перенаправить пользователя по предоставленному URL. Если оба переменных значения доступны, то стандартным используемы методом будет заявка по имэйлу.

 

  Формат Заявки по имэйлу  


Заявка по имэйлу будет отправлена от индивидуально сгенерированного адреса электронной почты на указанный адрес электронной почты со следующей темойЗаявка на{заголовок_вакансии} - {ссылка_вакансии}.

Письмо также содержит reply-to заголовок с имейл-адресом конечного пользователя.

Тело письма содержит HTML и версии простого текста. Обе версии содержат поля, объяснение которым дается ниже. HTML верия состоит из тэгов HTML формата, а текстовая верия из формата JSON.

Название поля Описание
название_вакансии Название вакансии
ссылка_вакансии Сыылка вакансии, если имеется.
Имя Имя соискателя
Фамилия Фамилия соискателя
имэйл имэйл соискателя
сопроводительное_письмо Сопроводительно письмо при наличии.