API почтовой рассылки с регистрацией заказов

Содержание

Введение


Партнер предоставляет Трипстеру данные о заказах услуг, которые он оказывает (авиабилеты, отели, такси и т.п.), и Трипстер рассылает таргетированные письма с предложениями экскурсий от имени самого партнера, используя необходимый шаблон письма с фирменным стилем партнера. Например, партнер продал авиабилет в Париж и сообщил об этом Трипстеру, а за неделю до вылета Трипстер отправляет с почтового адреса партнера письмо с экскурсиями в Париже.

Партнер получает процент от комиссии Трипстера с фактически оплаченных экскурсий, заказанных по ссылке из письма с партнерской меткой.

Схема почтовой рассылки

Как это работает

  • Доступ к REST API Трипстера. Трипстер предоставляет партнеру ID и секретный ключ для аутентификации в своем REST API для регистрации заказов партнера.
  • Регистрация заказов партнера через API. Партнер через API Трипстера получает geo-id города, в котором он продал услугу своему клиенту. Затем регистрирует данные о новом заказе на сервере Трипстера. В зависимости от типа продаваемых услуг, партнер может указать дату и город как прибытия (отель, трансфер), так и возвращения (обратный авиабилет). Таким образом можно рассказать клиенту о возможности заказать экскурсию и во время путешествия, и в его родном городе в качестве досуга.
  • Отправка партнерской рассылки. Ежедневно в 00:00 и 18:00 происходит проверка на условия рассылки предложений с экскурсиями. Период отправки рассылки зависит от того, за сколько времени до прибытия был зарегистрирован заказ партнера:
    • Письмо "до прибытия в город назначения" отправляется за 12 дней, но не позже 1 дня до даты прибытия.
    • Письмо "после возвращения обратно" отправляется через 7 дней после даты возвращения, если она была указана.
  • Отправка писем. Письма пользователю отправляются в дизайне партнера. Возможна отправка как с адреса (partner)@tripster.ru, так и с адреса в домене партнера. Для последнего партнеру необходимо настроить DNS-записи своего домена.
  • Шаблон партнерской рассылки. Партнер предоставляет Трипстеру свой типовой почтовый шаблон, чтобы на его основе создать письмо рассылки в фирменном стиле партнера. В шаблоне прописываются utm-метки и ID партнера, по которому отслеживаются заказы для выплаты партнерского вознаграждения.
  • Статистика по партнерской программе. Партнер через REST API может смотреть список заказов экскурсий, совершенных с использованием его партнерской метки. Также партнер может запросить доступ к Google Analytics для просмотра статистики переходов из рассылки с utm-метками.

Регистрация заказов партнера через API


Регистрация нового заказа

Добавление заказа: http://experience.tripster.ru/api/partners/{partner}/partnerorders/

Параметр ссылки: partner — ID партнера, выдается Трипстером

Метод: POST



ПараметрОписание
1order_idID заказа продукта партнера в его системе учета (string, обязательно)
2product_type

Тип продукта, продаваемого партнером (string, обязательно)

  1. avia — для авиабилетов (партнерские письма отправляются только по заказам со статусом 1)
  2. hotels — резервирование отелей (партнерские письма отправляются по заказам с любым статусом)
3 status

Статус заказа (integer, обязательно)

0 — новый неоплаченный заказ
1 — оплаченный заказ
2 — отмененный заказ

4cityГород прибытия (обязателен), geo-id города, предварительно полученного по названию или IATA-коду через API города
5city_originГород возвращения (geo-id, опционально)
6date_inДата прибытия, 2014-11-20 (string, обязательно)
7date_outДата отбытия, 2014-11-30 (string, опционально)
8nameИмя пассажира (Имя Фамилия: BORIS PLOTITSA или БОРИС ПЛОТИЦА) (string, обязательно)
9emailemail пассажира (string, обязательно)
10count_adultsЧисло взрослых пассажиров (integer, опционально)
11count_childrenЧисло детей (integer, опционально)


Ответ:

  1. HTTP 201 — ок. В теле ответа зарегистрированный заказ. Если клиент уже существует в нашей БД поле user будет отличаться от null.
  2. HTTP 400 или другой отличный от 2xx — ошибка. В теле ответа дополнительные данные об ошибке.

Примеры ответов

Пример положительного ответа
{
    "id": tripster-avia-12345,
    "order_id": "12345",
    "product_type": "avia",
    "status": 0,
    "city_id": 12345,
    "date_in": 2014-11-20,
    "date_out": 2014-11-30,
    "name": "БОРИС ПЛОТИЦА",
    "email": "boris@yandex.ru",
    "user": null,
    "count_adults": 1,
    "count_children": 0,
    "email_sent": false,
}



Пример ответа с ошибкой запроса
{
    "detail": "JSON parse error - No JSON object could be decoded"
}



Пример ответа с ошибками валидации
{
    "iata": [
        "City with IATA not found"
    ],
    "order_id": [
        "Required"
    ],
    "status": [
        "Unknown status"
    ],
    "non_field_errors": [
        "Unable to login with provided credentials."
    ]
}

Обновление данных о заказе

Обновление данных о заказе: http://experience.tripster.ru/api/partners/{partner_id}/partnerorders/{id}

Параметры ссылки:

  1. partner_id — ID партнера, выдается Трипстером индивидуально по запросу
  2. id — id заказа в базе Трипстера, сформированный по шаблону: {partner}-{product_type}-{order_id}

То есть для обновления данных, партнер формирует запрос из своего партнерского id, типа продукта (например, avia) и фактического id заказа в своей системе учета, перечислив их через знак "минус". Пример: tripster-avia-12345

Метод: PATCH

Параметры: те же, что и при регистрации нового, только те, что изменились.

Ответ: тот же, что и при регистрации, только код 200 (OK), а не 201 (Created).

Отправка писем

Мы можем отправлять письма как со своего адреса – (partner)@tripster.ru, так и с адреса партнера (xxx)@partner.ru. Для последнего требуется настройка DNS записей для домена партнера:

  1. Amazon SES генерирует письмо на адрес электронной почты партнера для разрешения отсылать почту с этого адреса, например orders@partner.ru
  2. Партнер добавляет/обновляет spf-запись в DNS домена, с которого будут отсылаться письма, в данном случае partner.ru, включая в него сервера Amazon SES: include:amazonses.com. (info) Справка по настройке spf-записи.
  3. Партнер добавляет три CNAME-записи для DKIM-верификации:
name: unique_id._domainkey.partner.ru
type: CNAME
value: unique_id.dkim.amazonses.com

Шаблон партнерской рассылки

Образец HTML шаблона: tripster-partner-newsletter-example.html