Devino AddressBook Api¶

Предупреждение

Внимание! Для использования данного вида интеграции необходимо обратиться к своему менеджеру, либо в техническую поддержку support@devinotele.com для настройки доступа.

Описание¶

Сервис представляет собой удобный интерфейс для управления списками контактов адресной книги и получения списка отписавшихся от рассылок.

Список методов¶

Набор методов для работы с группами контактов - ContactGroups.

Ресурс	Метод	Описание
/ContactGroups	GET	Получение списка всех групп
/ContactGroups/{ContactGroupId}	GET	Получение группы с подробной информацией
/ContactGroups	POST	Добавление группы
/ContactGroups/{ContactGroupId}	PUT	Редактирование группы
/ContactGroups/{ContactGroupId}	DELETE	Удаление группы

Набор методов для импорта контактов - ContactsImport.

Ресурс	Метод	Описание
/ContactsImport	POST	Импорт контактов
/ContactsImport/{ImportId}/Progress	GET	Запрос прогресса добавления контактов в базу
/ContactsImport/{ImportId}/Duplicates	DELETE	Удаление дубликатов из завершённого импорта

Набор методов для работы с контактами - Contacts.

Ресурс	Метод	Описание
/Contacts?Query={Key}	GET	Получение диапазона контактов по телефону или почте
/Contacts/{ContactId}	GET	Получение контакта с подробной информацией
/Contacts	POST	Создание контакта
/Contacts/{ContactId}	PATCH	Редактирование контакта
/Contacts/{ContactId}	DELETE	Удаление контакта

Набор методов для работы с отписавшимися - Unsubscribed.

Ресурс	Метод	Описание
/Unsubscribed?TaskId={TaskId}	GET	Получение диапазона отписавшихся по рассылке
/Unsubscribed	GET	Получение диапазона отписавшихся

Запрос к API состоит из следующих элементов:

Основного URL запроса: https://integrationapi.net/addressbook/v2
Ресурса, например: /Contacts
Параметров запроса в кодировке UTF-8.

Сервис позволяет передавать параметры в следующих форматах: XML, JSON, JSV, CSV.

Авторизация¶

