Перейти к содержимому
BILLZ для разработчиков

Изменение даты продажи

PATCH
/v2/order/{id}
curl --request PATCH \
  --url 'https://api-admin.billz.ai/v2/order/5f6d2c0e-8a39-4c77-9a42-1d0a6d6f7a11?Billz-Response-Channel=HTTP' \
  --header 'Authorization: Bearer <token>' \
  --header 'Billz-Response-Channel: HTTP' \
  --header 'Content-Type: application/json' \
  --header 'platform-id: 7d4a4c38-dd84-4902-b744-0488b80a4c01' \
  --data '{ "sold_at": "2023-05-14 18:32:10" }'

Асинхронный метод. Чтобы получить результат синхронно по HTTP, передайте заголовок Billz-Response-Channel: HTTP — иначе ответ будет 200 {"message": "<correlation_id>"}. Максимальное ожидание — 600 секунд, далее 408 с error.code = TIMEOUT.

Меняет только дату (sold_at) завершённой продажи, возврата или обмена. Товары, суммы, оплаты, клиент и статус документа остаются прежними.

Новая дата передаётся в часовом поясе компании и должна укладываться в правила:

  • не позже текущего момента и не раньше 2000-01-01 00:00:00;
  • возврат или обмен — не раньше исходной продажи, продажа — не позже своего первого возврата или обмена;
  • если в компании включены финансы и документ относится к смене кассы — в границах этой смены, в том числе для старых дат.

Повторный вызов с той же датой вернёт 200 с changed: false.

В ответе даты в UTC (RFC 3339), а не во времени компании, как в запросе.

Коды ошибок: 408 — таймаут ожидания асинхронного ответа; 401, 403, 429, 500 — общие для всех методов. Форматы тела и семантика — Коды ответов и ошибки.

Authorizations

Заголовок раздела «Authorizations»

Parameters

Заголовок раздела «Parameters»

Path Parameters

Заголовок раздела «Path Parameters»
id
required
string format: uuid

ID продажи, возврата или обмена

Example
5f6d2c0e-8a39-4c77-9a42-1d0a6d6f7a11

Header Parameters

Заголовок раздела «Header Parameters»
platform-id
string
default: 7d4a4c38-dd84-4902-b744-0488b80a4c01

Идентификатор платформы. Для интеграций используется статичное значение.

Billz-Response-Channel
string
Allowed values: HTTP

HTTP — дождаться результата обработки события и вернуть его в HTTP-ответе. Без заголовка метод вернёт только correlation_id опубликованного события.

Query Parameters

Заголовок раздела «Query Parameters»
Billz-Response-Channel
string
Allowed values: HTTP

То же, что заголовок Billz-Response-Channel, — для клиентов, которые не могут передать свой заголовок. Если переданы оба, действует заголовок.

Request Bodyrequired

Заголовок раздела «Request Bodyrequired»
Media typeapplication/json
object
sold_at
required

Новая дата и время в часовом поясе компании, формат YYYY-MM-DD HH:MM:SS

string
Example
{
  "sold_at": "2023-05-14 18:32:10"
}

Responses

Заголовок раздела «Responses»

200

Заголовок раздела «200»

Успех. С заголовком Billz-Response-Channel: HTTP — конверт асинхронного ответа, без него — {"message": "<correlation_id>"}.

Media typeapplication/json
One of:
object
session_id

Идентификатор сессии клиента

string format: uuid
status_code

Итоговый HTTP-код, 200

integer
correlation_id

Идентификатор запроса

string format: uuid
topic

Тип ответного события, например <event_type>.success

string
id

ID продажи, возврата или обмена

string format: uuid
data
object
order_id

ID продажи, возврата или обмена

string format: uuid
order_type

Тип документа: продажа, возврат или обмен

string
Allowed values: SALE RETURN EXCHANGE
old_sold_at

Дата до изменения, UTC

string format: date-time
sold_at

Дата после изменения, UTC

string format: date-time
changed

false, если переданная дата совпала с текущей и документ не изменился

boolean
Example
{
  "session_id": "7c2a0f3e-3c52-4a4a-9d0e-5d3a8f1b2c11",
  "status_code": 200,
  "id": "5f6d2c0e-8a39-4c77-9a42-1d0a6d6f7a11",
  "topic": "v2.order_service.order.patch.success",
  "data": {
    "order_id": "5f6d2c0e-8a39-4c77-9a42-1d0a6d6f7a11",
    "order_type": "SALE",
    "old_sold_at": "2026-03-10T12:00:00Z",
    "sold_at": "2026-01-05T05:00:00Z",
    "changed": true
  }
}

400

Заголовок раздела «400»

Дата не принята. Без sold_at, с другими полями в теле или с неверным JSON — 400 сразу, без конверта. Остальные причины приходят в конверте, код — в data.error_code:

  • 20127 — документ не завершён;
  • 20128 — sold_at не в формате YYYY-MM-DD HH:MM:SS;
  • 20129 — дата в будущем или раньше 2000-01-01;
  • 20130 — возврат или обмен раньше исходной продажи; в data.data — parent_order_id и parent_sold_at (UTC, YYYY-MM-DD HH:MM:SS);
  • 20131 — продажа позже своего первого возврата или обмена; в data.data — child_order_id и child_sold_at (UTC, YYYY-MM-DD HH:MM:SS);
  • 20132, 20133 — дата вне смены кассы, к которой относится документ.
Media typeapplication/json
One of:

Тело ошибки. В API сосуществует несколько форматов тела ошибки; все форматы и коды описаны в разделе «Коды ответов и ошибки».

object
code

HTTP-код или внутренний числовой код ошибки

integer
message

Человекочитаемое сообщение

string
error
One of:
string
data

Полезная нагрузка (обычно null при ошибке)

object
Example
{
  "session_id": "7c2a0f3e-3c52-4a4a-9d0e-5d3a8f1b2c11",
  "status_code": 400,
  "topic": "v2.order_service.order.patch.failed",
  "data": {
    "error_code": 20130,
    "message": "return or exchange can't be dated earlier than its sale",
    "data": {
      "parent_order_id": "a1000000-0000-4000-8000-000000000001",
      "parent_sold_at": "2026-03-10 12:00:00"
    }
  }
}

404

Заголовок раздела «404»

Документ не найден в компании, data.error_code = 20088.

Media typeapplication/json
One of:

Тело ошибки. В API сосуществует несколько форматов тела ошибки; все форматы и коды описаны в разделе «Коды ответов и ошибки».

object
code

HTTP-код или внутренний числовой код ошибки

integer
message

Человекочитаемое сообщение

string
error
One of:
string
data

Полезная нагрузка (обычно null при ошибке)

object
Examplegenerated
{
  "code": 1,
  "message": "example",
  "error": {
    "code": "example",
    "message": "example"
  },
  "data": {}
}