API для розробників

Публічний REST API дозволяє керувати вашим інвентарем і цінами, виконувати масові операції та перевіряти наявність товарів на маркетплейсі.

Використання з ШІ-агентами (MCP)

Цей API доступний як MCP-сервер для Claude Desktop/Code та інших MCP-клієнтів — керуйте інвентарем і цінами прямо з ШІ-агента, використовуючи ваш токен. Запустіть його локально через npx @brickmart/mcp.

Автентифікація

Згенеруйте персональний токен на сторінці редагування профілю. Токен показується лише один раз — збережіть його. Передавайте його у заголовку кожного запиту:

Authorization: Bearer bm_live_xxxxxxxxxxxxxxxxxxxx

Запити автентифікуються як ви — усі операції стосуються вашого власного інвентарю. Відкликати токен можна будь-коли на сторінці профілю.

Базовий URL

https://brickmart.shop/public-api

Обмеження частоти

Приблизно 120 запитів на хвилину на токен; масові операції обмежені суворіше (приблизно 10/хв). Коли ліміт вичерпано, API повертає статус 429 із заголовками X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset та Retry-After.

Ендпоінти

GET/listings

Перелік ваших оголошень. Параметри: itemType, status, condition, q, sort, page, size.

POST/listings

Створити оголошення.

curl -X POST https://brickmart.shop/public-api/listings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "itemType": "set",
    "itemId": "75060-1",
    "condition": "new",
    "price": 1299.00,
    "currency": "UAH",
    "quantity": 2,
    "comment": "Sealed box"
  }'
PUT/listings/{id}

Оновити ціну, кількість, статус або коментар. Усі поля необовʼязкові.

curl -X PUT https://brickmart.shop/public-api/listings/$ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "price": 1150.00, "quantity": 1 }'
DELETE/listings/{id}

Видалити оголошення.

POST/listings/bulk

Створити до 100 оголошень за один запит. Повертає результат по кожному елементу.

[
  { "itemType": "set", "itemId": "75060-1", "condition": "new", "price": 1299, "currency": "UAH", "quantity": 2 },
  { "itemType": "minifig", "itemId": "sw0547", "condition": "used", "price": 150, "currency": "UAH", "quantity": 1 }
]

// response
[
  { "index": 0, "ok": true,  "listingId": "7b3e...", "error": null },
  { "index": 1, "ok": false, "listingId": null,      "error": "Item not found in catalog" }
]
POST/listings/bulk-update

Оновити ціну/кількість/статус до 100 оголошень за один запит.

[
  { "listingId": "7b3e...", "price": 1150, "quantity": 1 },
  { "listingId": "9f2a...", "status": "removed" }
]
GET/availability

Наявність товару в усіх продавців маркетплейсу. Параметри: itemType, itemId, page, size. Ціни конвертуються в UAH.

GET /public-api/availability?itemType=set&itemId=75060-1

{
  "itemType": "set",
  "itemId": "75060-1",
  "available": true,
  "totalOffers": 4,
  "page": 0, "size": 20, "totalPages": 1,
  "offers": [
    { "listingId": "7b3e...", "sellerId": "a1c2...", "condition": "new", "price": 1299, "currency": "UAH", "quantity": 2, "comment": "Sealed box" }
  ]
}

Схема даних

Детальний опис полів обʼєктів запитів і відповідей. Усі ідентифікатори — UUID; грошові суми — десяткові числа; часові мітки — у форматі ISO-8601 (UTC).

Listing

Повертається з GET /listings, POST /listings та PUT /listings/{id}.

