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

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

Counterparties

Обновлено 09.02.2023
223 кб

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
ParameterRequiredTypeDescription
appkeyYesstring

Application key. To get the key, register

sessionID

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

Flag for getting the list of counterparties with/without "anonymous" receivers (1).

Possible values:

  • "true" - the response must include "anonymous" receivers;
  • "false" - the response must exclude "anonymous" receivers.

Default value: "false"

isAnonymNoboolean

Flag for getting the list of counterparties including only "anonymous" receivers (1).

Possible values:

  • "true" - the response must include only "anonymous" receivers;
  • "false" - the response must include "anonymous" receivers and regular receivers. 

Default value: "false"

If the request contains parameters "withAnonym" = "false" and "isAnonym" = "true" then response contains the list of only "anonymous" receivers
counteragentIdsNoarray 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:

  1. Receivers on which minimum information (only name and phone number) is available

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

Counterparties data

Data
Data
ParameterTypeDescription
idintegerCounterparty ID
isAnonymstring

"Anonymous" receiver (1) indicator.

Possible values:

  • "true" - an "anonymous" receiver;
  • "false" - not an "anonymous" receiver
formstringLegal form of organization of the counterparty
formUIDstringUID of legal form of organization, see "Search of forms of organization" method
namestringCounterparty name. Full name for "anonymous" receiver (1)
phonestringPhone 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"
emailstringEmail of "anonymous" receiver (1). If counterparty is not an "anonymous" receiver (response parameter "data.isAnonym" value is "false"), then the parameter value is "null"
juridicalboolean

Counterparty type:

  • "true" - legal entity;
  • "false" - individual
addressesintegerQuantity of delivery addresses of the counterparty
innstringCounterparty TIN (taxpayer identification number). If counterparty is an individual (response parameter "data.juridical" value is "false"), then the parameter value is "null"
documentobjectIdentification 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.typestring

Document type.

Possible values:

  • "passport";
  • "drivingLicence";
  • "foreignPassport" - international passport
document.serialstringDocument series
document.numberstringDocument number. Number format may vary depending on the country
document.datestring

Document issue date.

Format: YYYY-MM-DD

lastUpdatestring

Date of the last update of information about the current counterparty.

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

countryUidstringCountry UID, see "Countries search"
uidstring

Counterparty UID

dataForReceiptobject

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.phoneNumberstring

Phone number to send the payment receipt

dataForReceipt.emailstringEmail to send the payment receipt

Notes:

  1. "Anonymous" receiver - a receiver on whom minimum info was provided.

    Delovye Linii company allows providing minimum information on the receiver - only name and phone number. In this case SMS with a code is sent to the phone number. The code is used to receive the goods. For more information see the description of Simplified Shipping service on Delovye Linii company website

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)

"Anonymous" receiver - a receiver on whom minimum info was provided.Delovye Linii company allows providing minimum information on the receiver - only name and phone number. In this case SMS with a code is sent to the phone number. The code is used to receive the goods. For more information see the description of Simplified Shipping service on Delovye Linii company website

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.

It is not possible to update "anonymous" receiver data

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
ParameterRequiredTypeDescription
appkeyYesstring

Application key. To get the key, register

sessionID

YesstringTo get the session ID, use the "User Authorization" method
formNo*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

nameNo*string

Individual or company name.

*If adding a new counterparty, the parameter is required

innNo*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

juridicalAddressNo*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

documentNo*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

dataForReceiptNoDataForReceiptContact data to send the payment receipt to the individual. The parameter is used for individuals only
isAnonymNo*boolean

Flag indicating that the counterparty is an "anonymous" receiver.

Possible values:

  • "true" - counterparty is an "anonymous" receiver;
  • "false" - counterparty is not an "anonymous" receiver.

Default value is "false".

*If adding a new "anonymous" receiver, the parameter is required

phoneNo*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

emailNostring

"Anonymous" receiver email. The parameter is used only for "anonymous" receivers

counteragentIDNo*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
ParameterRequiredTypeDescription

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

streetNo (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

houseNo (1)string

House 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 number. For example, "222 A" (2), (3).

Maximum 5 characters

Notes:

  1. Address information must be passed in the request therefore either "search" parameter is required or "street" and "house" parameters are required.
  2. If "search" parameter is passed in the request, then "street", "house", "building" and "structure" parameters must not be passed, but "flat" parameter may be passed (in this case 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

Document
Document
ParameterRequiredTypeDescription
typeYesstring

Document type.

Possible values:

  • "passport";
  • "drivingLicence";
  • "foreignPassport" - international passport. For some countries "foreignPassport" value is not available
serialYes*string

Document series

*For some countries the parameter is not required and therefore ignored

numberYesstringDocument number. Number format may vary depending on the country
dateNostringDocument issue date  (Format: "YYYY-MM-DD")

DataForReceipt
DataForReceipt
ParameterRequiredTypeDescription
phoneNostring

Phone number for sending the payment receipt, required format: "+79XXXXXXXXX" (where X is any digit)

emailNostringEmail 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
ParameterTypeDescription
metadataobjectSystem information
metadata.statusintegerEmulated status http-code. If successful, code 200 is returned
metadata.generated_atstring

Server response date and time.

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

dataobjectNew/updated counterparty info
data.counteragentIDintegerNew/updated counterparty ID
data.statestring

Counterparty status. Possible Values

  • "existing" - the existing counterparty info has been edited;
  • "new" - a new counterparty has been added
data.foundAddressesarray of FoundAddressesData on found addresses. The parameter is present in the response if "search" parameter of Address class of was passed in the request

FoundAddresses
FoundAddresses
ParameterTypeDescription
fieldstringThe parent object that was used to pass the "search" parameter
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.

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
ParameterRequiredTypeDescription
appkeyYesstring

Application key. To get the key, register

sessionID

Nostring

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

countryNostring

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

queryYesstring

Part of the counterparty name, legal form of organization or TIN (taxpayer identification number). Minimum 1 symbol, maximum 255

juridicalNoboolean

Counterparty type:

  • "true" - legal entity;
  • "false" - individual.

If the parameter is not passed in the request, the response will contain the legal entities data.

The response does not contain data:

  • about legal entities from the address book that are not in the USRLE (1) and for which there are no waybills and orders;
  • about individuals from the address book for which there are no waybills and orders

Notes:

  1. USRLE - Unified State Register of Legal Entities.
  2. USRIE - Unified State Register of Individual Entrepreneurs

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
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 DataList of counterparties found. Maximum 20 elements in the array
data.innstringCounterparty TIN (taxpayer identification number)
data.kppstringCounterparty tax resgistration event code
data.namestringCompany/individual name
data.opfUidstring

UID of legal form of organization, see "Search of forms of organization" method

data.opfNamestringLegal form of organization of the counterparty
data.statestring

Status in accordance with Federal Tax Service of Russia.

Possible values:

  • "ACTIVE";  
  • "LIQUIDATING" - is being liquidated; 
  • "LIQUIDATED";  
  • "REORGANIZING" - is being merged by another company in order to be liquidated

Error handling

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