Guida · store:write · orders:write

Gestire uno store Bloop

Collega il tuo magazzino, il tuo e-commerce o il tuo foglio di calcolo al tuo store Bloop su Linework: prodotti, magazzino, ordini e spedizioni.

Scope: store:read, store:write, orders:read, orders:write.

I pagamenti sono gestiti da Linework all'interno dell'app. L'API non muove mai denaro: tu gestisci il catalogo e l'evasione degli ordini, gli acquirenti pagano su Linework come sempre.

Gli endpoint#

Endpoint	Uso
GET `/store`	Il tuo store.
POST `/store`	Crea il tuo store, se non ne hai ancora uno.
PATCH `/store`	Aggiorna nome, descrizione e altri dati dello store.
GET `/store/products`	Elenca i tuoi prodotti (paginato).
POST `/store/products`	Crea un prodotto.
PATCH `/store/products/{id}`	Aggiorna un prodotto.
DELETE `/store/products/{id}`	Rimuove un prodotto.
PATCH `/store/products/{id}/stock`	Imposta la quantità disponibile.
GET `/store/orders`	Ordini ricevuti (paginato).
GET `/store/orders/{id}`	Un ordine con articoli e indirizzo di spedizione.
POST `/store/orders/{id}/ship`	Segna un ordine come spedito, con il tracking.

1. Controlla il tuo store#

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

Se non hai ancora uno store, GET /store restituisce 404 NOT_FOUND: crealo con POST /store (i campi sono nel Riferimento API).

2. Crea un prodotto#

Prima carica le foto con POST /media (vedi Pubblicare post con media), poi crea il prodotto con i loro 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. Mantieni il magazzino sincronizzato#

Usa l'endpoint dedicato al magazzino: è leggero e non tocca il resto del prodotto.

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 tipico job di sincronizzazione legge le quantità dal tuo sistema e aggiorna solo i prodotti che sono cambiati:

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 il magazzino a 0 il prodotto resta nel catalogo come esaurito. Per rimuoverlo usa DELETE /store/products/{id}.

4. Leggi i nuovi ordini#

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

Gli ordini vengono restituiti dal più recente. Ogni ordine ha un id, uno stato, i suoi articoli, i totali e, per GET /store/orders/{id}, l'indirizzo di spedizione. Recupera l'elenco ogni pochi minuti ed evadi gli ordini pagati e non ancora spediti. Lo schema completo dell'ordine e i valori di stato sono nel Riferimento API.

Gli ordini contengono dati personali degli acquirenti (nome, indirizzo). Usali solo per evadere l'ordine, conservali in modo sicuro e non condividerli. Vedi i Termini dell'API.

5. Segna come spedito#

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

L'acquirente riceve una notifica nell'app con i dati del tracking. Spedire due volte lo stesso ordine, o un ordine che non può essere spedito (per esempio annullato), fallisce con 409 CONFLICT.