Техническая интеграция брендов с Travelpayouts

Вы уже зарегистрировались в платформе и изучили основную статью? Следующий шаг — техническая интеграция для запуска вашей программы. Она нужна, чтобы связать бронирования пользователей на вашем ресурсе и партнёров, которые их привели. 

Существуют разные способы интеграции, но мы используем самый надёжный и удобный — интеграция через API. В данной статье содержится информация о процессе интеграции.

Как происходит отслеживание перехода на сайт бренда?

Каждый переход осуществляется с определённой меткой. С её помощью вы можете отделить трафик, поступающий от Travelpayouts, от любого другого. Метка может быть совершенно любой — решение за вами. Чаще всего используют utm_source=travelpayouts. 

Вы можете найти информацию о том, как ставить и анализировать метки в статье: Как правильно сделать UTM-метку.

При каждом переходе необходимо принять от Travelpayouts дополнительный параметр, в котором всегда находится уникальное значение для перехода. Параметр необходим, чтобы связывать бронирования, клики и партнёров в нашей системе учёта бронирований.

Название данного параметра определяете вы сами. Чаще всего наши бренды используют track_id. Значение этого параметра — строка, содержащая латинские буквы, цифры и тире. Длина параметра — 32 символа. Пример: 32990942748b4e5db9e8096127-79430. Однако, если есть возможность, то лучше поддержать 64 символа.

При каждом переходе вам нужно записывать значение параметра в файл cookie, на срок, прописанный в договоре. Если пользователь напрямую переходит на ваш сайт в течение этого времени и бронирует услугу, то вместе с информацией о бронировании необходимо сохранять параметр track_id, который был передан вам в момент последнего перехода пользователя. Примеры кода для записи параметра в cookie можно посмотреть в личном кабинете, в разделе Интеграция.

Как происходит сбор информации о бронированиях?

Чтобы мы могли связать бронирования и партнёров, вам необходимо передавать в Travelpayouts информацию определённый набор данных в JSON формате.

Доступ к информации должен осуществляться по прямому URL без необходимости проходить авторизацию. По желанию возможен вариант с передачей ключа / токена в запросе.

Мы должны иметь возможность задать период выгрузки данных в запросе. Параметры должны называться from и to. Их формат — YYYY-MM-dd. Например, “from=2021-10-01&to=2021-10-20” выгрузит все бронирования, которые менялись в этот период.

Обязательные данные в выгрузке:

  • order_number — уникальный номер заказа в вашей системе;
  • price — полная стоимость бронирования, от которой мы считаем вознаграждение партнёра и Travelpayouts в случае, если мы работаем с вами по схеме Стоимость заявки;
  • base_profit — значение, от которого считается вознаграждение партнёра и Travelpayouts в случае, если мы работаем с вами по схеме Доход рекламодателя;
  • profit — полное вознаграждение партнёра и Travelpayouts. Та сумма, которая будет включена в счёт;
  • currency — код валюты, в которой отображаются данные price и profit (RUB, EUR, USD и т. д.);
  • description — описание заказа, которое увидит партнёр. Необходимо использовать вложенную структуру для описания всех деталей заказа, например: "{checkin_date: "2021-10-01", checkout_date: "2021-10-05", country:"Russia", city: "Moscow", property_name: "Ritz Apartments", guests_count: "2"}". Если сумма вознаграждения зависит от параметров бронирования, то укажите эти параметры в этом блоке. Здесь же указывается любая другая информация, которая поможет нашему партнёру лучше понимать конверсию.
    Вы должны отправлять всю информацию о заказе, не раскрывая персональные данные пользователя. Минимальная информация: даты, города и страны въезда/выезда. Если у вас несколько типов продуктов, то дополнительно необходимо уточнить тип: тур, автобусы, экскурсии, трансфер и т.п. Мы всё аккуратно разберём на параметры и покажем партнёру в личном кабинете. Эта информация очень полезна, поэтому стоит передавать как можно больше данных.
    Пример:
    mceclip0.png
  • track_id — параметр, который передаётся нами при переходе пользователя на ваш ресурс (пример: track_id=32990942748b4e5db9e8096127-79430);
  • status — статус бронирования:
    • processing — бронирование создано, но ещё не оплачено или не подтверждено. Средства партнёру ещё не начислены, но он видит бронирование в своём личном кабинете;
    • paid — бронирование оплачено, средства начисляются нашему партнёру. Вы гарантируете оплату вознаграждения за бронирование;
    • cancelled — бронирование полностью отменено, средства списаны с баланса нашего партнёра. Вы не должны оплачивать нам это бронирование;
  • updated_at — дата последнего изменения бронирования. Если изменились статус, стоимость, доход или другие данные, то параметр updated_at должен содержать дату и время изменения.

    Все бронирования в выгрузке сортируются по параметру updated_at от меньшего к большему.

    Таким образом, любое изменение бронирования будет учтено, в том числе любые возвраты и т. д.

Пример выгрузки одного из наших брендов:

[
  {
    "order_number": 8717,
     "price": "500.0",
     "profit": "40.0",
     "currency": "rub",
     "description": {
        checkin_date: "2018-01-01",
        checkout_date: "2018-01-10",
        city: "Moscow",
        property_name: "Ritz-Carlton, Moscow",
        guests_count: "2"
     },
     "track_id": "32990942748b4e5db9e8096127-79430";
     "status": "processing",
     "updated_at":"2017-02-15T16:36:40"
  }
]

Пожалуйста, обратите внимание на параметр status. Как бренд, вы оплачиваете только бронирования, перешедшие в статус Paid. Если бронирование было отменено (статус Cancelled) или дата его проведения ещё не наступила (статус Processing), оно не попадает в ваш ежемесячный счёт на оплату.

Краткое резюме

В результате интеграции от вас требуется две ссылки:

  1. Ссылка на ваш сайт с параметрами трекинга. Например, https://www.advertiser.com/?utm_source=travelpayouts&track_id=XXXX (как указано выше, названия переменных для данных параметров определяете вы сами). 
  2. Ссылка на статистику бронирований.

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

Была ли эта статья полезной?

Еще есть вопросы? Отправить запрос