Creating and changing point of sale licenses

Description

POST /campaigns/{campaignId}/outlets/licenses

Sends information about new and existing point of sale licenses.

Only retail licenses for alcoholic beverages are supported. To place alcohol products in Yandex.Market, you need to send a letter of guarantee (if you didn't do this before) and place the offers in the price list according to the rules. For more information, see How to list alcoholic beverages in Yandex.MarketRU in Yandex.Market Help for stores.

The license information is checked.

Resource URL:

https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/outlets/licenses.[format]

Input data

Parameter

Type

Value

Required

campaignId

Int64

Campaign ID.

To find out the ID, log in to your personal account, click the store name in the top row, and copy the number after the hyphen from the Кампания № (“Campaign No.”) column. For example, if the column contains the value “11-213856”, the campaign ID is 213856.

Parameter

Type

Value

Required

campaignId

Int64

Campaign ID.

To find out the ID, log in to your personal account, click the store name in the top row, and copy the number after the hyphen from the Кампания № (“Campaign No.”) column. For example, if the column contains the value “11-213856”, the campaign ID is 213856.

Structure of POST request body:

<licenses>
  <license id="{int64}" outlet-id="{int64}" license-type="{enum}" number="{string}"
           date-of-issue="{date}" date-of-expiry="{date}"/>
  ...
</licenses>

Parameters of POST request body:

Parameter for XML format

Parameter for JSON format

Type

Value

licenses licenses

List of licenses.

Required parameter. Must contain information about at least one license.

Parameters nested in licenses

license

License information.

Required parameter, specified only for XML format.

Parameters nested in license / licenses

id id Int64

License ID.

This parameter is specified only if you need to change information about an existing license. Use the GET /campaigns/{campaignId}/outlets/licenses request to find the license ID. When sending information about a new license, you don't need to specify the ID.

The license ID is assigned by Yandex.Market. Don't confuse it with the number specified in the license: it is passed in the number parameter.

For XML format, it is an attribute of the license parameter.

outlet-id outletId Int64

ID of the point of sale that the license is valid for.

Required parameter.

For XML format, it is an attribute of the license parameter.

license-type licenseType Enum

License type:

  • ALCOHOL — The retail license for alcoholic beverages.

Required parameter.

For XML format, it is an attribute of the license parameter.

number number String

License number.

Required parameter.

Can't be an empty string.

For XML format, it is an attribute of the license parameter.

date-of-issue dateOfIssue Date

The license date of issue.

Date format: ISO 8601 with a UTC offset. You need to pass the date specified in the license, as well as the 00:00:00 time and the time zone of the point of sale region. For example, if the license for a point of sale in Moscow was issued on November 13, 2017, the parameter should have the value 2017-11-13T00:00:00+03:00.

Required parameter.

Can't be later than the expiration date specified in the date-of-expiry parameter.

For XML format, it is an attribute of the license parameter.

date-of-expiry dateOfExpiry Date

The license expiration date.

Date format: ISO 8601 with a UTC offset. You need to pass the date specified in the license, as well as the 00:00:00 time and the time zone of the point of sale region. For example, if the license for a point of sale in Moscow ends on November 20, 2022, the parameter should have the value 2022-11-20T00:00:00+03:00.

Required parameter.

Can't be earlier than the issue date specified in the date-of-issue parameter.

For XML format, it is an attribute of the license parameter.

Parameter for XML format

Parameter for JSON format

Type

Value

licenses licenses

List of licenses.

Required parameter. Must contain information about at least one license.

Parameters nested in licenses

license

License information.

Required parameter, specified only for XML format.

Parameters nested in license / licenses

id id Int64

License ID.

This parameter is specified only if you need to change information about an existing license. Use the GET /campaigns/{campaignId}/outlets/licenses request to find the license ID. When sending information about a new license, you don't need to specify the ID.

The license ID is assigned by Yandex.Market. Don't confuse it with the number specified in the license: it is passed in the number parameter.

For XML format, it is an attribute of the license parameter.

outlet-id outletId Int64

ID of the point of sale that the license is valid for.

Required parameter.

For XML format, it is an attribute of the license parameter.

license-type licenseType Enum

License type:

  • ALCOHOL — The retail license for alcoholic beverages.

Required parameter.

For XML format, it is an attribute of the license parameter.

number number String

License number.

Required parameter.

Can't be an empty string.

For XML format, it is an attribute of the license parameter.

date-of-issue dateOfIssue Date

The license date of issue.

Date format: ISO 8601 with a UTC offset. You need to pass the date specified in the license, as well as the 00:00:00 time and the time zone of the point of sale region. For example, if the license for a point of sale in Moscow was issued on November 13, 2017, the parameter should have the value 2017-11-13T00:00:00+03:00.

Required parameter.

Can't be later than the expiration date specified in the date-of-expiry parameter.

For XML format, it is an attribute of the license parameter.

date-of-expiry dateOfExpiry Date

The license expiration date.

Date format: ISO 8601 with a UTC offset. You need to pass the date specified in the license, as well as the 00:00:00 time and the time zone of the point of sale region. For example, if the license for a point of sale in Moscow ends on November 20, 2022, the parameter should have the value 2022-11-20T00:00:00+03:00.

Required parameter.

Can't be earlier than the issue date specified in the date-of-issue parameter.

For XML format, it is an attribute of the license parameter.

Output data

The output data structure is shown below. The order of parameters is not guaranteed.

<response>
  <status>{enum}</status>
  <errors>
    <error code="{enum}" message="{string}"/>
    ...
  </errors>
</response>

Parameter description:

Parameter for XML format

Parameter for JSON format

Type

Value

response

Response.

This parameter is returned only for XML format.

Parameters nested in response

status status Enum

Request execution status.

Possible values:

  • OK — The request is successfully completed, all licenses are sent for verification.

  • ERROR — An error was found in information for at least one license, none of the licenses were sent for verification.

errors errors

List of errors.

Returned in case status="ERROR".

Parameters nested in errors

error

Information about the error.

This parameter is returned only for XML format.

Parameters nested in error / errors

code code Enum

Error code:

  • CONSTRAINT_VIOLATION — The license number, date of issue or date of expiry is specified incorrectly.
  • ITEM_DUPLICATE — The point of sale already has a license of the specified type.

  • MISSING_PARAM — The request doesn't provide information about any licenses.
  • NOT_FOUND — The license or point of sale with the specified ID wasn't found.

For XML format, it is an attribute of the error parameter.

message message String

Description of the error.

For XML format, it is an attribute of the error parameter.

Parameter for XML format

Parameter for JSON format

Type

Value

response

Response.

This parameter is returned only for XML format.

Parameters nested in response

status status Enum

Request execution status.

Possible values:

  • OK — The request is successfully completed, all licenses are sent for verification.

  • ERROR — An error was found in information for at least one license, none of the licenses were sent for verification.

errors errors

List of errors.

Returned in case status="ERROR".

Parameters nested in errors

error

Information about the error.

This parameter is returned only for XML format.

Parameters nested in error / errors

code code Enum

Error code:

  • CONSTRAINT_VIOLATION — The license number, date of issue or date of expiry is specified incorrectly.
  • ITEM_DUPLICATE — The point of sale already has a license of the specified type.

  • MISSING_PARAM — The request doesn't provide information about any licenses.
  • NOT_FOUND — The license or point of sale with the specified ID wasn't found.

For XML format, it is an attribute of the error parameter.

message message String

Description of the error.

For XML format, it is an attribute of the error parameter.

Error description

If an error occurs, the server returns the HTTP response code and a short error description.

Errors that contain short descriptions specific to this method:

Description

Explanation

Possible solution

Error 400 Bad Request

Found more than one
  license of type {type}
  for outlet with id
  {outletId}

The point of sale already has a license of the specified type.

Make sure that you send the correct data.

Licenses should not be
  empty

The request doesn't provide information about any licenses.

Make sure that you send the correct data.

License number cannot be
  blank

An empty string is specified instead of license number.

Enter the correct license number.

Date of issue should be
  before date of expiry

The license date-of-issue is later than the date-of-expiry.

Specify the correct license issue date and expiration date.

Error 404 Not Found

Outlets not found: 
  {outletIds}

No points of sale were found.

Make sure you send the correct point of sale IDs.

Licenses with ids {ids}
  not found

Licenses not found.

Make sure you send the correct license IDs.

Description

Explanation

Possible solution

Error 400 Bad Request

Found more than one
  license of type {type}
  for outlet with id
  {outletId}

The point of sale already has a license of the specified type.

Make sure that you send the correct data.

Licenses should not be
  empty

The request doesn't provide information about any licenses.

Make sure that you send the correct data.

License number cannot be
  blank

An empty string is specified instead of license number.

Enter the correct license number.

Date of issue should be
  before date of expiry

The license date-of-issue is later than the date-of-expiry.

Specify the correct license issue date and expiration date.

Error 404 Not Found

Outlets not found: 
  {outletIds}

No points of sale were found.

Make sure you send the correct point of sale IDs.

Licenses with ids {ids}
  not found

Licenses not found.

Make sure you send the correct license IDs.

Restrictions

During one day, you can use this and other requests about points of sale, except for the GET /delivery/services request, to get and change information about a total number of points of sale. It depends on the number of the store's points of sale.

Examples

Request:

curl -i -X POST \
-H 'Content-Type: application/xml' \
-H 'Authorization: OAuth oauth_token="<token>", oauth_client_id="<ID>"' \
-d \
'<licenses>
  <license outlet-id="171819" license-type="ALCOHOL" number="01АБВ23456789"
           date-of-issue="2017-11-13T00:00:00+03:00"
           date-of-expiry="2022-11-20T00:00:00+03:00"/>
</licenses>' \
'https://api.partner.market.yandex.ru/v2'\
'/campaigns/10001/outlets/licenses.xml'

Response:

HTTP/1.1 200 OK
Date: Mon, 29 Apr 2019 09:42:57 GMT
Content-Type: application/xml;charset=utf-8
...

<response>
  <status>OK</status>
</response>