Поиск по сайту

API
Главная / API - Контрагенты

Контрагенты

Обновлено 10.09.2020
204 кб

Общие сведения

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

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

Список контрагентов из адресной книги

Запрос метода

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

Адрес метода: 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ДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"
withAnonymНетboolean

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

Доступные значения:

  • "true" - ответ должен включать "анонимных" получателей;
  • "false" - ответ не должен включать "анонимных" получателей.

Значение по умолчанию: "false"

isAnonymНетboolean

Признак запроса списка контрагентов, включающего только "анонимных" получателей (1). 

Доступные значения:

  • "true" - ответ должен включать только "анонимных" получателей;
  • "false" - ответ должен включать не только "анонимных" получателей.

Значение по умолчанию: "false"

Если в запросе передан параметр "withAnonym" со значением "false" и параметр "isAnonym" со значением "true", то ответ будет содержать список контрагентов, включающий только "анонимных" получателей
counteragentIdsНетarray of integer

Список ID контрагентов, по которым необходима информация.

Если параметр не передан в запросе, то в ответе будет получен полный список контрагентов

Примечания:

  1. "Анонимный" получатель - получатель, о котором предоставлен минимум информации (см. описание услуги "Упрощённая отправка груза" на сайте компании "Деловые Линии")

Ответ метода

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

{
   "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>
   <metadata>
      <status>200</status>
      <generated_at>2015-06-18 12:37:28</generated_at>
   </metadata>
   <data>
      <id>1</id>
      <isAnonym>false</isAnonym>
      <form>ООО</form>
      <formUID>0x92EE03691F25A9FE4BE9910CD87CA9CA</formUID>
      <name>Ромашка</name>
      <phone />
      <email />
      <juridical>true</juridical>
      <addresses>3</addresses>
      <inn>1234567890</inn>
      <document />
      <lastUpdate>2015-07-04 02:27:15</lastUpdate>
      <countryUid>0x8f51001438c4d49511dbd774581edb7a</countryUid>
      <uid>00000000-0000-0000-0000-000000000000</uid>
      <dataForReceipt>
         <phoneNumber />
         <email />
      </dataForReceipt>
   </data>
   <data>
      <id>2</id>
      <isAnonym>true</isAnonym>
      <form>Ч/Л</form>
      <formUID>0xAB91FEEA04F6D4AD48DF42161B6C2E7A</formUID>
      <name>Петрович</name>
      <phone>+7 (900) 000-00-00</phone>
      <email>petro@mail.com</email>
      <juridical>false</juridical>
      <addresses>1</addresses>
      <inn />
      <document />
      <lastUpdate>2015-07-04 02:27:15</lastUpdate>
      <countryUid>0x8f51001438c4d49511dbd774581edb7a</countryUid>
      <uid>00000000-0000-0000-0000-000000000000</uid>
      <dataForReceipt>
         <phoneNumber />
         <email />
      </dataForReceipt>
   </data>
   <data>
      <id>3</id>
      <isAnonym>false</isAnonym>
      <form>Ч/Л</form>
      <formUID>0x8F51001438C4D49511DBD774581EDB80</formUID>
      <name>Иванов Иван Иванович</name>
      <phone />
      <email />
      <juridical>false</juridical>
      <addresses>1</addresses>
      <inn />
      <document>
         <type>passport</type>
         <serial>0000</serial>
         <number>000000</number>
         <date>2014-01-23</date>
      </document>
      <lastUpdate>2015-07-04 02:27:15</lastUpdate>
      <countryUid>0x8f51001438c4d49511dbd774581edb7a</countryUid>
      <uid>00000000-0000-0000-0000-000000000000</uid>
      <dataForReceipt>
         <phoneNumber>+79ХХХХХХХХХ</phoneNumber>
         <email>meow@mail.ru</email>
      </dataForReceipt>
   </data>
</response>

Описание параметров

Response
Response
ПараметрТипОписание

metadata

objectСистемная информация
metadata.statusintegerЭмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK)
metadata.generatedAtstring

Дата и время генерации ответа сервера.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

dataDataСведения о контрагентах

Data
Data
ПараметрТипОписание
idintegerID контрагента
isAnonymstring

Признак "анонимного" получателя (1).

Возможные значения:

  • "true" – "анонимный" получатель;
  • "false" – не "анонимный" получатель
formstringОрганизационно-правовая форма контрагента (далее - ОПФ)
formUIDstringUID ОПФ. Заполняется на основании "Справочника ОПФ"
namestringНаименование контрагента (для "анонимного" получателя (1) - имя)
phonestringНомер телефона "анонимного" получателя (1) . Если контрагент не является "анонимным" получателем (значение параметра ответа "data.isAnonym" - "false"), то значение параметра - "null"
emailstringАдрес электронной почты "анонимного" получателя (1) . Если контрагент не является "анонимным" получателем (значение параметра ответа "data.isAnonym" - "false"), то значение параметра - "null"
juridicalboolean

Тип контрагента:

  • "true" - юридическое лицо;
  • "false" - физическое лицо
addressesintegerКоличество адресов доставки контрагента
innstringИНН контрагента. Если контрагент - физическое лицо (значение параметра ответа "data.juridical" - "false"), то значение параметра - "null". Максимальная допустимая длина поля зависит от страны и ОПФ
documentobjectДанные документа, удостоверяющего личность. Если контрагент - юридическое лицо (значение параметра ответа "data.juridical" - "true") или "анонимный" получатель (значение параметра ответа "data.isAnonym" - "true"), то значение параметра - "null"
document.typestring

Тип документа.

