Руководство · store:write · orders:write

Магазин Bloop

Подключите свой склад, интернет-магазин или таблицу к магазину Bloop в Linework: товары, остатки, заказы и доставка.

Scopes: store:read, store:write, orders:read, orders:write.

Платежи обрабатывает Linework внутри приложения. API никогда не перемещает деньги: вы управляете каталогом и выполнением заказов, а покупатели, как обычно, платят в Linework.

Endpoint#

Endpoint	Назначение
GET `/store`	Ваш магазин.
POST `/store`	Создать магазин, если у вас его ещё нет.
PATCH `/store`	Обновить название, описание и другие данные магазина.
GET `/store/products`	Список ваших товаров (с пагинацией).
POST `/store/products`	Создать товар.
PATCH `/store/products/{id}`	Обновить товар.
DELETE `/store/products/{id}`	Удалить товар.
PATCH `/store/products/{id}/stock`	Задать доступное количество.
GET `/store/orders`	Полученные заказы (с пагинацией).
GET `/store/orders/{id}`	Один заказ с позициями и адресом доставки.
POST `/store/orders/{id}/ship`	Отметить заказ как отправленный, с трек-номером.

1. Проверьте свой магазин#

curl https://api.linework.app/open/v1/store \
  -H "Authorization: Bearer $LINEWORK_API_KEY"

Если у вас ещё нет магазина, GET /store возвращает 404 NOT_FOUND: создайте его с помощью POST /store (поля описаны в справочнике API).

2. Создайте товар#

Сначала загрузите фотографии через POST /media (см. Пост с медиафайлами), затем создайте товар с их mediaId.

curl https://api.linework.app/open/v1/store/products \
  -H "Authorization: Bearer $LINEWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Linen shirt",
    "description": "100% Italian linen, made in Biella.",
    "price": 59.00,
    "currency": "EUR",
    "stock": 25,
    "sku": "SHIRT-LIN-M",
    "mediaIds": ["m_8f2c1a"]
  }'

const res = await fetch("https://api.linework.app/open/v1/store/products", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LINEWORK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Linen shirt",
    description: "100% Italian linen, made in Biella.",
    price: 59.0,
    currency: "EUR",
    stock: 25,
    sku: "SHIRT-LIN-M",
    mediaIds: [mediaId],
  }),
});
const product = await res.json();

import os, requests

API = "https://api.linework.app/open/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['LINEWORK_API_KEY']}"

product = s.post(API + "/store/products", json={
    "title": "Linen shirt",
    "description": "100% Italian linen, made in Biella.",
    "price": 59.00,
    "currency": "EUR",
    "stock": 25,
    "sku": "SHIRT-LIN-M",
    "mediaIds": [media_id],
}, timeout=30).json()

3. Синхронизируйте остатки#

Используйте специальный endpoint для остатков: он лёгкий и не затрагивает остальные данные товара.

curl -X PATCH https://api.linework.app/open/v1/store/products/7781/stock \
  -H "Authorization: Bearer $LINEWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stock": 12 }'

Типичная задача синхронизации считывает количества из вашей системы и обновляет только изменившиеся товары:

const API = "https://api.linework.app/open/v1";
const headers = { Authorization: `Bearer ${process.env.LINEWORK_API_KEY}`, "Content-Type": "application/json" };

const warehouse = { "SHIRT-LIN-M": 12, "SHIRT-LIN-L": 0 }; // from your system

let cursor = null;
do {
  const url = `${API}/store/products?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
  const page = await fetch(url, { headers }).then((r) => r.json());
  for (const p of page.data) {
    const qty = warehouse[p.sku];
    if (qty !== undefined && qty !== p.stock) {
      await fetch(`${API}/store/products/${p.id}/stock`, {
        method: "PATCH", headers, body: JSON.stringify({ stock: qty }),
      });
    }
  }
  cursor = page.next_cursor;
} while (cursor);

warehouse = {"SHIRT-LIN-M": 12, "SHIRT-LIN-L": 0}  # from your system

cursor = None
while True:
    params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
    page = s.get(API + "/store/products", params=params, timeout=30).json()
    for p in page["data"]:
        qty = warehouse.get(p.get("sku"))
        if qty is not None and qty != p["stock"]:
            s.patch(f"{API}/store/products/{p['id']}/stock", json={"stock": qty}, timeout=30)
    cursor = page.get("next_cursor")
    if not cursor:
        break

При остатке 0 товар остаётся в каталоге с пометкой «нет в наличии». Чтобы удалить его, используйте DELETE /store/products/{id}.

4. Получайте новые заказы#

curl "https://api.linework.app/open/v1/store/orders?limit=50" \
  -H "Authorization: Bearer $LINEWORK_API_KEY"

Заказы возвращаются начиная с самых новых. У каждого заказа есть id, статус, позиции, итоговые суммы, а в ответе GET /store/orders/{id} — ещё и адрес доставки. Запрашивайте список каждые несколько минут и обрабатывайте оплаченные, но ещё не отправленные заказы. Полная схема заказа и возможные значения статуса приведены в справочнике API.

Заказы содержат персональные данные покупателей (имя, адрес). Используйте их только для выполнения заказа, храните надёжно и никому не передавайте. См. Условия использования API.

5. Отметьте заказ как отправленный#

curl https://api.linework.app/open/v1/store/orders/50213/ship \
  -H "Authorization: Bearer $LINEWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "carrier": "BRT", "trackingNumber": "084512345678" }'

Покупатель получает уведомление в приложении с данными для отслеживания. Повторная отправка заказа или отправка заказа, который нельзя отправить (например, отменённого), завершается ошибкой 409 CONFLICT.