Skip to content

Instantly share code, notes, and snippets.

@ifgeny87

ifgeny87/Mts_Api_Integration.md

Last active August 11, 2022 20:41
Show Gist options
  • Save ifgeny87/5dc906d119a5876954f3028ac8a91774 to your computer and use it in GitHub Desktop.
Save ifgeny87/5dc906d119a5876954f3028ac8a91774 to your computer and use it in GitHub Desktop.
Download ZIP
Sever.ai - MTS: API integration documentation
Raw
Mts_Api_Integration.md

Sever.ai - MTS: API integration Documentation

Содержание

1. Окружения

2. Получение токена Bearer авторизации

Срок жизни токена авторизации - 10 дней.

Токен используется в заголовке запросов: Authorization: Bearer <token>.

Request

POST /login
{
  "username": "<username>",
  "password": "<password>"
}

Response

200 OK
header Authorization: <token>

3. Получение кандидатов

☝ наверх

Request

GET /api/integrations/mts/vacancy/<vacancyId>/candidates
header Authorization: Bearer <token>

Response

{
  "content": [
    {
      "id": 112795,
      "lastName": "Фамилия2",
      "firstName": "Алексей",
      "middleName": "Отчество2",
      "phone": "234",
      "email": "[email protected]",
      "citizenship": "Россия",
      "educationType": {
        "name": "DEGREE",
        "title": "Ученая степень"
      },
      "primaryEducations": [
        {
          "id": 15,
          "universityName": "Уральский филиал Московской финансово-юридической академии",
          "faculty": null,
          "profession": "Юриспруденция",
          "endYear": 2018
        }
      ],
      "sex": {
        "name": "FEMALE",
        "title": "Женский"
      },
      "candidateStatus": {
        "title": "Заинтересован",
        "name": "INTERESTED"
      },
      "city": {
        "id": 887,
        "name": "Москва",
        "country": {
          "id": 113,
          "name": "Россия"
        },
        "publicationPermitted": true
      },
      "scorePoint": 90,
      "vacancyId": 2233,
      "createdDate": "2021-07-26T10:35:41.878+0000",
      "lastModifiedDate": "2021-08-06T11:29:15.676+0000"
    },
    {
      "id": 112797,
      "lastName": "Фамилия5",
      "firstName": "Алексей",
      "phone": "567",
      "email": "[email protected]",
      "birthDate": "1965-06-28",
      "citizenship": "Россия",
      "educationType": {
        "name": "ABSENT",
        "title": "Отсутствует"
      },
      "primaryEducations": [
        {
          "id": 6,
          "universityName": "Российский государственный гуманитарный университет",
          "faculty": null,
          "profession": "Управление персоналом",
          "endYear": 2014
        },
        {
          "id": 12,
          "universityName": "Московский Государственный Политехнический Университет (Московский Политех)",
          "faculty": "Менеджмент в сфере науки и технологий",
          "profession": "Менеджмент. Управление инновационными проектами",
          "endYear": 2017
        }
      ],
      "sex": {
        "name": "FEMALE",
        "title": "Женский"
      },
      "candidateStatus": {
        "title": "Заинтересован",
        "name": "INTERESTED"
      },
      "city": {
        "id": 3741,
        "name": "Ростов-на-Дону",
        "region": {
          "id": 1530,
          "name": "Ростовская область",
          "country": {
            "id": 113,
            "name": "Россия"
          }
        },
        "country": {
          "id": 113,
          "name": "Россия"
        },
        "publicationPermitted": true
      },
      "vacancyId": 2233,
      "resumeLastUpdate": "2021-04-04T23:19:53.910Z",
      "createdDate": "2021-07-26T10:35:41.878+0000",
      "lastModifiedDate": "2021-08-06T11:33:31.583+0000"
    },
    {
      "id": 112798,
      "lastName": "Фамилия1",
      "firstName": "Вадим",
      "middleName": "Отчество1",
      "phone": "123",
      "email": "[email protected]",
      "birthDate": "1999-01-28",
      "citizenship": "Россия",
      "educationType": {
        "name": "ABSENT",
        "title": "Отсутствует"
      },
      "additionalEducations": [
        {
          "id": 274,
          "organization": "Comtech",
          "courseName": "Comtech",
          "endYear": 2012
        }
      ],
      "candidateStatus": {
        "title": "Найден",
        "name": "FOUND"
      },
      "city": {
        "id": 887,
        "name": "Москва",
        "country": {
          "id": 113,
          "name": "Россия"
        },
        "publicationPermitted": true
      },
      "vacancyId": 2233,
      "createdDate": "2021-07-26T10:35:41.878+0000",
      "lastModifiedDate": "2021-08-05T14:11:54.307+0000"
    }
  ]
}

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