Доступные значения:

  • "passport" - паспорт;
  • "drivingLicence" - водительское удостоверение;
  • "foreignPassport" - заграничный паспорт
document.serialstringСерия документа
document.numberstringНомер документа. Формат номера зависит от страны
document.datestring

Дата выдачи документа в формате "ГГГГ-ММ-ДД"

Формат: "ГГГГ-ММ-ДД"

lastUpdatestring

Дата последнего обновления информации о данном контрагенте.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

countryUidstringUID страны из "Справочника стран"
uidstring

UID контрагента

dataForReceiptobject

Контактные данные для отправки электронного чека плательщику-физическому лицу (значение параметра ответа "data.juridical" - "false"), не являющемуся "анонимным" получателем (значение параметра ответа "data.isAnonym" - "false")

dataForReceipt.phoneNumberstring

Номер телефона для отправки чека

dataForReceipt.emailstringАдрес электронной почты для отправки чека

Примечания:

  1. "Анонимный" получатель - получатель, о котором предоставлен минимум информации (см. описание услуги "Упрощённая отправка груза" на сайте компании "Деловые Линии")

Обработка ошибок

В методе используются общие ошибки 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,
   "form":"0x8F51001438C4D49511DBD774581EDB80"
}

Адрес метода: 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>
   <form>0x8F51001438C4D49511DBD774581EDB80</form>
</request>

Описание параметров

Request
Request
ПараметрОбязательныйТипОписание
appkeyДаstringКлюч приложения. Для получения ключа необходимо пройти регистрацию
sessionIDДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"
formНет*string

UID ОПФ. Заполняется на основании "Справочника ОПФ".

При передаче данных об "анонимном" получателе (значение параметра "isAnonym" - "true") необходимо передать пустой параметр или UID физического лица РФ ("0xAB91FEEA04F6D4AD48DF42161B6C2E7A").

*Параметр является обязательным при создании контрагента

nameНет*string

Наименование юридического лица или имя физического лица.

*Параметр является обязательным при создании контрагента

innНет*string

ИНН юридического лица. Параметр используется, только если контрагент является юридическим лицом.

*При создании контрагента-юридического лица параметр является обязательным

juridicalAddressНет*JuridicalAddress

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

*При создании контрагента-юридического лица параметр является обязательным

document

Нет*Document

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

*При создании контрагента-физического лица параметр является обязательным

dataForReceiptНетDataForReceipt

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

isAnonym

Нет*boolean

Признак "анонимного" получателя.

Доступные значения:

  • "true" - контрагент является "анонимным" получателем;
  • "false" - контрагент не является "анонимным" получателем.

Значение по умолчанию: "false".

*При создании "анонимного" получателя параметр является обязательным

phoneНет*string

Номер телефона "анонимного" получателя в формате "7XXXXXXXXXX" (где X - любая цифра). Параметр используется только для "анонимного" получателя.

*При создании "анонимного" получателя параметр является обязательным

email

Нетstring

Адрес электронной почты "анонимного" получателя. Параметр используется только для "анонимного" получателя

counteragentIDНет*integer

ID контрагента, информацию о котором нужно отредактировать.

*Параметр является обязательным при редактировании контрагента. При создании контрагента параметр не используется

JuridicalAddress
JuridicalAddress
ПараметрОбязательныйТипОписание

search

Нет (1)stringАдрес в виде произвольной строки. Минимум 2 символа, максимум - 1024 (2)
streetНет (1)string

Код КЛАДР улицы. Может быть получен с помощью сервисов, представленных на странице "Использование кодов КЛАДР" (2)

houseНет (1)stringНомер дома, включая литеру. Например, "13/А" (2)
buildingНетstringКорпус (2)
structureНетstringСтроение (2)
flatНетstringНомер квартиры/офиса. Допускается написание с буквой, например "222 А" (2)

Примечания:

  1. Обязательно должен быть передан адрес - в виде произвольной строки ("search") или набора параметров (в этом случае обязательными являются параметры "street" и "house"). 
  2. Передача параметра "search" исключает передачу параметров "street", "house", "building", "structure" и "flat"

Document
Document
ПараметрОбязательныйТипОписание
typeДаstring

Тип документа.

Доступные значения:

  • "passport" - паспорт;
  • "drivingLicence" - водительское удостоверение;
  • "foreignPassport" - заграничный паспорт. Для некоторых стран значение "foreignPassport" недоступно
serialДа*string

Серия документа

*Для некоторых стран параметр не является обязательным и игнорируется

numberДаstringНомер документа. Формат номера зависит от страны
dateНетstringДата выдачи документа в формате "ГГГГ-ММ-ДД"

DataForReceipt
DataForReceipt
ПараметрОбязательныйТипОписание
phoneНетstring

Номер телефона для отправки чека в формате "+79XXXXXXXXX" (где X - любая цифра)

emailНет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
ПараметрТипОписание
metadataobjectСистемная информация
metadata.statusintegerЭмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK)
metadata.generated_atstring

Дата и время генерации ответа сервера.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

dataobjectИнформация об новом/отредактированном контрагенте
data.counteragentIDintegerID нового/отредактированного контрагента
data.statestring

Статус контрагента. Возможные значения:

  • "existing" - отредактированы данные существующего контрагента;
  • "new" - создан новый контрагент
data.foundAddressesarray of FoundAddressesДанные по найденным адресам. Параметр присутствует в ответе, только если в запросе был передан параметр "search"

FoundAddresses
FoundAddresses
ПараметрТипОписание
fieldstringОбъект, в котором был передан параметр "search"
sourcestring

Введённое значение

resultstring

Найденный адрес

Обработка ошибок

В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".