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.
Ендпоінти
Перелік ваших оголошень. Параметри: itemType, status, condition, q, sort, page, size.
Створити оголошення.
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"
}'Оновити ціну, кількість, статус або коментар. Усі поля необовʼязкові.
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 }'Видалити оголошення.
Створити до 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" }
]Оновити ціну/кількість/статус до 100 оголошень за один запит.
[
{ "listingId": "7b3e...", "price": 1150, "quantity": 1 },
{ "listingId": "9f2a...", "status": "removed" }
]Наявність товару в усіх продавців маркетплейсу. Параметри: 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}.
| Поле | Тип | Обовʼязкове | Опис |
|---|---|---|---|
| id | UUID | — | Унікальний ідентифікатор оголошення. |
| sellerId | UUID | — | Власник оголошення (ви). |
| itemType | string | — | Одне з: set, minifig, element, part, custom. |
| itemId | string | — | Ідентифікатор товару в каталозі. |
| itemName | string | — | Назва товару з каталогу. |
| condition | string | — | new або used. |
| price | number | — | Ціна у валюті оголошення. |
| currency | string | — | UAH, USD або EUR. |
| quantity | integer | — | Доступна кількість. |
| status | string | — | active, sold, reserved, removed, pending_approval або rejected. |
| comment | string | — | Публічний коментар для покупців. |
| remarks | string | — | Приватна нотатка продавця (лише у ваших оголошеннях). |
| details | object | — | Прапорці за типом (напр. комплектність набору, аксесуари мініфігурки). |
| primaryImageUrl | string | — | URL головного зображення. |
| images | array | — | Зображення: { id, url, displayOrder }. |
| featured | boolean | — | Прапорець «рекомендоване» (лише PRO-продавці). |
| soldAt | timestamp | — | Коли оголошення було продано (може бути null). |
| createdAt | timestamp | — | Час створення. |
| updatedAt | timestamp | — | Час останнього оновлення. |
| rejectionReason | string | — | Причина, встановлюється коли status = rejected. |
CreateListingRequest
Тіло запиту POST /listings (і елементи POST /listings/bulk).
| Поле | Тип | Обовʼязкове | Опис |
|---|---|---|---|
| itemType | string | так | set, minifig, element або custom. |
| itemId | string | — | Ідентифікатор каталогу (для set / minifig / custom). |
| partId | string | — | Номер деталі (для element; разом із colorName). |
| colorName | string | — | Назва кольору для визначення елемента. |
| condition | string | так | new або used. |
| price | number | так | Має бути більше 0. |
| currency | string | так | UAH, USD або EUR. |
| quantity | integer | так | Має бути щонайменше 1. |
| comment | string | — | Публічний коментар для покупців. |
| remarks | string | — | Приватна нотатка продавця. |
| details | object | — | Прапорці за типом. |
UpdateListingRequest
Тіло запиту PUT /listings/{id}. Поля зі значенням null не змінюються.
| Поле | Тип | Обовʼязкове | Опис |
|---|---|---|---|
| price | number | — | Нова ціна; має бути більше 0. |
| quantity | integer | — | Нова кількість; 0 або більше. |
| status | string | — | Новий статус, напр. removed. |
| comment | string | — | Публічний коментар. |
| remarks | string | — | Приватна нотатка. |
| details | object | — | Прапорці за типом. |
BulkUpdateItem
Елемент масиву в POST /listings/bulk-update.
| Поле | Тип | Обовʼязкове | Опис |
|---|---|---|---|
| listingId | UUID | так | Оголошення для оновлення. |
| price | number | — | Нова ціна (необовʼязково). |
| quantity | integer | — | Нова кількість (необовʼязково). |
| status | string | — | Новий статус (необовʼязково). |
BulkResultItem
Елемент відповіді масових операцій (bulk / bulk-update).
| Поле | Тип | Обовʼязкове | Опис |
|---|---|---|---|
| index | integer | — | Позиція елемента у надісланому масиві. |
| ok | boolean | — | Чи успішно оброблено елемент. |
| listingId | UUID | null | — | Ідентифікатор оголошення (null, якщо створення не вдалося). |
| error | string | null | — | Повідомлення про помилку, коли ok = false. |
AvailabilityResponse
Відповідь GET /availability. Ціни конвертуються в UAH.
| Поле | Тип | Обовʼязкове | Опис |
|---|---|---|---|
| itemType | string | — | Повторює запитаний тип товару. |
| itemId | string | — | Повторює запитаний ідентифікатор товару. |
| available | boolean | — | True, якщо є хоча б одна активна пропозиція. |
| totalOffers | integer | — | Загальна кількість активних пропозицій від усіх продавців. |
| page | integer | — | Поточна сторінка (від 0). |
| size | integer | — | Розмір сторінки. |
| totalPages | integer | — | Загальна кількість сторінок. |
| offers | Offer[] | — | Пропозиції на цій сторінці (див. нижче). |
Offer
Один запис у AvailabilityResponse.offers. Приватні поля інших продавців не розкриваються.
| Поле | Тип | Обовʼязкове | Опис |
|---|---|---|---|
| listingId | UUID | — | Ідентифікатор оголошення-пропозиції. |
| sellerId | UUID | — | Продавець, що пропонує товар. |
| condition | string | — | new або used. |
| price | number | — | Ціна, конвертована в UAH. |
| currency | string | — | Завжди UAH для наявності. |
| quantity | integer | — | Доступна кількість. |
| comment | string | — | Публічний коментар для покупців. |
Помилки
Помилки повертаються зі стандартним HTTP-статусом і тілом:
{ "error": "Rate limit exceeded" }401 — відсутній або недійсний токен · 400 — некоректний запит · 404 — не знайдено · 422 — перевищено ліміт оголошень · 429 — перевищено ліміт запитів.
