Контрагенты
Общие сведения
Адресная книга представляет собой список контрагентов с реквизитами, которые могут быть использованы для оформления заказов. Записи, неиспользуемые в течение 6 месяцев, автоматически удаляются из адресной книги.
Адресная книга и контрагенты, доступные для учетной записи, - это разные понятия. Контрагенты из адресной книги могут использоваться только для быстрого оформления заказа, получение информации по ним недоступно.
Список контрагентов из адресной книги
Запрос метода
Структура запроса
Адрес метода: https://api.dellin.ru/v2/book/counteragents.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "withAnonym":"false", "isAnonym":"false", "counteragentIds":[ 1, 2, 3 ] }
Адрес метода: https://api.dellin.ru/v2/book/counteragents.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <withAnonym>false</withAnonym> <isAnonym>false</isAnonym> <counteragentIds>1</counteragentIds> <counteragentIds>2</counteragentIds> <counteragentIds>3</counteragentIds> </request>
Описание параметров
Request
Request | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
appkey | Да | string | Ключ приложения. Для получения ключа необходимо пройти регистрацию |
sessionID | Да | string | ID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя" |
withAnonym | Нет | boolean | Признак запроса списка контрагентов, включающего "анонимных" получателей (1). Доступные значения:
Значение по умолчанию: "false" |
isAnonym | Нет | boolean | Признак запроса списка контрагентов, включающего только "анонимных" получателей (1). Доступные значения:
Значение по умолчанию: "false" Если в запросе передан параметр "withAnonym" со значением "false" и параметр "isAnonym" со значением "true", то ответ будет содержать список контрагентов, включающий только "анонимных" получателей |
counteragentIds | Нет | array of integers | Список ID контрагентов, по которым необходима информация. Если параметр не передан в запросе, то в ответе будет получен полный список контрагентов |
Примечания:
|
Ответ метода
Структура ответа
{ "metadata":{ "status":200, "generated_at":"2015-06-18 12:37:28" }, "data":[ { "id":1, "isAnonym":"false", "form":"ООО", "formUID":"0x92EE03691F25A9FE4BE9910CD87CA9CA", "name":"Ромашка", "phone":null, "email":null, "juridical":"true", "addresses":3, "inn":"1234567890", "document":null, "lastUpdate":"2015-07-04 02:27:15", "countryUid":"0x8f51001438c4d49511dbd774581edb7a", "uid":"00000000-0000-0000-0000-000000000000", "dataForReceipt":{ "phoneNumber":null, "email":null } }, { "id":2, "isAnonym":"true", "form":"Ч/Л", "formUID":"0xAB91FEEA04F6D4AD48DF42161B6C2E7A", "name":"Леонид", "phone":"+7 (900) 000-00-00", "email":"petro@mail.com", "juridical":"false", "addresses":1, "inn":null, "document":null, "lastUpdate":"2015-07-04 02:27:15", "countryUid":"0x8f51001438c4d49511dbd774581edb7a", "uid":"00000000-0000-0000-0000-000000000000", "dataForReceipt":{ "phoneNumber":null, "email":null } }, { "id":3, "isAnonym":"false", "form":"Ч/Л", "formUID":"0x8F51001438C4D49511DBD774581EDB80", "name":"Иванов Иван Иванович", "phone":null, "email":null, "juridical":"false", "addresses":1, "inn":null, "document":{ "type":"passport", "serial":"0000", "number":"000000", "date":"2014-01-23" }, "lastUpdate":"2015-07-04 02:27:15", "countryUid":"0x8f51001438c4d49511dbd774581edb7a", "uid":"00000000-0000-0000-0000-000000000000", "dataForReceipt":{ "phoneNumber":"+79ХХХХХХХХХ", "email":"meow@mail.ru" } } ] }
{ "metadata":{ "status":200, "generated_at":"2015-06-18 12:37:28" }, "data":[ { "id":1, "isAnonym":"false", "form":"ООО", "formUID":"0x92EE03691F25A9FE4BE9910CD87CA9CA", "name":"Ромашка", "phone":null, "email":null, "juridical":"true", "addresses":3, "inn":"1234567890", "document":null, "lastUpdate":"2015-07-04 02:27:15", "countryUid":"0x8f51001438c4d49511dbd774581edb7a", "uid":"00000000-0000-0000-0000-000000000000", "dataForReceipt":{ "phoneNumber":null, "email":null } }, { "id":2, "isAnonym":"true", "form":"Ч/Л", "formUID":"0xAB91FEEA04F6D4AD48DF42161B6C2E7A", "name":"Леонид", "phone":"+7 (900) 000-00-00", "email":"petro@mail.com", "juridical":"false", "addresses":1, "inn":null, "document":null, "lastUpdate":"2015-07-04 02:27:15", "countryUid":"0x8f51001438c4d49511dbd774581edb7a", "uid":"00000000-0000-0000-0000-000000000000", "dataForReceipt":{ "phoneNumber":null, "email":null } }, { "id":3, "isAnonym":"false", "form":"Ч/Л", "formUID":"0x8F51001438C4D49511DBD774581EDB80", "name":"Иванов Иван Иванович", "phone":null, "email":null, "juridical":"false", "addresses":1, "inn":null, "document":{ "type":"passport", "serial":"0000", "number":"000000", "date":"2014-01-23" }, "lastUpdate":"2015-07-04 02:27:15", "countryUid":"0x8f51001438c4d49511dbd774581edb7a", "uid":"00000000-0000-0000-0000-000000000000", "dataForReceipt":{ "phoneNumber":"+79ХХХХХХХХХ", "email":"meow@mail.ru" } } ] }
Описание параметров
Response
Response | ||
---|---|---|
Параметр | Тип | Описание |
metadata | object | Системная информация |
metadata.status | integer | Эмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK) |
metadata.generatedAt | string | Дата и время генерации ответа сервера. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС" |
data | array of Data | Сведения о контрагентах |
Data
Data | ||
---|---|---|
Параметр | Тип | Описание |
id | integer | ID контрагента |
isAnonym | string | Признак "анонимного" получателя (1). Возможные значения:
|
form | string | Организационно-правовая форма контрагента (далее - ОПФ) |
formUID | string | UID ОПФ (см. метод "Поиск ОПФ") |
name | string | Наименование контрагента (для "анонимного" получателя (1) - имя) |
phone | string | Номер телефона "анонимного" получателя (1) . Если контрагент не является "анонимным" получателем (значение параметра ответа "data.isAnonym" - "false"), то значение параметра - "null" |
string | Адрес электронной почты "анонимного" получателя (1) . Если контрагент не является "анонимным" получателем (значение параметра ответа "data.isAnonym" - "false"), то значение параметра - "null" | |
juridical | boolean | Тип контрагента:
|
addresses | integer | Количество адресов доставки контрагента |
inn | string | ИНН контрагента. Если контрагент - физическое лицо (значение параметра ответа "data.juridical" - "false"), то значение параметра - "null". Максимальная допустимая длина поля зависит от страны и ОПФ |
document | object | Данные документа, удостоверяющего личность. Если контрагент - юридическое лицо (значение параметра ответа "data.juridical" - "true") или "анонимный" получатель (значение параметра ответа "data.isAnonym" - "true"), то значение параметра - "null" |
document.type | string | Тип документа. Доступные значения:
|
document.serial | string | Серия документа |
document.number | string | Номер документа. Формат номера зависит от страны |
document.date | string | Дата выдачи документа в формате "ГГГГ-ММ-ДД" Формат: "ГГГГ-ММ-ДД" |
lastUpdate | string | Дата последнего обновления информации о данном контрагенте. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС" |
countryUid | string | UID страны (см. метод "Поиск стран") |
uid | string | UID контрагента |
dataForReceipt | object | Контактные данные для отправки электронного чека плательщику - физическому лицу (значение параметра ответа "data.juridical" - "false"), не являющемуся "анонимным" получателем (значение параметра ответа "data.isAnonym" - "false") |
dataForReceipt.phoneNumber | string | Номер телефона для отправки чека |
dataForReceipt.email | string | Адрес электронной почты для отправки чека |
Примечания:
|
Обработка ошибок
В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".
Создание и редактирование контрагентов
Метод позволяет создавать новых контрагентов и редактировать информацию о них. Запрос метода отличается в зависимости от вида контрагента: юридическое или физическое лицо.
Запрос метода
Пример запроса: создание контрагента (юридического лица)
Адрес метода: https://api.dellin.ru/v2/book/counteragent/update.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "form":"0x8F51001438C4D49511DBD774581EDB80", "name":"Ромашка", "inn":"1234567890", "juridicalAddress":{ "search":"Омск, Ленина, 5", "street":"7800000000004380000000000", "house":"4", "building":"2", "structure":"3А", "flat":"Б-234" } }
Адрес метода: https://api.dellin.ru/v2/book/counteragent/update.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <form>0x8F51001438C4D49511DBD774581EDB80</form> <name>Ромашка</name> <inn>1234567890</inn> <juridicalAddress> <search>Омск, Ленина, 5</search> <street>7800000000004380000000000</street> <house>4</house> <building>2</building> <structure>3А</structure> <flat>Б-234</flat> </juridicalAddress> </request>
Пример запроса: создание контрагента (физического лица)
Адрес метода: https://api.dellin.ru/v2/book/counteragent/update.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "form":"0xAB91FEEA04F6D4AD48DF42161B6C2E7A", "name":"Петров А.А.", "document":{ "type":"passport", "serial":"XXXX", "number":"XXXX", "date":"YYYY-MM-DD" }, "dataForReceipt":{ "phone":"+79000000000", "email":"test@mail.ru" } }
Адрес метода: https://api.dellin.ru/v2/book/counteragent/update.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <form>0xAB91FEEA04F6D4AD48DF42161B6C2E7A</form> <name>Петров А.А.</name> <document> <type>passport</type> <serial>XXXX</serial> <number>XXXX</number> <date>YYYY-MM-DD</date> </document> <dataForReceipt> <phone>+79000000000</phone> <email>test@mail.ru</email> </dataForReceipt> </request>
Пример запроса: создание контрагента ("анонимного" получателя)
Адрес метода: https://api.dellin.ru/v2/book/counteragent/update.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "isAnonym":"true", "form":"0xAB91FEEA04F6D4AD48DF42161B6C2E7A", "name":"Леонид", "phone":"70000000000", "email":"petro@mail.com" }
Адрес метода: https://api.dellin.ru/v2/book/counteragent/update.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <isAnonym>true</isAnonym> <form>0xAB91FEEA04F6D4AD48DF42161B6C2E7A</form> <name>Леонид</name> <phone>70000000000</phone> <email>petro@mail.com</email> </request>
Пример запроса: редактирование данных контрагента
Для изменения данных контрагента, не являющегося "анонимным" получателем, необходимо передать в запросе ID клиента и те данные, которые нужно изменить.
Адрес метода: https://api.dellin.ru/v2/book/counteragent/update.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "counteragentID":1, "juridicalAddress":{ "street":"7800000000004380000000000", "house":"5" } }
Адрес метода: https://api.dellin.ru/v2/book/counteragent/update.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <counteragentID>1</counteragentID> <juridicalAddress> <street>7800000000004380000000000</street> <house>5</house> </juridicalAddress> </request>
Описание параметров
Request
Request | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
appkey | Да | string | Ключ приложения. Для получения ключа необходимо пройти регистрацию |
sessionID | Да | string | ID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя" |
form | Нет* | string | UID ОПФ (см. метод "Поиск ОПФ"). При передаче данных об "анонимном" получателе (значение параметра "isAnonym" - "true") необходимо передать пустой параметр или UID физического лица РФ ("0xAB91FEEA04F6D4AD48DF42161B6C2E7A"). *Параметр является обязательным при создании контрагента |
name | Нет* | string | Наименование юридического лица или имя физического лица. *Параметр является обязательным при создании контрагента |
inn | Нет* | string | ИНН юридического лица. Параметр используется, только если контрагент является юридическим лицом. *Параметр является обязательным при создании контрагента - юридического лица, а также при смене ОПФ контрагента - физического лица на юридическое лицо |
juridicalAddress | Нет* | Address | Юридический адрес. Параметр используется, только если контрагент является юридическим лицом. *Параметр является обязательным при создании контрагента - юридического лица, а также при смене ОПФ контрагента - физического лица на юридическое лицо |
document | Нет* | Document | Данные документа, удостоверяющего личность. Параметр используется, только если контрагент является физическим лицом. *Параметр является обязательным при создании контрагента - физического лица, а также при смене ОПФ контрагента - юридического лица на физическое лицо |
dataForReceipt | Нет | DataForReceipt | Контактные данные для отправки электронного чека плательщику - физическому лицу. Параметр используется в запросе, только если контрагент является физическим лицом |
isAnonym | Нет* | boolean | Признак "анонимного" получателя. Доступные значения:
Значение по умолчанию: "false". *При создании "анонимного" получателя параметр является обязательным |
phone | Нет* | string | Номер телефона "анонимного" получателя в формате "7XXXXXXXXXX" (где X - любая цифра). Параметр используется только для "анонимного" получателя. *При создании "анонимного" получателя параметр является обязательным |
Нет | string | Адрес электронной почты "анонимного" получателя. Параметр используется только для "анонимного" получателя | |
counteragentID | Нет* | integer | ID контрагента, информацию о котором нужно отредактировать. *Параметр является обязательным при редактировании контрагента. При создании контрагента параметр не используется |
Address
Address | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
search | Нет (1) | string | Адрес в виде текста (2). При передаче адреса в виде текста, помимо собственно адреса, в запрос следует включать наименование населённого пункта, элементы необходимо указывать через запятую, например "Омск, Ленина, 5". Минимум 2 символа, максимум - 1024 |
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 символов |
Примечания:
|
Document
Document | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
type | Да | string | Тип документа. Доступные значения:
|
serial | Да* | string | Серия документа *Для некоторых стран параметр не является обязательным и игнорируется |
number | Да | string | Номер документа. Формат номера зависит от страны |
date | Нет | string | Дата выдачи документа в формате "ГГГГ-ММ-ДД" |
DataForReceipt
DataForReceipt | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
phone | Нет | string | Номер телефона для отправки чека в формате "+79XXXXXXXXX" (где X - любая цифра) |
Нет | string | Адрес электронной почты для отправки чека |
Ответ метода
Структура ответа
{ "metadata":{ "status":200, "generated_at":"2015-06-18 12:37:28" }, "data":{ "counteragentID":1, "state":"new", "foundAddresses":[ { "field":"juridicalAddress", "source":"Омск, Ленина, 5", "result":"Россия, Омская обл, г Омск, ул Ленина, д 5" } ] } }
<response> <metadata> <status>200</status> <generated_at>2015-06-18 12:37:28</generated_at> </metadata> <data> <counteragentID>1</counteragentID> <state>new</state> <foundAddresses> <field>juridicalAddress</field> <source>Омск, Ленина, 5</source> <result>Россия, Омская обл, г Омск, ул Ленина, д 5</result> </foundAddresses> </data> </response>
Описание параметров
Response
Response | ||
---|---|---|
Параметр | Тип | Описание |
metadata | object | Системная информация |
metadata.status | integer | Эмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK) |
metadata.generated_at | string | Дата и время генерации ответа сервера. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС" |
data | object | Информация об новом/отредактированном контрагенте |
data.counteragentID | integer | ID нового/отредактированного контрагента |
data.state | string | Статус контрагента. Возможные значения:
|
data.foundAddresses | array of FoundAddresses | Данные по найденным адресам. Параметр присутствует в ответе, только если в запросе был передан параметр "search" класса "Address" |
FoundAddresses
FoundAddresses | ||
---|---|---|
Параметр | Тип | Описание |
field | string | Объект, в котором был передан параметр "search" |
source | string | Введённое значение |
result | string | Найденный адрес |
Обработка ошибок
В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".
Поиск контрагентов
Запрос метода
Структура запроса
Адрес метода: https://api.dellin.ru/v2/book/counteragents/search.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "country":"0x8f51001438c4d49511dbd774581edb7a", "query":"итал", "juridical":true }
Адрес метода: https://api.dellin.ru/v2/book/counteragents/search.xml
<request> <appkey>00000000-0000-0000-0000-000000000000</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <country>0x8f51001438c4d49511dbd774581edb7a</country> <query>итал</query> <juridical>true</juridical> </request>
Описание параметров
Request
Request | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
appkey | Да | string | Ключ приложения. Для получения ключа необходимо пройти регистрацию |
sessionID | Нет | string | ID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя". Неавторизованным пользователям доступен поиск только по данным ЕГРЮЛ (1) и ЕГРИП (2), авторизованным пользователям также доступны данные адресной книги |
country | Нет | string | UID страны, см. метод "Поиск стран". Если параметр не передан, то будет осуществлён поиск контрагентов из РФ. Источником данных о контрагентах не из РФ является адресная книга, таким образом, поиск по контрагентам не из РФ доступен только авторизованным пользователям |
query | Да | string | Часть наименования контрагента, его ОПФ или ИНН. Минимум 1 символ, максимум 255 |
juridical | Нет | boolean | Тип контрагента:
Если параметр не передан в запросе, то в ответе будут представлены данные по юридическим лицам. В ответ метода не выводятся данные:
|
Примечания:
|
Ответ метода
Структура ответа
{ "metadata":{ "status":200, "generated_at":"2020-09-02 15:40:53" }, "data":[ { "inn":"7842463725", "kpp":"772701351", "name":"ИТАЛ РУССИЯ", "opfUid":"0x92ee03691f25a9fe4be9910cd87ca9ca", "opfName":"ООО", "state":"ACTIVE" }, { "inn":"7704139509", "kpp":"772701001", "name":"ИТАЛИНТОРГ", "opfUid":"0xbc1e63c5f81187e244490a5afd657cbd", "opfName":"НАО", "state":"ACTIVE" } ] }
<response> <metadata> <status>200</status> <generated_at>2020-09-02 15:40:53</generated_at> </metadata> <data> <inn>7842463725</inn> <kpp>772701351</kpp> <name>ИТАЛ РУССИЯ</name> <opfUid>0x92ee03691f25a9fe4be9910cd87ca9ca</opfUid> <opfName>ООО</opfName> <state>ACTIVE</state> </data> <data> <inn>7704139509</inn> <kpp>772701001</kpp> <name>ИТАЛИНТОРГ</name> <opfUid>0xbc1e63c5f81187e244490a5afd657cbd</opfUid> <opfName>НАО</opfName> <state>ACTIVE</state> </data> </response>
Описание параметров
Response
Response | ||
---|---|---|
Параметр | Тип | Описание |
metadata | object | Системная информация |
metadata.status | integer | Эмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK) |
metadata.generatedAt | string | Дата и время генерации ответа сервера. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС" |
data | array of Data | Список найденных контрагентов. Максимум 20 элементов массива |
data.inn | string | ИНН контрагента |
data.kpp | string | КПП (код причины постановки на учёт) контрагента |
data.name | string | Наименование/ФИО контрагента |
data.opfUid | string | UID ОПФ (см. метод "Поиск ОПФ") |
data.opfName | string | ОПФ |
data.state | string | Статус по данным федеральной налоговой службы. Возможные значения:
|
Обработка ошибок
В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".