параметр пример описание
vacancyId 26 идентификатор вакансии в sever.ai
candidateStatuses FOUND,INTERESTED список статусов кандидата
page 0 номер страницы
size 50 количество кандидатов на странице
sort id,desc сортировать можно по id - идентификатору кандидата, createdDate - времени создания резюме, lastModifiedDate - времени обновления резюме. Через запятую указывается направление сортировки asc по возрастанию или desc по убыванию
createdDateAfter 2021-08-08T12:34:56Z время создания резюме больше или равно указанного момента времени, формат YYYY-MM-DD'T'hh:mm:ss'Z'
createdDateBefore 2021-08-08T12:34:56Z время создания резюме меньше или равно указанного момента времени, формат YYYY-MM-DD'T'hh:mm:ss'Z'
lastModifiedDateAfter 2021-08-08T12:34:56Z время обновления резюме больше или равно указанного момента времени, формат YYYY-MM-DD'T'hh:mm:ss'Z'
lastModifiedDateBefore 2021-08-08T12:34:56Z время обновления резюме меньше или равно указанного момента времени, формат YYYY-MM-DD'T'hh:mm:ss'Z'

Список статусов

  • FOUND - найден
  • INVITED - приглашен
  • INTERESTED - заинтересован
  • NOT_INTERESTED - не заинтересован
  • REJECTED_BY_CLIENT - отклонен клиентом

В запросе можно настроить сортировку по нескольким полям. Например, в ответе на следующий запрос вернется список кандидатов, в котором сортировка выполнена сначала по имени в обратном порядке, потом по дате обновления:

GET /api/integrations/mts/vacancy/<vacancyId>/candidates?sort=firstName,desc&sort=lastModifiedDate

В запросе можно настроить фильтр по нескольким значениям статуса. Например:

GET /api/integrations/mts/vacancy/<vacancyId>/candidates?candidateStatuses=INTERESTED,NOT_INTERESTED,REJECTED_BY_CLIENT

4. Получение одного кандидата

☝ наверх

Request

GET /api/integrations/mts/candidates/<candidateId>

Response

{
  "id": 112797,
  "lastName": "Фамилия5",
  "firstName": "Алексей",
  "phone": "567",
  "email": "[email protected]",
  "birthDate": "1965-06-28",
  "citizenship": "Россия",
  "educationType": {
    "name": "ABSENT",
    "title": "Отсутствует"
  },
  "primaryEducations": [
    {
      "id": 6,
      "universityName": "Российский государственный гуманитарный университет",
      "faculty": null,
      "profession": "Управление персоналом",
      "endYear": 2014
    },
    {
      "id": 12,
      "universityName": "Московский Государственный Политехнический Университет (Московский Политех)",
      "faculty": "Менеджмент в сфере науки и технологий",
      "profession": "Менеджмент. Управление инновационными проектами",
      "endYear": 2017
    }
  ],
  "additionalEducations": [],
  "sex": {
    "name": "FEMALE",
    "title": "Женский"
  },
  "candidateStatus": {
    "title": "Заинтересован",
    "name": "INTERESTED"
  },
  "city": {
    "id": 3741,
    "name": "Ростов-на-Дону",
    "region": {
      "id": 1530,
      "name": "Ростовская область",
      "country": {
        "id": 113,
        "name": "Россия"
      }
    },
    "country": {
      "id": 113,
      "name": "Россия"
    },
    "publicationPermitted": true
  },
  "vacancyId": 2233,
  "resumeLastUpdate": "2021-04-04T23:19:53.910Z",
  "createdDate": "2021-07-26T10:35:41.878+0000",
  "lastModifiedDate": "2021-08-06T11:33:31.583+0000"
}

5. Скачивание CV в формате Sever.ai

☝ наверх

Request

GET /api/integrations/mts/candidates/<candidateId>/download-cv

6. Получение списка звонков

☝ наверх

Request

GET /api/integrations/mts/candidates/<candidateId>/phone-calls

Response

