Skip to content

Instantly share code, notes, and snippets.

@Kiryous

Kiryous/products-guide.md Secret

Last active Oct 5, 2020
Embed
What would you like to do?
Surprise Me API. Инструкция по интеграции покупок экскурсий

Surprise Me API. Инструкция по интеграции покупок экскурсий

Содержание

  1. Вводные данные об API
  2. Начало работы
  3. Список эндпоинтов
  1. Отрисовка карточек товаров
  2. Отображение страницы оплаты
  3. О куках и имейлах
  4. Тестирование и вопросы

Вводные данные об API

API позволяет получить данные о экскурсиях Surprise Me, языках экскурсий и городах, доступных в магазине в данный момент.

Базовый URL

Здесь и далее JavaScript (ES2015)

const API_URL = "https://app.surprizeme.ru/api";

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

Content-Type: application/json; charset=utf-8

Начало работы

Для формирования реферальных ссылок на экскурсии, вам потребуется SUB_ID (если вы подключаетесь через TravelPayouts) или REFERER_ID (если вы подключаетесь напрямую к Партнерской программе Surprise Me).

Список эндпоинтов

Список языков

GET /languages/

Список городов

GET /cities/

Поиск города по частичному совпадению имени

Ищется от 3 символов и более.

GET /search/?query=Мос

Товары

GET /products/?city=moscow&lang=ru

GET-параметры для фильтрации
Параметр Смысл Доступные значения Пример
lang Код языка товара (контент, описание) code из GET /languages/ ru
city Уникальный идентификатор города slug из GET /search/ или GET /cities/ moscow

Декодированный ответ: под ключом data массив объектов, представляющих товар

