Адреса
Общие сведения
Сервис позволяет получить список адресов контрагента, а также добавлять и редактировать адреса в списке. Записи, неиспользуемые в течение 6 месяцев, автоматически удаляются из адресной книги.
Список адресов
Запрос метода
Структура запроса
Адрес метода: https://api.dellin.ru/v2/book/addresses.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "counteragentID":1 }
Адрес метода: https://api.dellin.ru/v2/book/addresses.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <counteragentID>1</counteragentID> </request>
Описание параметров
Request
Request | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
appkey | Да | string | Ключ приложения. Для получения ключа необходимо пройти регистрацию |
sessionID | Да | string | ID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя" |
counteragentID | Да | integer | ID контрагента, по которому нужно получить информацию об адресах |
Ответ метода
Структура ответа
{ "metadata":{ "status":200, "generated_at":"2015-06-18 12:37:28" }, "data":[ { "address":{ "id":1, "juridical":false, "cityID":"200601", "code":"7800000000002080000000000", "address":"190000, г. Санкт-Петербург, Васи Алексеева ул, д. 125 кв/оф. 513", "street":"Васи Алексеева", "house":"125", "building":"", "structure":"", "flat":"513", "contacts":2, "phones":4, "regionName":"Санкт-Петербург", "cityName":"Санкт-Петербург г", "cityCode":"7800000000000000000000000", "terminalUID":"0xa8e2001438c4d49511db5ab084a0d1bc", "terminalID":1 } }, { "address":{ "id":2, "juridical":true, "cityID":"588381", "code":"7700000000007000000000000", "address":"107078, г. Москва Академика Сахарова пр-кт, д. 34", "street":"Академика Сахарова", "house":"34", "building":"", "structure":"", "flat":"", "contacts":1, "phones":2, "regionName":"г. Москва", "cityName":"Москва г", "cityCode":"7700000000000000000000000", "terminalUID":null, "terminalID":null } } ] }
<response> <metadata> <status>200</status> <generated_at>2015-06-18 12:37:28</generated_at> </metadata> <data> <address> <id>1</id> <juridical>false</juridical> <cityID>200601</cityID> <code>7800000000002080000000000</code> <address>190000, г. Санкт-Петербург, Васи Алексеева ул, д. 125 кв/оф. 513</address> <street>Васи Алексеева</street> <house>125</house> <building></building> <structure></structure> <flat>513</flat> <contacts>2</contacts> <phones>4</phones> <regionName>Санкт-Петербург</regionName> <cityName>Санкт-Петербург г</cityName> <cityCode>7800000000000000000000000</cityCode> <terminalUID>0xa8e2001438c4d49511db5ab084a0d1bc</terminalUID> <terminalID>1</terminalID> </address> </data> <data> <address> <id>2</id> <juridical>true</juridical> <cityID>588381</cityID> <code>7700000000007000000000000</code> <address>107078, г. Москва Академика Сахарова пр-кт, д. 34</address> <street>Академика Сахарова</street> <house>34</house> <building></building> <structure></structure> <flat></flat> <contacts>1</contacts> <phones>2</phones> <regionName>г. Москва</regionName> <cityName>Москва г</cityName> <cityCode>7700000000000000000000000</cityCode> <terminalUID /> <terminalID /> </address> </data> </response>
Описание параметров
Response
Response | ||
---|---|---|
Параметр | Тип | Описание |
metadata | object | Системная информация |
metadata.status | integer | Эмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK) |
metadata.generatedAt | string | Дата и время генерации ответа сервера. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС" |
data | array of Data | Сведения об адресах контрагента |
Data
Data | ||
---|---|---|
Параметр | Тип | Описание |
address | object | Информация об адресе |
address.id | integer | ID адреса |
address.juridical | boolead | Тип адреса. Доступные значения:
|
address.cityID | string | ID населённого пункта, см. метод "Поиск населённых пунктов" |
address.code | string | Код КЛАДР улицы для адреса, если она добавлена из справочника. В противном случае - код КЛАДР населенного пункта |
address.address | string | Текстовое представление адреса |
address.street | string | Улица |
address.house | string | Номер дома, включая литеру. Например, "13/А" |
address.building | string | Корпус |
address.structure | string | Строение |
address.flat | string | Номер квартиры/офиса. Допускается написание с буквой, например "222 А" |
address.contacts | integer | Количество контактных лиц для адреса |
address.phones | integer | Количество контактных телефонов для адреса |
address.regionName | string | Регион |
address.cityName | string | Город |
address.cityCode | string | Код КЛАДР населённого пункта, см. метод "Поиск населённых пунктов" |
address.terminalUID | string | UID терминала, если адрес не является терминалом, то значение параметра - "null" |
address.terminalID | integer | ID терминала (см. "Справочник терминалов"), если адрес не является терминалом, то значение параметра - "null" |
Обработка ошибок
В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".
Создание и редактирование адреса
Запрос метода
Пример запроса (создание адреса)
Адрес метода: https://api.dellin.ru/v2/book/address/update.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "counteragentID":1, "search":"Омск, Ленина, 5", "street":"5500000100005970000000000", "house":"5", "building":"1", "structure":"лит. А", "flat":"214а" }
Адрес метода: https://api.dellin.ru/v2/book/address/update.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <counteragentID>1</counteragentID> <search>Омск, Ленина, 5</search> <street>5500000100005970000000000</street> <house>5</house> <building>1</building> <structure>лит. А</structure> <flat>214а</flat> </request>
Пример запроса (создание адреса на основе терминала)
При необходимости можно создать адрес на основе терминала компании "Деловые Линии". Вся информация об адресе в данном случае будет заполнена автоматически. Получить ID терминала можно из "Справочника терминалов". Пример запроса для данного случая представлен ниже.
Адрес метода: https://api.dellin.ru/v2/book/address/update.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "counteragentID":1, "terminalID":39 }
Адрес метода: https://api.dellin.ru/v2/book/address/update.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <counteragentID>1</counteragentID> <terminalID>39</terminalID> </request>
Пример запроса (редактирование адреса)
При редактировании адреса запрос аналогичен запросу для создании адреса, но из параметров адреса в этом случае достаточно передать только те, которые требуется отредактировать. Исключение составляют параметры из списка: "house", "building", "structure" и "flat" - при передаче какого-либо из этих параметров значения непереданных параметров из списка удаляются, поэтому необходимо повторно передавать в том числе те параметры из списка, значения которых не меняются
Адрес метода: https://api.dellin.ru/v2/book/address/update.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "addressID":1, "house":"12" }
Адрес метода: https://api.dellin.ru/v2/book/address/update.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <addressID>1</addressID> <house>12</house> </request>
Описание параметров
Request
Request | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
appkey | Да | string | Ключ приложения. Для получения ключа необходимо пройти регистрацию |
sessionID | Да | string | ID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя" |
counteragentID | Нет* | integer | ID контрагента, для которого нужно добавить адрес. *Параметр является обязательным при создании адреса. При редактировании адреса параметр не используется |
search | Нет (1) | string | Адрес в виде текста или координат. При передаче адреса в виде текста, помимо собственно адреса, в запрос следует включать наименование населённого пункта, элементы необходимо указывать через запятую, например "Омск, Ленина, 5". Координаты также указываются через запятую, первое число - широта, например "59.924501, 30.241762". Минимум 2 символа, максимум - 1024 (2) |
street | Нет (1) | string | Код КЛАДР улицы. Код КЛАДР может быть получен с помощью сервисов, представленных на странице "Поиск КЛАДР" (2) |
house | Нет (1) | string | Номер дома, включая литеру. Например, "13/А" (2), (3). Максимум 7 символов |
building | Нет | string | Корпус (2), (3). Максимум 5 символов |
structure | Нет | string | Строение (2), (3). Максимум 7 символов |
flat | Нет | string | Номер квартиры/офиса. Допускается написание с буквой, например "222 А" (2), (3). Максимум 5 символов |
terminalID | Нет (1) | integer | ID терминала из "Справочника терминалов". Параметр используется для создания адреса на основе терминала компании "Деловые Линии". Вся информация об адресе в данном случае заполняется автоматически (2) |
addressID | Нет* | integer | ID адреса, который нужно изменить. *Параметр является обязательным при редактировании адреса. При создании адреса параметр не используется |
Примечания:
|
Ответ метода
Структура ответа
{ "metadata":{ "status":200, "generated_at":"2015-06-18 12:37:28" }, "data":{ "state":"existing", "addressID":1, "foundAddresses":[ { "source":"Омск, Ленина, 5", "result":"Россия, Омская обл, г Омск, ул Ленина, д 5" } ] } }
<response> <metadata> <status>200</status> <generated_at>2015-06-18 12:37:28</generated_at> </metadata> <data> <state>existing</state> <addressID>1</addressID> <foundAddresses> <source>Омск, Ленина, 5</source> <result>Россия, Омская обл, г Омск, ул Ленина, д 5</result> </foundAddresses> </data> </response>
Описание параметров
Response
Response | ||
---|---|---|
Параметр | Тип | Описание |
metadata | object | Системная информация |
metadata.status | integer | Эмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK) |
metadata.generatedAt | string | Дата и время генерации ответа сервера. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС" |
data | object | Информация об отредактированном/добавленном адресе |
data.state | string | Статус адреса. Возможные значения:
|
data.addressID | integer | ID отредактированного/добавленного адреса |
data.foundAddresses | array of FoundAddresses | Данные по найденным адресам. Параметр присутствует в ответе, только если в запросе был передан параметр "search" |
FoundAddresses
FoundAddresses | ||
---|---|---|
Параметр | Тип | Описание |
source | string | Введённое значение |
result | string | Найденный адрес |
Обработка ошибок
В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".