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

API
Главная / API - Addresses

Addresses

Обновлено 20.01.2023
147 кб

General information

This service allows getting the list of counterparty addresses, adding and editing addresses in the list. The entries unused for 6 months are automatically removed from the address book.

Addresses list

Method request

Request structure

Method address: https://api.dellin.ru/v2/book/addresses.json

{
   "appkey":"00000000-0000-0000-0000-000000000000",
   "sessionID":"00000000-0000-0000-0000-000000000000",
   "counteragentID":1
}

Method address: 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>

Description of parameters

Request
Request
ParameterRequiredTypeDescription
appkeyYesstring

Application key. To get the key, register

sessionID

YesstringTo get the session ID, use the "User Authorization" method

counteragentID

Yesinteger

ID of counterparty for which the list of addresses is required

Method response

Response structure

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

Description of parameters

Response
Response
ParameterTypeDescription
metadataobjectSystem information
metadata.statusintegerEmulated status http-code. If successful, code 200 is returned
metadata.generatedAtstring

Server response date and time.

Format: YYYY-MM-DD HH:MM:SS

dataarray of Data

Information on counterparty addresses

Data
Data
ParameterTypeDescription
addressobjectInformation about the address
address.idintegerAddress ID
address.juridicalboolean

Address type.

Possible values:

  • "false" - delivery address;
  • "true" - legal address
address.cityIDstringCity ID, see "Places search" method
address.codestring

CLADR* code of the street if it exists in directory. Otherwise, CLADR code of the city

*CLADR - Classifier of Addresses of Russian Federation

address.addressstringTextual representation of address
address.streetstringStreet
address.housestring

House number, including the letter. For example, "13/A"

address.buildingstringBuilding
address.structurestringStructure
address.flatstringApartment/office, including the letter. For example, "222 A"
address.contactsintegerQuantity of contact persons for address
address.phonesintegerQuantity of contact phones for address
address.regionNamestringRegion
address.cityNamestringCity
address.cityCodestringCity CLADR code, see "Places search" method
address.terminalUIDstringTerminal UID, if address is not terminal address, then the parameter value is "null"
address.terminalIDinteger

Terminal ID (see "Terminals directory"), if address is not terminal address, then the parameter value is "null"

Error handling

The common API errors are used with the method, for errors format description and errors list see Errors of API methods.

Address address and editing

This method allows creating/editing only the delivery address. To add a legal address, use Counterparties adding and editing method

Method request

Request example (creating address)

Method address: 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а"
}

Method address: 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>

Request example (using company terminal ID to create an address)

It is possible to use company terminal ID to create an address. In this case address details will be added automatically. Terminal ID is available in the Terminals directory.

Method address: 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
}

Method address: 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>

Request example (editing an address)

In case of editing an address, the request is similar to the request for creating an address, but in this case it is enough to pass only those address parameters that need to be edited. However when updating one of the following parameters - "house", "building", "structure" or "flat" - it is necessary as well to pass those of the listed address parameters that does not need to be updated, otherwise the values passed before will be deleted

Method address: 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"
}

Method address: 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>

Description of parameters

Request
Request
ParameterRequiredTypeDescription
appkeyYesstringApplication key. To get the key, register

sessionID

YesstringTo get the session ID, use the "User Authorization" method

counteragentID

No*integer

ID of counterparty for which it is necessary to create an address.

*If creating an address, the parameter is required. If editing an address, the parameter is not used

search

No (1)string

Address as a string.

It is possible to pass address as text or as coordintaes.

When passing address as a text along with the address it is necessary to pass the name of the city, the address elements should be separated by comma, for example "Омск, Ленина, 5".

The coordinates should be separated by comma as well, the first number - latitude "59.924501, 30.241762".

Minimum 2 symbols, maximum 1024 (2)

streetNo (1)string

CLADR code of the street. It's possible to get CLADR code using the services listed on the page "CLADR search" (2)

houseNo (1)string

House number, including the letter. For example, "13/A" (2), (3).

Maximum 7 characters

buildingNostring

Building (2), (3).

Maximum 5 characters

structureNostring

Structure (2), (3).

Maximum 7 characters

flatNostring

Apartment/office, including the letter. For example, "222 A" (2), (3).

Maximum 5 characters

terminalIDNo (1)integer

Terminal ID from the "Terminals directory". If terminal ID is used to create an address, then the address details will be added automatically (2)

addressIDNo*integer

ID of address that needs to be edited.

*If editing an address the parameter is required. If creating an address the parameter is not used

Notes:

  1. If creating an address, information on the address must be passed in the request therefore one of the following is required "search" parameter/"street" and "house" parameters/"terminalID" parameter.
  2. If "search"/"terminalID" parameter is passed in the request, then "street", "house", "building" or "structure" parameters must not be passed in the request. If "search" and "flat" parameters are passed in the request together then the value of the "flat" parameter will be used as an apartment/office number.
  3. When updating one of the parameters - "house", "building", "structure" or "flat" - it is necessary as well to pass those address parameters that does not need to be updated. Otherwise the values passed before will be deleted

Method response

Response structure

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

Description of parameters

Response
Response
ParameterTypeDescription
metadataobjectSystem information
metadata.statusintegerEmulated status http-code. If successful, code 200 is returned
metadata.generatedAtstring

Server response date and time.

Format: YYYY-MM-DD HH:MM:SS

dataobjectInformation on created/edited addresses
data.statusstring

Address status. Possible values:

  • "existing" - the existing address has been edited;
  • "new" - a new address has been created
data.addressIDintegerID of the created/edited addresses
data.foundAddressesarray of FoundAddressesData on found addresses. The parameter is present in the response if "search" parameter was passed in the request

FoundAddresses
FoundAddresses
ParameterTypeDescription
sourcestring

Entered value

resultstring

Address found

Error handling

The common API errors are used with the method, for errors format description and errors list see Errors of API methods.