Для доступа к сервису необходимо пройти авторизацию. Сервис поддерживает базовую авторизацию через заголовок Authorization (https://en.wikipedia.org/wiki/Basic_access_authentication):

Authorization: Basic dGVzdGVyOjExMTExMQ==

В заголовке необходимо передать логин и пароль из ЛК (https://my.devinotele.com) в формате login:password в base64 кодировке.

Ответ API состоит из 2х частей:

Код с описанием - эта часть присутствует во всех ответах.
Result, специфичный для каждого запроса. Может отсутствовать.

{
    "Result":{
        ...
    },
    "Code": "validation_error",
    "Description": "user not found"
}

Набор кодов ограничен, а набор описаний зависит от конкретного метода. Код можно использовать для проверки статуса запроса, а описание предназначено для диагностики возможных проблем. Описание может быть изменено в новой версии API без предупреждения о нарушении обратной совместимости. Набор кодов также может быть расширен.

Локализация¶

В поле Description может возвращаться локализованная строка с текстом ошибки. Для этого необходимо передать заголовок Accept-Language с нужным языком. В текущей версии поддерживаются русский и английский языки.

По умолчанию, если заголовок не передан или язык не найден среди доступных возвращаются ответы на английском.

Accept-Language: ru-RU

Запрос диапазонов¶

Некоторые запросы предполагают возвращение только части данных. Для таких запросов необходимо передавать специальный заголовок:

Range: items=1-100

Оба предела диапазона включаются. Запросы, для которых нужен данный заголовок:

/Unsubscribed
/Contacts?Query={Key}

При отсутствии заголовка данные запросы возвращают ошибку validation_error с http кодом 416 RequestedRangeNotSatisfiable.

Список кодов ответов¶

Код	Http StatusCode	Расшифровка
validation_error	400 - 404, 416	Ошибки валидации, авторизации и доступа
ok	200, 201, 206	Запрос выполнен успешно
internal_error	500	Внутренняя ошибка сервиса, можно повторить запрос позже

Работа с группами контактов¶

ContactGroups GET (all)¶

https://integrationapi.net/addressbook/v2/ContactGroups

Метод возвращает список всех групп контактов пользователя. Возвращаемый результат - список объектов типа ContactGroupDto.

Возвращаемый результат - список записей ContactGroupDto

Параметр	Тип данных	Описание
ContactGroupId	int	Идентификатор группы
Name	string	Имя группы
Description	string	Описание группы
CreatedDate	DateTime	Дата создания
ContactsCount	int	Количество контактов в группе

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

{
    "Result":[
        {
            "ContactGroupId": 252,
            "Name": "snuk",
            "Description": "",
            "CreatedDate": "/Date(1426504354337-0000)/",
            "ContactsCount": 3
        },
        {
            "ContactGroupId": 331,
            "Name": "zzzzzzz04.02.2016 16:49:35",
            "Description": "AB api intgration test",
            "CreatedDate": "/Date(1454582978323-0000)/",
            "ContactsCount": 0
        }
    ],
    "Code": "ok",
    "Description": "ok"
}

ContactGroups GET¶

https://integrationapi.net/addressbook/v2/ContactGroups/{ContactGroupId}

Метод возвращает группу по идентификатору. В качестве Result возвращается объект ContactGroupDto, описание см. выше.

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

Параметр	Тип данных	Описание	Обязательнй
ContactGroupId	int	Идентификатор группы (предаётся в url)	Да

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

{
    "Result":{
        "ContactGroupId": 332,
        "Name": "new group",
        "Description": "best new group",
        "CreatedDate": "/Date(1454587881407-0000)/",
        "ContactsCount": 0
    },
    "Code": "ok",
    "Description": "ok"
}

ContactGroups POST¶

https://integrationapi.net/addressbook/v2/ContactGroups

Метод добавляет новую группу контактов. Если группа была успешно добавлена, возвращается код «ok» и http код 201. Метод возвращает идентификатор группы ContactGroupId в качестве Result.

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

Параметр	Тип данных	Описание	Обязательнй
Name	string	Имя группы	Да
Description	string	Описание группы	Нет

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

{
    "Name":"new group",
    "Description":"best group"
}

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

{
"Result": 332,
"Code": "ok",
"Description": "ok"
}

ContactGroups PUT¶

https://integrationapi.net/addressbook/v2/ContactGroups/{ContactGroupId}

Метод обновляет имя и описание группы, затирая старые значения, возвращается только стандартный ответ, без поля Result.

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

Параметр	Тип данных	Описание	Обязательнй
ContactGroupId	int	Идентификатор группы (передаётся в url)	Да
Name	string	Имя группы	Да
Description	string	Описание группы	Нет

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

{"Name":"new group","Description":"best new group"}

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

{
    "Code": "ok",
    "Description": "ok"
}

ContactGroups DELETE¶

https://integrationapi.net/addressbook/v2/ContactGroups/{ContactGroupId}

Метод удаляет группу, возвращается только стандартный ответ, без поля Result.

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

Параметр	Тип данных	Описание	Обязательнй
ContactGroupId	int	Идентификатор группы (передаётся в url)	Да

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

{
    "Code": "ok",
    "Description": "ok"
}

Работа с контактами¶

ContactsImport POST¶

https://integrationapi.net/addressbook/v2/ContactsImport/

Метод валидирует пачку контактов и добавляет во внутреннюю очередь для добавления в базу. Если контакты были успешно добавлены в очередь, возвращается код «ok» и http код 201. Метод возвращает счётчики провалидированных контактов в качестве Result.

Валидируются:

наличие группы, в которую импортируются контакты
максимальное количество контактов - не более 10 000

Контакты валидируются на:

наличие хотя бы одного поля - номер телефона или email адрес
валидность номера телефона, если он передан (непустая строка, состоящая из цифр, длиной от 8 до 15 символов, в начале может быть «+»)
валидность email адреса, если он передан
длина полей FirstName, MiddleName и LastName не должна превышать 100 символов, для ExtraField1 и ExtraField2 - ограничение 700 символов
пол, если передано значение отличное от 1 и 2, будет проставлено 3

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

Параметр	Тип данных	Описание	Обязательнй
ContactGroupId	int	Идентификатор группы, в которую импортируются контакты	Да
ImportId	GUID	Идентификатор импорта	Нет
ConvertDirectPhones	bool	Преобразовывать ли прямые номера в федеральные	Нет
FillGender	bool	Заполнять ли автоматически пол контакта на основе его ФИО	Нет
Contacts	ContactDto[]	Список импортируемых контактов	Да

ContactDto

Параметр	Тип данных	Описание	Обязательнй
PhoneNumber	string	Номер телефона	см. описание
Email	string	Email адрес	см. описание
FirstName	string	Имя	Нет
MiddleName	string	Отчество	Нет
LastName	string	Фамилия	Нет
Gender	int	Пол (1 - м, 2 - ж, 3 - неизвестно)	Нет
DateOfBirth	DateTime	Дата рождения	Нет
ExtraField1	string	Дополнительное поле №1	Нет
ExtraField2	string	Дополнительное поле №2	Нет
MergeFields	Dictionary	Пользовательский словарь «ключ-значение»	Нет

Возвращаемый результат

Параметр	Тип данных	Описание
ImportId	GUID	Идентификатор импорта - генерируется автоматически, если не был передан
ValidContacts	int	Количество валидных контактов
RejectedContacts	RejectedContactDto[]	Список невалидных контактов
InvalidPhoneNumbers	string[]	Список невалидных номеров телефонов
InvalidEmails	string[]	Список невалидных email адресов

RejectedContactDto

Параметр	Тип данных	Описание
Contact	ContactDto	Контакт
ErrorCode	ContactValidationCode	Тип ошибки валидации
ErrorDescription	string	Описание ошибки валидации
DuplicatesCount	int	Количество дублирований в начальном запросе

ContactValidationCode

Текст	Число	Описание
Ok	0	Значение по умолчанию
Duplicate	1	Дубликат
NoPhoneNoEmail	2	Не передан телефон или email адрес
InvalidPhone	3	Невалидный номер телефона
InvalidEmail	4	Невалидный email адрес
InvalidField	5	Невалидное поле - ФИО или ExtraField1, ExtraField2

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

{
    "ContactGroupId" : 9731,
    "ImportId" : "50210B41-1C4E-4E48-9837-FB382A9BAE01",
    "ConvertDirectPhones" : true,
    "FillGender" : false,
    "Contacts" :[
        {
            "PhoneNumber": "",
            "LastName": "Ivanov",
            "FirstName": "Ivan",
            "Email": "ivanov@ivanov.com",
            "DateOfBirth": "/Date(1454533200000-0000)/"
        },
        {
            "PhoneNumber": "+79001234567",
        }
    ]
}

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

{
    "Result":{
        "ImportId" : "50210B41-1C4E-4E48-9837-FB382A9BAE01",
        "ValidContacts": 2,
        "RejectedContacts":[],
        "InvalidPhoneNumbers":[],
        "InvalidEmails":[]
    },
    "Code": "ok",
    "Description": "ok"
}

ContactsImport Progress GET¶

https://integrationapi.net/addressbook/v2/ContactsImport/{ImportId}/Progress

Метод возвращает прогресс добавления контактов в базу по идентификатору импорта, который передаётся в url.

Возвращаемый результат

Параметр	Тип данных	Описание
Uploaded	int	Общее количество загруженных контактов через ContactsImport POST
Processed	int	Количество контактов, добавленных в базу

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

{
    "Result":{
        "Uploaded" : 1123456,
        "Processed": 1100000
    },
    "Code": "ok",
    "Description": "ok"
}

ContactsImport Duplicates DELETE¶

https://integrationapi.net/addressbook/v2/ContactsImport/{ImportId}/Duplicates

Метод удаляет дубликаты по идентификатору импорта, который передаётся в url.

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

Параметр	Тип данных	Описание	Обязательнй
ContactGroupId	int	Идентификатор группы, в которую импортированы контакты	Да
ImportId	GUID	Идентификатор импорта	Да
Field	DuplicatesCheckField	Ключевое поле для проверки - email или номер телефона	Нет
Scope	DuplicatesCheckScope	Область проверки на дубли	Нет
Groups	int[]	Список групп для проверки	Нет

Перечисление DuplicatesCheckField

Текст	Число	Описание
No	0	Не проверяем на дубли
PhoneNumber	1	Проверяем по номеру телефона
Email	2	Проверяем по email адресу

Перечисление DuplicatesCheckScope

Текст	Число	Описание
No	0	Не проверяем на дубли
Import	1	Проверяем в рамках импорта
Groups	2	Проверяем в переданных группах

DuplicatesCheckScope является битовой маской, можно передавать сочетания значений, т.е. можно передать 3 и проверка будет выполнена в рамках импорта и в переданных группах.

Возвращаемый результат

Параметр	Тип данных	Описание
InCurrentGroup	int	Количество дублей в текущей группе
InOtherGroups	int	Количество дублей в других группах
InCurrentImport	string[]	Список дублей в текущем импорте

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

{
    "ContactGroupId" : 9731,
    "ImportId" : "50210B41-1C4E-4E48-9837-FB382A9BAE01",
    "Field" : "Email",
    "Scope" : 3,
    "Groups" : [123, 345, 9731]
}

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

{
    "Result":{
        "InCurrentGroup" : 34,
        "InOtherGroups": 55,
        "InCurrentImport": ["79251234567"]
    },
    "Code": "ok",
    "Description": "ok"
}

Contacts GET (query)¶

https://integrationapi.net/addressbook/v2/Contacts?Query={Key}

Метод возвращает контакты по ключу, в качестве ключа может выступать email или номер телефона. Возвращаемый результат - список объектов типа ContactDto.

Также необходимо задать диапазон возвращаемых записей.

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

Параметр	Тип данных	Описание	Обязательнй
Query	string	Ключ для поиска контактов (передаётся в url)	Да

Возвращаемый результат - список записей ContactDto

Параметр	Тип данных	Описание
ContactId	long	Идентификатор контакта
PhoneNumber	string	Номер телефона
Email	string	Email адрес
FirstName	string	Имя
MiddleName	string	Отчество
LastName	string	Фамилия
Gender	int	Пол (1 - м, 2 - ж, 3 - неизвестно)
DateOfBirth	DateTime	Дата рождения
ExtraField1	string	Дополнительное поле №1
ExtraField2	string	Дополнительное поле №2
ContactGroupId	int	Идентификатор группы, в которой находится контакт
MergeFields	Dictionary	Пользовательский словарь в виде «ключ-значение»

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

{
    "Result":[{
        "ContactId": 1,
        "PhoneNumber": "",
        "LastName": "Snuk",
        "MiddleName": "Snuk",
        "FirstName": "Snuk",
        "Email": "xx@gmail.com",
        "Gender": 3,
        "DateOfBirth": "/Date(1454533200000-0000)/",
        "ExtraField1": "ddddddddddddddddd",
        "ExtraField2": "cccccccccccccccc",
        "ContactGroupId": 252
    },
    {
        "ContactId": 100005,
        "PhoneNumber": "",
        "LastName": "sdfsdfdsf",
        "MiddleName": "sfddsf",
        "FirstName": "sdfdsfds",
        "Email": "yy@list.ru",
        "Gender": 3,
        "ContactGroupId": 252
    }],
    "Code": "ok",
    "Description": "ok"
}

Contacts GET¶

https://integrationapi.net/addressbook/v2/Contacts/{ContactId}

Метод возвращает контакт по идентификатору, в качестве Result возвращается объект ContactDto, описание см. выше.

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

Параметр	Тип данных	Описание	Обязательнй
ContactId	int	Идентификатор контакта (передаётся в url)	Да

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

{
    "Result":{
        "ContactId": 1,
        "PhoneNumber": "",
        "LastName": "Snuk",
        "MiddleName": "Snuk",
        "FirstName": "Snuk",
        "Email": "xx@gmail.com",
        "Gender": 3,
        "DateOfBirth": "/Date(1454533200000-0000)/",
        "ExtraField1": "ddddddddddddddddd",
        "ExtraField2": "cccccccccccccccc",
        "ContactGroupId": 252
    },
    "Code": "ok",
    "Description": "ok"
}

Contacts POST¶

https://integrationapi.net/addressbook/v2/Contacts

Метод создаёт контакт. Если контакт был успешно создан, возвращается код «ok» и http код 201. В качестве Result возвращается идентификатор контакта.

Валидируются:

наличие хотя бы одного поля - номер телефона или email адрес
валидность номера телефона, если он передан
валидность email адреса, если он передан
длина полей FirstName, MiddleName и LastName не должна превышать 100 символов, для ExtraField1 и ExtraField2 - ограничение 700 символов
пол, если передано значение отличное от 1 и 2, будет проставлено 3
наличие группы, в которую добавляется контакт

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

Параметр	Тип данных	Описание	Обязательнй
PhoneNumber	string	Номер телефона	см. описание
Email	string	Email адрес	см. описание
FirstName	string	Имя	Нет
MiddleName	string	Отчество	Нет
LastName	string	Фамилия	Нет
Gender	int	Пол (1 - м, 2 - ж, 3 - неизвестно)	Нет
DateOfBirth	DateTime	Дата рождения	Нет
ExtraField1	string	Дополнительное поле №1	Нет
ExtraField2	string	Дополнительное поле №2	Нет
MergeFields	Dictionary	Пользовательский словарь «ключ-значение»	Нет
ContactGroupId	int	Идентификатор группы, в которой находится контакт	Да

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

{
    "PhoneNumber": "",
    "LastName": "Snuk",
    "MiddleName": "Snuk",
    "FirstName": "Snuk",
    "Email": "zzz@gmail.com",
    "Gender": 3,
    "DateOfBirth": "/Date(1454533200000-0000)/",
    "ExtraField1": "ddddddddddddddddd",
    "ExtraField2": "cccccccccccccccc",
    "ContactGroupId": 252
}

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

{
    "Result": 100013,
    "Code": "ok",
    "Description": "ok"
}

Contacts PATCH¶

https://integrationapi.net/addressbook/v2/Contacts/{ContactId}

Метод обновляет контакт. (PATCH по идеологии аналогичен PUT, с той лишь разницей, что PUT полностью заменяет ресурс, а PATCH меняет только те параметры, которые переданы.) Валидация идентична методу Contacts POST, исключается только проверка наличия группы, так как её менять нельзя. Возвращается только стандартный ответ, без поля Result.

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

Параметр	Тип данных	Описание	Обязательнй
ContactId	long	Идентификатор контакта (предаётся в url)	Да
PhoneNumber	string	Номер телефона	см. описание
Email	string	Email адрес	см. описание
FirstName	string	Имя	Нет
MiddleName	string	Отчество	Нет
LastName	string	Фамилия	Нет
Gender	int	Пол (1 - м, 2 - ж, 3 - неизвестно)	Нет
DateOfBirth	DateTime	Дата рождения	Нет
ExtraField1	string	Дополнительное поле №1	Нет
ExtraField2	string	Дополнительное поле №2	Нет
MergeFields	Dictionary	Пользовательский словарь «ключ-значение»	Нет

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

{
    "PhoneNumber": "",
    "LastName": "Snuk",
    "MiddleName": "Snuk",
    "FirstName": "Snuk",
    "Email": "zz@gmail.com",
    "Gender": 3,
    "DateOfBirth": "/Date(1454533200000-0000)/",
    "ExtraField1": "ddddddddddddddddd",
    "ExtraField2": "cccccccccccccccc"
}

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

{
    "Code": "ok",
    "Description": "ok"
}

Contacts DELETE¶

https://integrationapi.net/addressbook/v2/Contacts/{ContactId}

Метод удаляет контакт, возвращается только стандартный ответ, без поля Result.

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

Параметр	Тип данных	Описание	Обязательнй
ContactId	int	Идентификатор контакта (передаётся в url)	Да

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

{
    "Code": "ok",
    "Description": "ok"
}

Работа с отписавшимися¶

Unsubscribed GET¶

https://integrationapi.net/addressbook/v2/Unsubscribed?TaskId={TaskId}

Метод возвращает список отписавшихся от email рассылок. Можно получить список отписавшихся от определённой рассылки, для этого предусмотрен параметр taskId. Возвращаемый результат - список объектов типа UnsubscribedDto. Также необходимо задать диапазон возвращаемых записей.

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

Параметр	Тип данных	Описание	Обязательнй
TaskId	int	Идентификатор рассылки	Нет

Возвращаемый результат - список записей UnsubscribedDto

Параметр	Тип данных	Описание
Email	string	Email адрес
DateTime	DateTime	Дата и время добавления
Reason	string	Причина отписки
TaskId	int	Идентификатор рассылки

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

{
    "Result":[{
        "Email": "generated_1@generated.com",
        "DateTime": "/Date(1439219917910-0000)/",
        "Reason": "Другая причина",
        "TaskId": 133696
    },
    {
        "Email": "generated_11@generated.com",
        "DateTime": "/Date(1439219917910-0000)/",
        "Reason": "Скучные рассылки у вас",
        "TaskId": 133696
    }],
    "Code": "ok",
    "Description": "ok"
}