Addresses
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 | |||
---|---|---|---|
Parameter | Required | Type | Description |
appkey | Yes | string | Application key. To get the key, register |
sessionID | Yes | string | To get the session ID, use the "User Authorization" method |
counteragentID | Yes | integer | 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 | ||
---|---|---|
Parameter | Type | Description |
metadata | object | System information |
metadata.status | integer | Emulated status http-code. If successful, code 200 is returned |
metadata.generatedAt | string | Server response date and time. Format: YYYY-MM-DD HH:MM:SS |
data | array of Data | Information on counterparty addresses |
Data
Data | ||
---|---|---|
Parameter | Type | Description |
address | object | Information about the address |
address.id | integer | Address ID |
address.juridical | boolean | Address type. Possible values:
|
address.cityID | string | City ID, see "Places search" method |
address.code | string | CLADR* code of the street if it exists in directory. Otherwise, CLADR code of the city *CLADR - Classifier of Addresses of Russian Federation |
address.address | string | Textual representation of address |
address.street | string | Street |
address.house | string | House number, including the letter. For example, "13/A" |
address.building | string | Building |
address.structure | string | Structure |
address.flat | string | Apartment/office, including the letter. For example, "222 A" |
address.contacts | integer | Quantity of contact persons for address |
address.phones | integer | Quantity of contact phones for address |
address.regionName | string | Region |
address.cityName | string | City |
address.cityCode | string | City CLADR code, see "Places search" method |
address.terminalUID | string | Terminal UID, if address is not terminal address, then the parameter value is "null" |
address.terminalID | integer | 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
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 | |||
---|---|---|---|
Parameter | Required | Type | Description |
appkey | Yes | string | Application key. To get the key, register |
sessionID | Yes | string | To 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) |
street | No (1) | string | CLADR code of the street. It's possible to get CLADR code using the services listed on the page "CLADR search" (2) |
house | No (1) | string | House number, including the letter. For example, "13/A" (2), (3). Maximum 7 characters |
building | No | string | Building (2), (3). Maximum 5 characters |
structure | No | string | Structure (2), (3). Maximum 7 characters |
flat | No | string | Apartment/office, including the letter. For example, "222 A" (2), (3). Maximum 5 characters |
terminalID | No (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) |
addressID | No* | 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:
|
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 | ||
---|---|---|
Parameter | Type | Description |
metadata | object | System information |
metadata.status | integer | Emulated status http-code. If successful, code 200 is returned |
metadata.generatedAt | string | Server response date and time. Format: YYYY-MM-DD HH:MM:SS |
data | object | Information on created/edited addresses |
data.status | string | Address status. Possible values:
|
data.addressID | integer | ID of the created/edited addresses |
data.foundAddresses | array of FoundAddresses | Data on found addresses. The parameter is present in the response if "search" parameter was passed in the request |
FoundAddresses
FoundAddresses | ||
---|---|---|
Parameter | Type | Description |
source | string | Entered value |
result | string | 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.