Интеграция с API

Получение информации о мероприятии

Получить информацию о мероприятии можно, исполнив GET запрос по адресу https://api.reg.place/v1/events/{slug}?compact=false&races=true, где slug — уникальный идентификатор мероприятия. Вы получите json-объект, содержащий всю необходимую информацию для отображения мероприятия на вашем сайте. В полученном json необходимо обратить внимание на ключ races, в нём находятся дисциплины мероприятия, и на ключ form_fields, который присутствует у мероприятия и может присутствовать у дисциплин мероприятия.

Ключ form_fields содержит информацию для построителя форм, в нём описывается то, как должна выглядеть анкета для регистрации на дисциплину мероприятия. Если ключа form_fields нет в дисциплине, необходимо использовать данные из ключа form_fields мероприятия. Форма представляет собой массив объектов-полей.

Ниже представлена информация о том, как выглядит элемент массива — единичное поле. Ключ presence намекает на то, что это обязательное поле, ключ validator описывает формат поля (дата, телефон, время и т.д.). Ключ select_variants описывает допустимые варианты для селектора. Остальные атрибуты понятны без дополнительного описания.

{
  "name": "name_last",
  "label": "Фамилия",
  "placeholder": "ваша фамилия",
  "hint": "Введите вашу фамилию.",
  "type": "string",
  "default": "",
  "presence": true,
  "validator": null,
  "select_variants": {},
  "agreement_text": null
}

Получив информацию о мероприятии, вы можете составить заявку, включив в нее все обязательные поля из ключа form_fields для дисциплины или мероприятия.

Создание заявки

Для создания заявки необходимо выполнить json POST запрос по адресу https://api.reg.place/v1/heats. В запросе обязательно должны быть указаны: race_id — идентификатор дисциплины, token — уникальный идентификатор компании, проводящей мероприятия (этот параметр можно посмотреть в админке, в разделе своей компании). Также вам необходимо верно составить объект form_fields, содержащий ответы пользователя на вопросы анкеты.

Объект с ответами строится на базе информации о мероприятии из предыдущего раздела и представляет собой структуру. Пример:

  {
  "personal.name_last": "Савельев",
  "personal.name_first": "Константин",
  "personal.birthday": "1983-10-17",
  "personal.gender": "male",
  "contacts.email": "inferno@bugz.ru"
}

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

heat = {
  race_id: 783,
  token: '9f9a9bc1-428d-4d2c-9b08-4c0cc0d0f251', # это фейковый токен, не используйте его, он не будет работать
  code: 'DSDEFRG', # вы можете указать промокод, который будет использован для формирования заявки
  form_fields: {
    'personal.name_last': 'Савельев',
    'personal.name_first': 'Константин',
    'personal.birthday': '1983-10-17',
    'personal.gender': :male,
    'contacts.email': 'inferno@bugz.ru'
  }
}

c = Faraday.new(url: 'https://api.reg.place') do |faraday|
  faraday.headers['Content-Type'] = 'application/json'
  faraday.response :logger
  faraday.adapter Faraday.default_adapter
end

c.post do |req|
  req.url '/v1/heats'
  req.headers['Content-Type'] = 'application/json'
  req.body = heat.to_json
end

При успешной регистрации вы получите json-ответ, содержащий ссылку в ключе payment_url, перейдя по которой, вы попадете на сайт банка и сможете завершить оплату. Пример успешного ответа после создания заявки:

{
  "status" => "success",
  "event_name" => "Забег весёлых ежей",
  "race_name" => "Полумарафон",
  "heat" => {
    "id" => 78838,
    "status" => "created",
    "payment_url" => "https://securepayments.sberbank.ru/payment/merchants/rbs/payment_ru.html?mdOrder=7e936be5-01d0-437e-8200-31e0d459830b"
  }
}

При неудачной регистрации, ответ вида:

{
  "status" => "error",
  "message" => "не удалось создать заявку",
  "errors" => {
    "personal.name_last" => "не может быть пустым",
    "contacts.email" => "имеет неверное значение"
  }
}

Если вы попытаетесь зарегистрироваться на мероприятие с реквизитами, с которыми уже ранее создавали заявку (имя, фамилия, год рождения), вам будет возвращена информация о ранее созданной заявке. Используйте payment_url для повторной оплаты.

Примечание №1

Мероприятие можно настроить на сбор дополнительных взносов; при регистрации вы можете указать дополнительный взнос в ключе donation; если для мероприятия сбор дополнительных взносов запрещен, при попытке создать заявку вы получите ошибку.

Получение информации о заявке

Для получения информации о заявке вам необходимо выполнить GET-запрос по адресу https://api.reg.place/v1/heats/{id}, где id — номер заявки. Пример ответа:

{
  "heat": {
    "id": 78829,
    "status": "locked",
    // статус заявки: locked — оплачивается, ready — оплачено, created — новая, cancelled — отменена
    "name_first": "Константин",
    "name_last": "Савельев",
    "name_middle": null,
    "birthday": "1983-10-17",
    "gender": "male",
    "paid_at": null,
    // дата оплаты заявки, если оплата была
    "heat_url": "http://api.reg.place/heats/5d6ab3bb-7bce-48cc-8534-9fd382307a0c"
    // ссылка на страничку заявки на http://reg.place
  }
}

Также вы можете получить список всех актуальных заявок для всех дисциплин выбранного мероприятия, для этого выполните GET-запрос по адресу https://api.reg.place/v1/events/{slug}/heats, где slug — айди мероприятия. Будет возвращен json объект, содержащий все дисциплины и актуальные заявки для них.