Карты

Блокировка подарочных карт

Метод блокирует до 10 подарочных карт за один запрос с указанием причины из справочника. Заблокированной картой нельзя оплатить заказ, а причина и дата блокировки видны в карточке подарочной карты в Mindbox.

Блокировка необратима. Заблокированную карту нельзя разблокировать ни по API, ни в интерфейсе Mindbox.

Настройка операции

Создайте операцию с шагом «Подарочная карта — Заблокировать». Подробнее о создании операций — в статье V3 API.

Требования к операции:

шаг блокировки — единственный шаг операции;
у операции включена настройка «Требуется передача секретного сервисного ключа»: метод вызывается только с секретным ключом точки интеграции.

Запрос

Code
POST https://api.mindbox.ru/v3/operations/sync?endpointId={Идентификатор точки интеграции}&operation={Название операции}

Параметр	Тип	Обязательный	Описание
`endpointId`	string	Да	Идентификатор точки интеграции
`operation`	string	Да	Системное имя операции с шагом «Подарочная карта — Заблокировать»

Тело запроса

Поле	Тип	Обязательное	Описание
`giftCards`	array	Да	Список подарочных карт, от 1 до 10
`giftCards[].ids.number`	string	Да	Номер подарочной карты. Номера в одном запросе не должны повторяться
`giftCards[].blockReason.ids.systemName`	string	Да	Системное имя причины блокировки, см. раздел «Причины блокировки»

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

POST https://api.mindbox.ru/v3/operations/sync?endpointId=Website&operation=Website.BlockGiftCards

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Mindbox secretKey="{Секретный ключ}"

{
  "giftCards": [
    {
      "ids": {
        "number": "2800105307138"
      },
      "blockReason": {
        "ids": {
          "systemName": "CardLost"
        }
      }
    },
    {
      "ids": {
        "number": "2800105307139"
      },
      "blockReason": {
        "ids": {
          "systemName": "MoneyRefunded"
        }
      }
    }
  ]
}

Website.BlockGiftCards в примере — условное имя: подставьте системное имя своей операции.

Причины блокировки

Справочник закрытый: другие значения метод не принимает. Регистр букв не важен.

Системное имя	Название в карточке подарочной карты
`MoneyRefunded`	Возврат средств покупателю
`PartialRefund`	Возврат остатка по карте
`CardLost`	Клиент заявил об утере
`CvvBruteForce`	Подбор CVV
`FraudSuspected`	Подозрение на злоупотребление
`SoldByMistake`	Ошибка при продаже
`IssuedByMistake`	Ошибка при выпуске
`ExpiredByRules`	Истек срок по правилам клиента
`Other`	Другое

В карточке подарочной карты блокировка по API отображается в поле «Статус» в виде Заблокирована по API: {название причины}, а ниже указана дата блокировки.

Ответ

Каждая карта из запроса обрабатывается отдельно. Если запрос корректен, верхний статус ответа — Success, даже если часть карт не заблокирована. Результат по каждой карте — в поле processingStatus.

Поле	Описание
`status`	Статус обработки запроса: `Success` или `ValidationError`
`giftCards[].processingStatus`	Результат по карте, см. раздел «Статусы обработки карты»
`giftCards[].ids.number`	Номер карты из запроса
`giftCards[].blockReason.ids.systemName`	Причина блокировки карты. Для `AlreadyBlocked` — причина существующей блокировки, а не причина из запроса. Не передается для `NotFound` и `Redeemed`, а также для карт, заблокированных не по API
`giftCards[].pool.systemName`	Системное имя пула карты. Не передается для `NotFound`
`giftCards[].status.ids.systemName`	Статус карты после обработки запроса: `Inactive`, `CanBeUsed`, `AlreadyUsed`, `Blocked` или `Expired`. Не передается для `NotFound`

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

{
  "status": "Success",
  "giftCards": [
    {
      "processingStatus": "Blocked",
      "ids": {
        "number": "2800105307138"
      },
      "blockReason": {
        "ids": {
          "systemName": "CardLost"
        }
      },
      "pool": {
        "systemName": "pool1000"
      },
      "status": {
        "ids": {
          "systemName": "Blocked"
        }
      }
    },
    {
      "processingStatus": "NotFound",
      "ids": {
        "number": "2800105307139"
      }
    }
  ]
}

Статусы обработки карты

`processingStatus`	Когда возвращается
`Blocked`	Карта заблокирована этим запросом. Блокируются неактивные, активные, в том числе частично потраченные, и истекшие карты
`AlreadyBlocked`	Карта уже была заблокирована раньше. Причина и дата существующей блокировки не меняются
`NotFound`	Карта с таким номером не найдена
`Redeemed`	Карта полностью использована, блокировать ее нечем

Повторный запрос с теми же картами безопасен: заблокированные карты вернутся со статусом AlreadyBlocked, причина и дата первой блокировки сохранятся.

Ошибки запроса

Если запрос некорректен, он отклоняется целиком: ни одна карта не блокируется. Ответ приходит со статусом ValidationError и списком validationMessages, поле giftCards не передается. Общая схема ответа с ошибкой — в статье Обработка ошибок.

Пример ответа с ошибкой
{
  "status": "ValidationError",
  "validationMessages": [
    {
      "message": "За один запрос можно заблокировать не более 10 подарочных карт",
      "location": "giftCards"
    }
  ]
}

Причина	Текст ошибки
В запросе больше 10 карт	`За один запрос можно заблокировать не более 10 подарочных карт`
Номер карты повторяется	`Номера подарочных карт в запросе не должны повторяться. Повторяются: {номера}`
Не передана причина блокировки	`Нужно передать причину блокировки. Допустимые значения: {системные имена}`
Причина не из справочника, например `Lost`, число или несколько причин через запятую	`"Lost" не является корректным значением. Пример корректных значений: {системные имена}.`
Список `giftCards` пустой	`Элемент "/giftCards" не содержит ни одного элемента "/giftCard".`

Текст ошибок возвращается на языке проекта.

Ограничения

В одном запросе — до 10 карт.
Заблокированную карту нельзя разблокировать.
Если запрос завершился ошибкой сервера, ни одна карта из него не заблокирована. Повторите запрос целиком.

См. также

Last modified on November 3, 2026

Работа с подарочными картами в операциях сохранения заказов Массовый импорт точек контакта