{  
   "data":[  
        {
           "id":12,
           "name":"Неформальные достопримечательности Петербурга: Площадь Восстания",
           "hidden":false,
           "caption":"Красоты Санкт-Петербурга — это не только музеи и дворцы. Мы готовы доказать вам, что дворы и переулки хранят не меньше интересного, чем залы Эрмитажа. Яркие петербургские дворики, замысловатые памятники, достопримечательности и красочныый стрит-арт, спрятанные от любопытных глаз, ждут своих новых зрителей!\r\n\r\nПешеходный маршрут начинается у станции метро Достоевская и заканчивается недалеко от станции Площадь Востания.\r\n\r\nВ экскурсию входят объекты (дворы и парадные) с закрытыми воротами/входами. К сожалению, мы не можем предоставить вам коды или ключи от дворов. Советуем не упускать возможность насладиться уникальной достопримечательностью и дождаться, когда-то кто-то из жильцов будет возвращаться домой.",
           "short_caption":"Дворы и переулки хранят не меньше интересного, чем залы Эрмитажа. И мы готовы вам это доказать!",
           "attractions":"— Найдем памятник Фёдору Достоевскому\r\n— Памятник доблестным Трубочистам\r\n— Посетим сказочный Изумрудный город\r\n— Отыщем дворик, где с друзьями вы сможете разыграть шахматную партию (как в Гарри Поттере, помните?)\r\n— Увидим что осталось от неудавшегося советского стартапа\r\n— Посмотрим на настоящий Дом-коммуну\r\n— Посетим Эльфийский дворик и другие необычные достопримечательности Петербурга!",
           "distance":"4 км",
           "complexity":"easy",
           "locale":{
              "id":1,
              "name":"Русский",
              "code":"ru"
           },
           "city":{
              "id":1,
              "name":"Санкт-Петербург",
              "slug":"saint-petersburg",
              "country":{
                 "name":"Россия",
                 "code":"RU"
              },
              "bg_image":"https://app.surprizeme.ru/media/world/Saint_Petersburg_Surprise_Me.jpg",
              "preview_image":"https://app.surprizeme.ru/media/CACHE/images/world/Saint_Petersburg_Surprise_Me/a3ca495104075ec257b05fc2814fec47.jpg"
           },
           "start_location":"станция метро «Достоевская»",
           "location_geo":{
              "type":"Point",
              "coordinates":[
                 30.347509959201375,
                 59.92745122424092
              ]
           },
           "duration":"1,5 – 2 часа",
           "price":"1290",
           "discount":0,
           "price_mobile":{
              "itunes_id":"45",
              "google_id":"45",
              "price":"1290"
           },
           "exprice":null,
           "bg_image":"https://app.surprizeme.ru/media/store/img0240_18ZqqNi.jpg",
           "preview_image":"https://app.surprizeme.ru/media/CACHE/images/store/img0240_18ZqqNi/1903e38a672d63aaabce4459128e4208.jpg",
           "currency":{
              "id":1,
              "rate":1.0,
              "code":"RUB",
              "symbol":"₽"
           },
           "slug":"neformalnye-dostoprimechatelnosti-peterburga",
           "rating":4.6,
           "types":{
              "citys":true,
              "excursions":true
           },
           "author":{
              "avatar":"https://app.surprizeme.ru/media/users/135/id135-avatar_URV9iqA.png",
              "name":"Гаврил",
              "first_name":"Гаврил",
              "bio":"С детства люблю участвовать в квестах и обожаю родной Санкт-Петербург. В городе меня привлекают необычные места, за пределами туристических троп.",
              "nickname":"id135",
              "rating":4.636363636363637,
              "reviews_count":11,
              "cities":[
                 {
                    "id":1,
                    "name":"Санкт-Петербург",
                    "slug":"saint-petersburg",
                    "country":{
                       "name":"Россия",
                       "code":"RU"
                    },
                    "bg_image":"https://app.surprizeme.ru/media/world/Saint_Petersburg_Surprise_Me.jpg",
                    "preview_image":"https://app.surprizeme.ru/media/CACHE/images/world/Saint_Petersburg_Surprise_Me/a3ca495104075ec257b05fc2814fec47.jpg"
                 }
              ],
              "locales":[
                 {
                    "id":1,
                    "name":"Русский",
                    "code":"ru"
                 },
                 {
                    "id":2,
                    "name":"Английский",
                    "code":"en"
                 }
              ]
           },
           "reviews":[
              {
                 "name":"s4hbwsk8y2",
                 "text":"На первом памятнике убрали табличку. В остальном очень круто!",
                 "avatar":"",
                 "rating":5,
                 "date":"2020-06-29T06:27:47.913578Z"
              },
              {
                 "name":"Елена",
                 "text":"Спасибо, было здорово)",
                 "avatar":"",
                 "rating":4,
                 "date":"2019-09-30T08:06:45.636317Z"
              },
              {
                 "name":"Евгений ",
                 "text":"Интересно, погуляйте )",
                 "avatar":"",
                 "rating":5,
                 "date":"2019-05-06T10:43:32.448171Z"
              },
              {
                 "name":"Сергей",
                 "text":"Отличная квест-экскурсия, чтобы размяться и повидать интересные закоулочки и дворики))",
                 "avatar":"https://app.surprizeme.ru/media/users/13913/iuuj2kh7dhs.jpg",
                 "rating":5,
                 "date":"2018-11-06T07:38:23.022887Z"
              },
              {
                 "name":"micheev_al",
                 "text":"Круто, особенно понравился людоед, сделали кучу прикольных фоток!",
                 "avatar":"",
                 "rating":5,
                 "date":"2018-10-16T11:24:40.436687Z"
              },
              {
                 "name":"aektitorov",
                 "text":"Квест элементарный. В целом, квест создан для туриста, который не хочет бродить бесцельно.",
                 "avatar":"",
                 "rating":4,
                 "date":"2018-09-24T07:24:26.996905Z"
              },
              {
                 "name":"Алексей",
                 "text":"Интересно прогуляться.",
                 "avatar":"https://app.surprizeme.ru/media/users/11554/.aaue7mcry0e8io5ajrsmyfpjvowxvppjj0wt2klvyi06pws50",
                 "rating":5,
                 "date":"2018-08-01T02:02:47.139402Z"
              },
              {
                 "name":"imeitesovest",
                 "text":"Отличная идея, как погулять и хорошо провести время в компании!",
                 "avatar":"",
                 "rating":5,
                 "date":"2017-10-02T11:53:15.794179Z"
              },
              {
                 "name":"Кирилл",
                 "text":"Спасибо вам за такое замечательное приключение! Благодаря вам мы отрыли для себя много новых интересных и красивых мест в Петербурге!",
                 "avatar":"",
                 "rating":5,
                 "date":"2017-10-02T11:52:10.617317Z"
              },
              {
                 "name":"Настя",
                 "text":"Завтра продолжим, нам очень понравилось! Прямо молодцы, буду вас рекомендовать!",
                 "avatar":"https://app.surprizeme.ru/media/users/21/ava2.jpg",
                 "rating":5,
                 "date":"2017-05-20T05:09:25.089798Z"
              }
           ],
           "reviews_count":10,
           "images":[
              {
                 "id":170,
                 "preview":"https://app.surprizeme.ru/media/CACHE/images/store/12/img0280/0356bcb296c753d26856cecb04c9d9ac.jpg",
                 "full":"https://app.surprizeme.ru/media/store/12/img0280.jpg"
              },
              {
                 "id":168,
                 "preview":"https://app.surprizeme.ru/media/CACHE/images/store/12/img0253/8e8e30809c157a48c5f8148b3f601310.jpg",
                 "full":"https://app.surprizeme.ru/media/store/12/img0253.jpg"
              },
              {
                 "id":167,
                 "preview":"https://app.surprizeme.ru/media/CACHE/images/store/12/img0240/7f60bc43373faac3d9fa1b6a79c0209d.jpg",
                 "full":"https://app.surprizeme.ru/media/store/12/img0240.jpg"
              },
              {
                 "id":166,
                 "preview":"https://app.surprizeme.ru/media/CACHE/images/store/12/img0265/c696242a974dfa8f529f22f75c3faca2.jpg",
                 "full":"https://app.surprizeme.ru/media/store/12/img0265.jpg"
              },
              {
                 "id":165,
                 "preview":"https://app.surprizeme.ru/media/CACHE/images/store/12/img0272/9f251e7b83ae1638ab60d0184e12c34c.jpg",
                 "full":"https://app.surprizeme.ru/media/store/12/img0272.jpg"
              }
           ],
           "location":"['private', 'store']",
           "bounding_circle":{
              "coords":{
                 "lng":30.34691697943819,
                 "lat":59.92649211558415
              },
              "radius":743.2825098631802
           },
           "city_slug":"saint-petersburg",
           "collection_slug":"unusual",
           "cover_position":100,
           "status":"approved",
           "meta_title":"",
           "meta_description":"",
           "is_favorite":false,
           "is_online":false,
           "content_types":{
              "image":true,
              "video":false,
              "audio":true,
              "streetview":false
           }
        },
      ...
   ]
}

