API импорта сделок

Содержание:
   Запрос /deals
   Token авторизации
   Ответ
   Пример запроса

Запрос /deals

Общий вид запроса

POST https://widgets-api.mango-office.ru/v1/calltracking/<widgetId>/deals

где <widgetId> - идентификатор виджета.

Где узнать id-номер виджета, Вы можете узнать в этой статье.

Для авторизации запроса необходимо передать token

Тело запроса может быть в либо CSV (content type: text/csv, application/csv), либо формате JSON (content type: application/json).

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

Запрос в формате CSV ограничен 1 Мb.
Запрос в формате JSON ограничен 50 Kb.

Если формат JSON, то сделки передаются в массиве с набором следующих полей, см. таблицу Поля сделки

Если формат CSV, то сделки передаются по одной в каждой строке с разделителем ";". Также передается первая строка, в которой указывается набор передаваемых полей с учётом порядка.

Таблица "Поля сделки"

Название	Наличие	Тип данных	Описание

id	required	string	Уникальный идентификатор сделки
status	required	string	Статус сделки (список см. ниже)
timestamp	required	string (YYYY-MM-DDThh:mm:ss)	Дата последней модификации сделки или её статуса в формате ISO 8601
amount	optional	number	Сумма сделки в рублях
uid	optional	string	Идентификатор пользователя MANGO OFFICE
contactPhone	optional	string	Контакт (номер телефона) Клиента
gaCid	optional	string	Идентификатор пользователя Google Analytics (Client ID)
utmSource	optional	string	Источник (метка utm_source)
utmMedium	optional	string	Канал (метка utm_medium)
utmCampaign	optional	string	Кампания (метка utm_campaign)
utmContent	optional	string	Содержание (метка utm_content)
utmTerm	optional	string	Ключевое слово (метка utm_term)
regionCode	optional	string	ISO код региона, в котором пользователь зашёл на сайт (например MOW)
firstPath	optional	string	Путь, по которому пользователь зашёл на сайт (например /about)

Список статусов сделок:

new - новая;
accepted - в работе;
closed - успешно закрытая (сделка состоялась);
declined - отклоненная (сделка не состоялась).

Token авторизации

Для авторизации запроса /deals необходимо передать token, полученный в личном кабинете.

Узнать идентификатор Вашего виджета коллтрекинга и получить token для доступа к API Вы можете в личном кабинете MANGO OFFICE, руководствуясь статьей "Подключение API".

Передавать token в ДКТ нужно одним из следующих способов:

в параметрах:
access_token=<token>
в http заголовке:
Authorization: Bearer <token>

Ответ

Статусы ответов:

200 OK - сделки успешно загружены;
400 Bad Request - неверные параметры запроса, или ошибка в формате передаваемых данных, или слишком много данных в запросе;
401 Unauthorized - не передан token авторизации;
403 Forbidden - не хватает прав доступа у token'а;
429 Too Many Requests - ограничение по количеству запросов.

Ответ приходит в формате application/json.
В результате успешной обработки запроса, будет выдано следующее сообщение:

  {
       "status": "ok",
       "requestId": "<идентификатор запроса>"
  }

В случае ошибки ответ будет такой:

  {
      "status": "error",
      "requestId": "<идентификатор запроса>"
      "error": {
         "code": <код ошибки>
         "message": "<текстовое описание ошибки>"
     }   }

Поле requestId генерируется на сервере и присваивается запросу для последующего разбора инцидентов.

Список кодов ошибок:

Код ошибки	Описание

1001	Неизвестная/неклассифицированная ошибка
1101	Неизвестный source
1102	Недопустимый размер данных
1103	Неизвестный Content-Type
1131	CSV - ошибка парсинга
1132	CSV - похоже на неверный разделитель
1133	CSV - похоже на неверный разделитель
1151	JSON - ошибка парсинга
1152	JSON - как минимум одна строка недопустимого формата
1153	JSON - как минимум одна строка недопустимого формата
1002	В разработке
1003	Внутренний запрос закончился ошибкой

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

Здесь приведен пример запроса импорта сделок, переданный от сервиса интеграций Albato к ДКТ.

Запрос:

POST https://widgets-api.mango-office.ru/v1/calltracking/12345/deals/albato?access_token=dbf28bf3-6768-31...

Тело в формате application/json:

  [
       {
       "id": "22110885",
       "status": "new",
      "timestamp": "2019-09-04T16:10:43Z",
       "amount": 0,
       "uid": "37609b54f3eff487ef71",
       "contactPhone" : "79991234567",
       "gaCid": "578007821.1568880149",
       "utmSource": "google",
       "utmMedium": "cpc",
       "utmCampaign": "cars",
       "utmContent": "",
       "utmTerm": "купить машину",
       "regionCode": "MOW",
      "firstPath": "/new_cars"
   },
   {
       "id": "22113423",
        "status": "closed",
       "timestamp": "2019-09-04T17:12:01Z",
       "amount": 3540000,
       "uid": "23452f45234sd21234q3",
       "gaCid": "5780023421.15234280149",
       "utmSource": "yandex",
       "utmMedium": "display",
       "utmCampaign": "bmw",
       "utmContent": "",
       "utmTerm": "купить бмв",
       "regionCode": "SPB",
       "firstPath": "/"
       }
  ]

Тело в формате text/csv:

  id;status;timestamp;amount;uid;gaCid;utmSource;utmMedium;utmCampaign;utmContent;utmTerm;regionCode;firstPath
  22110885;new;2019-09-04T16:10:43Z;0;37609b54f3eff487ef71;578007821.1568880149;google;cpc;cars;;купить машину;MOW;/new_cars
  22113423;closed;2019-09-04T17:12:01Z;35329.52;23452f45234sd21234q3;5780023421.15234280149;yandex;display;bmw;;купить бмв;SPB;/

Ответ:

  {
       "status": "ok",
       "requestId": "2ar228bf3-6768-31a9-91ee-84ddc49wer8cb"
  }

Ответ с ошибкой:

  {
       "status": "error",
       "requestId": "2ar228bf3-6768-31a9-91ee-84ddc49wer8cb",
       "error": {
           "code": 1102,
           "message": "Недопустимый размер данных"
    }
  }