ПолеТипОбовʼязковеОпис
idUUID—Унікальний ідентифікатор оголошення.
sellerIdUUID—Власник оголошення (ви).
itemTypestring—Одне з: set, minifig, element, part, custom.
itemIdstring—Ідентифікатор товару в каталозі.
itemNamestring—Назва товару з каталогу.
conditionstring—new або used.
pricenumber—Ціна у валюті оголошення.
currencystring—UAH, USD або EUR.
quantityinteger—Доступна кількість.
statusstring—active, sold, reserved, removed, pending_approval або rejected.
commentstring—Публічний коментар для покупців.
remarksstring—Приватна нотатка продавця (лише у ваших оголошеннях).
detailsobject—Прапорці за типом (напр. комплектність набору, аксесуари мініфігурки).
primaryImageUrlstring—URL головного зображення.
imagesarray—Зображення: { id, url, displayOrder }.
featuredboolean—Прапорець «рекомендоване» (лише PRO-продавці).
soldAttimestamp—Коли оголошення було продано (може бути null).
createdAttimestamp—Час створення.
updatedAttimestamp—Час останнього оновлення.
rejectionReasonstring—Причина, встановлюється коли status = rejected.

CreateListingRequest

Тіло запиту POST /listings (і елементи POST /listings/bulk).

ПолеТипОбовʼязковеОпис
itemTypestringтакset, minifig, element або custom.
itemIdstring—Ідентифікатор каталогу (для set / minifig / custom).
partIdstring—Номер деталі (для element; разом із colorName).
colorNamestring—Назва кольору для визначення елемента.
conditionstringтакnew або used.
pricenumberтакМає бути більше 0.
currencystringтакUAH, USD або EUR.
quantityintegerтакМає бути щонайменше 1.
commentstring—Публічний коментар для покупців.
remarksstring—Приватна нотатка продавця.
detailsobject—Прапорці за типом.

UpdateListingRequest

Тіло запиту PUT /listings/{id}. Поля зі значенням null не змінюються.

ПолеТипОбовʼязковеОпис
pricenumber—Нова ціна; має бути більше 0.
quantityinteger—Нова кількість; 0 або більше.
statusstring—Новий статус, напр. removed.
commentstring—Публічний коментар.
remarksstring—Приватна нотатка.
detailsobject—Прапорці за типом.

BulkUpdateItem

Елемент масиву в POST /listings/bulk-update.

ПолеТипОбовʼязковеОпис
listingIdUUIDтакОголошення для оновлення.
pricenumber—Нова ціна (необовʼязково).
quantityinteger—Нова кількість (необовʼязково).
statusstring—Новий статус (необовʼязково).

BulkResultItem

Елемент відповіді масових операцій (bulk / bulk-update).

ПолеТипОбовʼязковеОпис
indexinteger—Позиція елемента у надісланому масиві.
okboolean—Чи успішно оброблено елемент.
listingIdUUID | null—Ідентифікатор оголошення (null, якщо створення не вдалося).
errorstring | null—Повідомлення про помилку, коли ok = false.

AvailabilityResponse

Відповідь GET /availability. Ціни конвертуються в UAH.

ПолеТипОбовʼязковеОпис
itemTypestring—Повторює запитаний тип товару.
itemIdstring—Повторює запитаний ідентифікатор товару.
availableboolean—True, якщо є хоча б одна активна пропозиція.
totalOffersinteger—Загальна кількість активних пропозицій від усіх продавців.
pageinteger—Поточна сторінка (від 0).
sizeinteger—Розмір сторінки.
totalPagesinteger—Загальна кількість сторінок.
offersOffer[]—Пропозиції на цій сторінці (див. нижче).

Offer

Один запис у AvailabilityResponse.offers. Приватні поля інших продавців не розкриваються.

ПолеТипОбовʼязковеОпис
listingIdUUID—Ідентифікатор оголошення-пропозиції.
sellerIdUUID—Продавець, що пропонує товар.
conditionstring—new або used.
pricenumber—Ціна, конвертована в UAH.
currencystring—Завжди UAH для наявності.
quantityinteger—Доступна кількість.
commentstring—Публічний коментар для покупців.

Помилки

Помилки повертаються зі стандартним HTTP-статусом і тілом:

{ "error": "Rate limit exceeded" }

401 — відсутній або недійсний токен · 400 — некоректний запит · 404 — не знайдено · 422 — перевищено ліміт оголошень · 429 — перевищено ліміт запитів.