Создание карты
const url = 'https://api-admin.billz.ai/v1/gift-card/activate-list?Billz-Response-Channel=HTTP';const options = { method: 'POST', headers: { 'platform-id': '7d4a4c38-dd84-4902-b744-0488b80a4c01', 'Billz-Response-Channel': 'HTTP', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"id":0,"is_activated":false,"gift_cards":[{"code":"1000000001","amount":10000,"expire_period":"31.12.2024"}],"card_type":"CERTIFICATE","expire_type":"ABSOLUTE","use_type":"SINGLE"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://api-admin.billz.ai/v1/gift-card/activate-list?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 '{ "id": 0, "is_activated": false, "gift_cards": [ { "code": "1000000001", "amount": 10000, "expire_period": "31.12.2024" } ], "card_type": "CERTIFICATE", "expire_type": "ABSOLUTE", "use_type": "SINGLE" }'Асинхронный метод. Чтобы получить результат синхронно по HTTP, передайте заголовок Billz-Response-Channel: HTTP — иначе ответ будет 200 {"message": "<correlation_id>"}. Максимальное ожидание — 600 секунд, далее 408 с error.code = TIMEOUT.
Список карт создаётся в интерфейсе BILLZ (Маркетинг → Подарочные карты); отдельного метода создания списка в API нет. id — идентификатор уже созданного списка, метод активирует карты в нём.
Коды ошибок: 400 — ошибка валидации входных данных; 404 — объект не найден; 408 — таймаут ожидания асинхронного ответа; 401, 403, 429, 500 — общие для всех методов. Форматы тела и семантика — Коды ответов и ошибки.
Authorizations
Заголовок раздела «Authorizations»Parameters
Заголовок раздела «Parameters»Header Parameters
Заголовок раздела «Header Parameters»Идентификатор платформы. Для интеграций используется статичное значение.
HTTP — дождаться результата обработки события и вернуть его в HTTP-ответе. Без заголовка метод вернёт только correlation_id опубликованного события.
Query Parameters
Заголовок раздела «Query Parameters»То же, что заголовок Billz-Response-Channel, — для клиентов, которые не могут передать свой заголовок. Если переданы оба, действует заголовок.
Request Bodyrequired
Заголовок раздела «Request Bodyrequired»object
Идентификатор существующего списка карт
Создать предактивированную карту (только для VOUCHER)
Список карт
object
Код карты
Номинал
Срок действия; трактуется согласно expire_type
CERTIFICATE | VOUCHER
ABSOLUTE или RELATIVE
SINGLE | MULTIPLE
Example
{ "id": 0, "is_activated": false, "gift_cards": [ { "code": "1000000001", "amount": 10000, "expire_period": "31.12.2024" } ], "card_type": "CERTIFICATE", "expire_type": "ABSOLUTE", "use_type": "SINGLE"}Responses
Заголовок раздела «Responses»Успех. С заголовком Billz-Response-Channel: HTTP — конверт асинхронного ответа, без него — {"message": "<correlation_id>"}.
Конверт асинхронного ответа. Возвращается, когда передан заголовок Billz-Response-Channel: HTTP. Итоговый HTTP-код запроса берётся из поля status_code.
object
Идентификатор сессии клиента
Статус обработки события (он же итоговый HTTP-код ответа)
object
Код ошибки, пустая строка если ошибки нет
Текст ошибки, пустая строка если ошибки нет
Идентификатор запроса, совпадает с ID опубликованного события
Тип ответного события, например <event_type>.success
Результат операции, если метод его возвращает
object
Ответ асинхронного метода без заголовка Billz-Response-Channel — событие опубликовано.
object
Correlation_id опубликованного события
object
Внутренний id сессии подключения
Код результата обработки события (200 при успехе)
Id сообщения-ответа
Id компании
Внутренний код/сообщение ошибки
object
Полезная нагрузка ответа
Идентификатор запроса
Тип ответного события, например <event_type>.success
Examplegenerated
{ "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "status_code": 1, "error": { "code": "example", "message": "example" }, "correlation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "topic": "example", "data": {}}