Схема интеграции по Электронным Подарочным Сертификатам (ЭПС)

Шаги для запуска продаж ЭПС через платформу Giftery

План запуска продажи ЭПС через платформу Giftery:

• заполнить анкету поставщика, отправить менеджеру Giftery, согласовать шаблон ЭПС (дизайн, формат кода/штрих-кода);
• определится со схемой передачи и активации ЭПС, настроить интеграцию (см. ниже);
• пройти финальное тестирование с выпуском, активацией и погашением на кассе/интернет-магазине.

Коды ЭПС

Под кодом ЭПС подразумевается номер и/или секретный код (PIN), которые будут указаны на ЭПС конечного получателя. Номер/PIN могут быть указаны в виде штрих-кода для удобства приёма на кассе торговой точки. Помимо этого, в ЭПС будут указаны:

• номинал ЭПС в рублях;
• дата истечения срока действия ЭПС (если срок действия ограничен);
• условия использования ЭПС;
• номер заказа и контактная информация для обращения в клиентскую службу поддержки Giftery.

Передача и активация кодов ЭПС

Существуют 3 стандартных схемы передачи кодов ЭПС: автоматический, ручная передача пула номеров (неактивные или активные), коды Giftery (без передачи). Также потребуется определиться со схемой активации, если при передаче кодов они неактивны.

Автоматическая передача/активация кодов ЭПС через API поставщика

Поставщик предоставляет со своей стороны API, который по запросу со стороны Giftery будет передавать код ЭПС, PIN (опционально) и срок действия (опционально). Платформа Giftery автоматически выполняет запрос к API поставщика чтобы получить от него код ЭПС в момент продажи ЭПС конечному пользователю.

Список передаваемых и возвращаемых параметров зависит от особенностей реализации API поставщика. Рекомендуемые интерфейсы: SOAP/REST/RPC.

Желательно, чтобы среди параметров передавался уникальный ID запроса, например request_id — он применяется для защиты от сетевых ошибок, runtime-ошибок и т.п. Это позволяет безболезненно повторить запрос в случае возникновения ошибки и получить данные по ЭПС без проблемы с возможным дублированием запроса.

Пример запроса:

POST /api/issueCertificate HTTP/1.1
Host: supplier.ru
Content-Type: application/json
Connection: Close

{
  "request_id": "Hdt1njMDOwbdgSDhgSDhsdmwei",
  "denomination": 1000
}

Пример ответа:

HTTP/1.1 201 Created
Content-Type: application/json
Connection: Close

{
  "request_id": "Hdt1njMDOwbdgSDhgSDhsdmwei",
  "denomination": 1000,
  "code": 1234567890,
  "pin": 123,
  "expire_at": "2018-12-31 23:59:59"
}

Плюсы: Полностью автоматическая схема, отсутствует "человеческий фактор".

Минусы: Единовременные затраты IT-ресурсов на доработку и тестирование интеграции.

Ручная передача пула кодов ЭПС

• Ответственный сотрудник со стороны поставщика формирует файл в согласованном формате (обычно это документ Excel) и отправляет его на адрес code@giftery.ru.
• Ответственный сотрудник со стороны Giftery проводит загрузку кодов в хранилище кодов Giftery. Коды могут быть активные или неактивные (потребуется определиться со схемой активации).

Плюсы: Способ не требует технических доработок. Как правило используется для "быстрого старта" продаж, даёт отсрочку необходимости настройки "Автоматической схемы" (см. выше).

Минусы: Требуется ответственный сотрудник со стороны поставщика. Возникает "человеческий фактор".

Активация кодов по email-заявке

• Платформа Giftery периодически (например: ежедневно, в будни, в 12-00) высылает заявку на активацию кодов, проданных за прошедший период на email ответственного сотрудника со стороны поставщика. Формат заявки заранее согласовывается с поставщиком, как правило — это таблица, включающая в себя: номер сертификата, номинал, срок действия, номер заказа в Giftery.
• Ответственный сотрудник со стороны поставщика активирует коды и сообщает об этом в ответном письме.

Потребуется email-адрес, на который ежедневно (расписание можно менять индивидуально) будет приходить список реализованных кодов поставщика за предыдущий день.

Плюсы: Способ не требует технических доработок. Как правило используется для "быстрого старта" продаж, даёт отсрочку необходимости настройки интеграции "Автоматическая схема" (см. выше).

Минусы: Требуется ответственный сотрудник со стороны поставщика. Возникает "человеческий фактор".

Активация кодов через API поставщика

Поставщик предоставляет со своей стороны API, который по запросу со стороны Giftery будет активировать коды ЭПС. Данная схема предполагает предварительную ручную загрузку пула кодов и хранение в БД Giftery. В момент продажи ЭПС конечному пользователю API Giftery будет обращаться к API поставщика и получать от него подтверждение активации кода. Список передаваемых и возвращаемых API поставщика параметров зависит от особенностей реализации API поставщика. Рекомендуемые интерфейсы: SOAP/REST/RPC.

Желательно, чтобы среди параметров передавался уникальный ID запроса, например request_id — он применяется для защиты от сетевых ошибок, runtime-ошибок и т.п. Это позволяет безболезненно повторить ошибочный запрос и получить данные по ЭПС без проблемы с возможным дублированием запроса.

Пример запроса:

PUT /api/activateCertificate HTTP/1.1
Host: supplier.ru
Content-Type: application/json
Connection: close

{
  "request_id": "Hdt1njMDOwbdgSDhgSDhsdmwei",
  "code": 1234567890
}

Пример ответа:

HTTP/1.1 200 OK
Connection: close

Плюсы: Автоматическая схема активации, отсутствует "человеческий фактор".

Минусы: Единовременные затраты IT-ресурсов на доработки и тестирование интеграции.

Активация кодов через периодическую выгрузку (pull-схема)

В этой схеме поставщик самостоятельно периодически запрашивает список ЭПС, реализованных Giftery за определённый интервал времени. Со стороны Giftery возможна настройка удобного поставщику формат ответа (JSON, XML, CSV) и набора полей ЭПС.

Пример запроса (запрос раз в час, данные за прошедший час):

GET /integration/v1/used?from=2018-12-31%2012:00:00&to=2018-12-31%2012:59:59 HTTP/1.1
Host: integration.giftery.ru
Connection: close

Пример ответа:

HTTP/1.1 200 OK
Content-Type: application/json
Connection: close

[
  {
    "code": 1234567890
  },
  {
    "code": 1234567891
  },
  ...
]

Плюсы: Полностью автоматическая схема, отсутствует "человеческий фактор". Нет необходимости предоставлять и поддерживать внешний API.

Минусы: Единовременные затраты IT-ресурсов на доработки и тестирование интеграции.

Коды Giftery

Уникальные коды ЭПС генерируются автоматически в момент продажи ЭПС конечному пользователю. Для приёма ЭПС в торговой точке используется ЛК поставщика Giftery. Кабинет позволяет проверить статус ЭПС номеру, а также "погасить" ЭПС в момент приёма к оплате в торговой точке. При погашении возвращается уникальный номер транзакции, гарантирующий, что сертификат принят к оплате 1 раз (повторная попытка погашения приведет к ошибке "ЭПС уже погашен."). Как правило, этот вариант подходит небольшим интернет-магазинам у которых нет своих ЭПС.

Плюсы: Способ не требует технических доработок со стороны поставщика. Подходит для поставщиков, которые не имеют существующей у себя схемы приёма ЭПС. Снимают необходимость передачи/активации кодов.

Минусы: Необходимость ручного приёма ЭПС через ЛК и, как следствие, необходимость обучения кассиров.