Отрисовка карточек товаров

Эта часть, как говорится, is up to you. Посмотрите, как мы делаем это в магазине.

В качестве картинки используйте preview_image. По клику на карточку перенаправляйте. на наш сайт.

Перенаправление на сайт Surprise Me

Вам понадобится slug из объекта товара (cм. Получение JSON товаров) и SUB_ID либо REFERER_ID.

1. Перенаправление на страницу товара в магазине (рекомендуемый способ)

  • TravelPayouts URL https://surprizeme.ru/ru/store/${slug}/?sub_id=${SUB_ID}
  • Напрямую Surprise Me URL https://surprizeme.ru/ru/store/${slug}/?coupon=${REFERER_ID}

Пример для аудиоэкскурсии «Неформальные достопримечательности Петербурга: Площадь Восстания» URL https://surprizeme.ru/ru/saint-petersburg/unusual/neformalnye-dostoprimechatelnosti-peterburga/?coupon=3

  <a href="https://surprizeme.ru/ru/store/neformalnye-dostoprimechatelnosti-peterburga/?coupon=3">
    Подробнее
  </a>

2. Перенаправление на чекаут в магазине

  • TravelPayouts URL https://surprizeme.ru/ru/checkout/${slug}/?sub_id=${SUB_ID}
  • Напрямую Surprise Me URL https://surprizeme.ru/ru/checkout/${slug}/?coupon=${REFERER_ID}

Пример для аудиоэкскурсии «Неформальные достопримечательности Петербурга: Площадь Восстания» URL https://surprizeme.ru/ru/checkout/neformalnye-dostoprimechatelnosti-peterburga/?coupon=3

  <a href="https://surprizeme.ru/ru/checkout/neformalnye-dostoprimechatelnosti-peterburga/?coupon=3">
    Купить
  </a>

О куках и имейлах

После перехода пользователя на сайт по вашей ссылке, ваш SUB_ID либо REFERER_ID сохраняется в куки на 30 дней. Если за это время пользователь совершил покупку или начал оплату — он привязывается к вашему аккаунту реферального партнера и все со всех последующих его покупок вы будете получать отчисления.

Surprise Me посылает письма пользователям начавшим, но не завершившим оплату. Это идет вам на пользу, так как в таком случае пользователь завершивших покупку привяжется к вашему аккаунту и будет приносить вам доход.

Тестирование и вопросы

Чтобы протестировать вашу интеграцию, а также по всем техническим вопросам пишите на kirill@surprizeme.ru.

Обновлено 25 сентября 2020 года

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment