Сумма покупок клиентов

PATCH

/v1/customer/bulk

curl --request PATCH \
  --url 'https://api-admin.billz.ai/v1/customer/bulk?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 '{ "customers": [ { "customer_id": "0c4bacfa-5a20-4ee0-befb-e2c27da19d0c", "purchase_amount": 2100000 }, { "customer_id": "2be17079-dead-45a2-9b27-c7a7ceaf1476", "purchase_amount": 650000 } ] }'

• Production

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

Устанавливает итоговую сумму покупок клиентов: новое значение заменяет текущее, а не прибавляется к нему. За один запрос — до 1000 клиентов, тело запроса — не больше 1 МБ.

Всё или ничего: если хотя бы один клиент не найден в компании, не обновляется никто, а в ответе 404 — список ненайденных.

Ноль и отрицательные суммы допустимы. Удалённые и архивные клиенты тоже обновляются.

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

Authorizations

• BearerAuth

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

Billz-Response-Channel

string

Allowed values: HTTP

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

Request Body^required

Media typeapplication/json

object

customers

required

Клиенты и их новые суммы покупок; клиент не должен повторяться

Array<object>

>= 1 items <= 1000 items

object

customer_id

required

ID клиента

string format: uuid

purchase_amount

required

Итоговая сумма покупок; заменяет текущую

number format: double

Example

{
  "customers": [
    {
      "customer_id": "0c4bacfa-5a20-4ee0-befb-e2c27da19d0c",
      "purchase_amount": 2100000
    },
    {
      "customer_id": "2be17079-dead-45a2-9b27-c7a7ceaf1476",
      "purchase_amount": 650000
    }
  ]
}

Responses

200

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

Media typeapplication/json

One of:

object

object

session_id

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

string format: uuid

status_code

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

integer

correlation_id

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

string format: uuid

topic

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

string

data

object

updated

Сколько клиентов обновлено

integer

object

Ответ асинхронного метода без заголовка Billz-Response-Channel — событие опубликовано.

object

message

Correlation_id опубликованного события

string format: uuid

Example

{
  "session_id": "7c2a0f3e-3c52-4a4a-9d0e-5d3a8f1b2c11",
  "status_code": 200,
  "topic": "v1.user_service.customer.bulk_patch.success",
  "data": {
    "updated": 2
  }
}

400

Запрос не принят, никто не обновлён. С неизвестным полем в теле, с неверным JSON или с телом больше 1 МБ — 400 сразу, без конверта. Остальные причины приходят в конверте, код — в data.error_code:

• 1007 — список customers пуст;
• 1008 — больше 1000 клиентов;
• 1009 — customer_id не UUID;
• 1010 — клиент повторяется в запросе;
• 1011 — у клиента не передан purchase_amount.

Проверка останавливается на первой ошибке; для 1009–1011 в data.data — строкой customer_id этого клиента.

Media typeapplication/json

One of:

object

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

object

code

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

integer

message

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

string

error

One of:

string

string

object

object

code

string

message

string

data

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

object

object

Конверт асинхронного ответа. Возвращается, когда передан заголовок Billz-Response-Channel: HTTP. Итоговый HTTP-код запроса берётся из поля status_code.

object

session_id

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

string format: uuid

status_code

Статус обработки события (он же итоговый HTTP-код ответа)

integer

error

object

code

Код ошибки, пустая строка если ошибки нет

string

message

Текст ошибки, пустая строка если ошибки нет

string

correlation_id

Идентификатор запроса, совпадает с ID опубликованного события

string format: uuid

topic

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

string

data

Результат операции, если метод его возвращает

object

Example^generated

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

404

Хотя бы один клиент не найден в компании, никто не обновлён. data.error_code = 1012, в data.data — missing_customer_ids (не больше 100) и missing_total — сколько всего не найдено.

Media typeapplication/json

One of:

object

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

object

code

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

integer

message

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

string

error

One of:

string

string

object

object

code

string

message

string

data

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

object

object

Конверт асинхронного ответа. Возвращается, когда передан заголовок Billz-Response-Channel: HTTP. Итоговый HTTP-код запроса берётся из поля status_code.

object

session_id

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

string format: uuid

status_code

Статус обработки события (он же итоговый HTTP-код ответа)

integer

error

object

code

Код ошибки, пустая строка если ошибки нет

string

message

Текст ошибки, пустая строка если ошибки нет

string

correlation_id

Идентификатор запроса, совпадает с ID опубликованного события

string format: uuid

topic

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

string

data

Результат операции, если метод его возвращает

object

Example

{
  "session_id": "7c2a0f3e-3c52-4a4a-9d0e-5d3a8f1b2c11",
  "status_code": 404,
  "topic": "v1.user_service.customer.bulk_patch.failed",
  "data": {
    "error_code": 1012,
    "message": "customers not found, nothing was updated",
    "data": {
      "missing_customer_ids": [
        "2be17079-dead-45a2-9b27-c7a7ceaf1476"
      ],
      "missing_total": 1
    }
  }
}