Перейти к содержанию

Devino AddressBook Api

Описание

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

Внимание

Для использования сервиса необходимо обратиться к менеджеру компании либо в техническую поддержку.

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

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 Получение контактов по номеру телефона или email
/Contacts/{ContactId} GET Получение подробной информации о контакте
/Contacts POST Создание контакта
/Contacts/{ContactId} PATCH Редактирование контакта
/Contacts/{ContactId} DELETE Удаление контакта

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

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

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

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

Авторизация

Для доступа к сервису необходимо пройти авторизацию. Сервис поддерживает базовую авторизацию через заголовок Authorization:

    Authorization: Basic dGVzdGVyOjExMTExMQ==

В заголовке необходимо передать логин и пароль из личного кабинета в формате login:password в кодировке base64.

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

  1. Код с описанием - присутствует во всех ответах.
  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.

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

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

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

Получить все ContactGroups

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

Метод возвращает список всех групп контактов пользователя.

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

Результат - список объектов ContactGroupDto:

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

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

{
    "Result":[
        {
            "ContactGroupId": 252,
            "Name": "snuk",
            "Description": "",
            "CreatedDate": "/Date(1426504354337-0000)/",
            "ContactsCount": 3
        },
        {
            "ContactGroupId": 331,
            "Name": "Group",
            "Description": "AB api integration test",
            "CreatedDate": "/Date(1454582978323-0000)/",
            "ContactsCount": 0
        }
    ],
    "Code": "ok",
    "Description": "ok"
}

Получить ContactGroups по ID

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

Метод возвращает группу контактов по ID.

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

Параметр Тип данных Описание
ContactGroupId
обязательный		 integer ID группы. Передается в URL.

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

Результат - объект ContactGroupDto:

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

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

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

Добавить ContactGroups

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

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

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

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

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

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

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

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

Обновить ContactGroups

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

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

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

Параметр Тип данных Описание
ContactGroupId
обязательный		 integer ID группы. Передается в URL.
Name
обязательный		 string Имя группы
Description string Описание группы

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

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

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

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

Удалить ContactGroups

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

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

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

Параметр Тип данных Описание
ContactGroupId
обязательный		 integer ID группы. Передается в URL.

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

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

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

Импорт контактов

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
обязательный		 integer ID группы, в которую импортируются контакты.
ImportId string ID импорта
ConvertDirectPhones bool Преобразовывать ли прямые номера в федеральные
FillGender bool Заполнять ли автоматически пол контакта на основе его ФИО
Contacts
обязательный		 ContactDto[] Список импортируемых контактов
ContactDto
Параметр Тип данных Описание
PhoneNumber
обязательный		 string Номер телефона
Email
обязательный		 string Email-адрес
FirstName string Имя
MiddleName string Отчество
LastName string Фамилия
Gender integer

Пол контакта

Возможные значения:
○ 1 - мужской
○ 2 - женский
○ 3 - пол неизвестен
DateOfBirth DateTime Дата рождения
ExtraField1 string Дополнительное поле №1
ExtraField2 string Дополнительное поле №2
MergeFields Dictionary Пользовательский словарь ключ-значение

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

Параметр Тип данных Описание
ImportId string ID импорта. Генерируется автоматически, если не был передан
ValidContacts integer Количество валидных контактов
RejectedContacts array[RejectedContactDto] Список невалидированных контактов
InvalidPhoneNumbers array[string] Список невалидированных номеров телефонов
InvalidEmails array[string] Список невалидированных email-адресов
RejectedContactDto
Параметр Тип данных Описание
Contact ContactDto Параметры контакта
ErrorCode ContactValidationCode Тип ошибки валидации
ErrorDescription string Описание ошибки валидации
DuplicatesCount integer Количество дублирований в изначальном запросе
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"
}

Прогресс импорта контактов

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

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

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

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

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

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

Удалить дубликаты контактов

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

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

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

Параметр Тип данных Описание
ContactGroupId
обязательный		 integer ID группы, в которую импортированы контакты.
ImportId
обязательный		 GUID ID импорта
Field DuplicatesCheckField Ключевое поле для проверки - email или номер телефона
Scope DuplicatesCheckScope Область проверки на дубли
Groups array[integer] Список групп для проверки
Значения DuplicatesCheckField
Текст Число Описание
No 0 Без проверки на дубли
PhoneNumber 1 Проверка на дубли по номеру телефона
Email 2 Проверка на дубли по email-адресу
Значения DuplicatesCheckScope
Текст Число Описание
No 0 Без проверки на дубли
Import 1 Проверка на дубли в рамках импорта
Groups 2 Проверка на дубли в переданных группах

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

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

Параметр Тип данных Описание
InCurrentGroup integer Количество дублей в текущей группе
InOtherGroups integer Количество дублей в других группах
InCurrentImport array[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

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

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

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

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

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

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

Метод возвращает список записей ContactDto:

Параметр Тип данных Описание
ContactId long ID контакта
PhoneNumber string Номер телефона
Email string Email-адрес
FirstName string Имя
MiddleName string Отчество
LastName string Фамилия
Gender integer

Пол контакта

Возможные значения:
○ 1 - мужской
○ 2 - женский
○ 3 - пол неизвестен
DateOfBirth DateTime Дата рождения
ExtraField1 string Дополнительное поле №1
ExtraField2 string Дополнительное поле №2
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"
}

Получить контакты

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

Метод возвращает контакт по ID, в качестве Result возвращается объект ContactDto.

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

Параметр Тип данных Описание
ContactId
обязательный		 integer ID контакта. Передается в 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"
}

Добавить контакты

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

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

Контакты проверяются на:

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

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

Параметр Тип данных Описание
PhoneNumber
обязательный		 string Номер телефона
Email
обязательный		 string Email-адрес
FirstName string Имя
MiddleName string Отчество
LastName string Фамилия
Gender integer

Пол контакта

Возможные значения:
○ 1 - мужской
○ 2 - женский
○ 3 - пол неизвестен
DateOfBirth DateTime Дата рождения
ExtraField1 string Дополнительное поле №1
ExtraField2 string Дополнительное поле №2
MergeFields Dictionary Пользовательский словарь ключ-значение
ContactGroupId
обязательный		 integer ID группы, которой принадлежит контакт.

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

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

Обновить контакты

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

Метод обновляет контакт.

Информация

PATCH по идеологии аналогичен PUT, с той лишь разницей, что PUT полностью заменяет ресурс, а PATCH меняет только те параметры, которые переданы.

Валидация идентична методу POST /Contacts. Исключается только проверка наличия группы контакта, так как группу менять нельзя. Возвращается только стандартный ответ, без поля Result.

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

Параметр Тип данных Описание
ContactId
обязательный		 long ID контакта. Передается в URL.
PhoneNumber
обязательный		 string Номер телефона
Email
обязательный		 string Email-адрес
FirstName string Имя
MiddleName string Отчество
LastName string Фамилия
Gender integer

Пол контакта

Возможные значения:
○ 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"
}

Удалить контакты

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

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

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

Параметр Тип данных Описание
ContactId
обязательный		 integer ID контакта. Передается в URL.

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

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

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

Получить отписавшиеся контакты

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

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

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

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

Параметр Тип данных Описание
TaskId integer ID рассылки

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

Результат - список объектов UnsubscribedDto:

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

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

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