Guía · store:write · orders:write

Gestionar una tienda Bloop

Conecta tu almacén, tu e-commerce o tu hoja de cálculo con tu tienda Bloop en Linework: productos, stock, pedidos y envíos.

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

Linework gestiona los pagos dentro de la aplicación. La API nunca mueve dinero: tú gestionas el catálogo y la preparación de los pedidos, y los compradores pagan en Linework como siempre.

Los endpoints#

Endpoint	Uso
GET `/store`	Tu tienda.
POST `/store`	Crea tu tienda, si todavía no tienes una.
PATCH `/store`	Actualiza el nombre, la descripción y otros datos de la tienda.
GET `/store/products`	Lista tus productos (paginado).
POST `/store/products`	Crea un producto.
PATCH `/store/products/{id}`	Actualiza un producto.
DELETE `/store/products/{id}`	Elimina un producto.
PATCH `/store/products/{id}/stock`	Establece la cantidad disponible.
GET `/store/orders`	Pedidos recibidos (paginado).
GET `/store/orders/{id}`	Un pedido con sus artículos y la dirección de envío.
POST `/store/orders/{id}/ship`	Marca un pedido como enviado, con seguimiento.

1. Comprueba tu tienda#

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

Si todavía no tienes una tienda, GET /store devuelve 404 NOT_FOUND: créala con POST /store (campos en la Referencia de la API).

2. Crea un producto#

Primero sube las fotos con POST /media (consulta Publicar con contenido multimedia) y después crea el producto con sus 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. Mantén el stock sincronizado#

Usa el endpoint dedicado al stock: es ligero y no modifica el resto del producto.

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 }'

Un proceso de sincronización típico lee las cantidades de tu sistema y actualiza solo los productos que han cambiado:

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

Con el stock a 0, el producto permanece en el catálogo como agotado. Para retirarlo, usa DELETE /store/products/{id}.

4. Lee los pedidos nuevos#

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

Los pedidos se devuelven del más reciente al más antiguo. Cada pedido tiene un id, un estado, sus artículos, los totales y, en GET /store/orders/{id}, la dirección de envío. Consulta la lista cada pocos minutos y procesa los pedidos pagados que aún no se hayan enviado. El esquema completo del pedido y los valores de estado están en la Referencia de la API.

Los pedidos contienen datos personales de los compradores (nombre, dirección). Úsalos solo para preparar y enviar el pedido, protégelos y no los compartas. Consulta los Términos de la API.

5. Marca como enviado#

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" }'

El comprador recibe una notificación en la aplicación con los datos de seguimiento. Enviar un pedido dos veces, o un pedido que no se puede enviar (por ejemplo, cancelado), falla con 409 CONFLICT.