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

:::danger

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

:::

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

Создайте операцию с шагом «Подарочная карта — Заблокировать». Подробнее о создании операций — в статье [V3 API](https://developers.mindbox.ru/docs/v3).

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

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

## Запрос

```
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 | Да | Системное имя причины блокировки, см. раздел «Причины блокировки» |

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

<CodeTabs>

```json title="JSON"
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"
        }
      }
    }
  ]
}
```

```xml title="XML"
POST https://api.mindbox.ru/v3/operations/sync?endpointId=Website&operation=Website.BlockGiftCards

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

<operation>
  <giftCards>
    <giftCard>
      <ids>
        <number>2800105307138</number>
      </ids>
      <blockReason>
        <ids>
          <systemName>CardLost</systemName>
        </ids>
      </blockReason>
    </giftCard>
    <giftCard>
      <ids>
        <number>2800105307139</number>
      </ids>
      <blockReason>
        <ids>
          <systemName>MoneyRefunded</systemName>
        </ids>
      </blockReason>
    </giftCard>
  </giftCards>
</operation>
```

</CodeTabs>

`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` |

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

<CodeTabs>

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

```xml title="XML"
<result>
  <status>Success</status>
  <giftCards>
    <giftCard>
      <blockReason>
        <ids>
          <systemName>CardLost</systemName>
        </ids>
      </blockReason>
      <ids>
        <number>2800105307138</number>
      </ids>
      <pool>
        <systemName>pool1000</systemName>
      </pool>
      <status>
        <ids>
          <systemName>Blocked</systemName>
        </ids>
      </status>
      <processingStatus>Blocked</processingStatus>
    </giftCard>
    <giftCard>
      <ids>
        <number>2800105307139</number>
      </ids>
      <processingStatus>NotFound</processingStatus>
    </giftCard>
  </giftCards>
</result>
```

</CodeTabs>

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

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

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

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

Если запрос некорректен, он отклоняется целиком: ни одна карта не блокируется. Ответ приходит со статусом `ValidationError` и списком `validationMessages`, поле `giftCards` не передается. Общая схема ответа с ошибкой — в статье [Обработка ошибок](https://developers.mindbox.ru/docs/error_processing).

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

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

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

## Ограничения

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

## См. также

* [Работа с подарочными картами в операциях сохранения заказов](https://developers.mindbox.ru/docs/gift-cards-in-order-save-operations)
* [Массовый импорт пула подарочных карт](https://developers.mindbox.ru/docs/bulk-import-gift-card-pool-v3)
* [Что такое «Подарочные карты»](https://help.mindbox.ru/docs/gift-cards-what-is)