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

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

Counterparties

Обновлено 23.04.2020
148 кб

General information

Address book is a list of counterparties that can be used to process orders.

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 example

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 integer

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 example

{
   "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 Directory of legal forms of organization
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 from the Countries directory
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":{
      "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>
      <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,
   "form":"0x8F51001438C4D49511DBD774581EDB80"
}

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>
   <form>0x8F51001438C4D49511DBD774581EDB80</form>
</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 from the Directory of legal forms of organization.

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, the parameter is required

juridicalAddressNo*JuridicalAddress

Legal address. The parameter is used for legal entities only.

*If adding a new counterparty that is 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, 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

JuridicalAddress
JuridicalAddress
ParameterRequiredTypeDescription
streetYesstring

CLADR* code of the street. It's possible to get the value using services presented on the Using CLADR codes page.

*CLADR - Classifier of Addresses of Russian Federation

houseYesstringHouse House number, including the letter. For example, "13/A"
buildingNostringBuilding
structureNostringStructure
flatNostringApartment/office number. For example, "222 A"

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 example

{
   "metadata":{
      "status":200,
      "generated_at":"2015-06-18 12:37:28"
   },
   "data":{
      "counteragentID":1,
      "state":"new"
   }
}
<response>
   <metadata>
      <status>200</status>
      <generated_at>2015-06-18 12:37:28</generated_at>
   </metadata>
   <data>
      <counteragentID>1</counteragentID>
      <state>new</state>
   </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

Error handling

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