Devino AddressBook Api

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

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

Описание

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

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

  1. Набор методов для работы с группами контактов - ContactGroups.
Ресурс Метод Описание
/ContactGroups GET Получение списка всех групп
/ContactGroups/{ContactGroupId} GET Получение группы с подробной информацией
/ContactGroups POST Добавление группы
/ContactGroups/{ContactGroupId} PUT Редактирование группы
/ContactGroups/{ContactGroupId} DELETE Удаление группы
  1. Набор методов для импорта контактов - ContactsImport.
Ресурс Метод Описание
/ContactsImport POST Импорт контактов
/ContactsImport/{ImportId}/Progress GET Запрос прогресса добавления контактов в базу
/ContactsImport/{ImportId}/Duplicates DELETE Удаление дубликатов из завершённого импорта
  1. Набор методов для работы с контактами - Contacts.
Ресурс Метод Описание
/Contacts?Query={Key} GET Получение диапазона контактов по телефону или почте
/Contacts/{ContactId} GET Получение контакта с подробной информацией
/Contacts POST Создание контакта
/Contacts/{ContactId} PATCH Редактирование контакта
/Contacts/{ContactId} DELETE Удаление контакта
  1. Набор методов для работы с отписавшимися - Unsubscribed.
Ресурс Метод Описание
/Unsubscribed?TaskId={TaskId} GET Получение диапазона отписавшихся по рассылке
/Unsubscribed GET Получение диапазона отписавшихся
Запрос к API состоит из следующих элементов:
  • Основного URL запроса: https://integrationapi.net/addressbook/v2 (https://integrationapi.net/addressbook/v1 - устарел)
  • Ресурса, например: /Contacts
  • Параметров запроса в кодировке UTF-8. Сервис реализован с использованием технологии ServiceStack, что позволяет передавать параметры в следующих форматах: 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х частей:

  1. Код с описанием - эта часть присутствует во всех ответах. В качестве описания возвращается user-friendly описание ошибки.
  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 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

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

Параметр Тип данных Описание Обязательнй
Login string Логин Да
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 Нет

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

Параметр Тип данных Описание
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}/Delete

Метод удаляет дубликаты по идентификатору импорта, который передаётся в 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 Проверяем в рамках импорта
Email 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 Идентификатор группы, в которой находится контакт

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

{
    "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 Нет
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 Нет

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

{
    "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"
}