{
  "content": [
    {
      "id": 521,
      "duration": 0,
      "phoneCallStatus": {
        "title": "Голосовая почта",
        "name": "VOICEMAIL"
      },
      "result": true,
      "interviewText": "{}",
      "interview": [],
      "createdDate": "2021-07-09T07:19:24.247+0000"
    },
    {
      "id": 527,
      "duration": 17,
      "phoneCallStatus": {
        "title": "Заинтересован",
        "name": "INTERESTED"
      },
      "result": true,
      "interviewText": "{}",
      "interview": [
        {
          "id": 619,
          "position": 0,
          "question": "Вы являетесь экспертом?",
          "open": false,
          "answer": "да ",
          "intent": "yes"
        },
        {
          "id": 620,
          "position": 1,
          "question": "Вам больше 40 лет?",
          "open": false,
          "answer": "да ",
          "intent": "yes"
        }
      ],
      "audioLink": "https://storage.com/link_to_audio_record",
      "createdDate": "2021-08-05T14:53:30.309+0000"
    }
  ]
}

В этом примере продемонстрирован список звонков кандидату с двумя возможными исходами.

Статусы звонков

  • FAILED - вызов кандидата прерывается до соединения
  • VOICEMAIL - кандидат отклонил звонок или не ответил
  • INTERESTED - кандидат завершил звонок с положительным результатом
  • NOT_INTERESTED - кандидат завершил звонок с отрицательным результатом
  • DISCONNECTED - кандидат взял трубку, но потом скинул до окончания сценария
  • REJECTED_BY_CLIENT - кандидат завершил звонок с отрицательным результатом

7. Получение списка диалогов с чатботом

☝ наверх

Request

GET /api/integrations/mts/candidates/<candidateId>/messenger-dialogs

Response

{
  "content": [
    {
      "id": 64,
      "scenarioId": "chatbot_test",
      "webhookBody": {
        "answers": {
          "1": {
            "question": "Рассматриваете ли Вы сейчас предложения о работе?",
            "value": "Да"
          },
          "2": {
            "question": "Укажите Ваш возраст",
            "value": "25"
          }
        }
      },
      "initialMessageStatus": "read",
      "result": "approved",
      "createdDate": "2021-07-16T08:03:18.448+0000"
    }
  ]
}

Поля ответа

поле описание
webhookBody.answers Список вопросов и ответов диалога
initialMessageStatus Последний статус диалога. Возможные значения: sent - отправлено, delivered - доставлено, read - прочитано, failed - отсутствует WA.
result Результат диалога. Возможные значения: not completed - не завершен, approved - положительное завершение диалога, rejected - отрицательное завершение диалога.

8. Сценарий обработки

☝ наверх

Предлагаем сценарий для обработки списка кандидатов:

  1. Запрос списка кандидатов с сортировкой по полю последнего обновления резюме и фильтром по финальному статусу кандидата.
  2. Загрузка списка звонков и диалогов.

В этом сценарии не потребуется загружать кандидатов на статусе "Найден".

1 шаг. Стартовый запрос списка кандидатов

В первом шаге выполняется стартовый запрос. Результатом запроса будет список кандидатов, имеющих статус завершения - INTERESTED, NOT_INTERESTED или REJECRED_BY_CLIENT. В запросе используется сортировка по дате обновления резюме. В последующих запросах списка кандидатов это поле можно будет использовать для фильтрации уже просмотренных кандидатов.

GET /api/integrations/mts/vacancy/<vacancyId>/candidates?candidateStatuses=INTERESTED,NOT_INTERESTED,REJECTED_BY_CLIENT&sort=lastModifiedDate&size=50

2 шаг. Загрузка списка звонков

Для каждого кандидата можно получить список звонков и проверить статус звонка. Если в списке звонков присутствует статус звонка INTERESTED, значит кандидат подтвердил свой интерес и положительно прошел сценарий звонка.

GET /api/integrations/mts/candidates/<candidateId>/phone-calls?sort=createdDate

3 шаг. Загрузка списка диалогов

Для каждого кандидато можно получить список диалогов и првоерить статус диалога. Если в списке диалогов присутстует статус approved, значит кандидат подтвердил свой интерес и положительно прошел сценарий диалога.

GET /api/integrations/mts/candidates/<candidateId>/messenger-dialogs?sort=createdDate

4 шаг. Загрузка списка кандидатов с фильтрацией по дате обновления

Чтобы не загружать повторно уже проверенных кандидатов, их можно отфильтровать по дате обновления резюме, взятой из последней записи в запросе на первом шаге.

GET /api/integrations/mts/vacancy/<vacancyId>/candidates?candidateStatuses=INTERESTED,NOT_INTERESTED,REJECTED_BY_CLIENT&sort=lastModifiedDate&size=50&lastModifiedDateAfter=2021-08-09T12:34:56Z
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment