Метод redeemCertificate

Описание

Метод предназначен для погашения сертификата. После погашения сертификатом нельзя воспользоваться повторно. Вызывается после метода checkCertificate.

Частичное погашение

Поставщику может быть доступно частиное погашение сертификата. В таком случае баланс сертификата может быть погашен за несколько раз. Определить возмость выполнения частичного погашения можно по параметру allow_partial_redeem в методе checkCertificate. Количество оставишхся погашений доступно в параметре available_number_of_uses. Частичное погашение выполняется через передачу параметра amount и указания на какую сумм баланса нужно провести частичное погашение. Следует учитывать, что если оставшийся баланс после выполенения последнего доступного частиного погашения использован не будет.

Филиальная система поставщика

В случае, когда у поставщика имеется филиальная сеть и погашение сертификата должно засчитываться как погашение филиалом, при выполнении операции redeemCertificate нужно вызывать метод с использованием ID и secret нужного филиала. В таком случае в истории погашений будет запись о погашении филиалом. Если же использовать реквизиты родительской компании, то погашение будет записано от неё. С нашей стороны оба варианта считаются допустимыми и мы никак это не проверяем была ли это родительская/дочерняя компания, на стороне поставщика стоит тщательно выбирать кто именно выполняет погашение.

Параметры запроса (data)

Параметр	Тип	Описание
code	string	Обязательное. Код сертификата.
pin	string	Секретный пин-код сертификата
amount	int	В случае частичного погашения необходимо передать какую часть баланса сертификата списываем. Если не передать данный параметр, будет выполнено обычное полное погашение. Если не передать данный параметр после успешных частичных погашений, будет выполнено полное погашение на оставщуюся сумму баланса сертификата. Баланс сертификата доступен в методе checkCertificate, параметр balance.

Параметры ответа (data)

Параметр	Тип	Описание
ok	integer
msg	string	Сообщение о проведённой операции
transaction_id	string	Deprecated. Идентификатор проведённой операции погашения сертификата. Данный параметр оставлен для обратной совместимости, вы не должны его использовать. Вместо него следует использовать идентификаторы из transactions_ids. Идентификатор transaction_id не будет встречаться в списке transaction_ids.
transaction_ids	List<int>	Идентификаторы проведённых операций погашений сертификата. Несмотря на то, метод возвращает список идентификаторов транзакций, в случае погашения сертификата поставщика этот список всегда будет содержать не более одного элемента.

Пример

# Получаем значение для подстановки SIG
# SECRET в данном случае - это хранящийся у клиента ключ для подписи запросов к API
$ echo -n 'redeemCertificate{"code":"00342-999-999-999","pin":"9999"}SECRET' | sha256sum - | awk '{print $1}'

# Используем известный клиенту ID и сгенерированный SIG для выполнения запроса
$ curl 'https://ssl-api.giftery.ru/?cmd=redeemCertificate&id=ID&in=json&out=json&data=%7B%22code%22%3A%2200342-999-999-999%22%2C%22pin%22%3A%229999%22%7D&sig=SIG'

Результат успешного запроса

{
  "status": "ok",
  "data": {
    "ok": 1,
    "msg": "Сертификат погашен",
    "transaction_id": "9999",
    "transaction_ids": [
      999
    ]
  }
}

Результат в случае ошибки

{
    "status": "error",
    "error": {
        "code": 1402,
        "text": "Сертификат не найден"
    }
}

Код ошибки	Описание
1402	Не удалось найти сертификат по предоставленному коду. Нужно проверить правильность передачи кода. Проверка пин-кода происходит только если сертификат был найден.
1403	Сертификат был заблокирован. Причину блокировки можно уточнить и персонального менеджера.
3304	Ошибка возникает при попытках повторного погашения сертификата