# Экспорт действий клиентов
## Общий контракт постановки задачи экспорта

Общий контракт постановки задачи экспорта описан [здесь](https://developers.mindbox.ru/docs/%D0%BE%D0%B1%D1%89%D0%B8%D0%B9-%D0%BF%D1%80%D0%B8%D0%BD%D1%86%D0%B8%D0%BF-%D1%8D%D0%BA%D1%81%D0%BF%D0%BE%D1%80%D1%82%D0%BE%D0%B2)

## Контракт экспорта действий клиентов

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

```json title="JSON"
POST https://api.mindbox.ru/v3/operations/sync?endpointId={endpointId}&operation={operation}
Accept: application/json
Content-Type: application/json
Authorization: SecretKey {Секретный ключ}

{
  "sinceDateTimeUtc": "<Дата и время самого раннего действия (UTC, YYYY-MM-DD hh:mm)>",
  "tillDateTimeUtc": "<Дата и время самого позднего действия невключительно (UTC, YYYY-MM-DD hh:mm)>",
  "segment": {
    "ids": {
      "externalId": "<Внешний идентификатор сегмента по действиям>"
    }
  }
}
```

Во входных параметрах можно указать:

* Дату "от" (sinceDateTimeUtc) в формате UTC. Тогда в выгрузку попадут только действия созданные в системе после этой даты
* Дату "до" (tillDateTimeUtc) в формате UTC. Тогда в выгрузку попадут только действия созданные в системе до этой даты
* externalID сегмента действий, если таковой не был выбран в настройках шага операции.

"Дата создания действия в системе" - это дата, когда Mindbox обработал это действие, фактически, действие могло быть совершено клиентом в другое время. Это важно учитывать, когда оперируете периодом в запросе выгружаемых данных.

Проверка попадания действия в запрошенный период происходит следующим образом:\
Дата "от" \<= дата создания действия в системе \< даты "до"

## Формат выгружаемого файла

## Описание базовых полей действий

```json title="JSON"
{
  "customerActions": [
    {
      "ids": {
        "mindboxId": "<Идентификатор Mindbox>",
        "<transactionId>": "<ID транзакции>"
      },
      "customFields": {
        "<Кастом поле действия>": "<Значение поля>",
        "<Множественное поле действия>": "<Значение поля>",
      },
      "actionTemplate": {
        "ids": {
          "systemName": "<Системное имя шаблона действия>"
        },
        "name": "<Имя шаблона действия>"
      },
      "dateTimeUtc": "<Дата совершения действия в UTC>",
      "creationDateTimeUtc": "<Дата создания действия в системе в UTC>",
      "brand": {
        "ids": {
          "systemName": "<Системное имя бренда>"
        }
      }, 
      "channel": {
        "ids": {
          "mindboxId": "<Идентификатор Mindbox>",
          "externalId": "<Внешний идентификатор точки контакта>",
          "systemName": "<Системное имя точки контакта>",
         },
        "utmCampaign": "<Значение метки utm_campaign>",
        "utmSource": "<Значение метки utm_source>",
        "utmMedium": "<Значение метки utm_medium>",
        "utmContent": "<Значение метки utm_content>",
        "utmTerm": "<Значение метки utm_term>"
      },
      "customer": {
        "ids": {
          "mindboxId": "<Идентификатор Mindbox>",
          "<Внешний идентификатор клиента>": "<Значение идентификатора>"
        }
      }
    }
  ]
}
```

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

## Рассылка

Для выгрузки взаимодействий с рассылками используйте [экспорт статусов](https://developers.mindbox.ru/docs/%D1%8D%D0%BA%D1%81%D0%BF%D0%BE%D1%80%D1%82-%D1%81%D1%82%D0%B0%D1%82%D1%83%D1%81%D0%BE%D0%B2-%D1%80%D0%B0%D1%81%D1%81%D1%8B%D0%BB%D0%BE%D0%BA#/).

```json title="JSON"
{
  "customerActions": [
    {       
      <Базовые поля>,
      "rootAction": {      
        "ids": {
          "mindboxId": <Идентификатор Mindbox>
        },
        "actionTemplate": {
          "ids": {
            "systemName": "<Системное имя шаблона действия>"
          },
          "name": "<Имя шаблона действия>"
        },
      },        
      "mailing": {
        "name": "<Название рассылки>",
        "ids": {
          "systemName": "<Системное имя рассылки>",
          "id": "<Идентификатор Mindbox>",
          "variantNum": "<Номер варианта рассылки>"
        },
        "action": "<Событие в рассылке>",
        "notSentReason": {
          "ids": {
            "systemName": "<Системное имя статуса, почему рассылка не отправилась>"
          },
          "name": "<Описание статуса, почему рассылка не отправилась>"
        },
        "notDeliveredReason": {
          "ids": {
            "systemName": "<Системное имя статуса, почему рассылка не доставилась>"
          },
          "name": "<Описание статуса, почему рассылка не доставилась>"
        },
        "link": "<Ссылка>",
        "viewEmailMessageUrl": "<Ссылка на просмотр отправленного сообщения>"
      }
    }
  ]
}
```

Действия по рассылке:

* Dispatch - Рассылка
* MailingSend - Рассылка отправлена
* MailingOpen - Рассылка открыта
* MailingNotSent - Рассылка не отправлялась
* MailingNotDelivered - Рассылка не доставлена
* MailingClick - Клик по ссылке в рассылке
* WaitingForDispatch - Участие в рассылке
* MailingUnsubscribe - Запрос отписки от рассылок

Статусы, почему рассылка не отправилась:

* ContactMissing - Отсутствует контакт
* InvalidContact - Невалидный контакт
* WaitingForConfirmationSubscriptionStatusRequried - Статус подписки потребителя должен быть "Требует подтверждения"
* CustomerUnsubscribed - Клиент отписан от рассылок
* CustomerInGlobalControlGroup - Клиент в глобальной контрольной группе
* CustomerInMailingControlGroup - Клиент в контрольной группе рассылки

Статусы, почему рассылка не доставилась:

* EmailBlackList - \[Email]: Отклонено, т.к. адрес в "черном" списке
* EmailConnectionFailureOnSending - \[Email]: Произошел обрыв соединения при отправке
* EmailInactiveAccount - \[Email]: Ящик неактивен или отключен
* EmailIncorrectAddressFormat - \[Email]: Неверный формат адреса
* EmailMailboxFull - \[Email]: Ящик переполнен
* EmailMxRecordWasntResolved - \[Email]: На указанном домене отсутствует почтовый сервер
* EmailNonExistingAddress - \[Email]: Несуществующий адрес
* EmailReceiverServerIsUnavailable - \[Email]: Сервер получателя недоступен
* EmailRejectedBecauseOfContent - \[Email]: Отклонено из-за содержимого
* EmailRejectedWithUnknownReason - \[Email]: Отклонено по неизвестной причине
* EmailServerProtocolOrTimeoutError - \[Email]: Ошибка протокола или превышение ожидания ответа сервера
* UnknownError - \[Email]: Неизвестная ошибка

## Связанная категория продуктов

```json title="JSON"
{
  "customerActions": [
    {
      <Базовые поля>,
      "productCategories": [
        {
          "ids": {
            "<Системное имя внешней системы>": "<Внешнее Id категории продукта>"
          }
        }
      ]
    }
  ]
}
```

## Связанный продукт

```json title="JSON"
{
  "customerActions": [
    {
      <Базовые поля>,
      "products": [
        {
          "ids": {
            "<Системное имя внешней системы>": "<Внешнее Id продукта>"
          }
        }
      ]
    }
  ]
}
```

## Связанные группы продуктов

```json title="JSON"
{
  "customerActions": [
    {
      <Базовые поля>,
      "productGroups": [
        {
          "ids": {
            "<Системное имя внешней системы>": "<Внешнее Id продукта>"
          }
        }
      ]
    }
  ]
}
```

## Связанное изменение баланса

```json title="JSON"
{
  "customerActions": [
    {
      <Базовые поля>,
      "customerBalanceChanges": [
        {
          "balanceType": {
            "ids": {
              "systemName": "<Системное имя балльного счёта>"
            },
            "name": "<Название балльного счёта>"
          },
          "changeAmount": "<Сумма изменения баланса>",
          "availableFromDateTimeUtc": "<Дата доступности баланса>",
          "expirationDateTimeUtc": "<Дата сгорания баллов>",
          "comment": "<Комментарий к изменению баланса>",
          "balanceChangeKind": "<Вид изменения баланса>"
        }
      ]

    }
  ]
}
```

Вид изменения баланса может принимать следующие значения

| Системное имя      | Тип изменения                                                                           | Поле отображения                  |
| :----------------- | :-------------------------------------------------------------------------------------- | :-------------------------------- |
| Expired            | Сгорание баллов                                                                         | Сгорание баллов                   |
| Custom             | Корректировка баллов триггером или ручная корректировка                                 | "Comment" или "Начисление баллов" |
| RetailOrderBonus   | Баллы за заказ, могут быть положительные и отрицательные, в случае возвратов            | Бонус за заказ                    |
| RetailOrderPayment | Баллы, потраченные за заказ. Могут быть отрицательные и положительные в случае возврата | Списание за заказ                 |

## Связанный заказ

```json title="JSON"
{
  "customerActions": [
    {
      <Базовые поля>,
      "order": {
        "firstAction": {
          "ids": {
            "mindboxId": "<Идентификатор первого действия заказа>",
          },
          "channel": {
            "ids": {
              "mindboxId": "<Идентификатор точки контакта",
              "externalId": "<Внешний идентификатор точки контакта>"
            },
            "name": "<Имя точки контакта>"
          },
        }
        "ids": {
          "mindboxId": "<Идентификатор Mindbox>",
          "orderMobileAppIdId": "<Идентификатор заказа Идентификатор в мобильном приложении>"
        },
        "totalPrice": "<Стоимость заказа с учетом скидок>",
        "lines": [
          {
            "product": {
              "ids": {
                "system1c": "<Id продукта в 1C>",
                "website": "<Id продукта в Сайт>"
              }
            }
            "quantity": "<Количество единиц продукта>",
            "basePricePerItem": "<Базовая цена товара за единицу товара>",
            "priceOfLine": "<Конечная цена за линию чека>",
            "status": {
              "ids": {
                "externalId": "<Идентификатор статуса покупки>"
              }
            },
            "appliedPromotions": [
              {
                "type": "<earnedBonusPoints>",
                "coupon": {
                  "ids": {
                    "code": "<Промокод>"
                  },
                  "pool": {
                    "ids": {
                      "mindboxId": "<Идентификатор Mindbox>",
                      "externalId": "<Внешний идентификатор пула промокодов>"
                    },
                    "name": "<Наименование пула промокодов>",
                    "description": "<Описание пула промокодов>"
                  }
                },
                "promotion": {
                  "ids": {
                    "mindboxId": "<Идентификатор Mindbox>",
                    "externalId": "<Внешний идентификатор промоакции>"
                  },
                  "name": "<Наименование промоакции>",
                  "type": "<Тип промоакции>"
                },
                "balanceType": {
                  "ids": {
                    "systemName": "<Системное имя балльного счёта>"
                  },
                  "name": "<Название балльного счёта>"
                },
                "amount": "<Размер скидки или бонуса примененной промоакции>",
                "expirationDateTimeUtc": "<Дата сгорания баллов>"
              },
              {
                "type": "<spentBonusPoints>",
                "coupon": {
                  "ids": {
                    "code": "<Промокод>"
                  },
                  "pool": {
                    "ids": {
                      "mindboxId": "<Идентификатор Mindbox>",
                      "externalId": "<Внешний идентификатор пула промокодов>"
                    },
                    "name": "<Наименование пула промокодов>",
                    "description": "<Описание пула промокодов>"
                  }
                },
                "promotion": {
                  "ids": {
                    "mindboxId": "<Идентификатор Mindbox>",
                    "externalId": "<Внешний идентификатор промоакции>"
                  },
                  "name": "<Наименование промоакции>",
                  "type": "<Тип промоакции>"
                },
                "balanceType": {
                  "ids": {
                    "systemName": "<Системное имя балльного счёта>"
                  },
                  "name": "<Название балльного счёта>"
                },
                "amount": "<Размер скидки или бонуса примененной промоакции>"
              },
              {
                "type": "<discount>",
                "coupon": {
                  "ids": {
                    "code": "<Промокод>"
                  },
                  "pool": {
                    "ids": {
                      "mindboxId": "<Идентификатор Mindbox>",
                      "externalId": "<Внешний идентификатор пула промокодов>"
                    },
                    "name": "<Наименование пула промокодов>",
                    "description": "<Описание пула промокодов>"
                  }
                },
                "promotion": {
                  "ids": {
                    "mindboxId": "<Идентификатор Mindbox>",
                    "externalId": "<Внешний идентификатор промоакции>"
                  },
                  "name": "<Наименование промоакции>",
                  "type": "<Тип промоакции>"
                },
                "amount": "<Размер скидки или бонуса примененной промоакции>"
              },
              {
                "type": "<deliveryDiscount>",
                "coupon": {
                  "ids": {
                    "code": "<Промокод>"
                  },
                  "pool": {
                    "ids": {
                      "mindboxId": "<Идентификатор Mindbox>",
                      "externalId": "<Внешний идентификатор пула промокодов>"
                    },
                    "name": "<Наименование пула промокодов>",
                    "description": "<Описание пула промокодов>"
                  }
                },
                "promotion": {
                  "ids": {
                    "mindboxId": "<Идентификатор Mindbox>",
                    "externalId": "<Внешний идентификатор промоакции>"
                  },
                  "name": "<Наименование промоакции>",
                  "type": "<Тип промоакции>"
                },
                "amount": "<Размер скидки или бонуса примененной промоакции>"
              },
              {
                "type": "<message>",
                "coupon": {
                  "ids": {
                    "code": "<Промокод>"
                  },
                  "pool": {
                    "ids": {
                      "mindboxId": "<Идентификатор Mindbox>",
                      "externalId": "<Внешний идентификатор пула промокодов>"
                    },
                    "name": "<Наименование пула промокодов>",
                    "description": "<Описание пула промокодов>"
                  }
                },
                "promotion": {
                  "ids": {
                    "mindboxId": "<Идентификатор Mindbox>",
                    "externalId": "<Внешний идентификатор промоакции>"
                  },
                  "name": "<Наименование промоакции>",
                  "type": "<Тип промоакции>"
                }
              },
              {
                "type": "<issuedCoupon>",
                "coupon": {
                  "ids": {
                    "code": "<Промокод>"
                  },
                  "pool": {
                    "ids": {
                      "mindboxId": "<Идентификатор Mindbox>",
                      "externalId": "<Внешний идентификатор пула промокодов>"
                    },
                    "name": "<Наименование пула промокодов>",
                    "description": "<Описание пула промокодов>"
                  }
                },
                "promotion": {
                  "ids": {
                    "mindboxId": "<Идентификатор Mindbox>",
                    "externalId": "<Внешний идентификатор промоакции>"
                  },
                  "name": "<Наименование промоакции>",
                  "type": "<Тип промоакции>"
                },
                "issuedCoupon": {
                  "ids": {
                    "code": "<Промокод>"
                  },
                  "pool": {
                    "ids": {
                      "mindboxId": "<Идентификатор Mindbox>",
                      "externalId": "<Внешний идентификатор пула промокодов>"
                    },
                    "name": "<Наименование пула промокодов>",
                    "description": "<Описание пула промокодов>"
                  }
                }
              },
              {
                "type": "<discount>",
                "promotion": {
                  "ids": {
                    "mindboxId": "<Идентификатор Mindbox>",
                    "externalId": "<Внешний идентификатор промоакции>"
                  },
                  "name": "<Наименование промоакции>",
                  "type": "<Тип промоакции>"
                },
                "amount": "<Размер скидки или бонуса примененной промоакции>"
              },
              {
                "type": "<discount>",
                "coupon": {
                  "ids": {
                    "code": "<Промокод>"
                  },
                  "pool": {
                    "ids": {
                      "mindboxId": "<Идентификатор Mindbox>",
                      "externalId": "<Внешний идентификатор пула промокодов>"
                    },
                    "name": "<Наименование пула промокодов>",
                    "description": "<Описание пула промокодов>"
                  }
                },
                "amount": "<Размер скидки или бонуса примененной промоакции>"
              }
            ],
            "giftCard": {
              "amount": "<Номинал>",
              "status": {
                "ids": {
                  "systemName": "<Системное имя статуса карты>"
                }
              }
            },
            "lineNumber": "<Номер позиции заказа>",
            "lineId": "<Идентификатор позиции заказа>"
          },
        ],
        "appliedPromotions": [
          {
            "type": "<earnedBonusPoints>",
            "coupon": {
              "ids": {
                "code": "<Промокод>"
              },
              "pool": {
                "ids": {
                  "mindboxId": "<Идентификатор Mindbox>",
                  "externalId": "<Внешний идентификатор пула промокодов>"
                },
                "name": "<Наименование пула промокодов>",
                "description": "<Описание пула промокодов>"
              }
            },
            "promotion": {
              "ids": {
                "mindboxId": "<Идентификатор Mindbox>",
                "externalId": "<Внешний идентификатор промоакции>"
              },
              "name": "<Наименование промоакции>",
              "type": "<Тип промоакции>"
            },
            "balanceType": {
              "ids": {
                "systemName": "<Системное имя балльного счёта>"
              },
              "name": "<Название балльного счёта>"
            },
            "amount": "<Размер скидки или бонуса примененной промоакции>",
            "expirationDateTimeUtc": "<Дата сгорания баллов>"
          },
          {
            "type": "<spentBonusPoints>",
            "coupon": {
              "ids": {
                "code": "<Промокод>"
              },
              "pool": {
                "ids": {
                  "mindboxId": "<Идентификатор Mindbox>",
                  "externalId": "<Внешний идентификатор пула промокодов>"
                },
                "name": "<Наименование пула промокодов>",
                "description": "<Описание пула промокодов>"
              }
            },
            "promotion": {
              "ids": {
                "mindboxId": "<Идентификатор Mindbox>",
                "externalId": "<Внешний идентификатор промоакции>"
              },
              "name": "<Наименование промоакции>",
              "type": "<Тип промоакции>"
            },
            "balanceType": {
              "ids": {
                "systemName": "<Системное имя балльного счёта>"
              },
              "name": "<Название балльного счёта>"
            },
            "amount": "<Размер скидки или бонуса примененной промоакции>"
          },
          {
            "type": "<discount>",
            "coupon": {
              "ids": {
                "code": "<Промокод>"
              },
              "pool": {
                "ids": {
                  "mindboxId": "<Идентификатор Mindbox>",
                  "externalId": "<Внешний идентификатор пула промокодов>"
                },
                "name": "<Наименование пула промокодов>",
                "description": "<Описание пула промокодов>"
              }
            },
            "promotion": {
              "ids": {
                "mindboxId": "<Идентификатор Mindbox>",
                "externalId": "<Внешний идентификатор промоакции>"
              },
              "name": "<Наименование промоакции>",
              "type": "<Тип промоакции>"
            },
            "amount": "<Размер скидки или бонуса примененной промоакции>"
          },
          {
            "type": "<deliveryDiscount>",
            "coupon": {
              "ids": {
                "code": "<Промокод>"
              },
              "pool": {
                "ids": {
                  "mindboxId": "<Идентификатор Mindbox>",
                  "externalId": "<Внешний идентификатор пула промокодов>"
                },
                "name": "<Наименование пула промокодов>",
                "description": "<Описание пула промокодов>"
              }
            },
            "promotion": {
              "ids": {
                "mindboxId": "<Идентификатор Mindbox>",
                "externalId": "<Внешний идентификатор промоакции>"
              },
              "name": "<Наименование промоакции>",
              "type": "<Тип промоакции>"
            },
            "amount": "<Размер скидки или бонуса примененной промоакции>"
          },
          {
            "type": "<message>",
            "coupon": {
              "ids": {
                "code": "<Промокод>"
              },
              "pool": {
                "ids": {
                  "mindboxId": "<Идентификатор Mindbox>",
                  "externalId": "<Внешний идентификатор пула промокодов>"
                },
                "name": "<Наименование пула промокодов>",
                "description": "<Описание пула промокодов>"
              }
            },
            "promotion": {
              "ids": {
                "mindboxId": "<Идентификатор Mindbox>",
                "externalId": "<Внешний идентификатор промоакции>"
              },
              "name": "<Наименование промоакции>",
              "type": "<Тип промоакции>"
            }
          },
          {
            "type": "<issuedCoupon>",
            "coupon": {
              "ids": {
                "code": "<Промокод>"
              },
              "pool": {
                "ids": {
                  "mindboxId": "<Идентификатор Mindbox>",
                  "externalId": "<Внешний идентификатор пула промокодов>"
                },
                "name": "<Наименование пула промокодов>",
                "description": "<Описание пула промокодов>"
              }
            },
            "promotion": {
              "ids": {
                "mindboxId": "<Идентификатор Mindbox>",
                "externalId": "<Внешний идентификатор промоакции>"
              },
              "name": "<Наименование промоакции>",
              "type": "<Тип промоакции>"
            },
            "issuedCoupon": {
              "ids": {
                "code": "<Промокод>"
              },
              "pool": {
                "ids": {
                  "mindboxId": "<Идентификатор Mindbox>",
                  "externalId": "<Внешний идентификатор пула промокодов>"
                },
                "name": "<Наименование пула промокодов>",
                "description": "<Описание пула промокодов>"
              }
            }
          },
          {
            "type": "<discount>",
            "promotion": {
              "ids": {
                "mindboxId": "<Идентификатор Mindbox>",
                "externalId": "<Внешний идентификатор промоакции>"
              },
              "name": "<Наименование промоакции>",
              "type": "<Тип промоакции>"
            },
            "amount": "<Размер скидки или бонуса примененной промоакции>"
          },
          {
            "type": "<discount>",
            "coupon": {
              "ids": {
                "code": "<Промокод>"
              },
              "pool": {
                "ids": {
                  "mindboxId": "<Идентификатор Mindbox>",
                  "externalId": "<Внешний идентификатор пула промокодов>"
                },
                "name": "<Наименование пула промокодов>",
                "description": "<Описание пула промокодов>"
              }
            },
            "amount": "<Размер скидки или бонуса примененной промоакции>"
          }
        ],
        "area": {
          "ids": {
            "externalId": "<Идентификатор географической зоны клиента>"
          }
        },
        "deliveryCost": "<Стоимость доставки>",
        "payments": [
          {
            "type": "<Тип платежа>",
            "id": "<Идентификатор платежа>",
            "amount": "<Размер платежа, примененного к заказу>",
            "creditCard": {
              "hash": "<Хеш банковской карты>"
            }
          }
        ],
        "customFields": {
          "defectTestField": "<defectTestField>",
          "socialcard": "<Соцкарта>"
        }
      }
    }
  ]
}
```