# Получение статуса импорта

Статус импорта, поставленного запросом `POST https://api.mindbox.ru/v3/operations/bulk`, можно получить по его идентификатору. В ответе приходят статус импорта и количество обработанных строк, строк с ошибками и строк с предупреждениями.

Общая схема запросов:

1. Запрос импорта и получение идентификатора импорта `importId`.
2. Запрос статуса импорта по `importId`. Повторяйте запрос, пока импорт не завершится.

## Идентификатор импорта

Идентификатор импорта приходит в ответе на запрос импорта, например [массового импорта клиентов](https://developers.mindbox.ru/docs/customers-import-v3), в поле `data.importId`.

### Ответ об успешной постановке импорта

```json title="Ответ"
Content-Type: application/json

{
  "status": "Success",
  "data": {
    "workItemId": <Номер задачи импорта в административной панели>,
    "importId": "<Идентификатор импорта, который нужно передать в запросе статуса>"
  }
}
```

| Поле | Описание |
| :--- | :--- |
| workItemId | Необязательное поле, приходит не для всех типов импорта. Номер задачи импорта: по нему можно найти задачу в административной панели и посмотреть ее статус. |
| importId | Идентификатор импорта. Используйте его в [запросе статуса импорта](#запрос-статуса-импорта). |

### Ответ при повторном запросе

Если повторить запрос импорта с тем же ключом идемпотентности `transactionId`, новый импорт не ставится. В ответе приходит статус `TransactionAlreadyProcessed` и идентификатор первого импорта с этим `transactionId`.

```json title="Ответ"
Content-Type: application/json

{
  "status": "TransactionAlreadyProcessed",
  "data": {
    "importId": "<Идентификатор первого импорта с этим transactionId>"
  }
}
```

Поле `workItemId` в ответе на повторный запрос не приходит. Чтобы найти задачу импорта в административной панели, сохраните `workItemId` из ответа на первый запрос.

Для импортов, поставленных до появления метода, поле `data` в ответе на повторный запрос может не прийти.

## Запрос статуса импорта

```text title="Запрос статуса импорта"
GET https://api.mindbox.ru/v3/operations/bulk/status?endpointId={endpointId}&importId={importId}

Authorization: SecretKey {Секретный ключ}
Accept: application/json
```

**Параметры запроса**

* endpointId — идентификатор точки интеграции проекта. Подойдет любая точка интеграции проекта, не обязательно та, через которую поставлен импорт.
* importId — идентификатор импорта из ответа на запрос импорта, в формате GUID.

### Ответ о статусе импорта

```json title="Ответ"
Content-Type: application/json

{
  "status": "Success",
  "importStatus": "<Статус импорта>",
  "failureReason": null,
  "rowsProcessed": 1000,
  "rowsWithErrors": 12,
  "rowsWithWarnings": 3
}
```

| Поле | Описание |
| :--- | :--- |
| importStatus | Статус импорта. Значения описаны ниже. |
| failureReason | Причина, по которой импорт не выполнен. Заполняется только для статуса `Failed`, для остальных статусов — `null`. |
| rowsProcessed | Количество обработанных строк файла. |
| rowsWithErrors | Количество строк, которые не загрузились из-за ошибок. |
| rowsWithWarnings | Количество строк, которые загрузились с предупреждениями. |

Счетчики строк приходят всегда. Для части операций импорта счетчики заполняются только после завершения импорта, поэтому пока импорт выполняется, в них может приходить `0`.

**Статусы импорта**

| Статус | Описание |
| :--- | :--- |
| InProgress | Импорт выполняется. |
| Paused | Импорт приостановлен из административной панели. |
| Completed | Импорт завершен без ошибок. Строки с предупреждениями при этом могут быть. |
| CompletedWithValidationErrors | Импорт завершен, но часть строк не загрузилась из-за ошибок. |
| Failed | Импорт не выполнен. Причина — в поле `failureReason`. |

Статусы `Completed`, `CompletedWithValidationErrors` и `Failed` — итоговые: после них статус импорта не меняется. Подробности по строкам с ошибками и предупреждениями смотрите в отчете по импорту в административной панели.

### Ответ о статусе импорта (в случае отмены)

```json title="Ответ"
Content-Type: application/json

{
  "status": "Success",
  "importStatus": "Failed",
  "failureReason": "<Причина отмены>",
  "rowsProcessed": 4500,
  "rowsWithErrors": 12,
  "rowsWithWarnings": 3
}
```

Счетчики показывают строки, обработанные до остановки импорта. Для части операций импорта счетчики заполняются только после завершения, поэтому при отмене в них может прийти `0`, даже если часть строк уже обработана.

Импорт может быть не выполнен:

* если его отменили из административной панели;
* из-за внутренней ошибки;
* если файл импорта не удалось обработать.

Значение `failureReason` — текст для чтения человеком: формулировка зависит от операции импорта и языка проекта. Не используйте его для автоматической обработки, ориентируйтесь на `importStatus`.

## Ошибки

```json title="Ответ"
Content-Type: application/json

{
  "status": "ProtocolError",
  "errorMessage": "Import with ImportId='<importId>' not found.",
  "errorId": null,
  "httpStatusCode": 400
}
```

| HTTP-статус | errorMessage | Что проверить |
| :--- | :--- | :--- |
| 400 | `EndpointId is required.` | Передайте параметр `endpointId`. |
| 400 | `ImportId is required.` | Передайте параметр `importId`. |
| 400 | `Invalid ImportId='…' value. Should be non-empty GUID value.` | `importId` должен быть непустым GUID. |
| 400 | `Import with ImportId='…' not found.` | Импорт с таким `importId` не найден в проекте точки интеграции. Проверьте `importId` и что `endpointId` относится к тому же проекту, в котором поставлен импорт. |
| 401 | `Incorrect secret key for endpoint '…'.` или пустое тело | Проверьте секретный ключ и что `endpointId` относится к нужному проекту. |
| 500 | `Internal error during processing request` | Временная ошибка. Повторите запрос позже. |