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
Параметр | Описание | |
---|---|---|
1 | order_id | ID заказа продукта партнера в его системе учета (string, обязательно) |
2 | product_type | Тип продукта, продаваемого партнером (string, обязательно)
|
3 | status | Статус заказа (integer, обязательно) 0 — новый неоплаченный заказ |
4 | city | Город прибытия (обязателен), geo-id города, предварительно полученного по названию или IATA-коду через API города |
5 | city_origin | Город возвращения (geo-id, опционально) |
6 | date_in | Дата прибытия, 2014-11-20 (string, обязательно) |
7 | date_out | Дата отбытия, 2014-11-30 (string, опционально) |
8 | name | Имя пассажира (Имя Фамилия: BORIS PLOTITSA или БОРИС ПЛОТИЦА) (string, обязательно) |
9 | email пассажира (string, обязательно) | |
10 | count_adults | Число взрослых пассажиров (integer, опционально) |
11 | count_children | Число детей (integer, опционально) |
Ответ:
- HTTP 201 — ок. В теле ответа зарегистрированный заказ. Если клиент уже существует в нашей БД поле user будет отличаться от null.
- 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}
Параметры ссылки:
- partner_id — ID партнера, выдается Трипстером индивидуально по запросу
- 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 записей для домена партнера:
- Amazon SES генерирует письмо на адрес электронной почты партнера для разрешения отсылать почту с этого адреса, например orders@partner.ru
- Партнер добавляет/обновляет spf-запись в DNS домена, с которого будут отсылаться письма, в данном случае partner.ru, включая в него сервера Amazon SES: include:amazonses.com.
Справка по настройке spf-записи.
- Партнер добавляет три CNAME-записи для DKIM-верификации:
name: unique_id._domainkey.partner.ru type: CNAME value: unique_id.dkim.amazonses.com
Шаблон партнерской рассылки
Образец HTML шаблона: tripster-partner-newsletter-example.html