Counterparties
General information
Address book is a list of counterparties that can be used to process orders. The entries unused for 6 months are automatically removed from the address book.
Address book and list of available counterparties are different concepts. Counterparties from the address book can be used for orders processing only, detailed information about them is unavailable.
Counterparties list from address book
Method request
Request structure
Method address: 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 ] }
Method address: 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>
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 |
withAnonym | No | boolean | Flag for getting the list of counterparties with/without "anonymous" receivers (1). Possible values:
Default value: "false" |
isAnonym | No | boolean | Flag for getting the list of counterparties including only "anonymous" receivers (1). Possible values:
Default value: "false" If the request contains parameters "withAnonym" = "false" and "isAnonym" = "true" then response contains the list of only "anonymous" receivers |
counteragentIds | No | array of integers | The list of IDs of counterparties on which information is required. If the parameter is not passed in the request, the response will contain the full list of counterparties |
Notes:
|
Method response
Response structure
{ "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>
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 | Counterparties data |
Data
Data | ||
---|---|---|
Parameter | Type | Description |
id | integer | Counterparty ID |
isAnonym | string | "Anonymous" receiver (1) indicator. Possible values:
|
form | string | Legal form of organization of the counterparty |
formUID | string | UID of legal form of organization, see "Search of forms of organization" method |
name | string | Counterparty name. Full name for "anonymous" receiver (1) |
phone | string | Phone number of "anonymous" receiver (1). If counterparty is not an "anonymous" receiver (response parameter "data.isAnonym" value is "false"), then the parameter value is "null" |
string | Email of "anonymous" receiver (1). If counterparty is not an "anonymous" receiver (response parameter "data.isAnonym" value is "false"), then the parameter value is "null" | |
juridical | boolean | Counterparty type:
|
addresses | integer | Quantity of delivery addresses of the counterparty |
inn | string | Counterparty TIN (taxpayer identification number). If counterparty is an individual (response parameter "data.juridical" value is "false"), then the parameter value is "null" |
document | object | Identification document data. If counterparty is a legal entity (response parameter "data.juridical" value is "true") or the receiver is "anonymous" (response parameter "data.isAnonym" value is "true"), then the parameter value is "null" |
document.type | string | Document type. Possible values:
|
document.serial | string | Document series |
document.number | string | Document number. Number format may vary depending on the country |
document.date | string | Document issue date. Format: YYYY-MM-DD |
lastUpdate | string | Date of the last update of information about the current counterparty. Format: YYYY-MM-DD HH:MM:SS |
countryUid | string | Country UID, see "Countries search" |
uid | string | Counterparty UID |
dataForReceipt | object | Contact information to send an electronic payment receipt to the payer that is an individual (response parameter "data.juridical" value is "false") and is not an "anonymous" receiver (response parameter "data.isAnonym" value is "false") |
dataForReceipt.phoneNumber | string | Phone number to send the payment receipt |
dataForReceipt.email | string | Email to send the payment receipt |
Notes:
|
Error handling
The common API errors are used with the method, for errors format description and errors list see Errors of API methods.
Counterparties adding and editing
This method allows adding new counterparties to the address book and editing information about them. Method request depends on type of the counterparty (an individual or a legal entity).
Method request
Request example: adding counterparty (legal entity)
Method address: 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" } }
Method address: 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>
Request example: adding counterparty (individual)
Method address: 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" } }
Method address: 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>
Request example: adding counterparty ("anonymous" receiver)
Method address: 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" }
Method address: 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>
Request example: editing counterparty info
To update the info of the counterparty that is not an "anonymous" receiver it is necessary pass counterparty ID and the data that need to be updated in the request.
Method address: 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" } }
Method address: 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>
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 |
form | No* | string | UID of legal form of organization, see "Search of forms of organization" method. When passing data about the "anonymous" receiver ("isAnonym" parameter value is "true") it is necessary to pass either empty parameter or UID of individual in Russian Federation ("0xAB91FEEA04F6D4AD48DF42161B6C2E7A"). *If adding a new counterparty, the parameter is required |
name | No* | string | Individual or company name. *If adding a new counterparty, the parameter is required |
inn | No* | string | TIN (taxpayer identification number). The parameter is used for legal entities only. Allowed number of characters may vary depending on country and legal form of organization *If adding a new counterparty that is a legal entity or changing the counterparty legal form from an individual to a legal entity, the parameter is required |
juridicalAddress | No* | Address | Legal address. The parameter is used for legal entities only. *If adding a new counterparty that is a legal entity or changing the counterparty legal form from an individual to a legal entity, the parameter is required |
document | No* | Document | Personal ID data. The parameter is used only for individuals. *If adding a new counterparty that is an individual or changing the counterparty legal form from a legal entity to an individual, the parameter is required |
dataForReceipt | No | DataForReceipt | Contact data to send the payment receipt to the individual. The parameter is used for individuals only |
isAnonym | No* | boolean | Flag indicating that the counterparty is an "anonymous" receiver. Possible values:
Default value is "false". *If adding a new "anonymous" receiver, the parameter is required |
phone | No* | string | "Anonymous" receiver phone, required format: "7XXXXXXXXXX" (where X is any digit). The parameter is used only for "anonymous" receivers. *The parameter is required when adding a new "anonymous" receiver |
No | string | "Anonymous" receiver email. The parameter is used only for "anonymous" receivers | |
counteragentID | No* | integer | ID of the counterparty that needs to be edited. *The parameter is required only when editing a counterparty. When adding a new counterparty the parameter is not used |
Address
Address | |||
---|---|---|---|
Parameter | Required | Type | Description |
search | No (1) | string | Address as a string (2). It is possible to pass address as text. 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". Minimum 2 symbols, maximum 1024 |
street | No (1) | string | CLADR* code of the street. It's possible to get the value using services presented on the "CLADR search" page (2). *CLADR - Classifier of Addresses of Russian Federation |
house | No (1) | string | House 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 number. For example, "222 A" (2), (3). Maximum 5 characters |
Notes:
|
Document
Document | |||
---|---|---|---|
Parameter | Required | Type | Description |
type | Yes | string | Document type. Possible values:
|
serial | Yes* | string | Document series *For some countries the parameter is not required and therefore ignored |
number | Yes | string | Document number. Number format may vary depending on the country |
date | No | string | Document issue date (Format: "YYYY-MM-DD") |
DataForReceipt
DataForReceipt | |||
---|---|---|---|
Parameter | Required | Type | Description |
phone | No | string | Phone number for sending the payment receipt, required format: "+79XXXXXXXXX" (where X is any digit) |
No | string | Email address for sending the payment receipt |
Method response
Response structure
{ "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>
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.generated_at | string | Server response date and time. Format: YYYY-MM-DD HH:MM:SS |
data | object | New/updated counterparty info |
data.counteragentID | integer | New/updated counterparty ID |
data.state | string | Counterparty status. Possible Values
|
data.foundAddresses | array of FoundAddresses | Data on found addresses. The parameter is present in the response if "search" parameter of Address class of was passed in the request |
FoundAddresses
FoundAddresses | ||
---|---|---|
Parameter | Type | Description |
field | string | The parent object that was used to pass the "search" parameter |
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.
Counterparties search
Method request
Request structure
Method address: https://api.dellin.ru/v2/book/counteragent/search.json
{ "appkey":"00000000-0000-0000-0000-000000000000", "sessionID":"00000000-0000-0000-0000-000000000000", "country":"0x8f51001438c4d49511dbd774581edb7a", "query":"итал", "juridical":true }
Method address: https://api.dellin.ru/v2/book/counteragent/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>
Description of parameters
Request
Request | |||
---|---|---|---|
Parameter | Required | Type | Description |
appkey | Yes | string | Application key. To get the key, register |
sessionID | No | string | To get the session ID, use the "User Authorization" method. If the user is not authorized, USRLE (1) and USRIE (2) data is used, if the users is authorized address book data is used as well |
country | No | string | Country UID, see "Countries search" method. If the parameter is not passed in the request, the response will contain only the data of the counterparties not from the Russian Federation. The source of data on counterparties not from the Russian Federation is the address book, thus, the search for counterparties not from the Russian Federation is available only to authorized users |
query | Yes | string | Part of the counterparty name, legal form of organization or TIN (taxpayer identification number). Minimum 1 symbol, maximum 255 |
juridical | No | boolean | Counterparty type:
If the parameter is not passed in the request, the response will contain the legal entities data. The response does not contain data:
|
Notes:
|
Method response
Response structure
{ "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>
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 | List of counterparties found. Maximum 20 elements in the array |
data.inn | string | Counterparty TIN (taxpayer identification number) |
data.kpp | string | Counterparty tax resgistration event code |
data.name | string | Company/individual name |
data.opfUid | string | UID of legal form of organization, see "Search of forms of organization" method |
data.opfName | string | Legal form of organization of the counterparty |
data.state | string | Status in accordance with Federal Tax Service of Russia. Possible values:
|
Error handling
The common API errors are used with the method, for errors format description and errors list see Errors of API methods.