API Sticker Mule

Guida rapida

1. Genera una chiave API

Apri le impostazioni del tuo profilo e, nella sezione "Impostazioni del negozio", genera una chiave API. Copialo subito: viene visualizzato solo una volta.

2. Chiama l'API

Invia la tua chiave come Bearer token. Questo esempio effettua un ordine per un articolo salvato:

curl -X POST https://www.stickermule.com/api/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "id": "456", "quantity": 50 }],
    "addressId": "22",
    "paymentId": "7"
  }'

Autenticazione

Ogni richiesta deve includere la tua chiave API come Bearer token nell'intestazione Autorizzazione.

Authorization: Bearer YOUR_API_KEY

• L'API è disponibile solo per profili personali, non per i profili team.
• Ogni profilo ha una chiave. Generare una nuova chiave sostituisce quella precedente.
• Pensa alla chiave come una password. Può effettuare ordini e accedere ai tuoi dati salvati.

URL base

Tutti gli endpoint sono relativi a questo URL di base.

https://www.stickermule.com/api

Endpoint

GET /api/items - Elenca articoli

Restituisce gli articoli che puoi riordinare. L'ID di ciascun articolo è valido come items[].id quando crei un ordine.

GET /api/items

Copia

curl "https://www.stickermule.com/api/items?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parametri della ricerca

Parametro	Tipo	Predefinito	Descrizione
limit	number	20	Numero di articoli da restituire, da 1 a 50.
offset	number	0	Numero di elementi da saltare prima di visualizzare i risultati.
currency	string	USD	Codice valuta ISO 4217 utilizzato per i prezzi.
locale	string	en	Localizzazione utilizzata per i nomi e i prezzi dei prodotti.

Risposta

I risultati sono impaginati con limitazione e offset, e canLoadMore è vero quando sono disponibili altri elementi. Poiché l'impaginazione è basata su offset, le pagine possono cambiare con l'arrivo di nuovi ordini.

Campo	Tipo	Descrizione
id	string	Identificativo dell'articolo. Utilizzalo come items[].id durante la creazione di un ordine.
name	string | null	Nome personalizzato assegnato all'articolo, se presente.
productId	number	Identificativo prodotto Sticker Mule
productName	string | null	Nome del prodotto, oppure valore nullo se il prodotto non è più disponibile.
quantity	number	Quantità dell'ordine originale.
size	RegularItemDimensions | TShirtDimensions | HoodieDimensions	Taglia dell'articolo. Per le magliette e le magliette di cotone pesante, un oggetto taglia di abbigliamento con __typename TShirtDimensions e una taglia. Per le Felpe, __typename HoodieDimensions e una taglia. Per qualsiasi altro prodotto, dimensioni fisiche in pollici con __typename RegularItemDimensions e larghezza e altezza.
isSizeRequired	boolean	Vero se per il prodotto è necessario specificare una taglia di abbigliamento per riordinare (magliette, magliette di cotone pesante e felpe). Altrimenti falso.
buyingOptions	object | null	Quantità di riordino consentite (minima, massima e incremento). Valore nullo se il prodotto non è disponibile.
retailPrice	number | null	Prezzo per la quantità minima, oppure valore nullo se il prezzo non è disponibile.
artworkUrls	string[]	URL delle grafiche approvate per l'articolo.

Esempio di risposta

Copia

{
  "items": [
    {
      "id": "456",
      "name": "Logo stickers",
      "productId": 12,
      "productName": "Die cut stickers",
      "quantity": 50,
      "size": { "__typename": "RegularItemDimensions", "width": 3, "height": 3 },
      "isSizeRequired": false,
      "buyingOptions": {
        "quantity": { "min": 50, "max": 5000, "increment": 5 }
      },
      "retailPrice": 79,
      "artworkUrls": ["https://cdn.stickermule.com/artwork.png"]
    },
    {
      "id": "789",
      "name": "Team t-shirt",
      "productId": 34,
      "productName": "Custom t-shirts",
      "quantity": 25,
      "size": { "__typename": "TShirtDimensions", "size": "sizeL" },
      "isSizeRequired": true,
      "buyingOptions": {
        "quantity": { "min": 1, "max": 500, "increment": 1 }
      },
      "retailPrice": 18,
      "artworkUrls": ["https://cdn.stickermule.com/shirt.png"]
    },
    {
      "id": "812",
      "name": "Team hoodie",
      "productId": 56,
      "productName": "Custom hoodies",
      "quantity": 10,
      "size": { "__typename": "HoodieDimensions", "size": "sizeM" },
      "isSizeRequired": true,
      "buyingOptions": {
        "quantity": { "min": 1, "max": 500, "increment": 1 }
      },
      "retailPrice": 32,
      "artworkUrls": ["https://cdn.stickermule.com/hoodie.png"]
    }
  ],
  "canLoadMore": true
}

GET /api/addresses - Elenca indirizzi

Restituisce gli indirizzi di spedizione salvati, con quello predefinito per primo. Ogni ID è valido come addressId al momento della creazione di un ordine.

GET /api/addresses

Copia

curl https://www.stickermule.com/api/addresses \
  -H "Authorization: Bearer YOUR_API_KEY"

Risposta

Campo	Tipo	Descrizione
id	string	Identificativo dell'indirizzo. Utilizzalo come addressId quando crei un ordine.
name	string | null	Nome completo del destinatario.
firstName	string | null	Nome del destinatario.
lastName	string | null	Cognome del destinatario.
companyName	string | null	Nome dell'azienda, se presente.
addressLine1	string	Indirizzo.
addressLine2	string | null	Eventuale riga aggiuntiva per l'indirizzo.
cityName	string	Città.
stateName	string | null	Nome dello stato o della provincia, se presente.
stateAbbreviation	string | null	Abbreviazione dello stato o della provincia, se presente.
zipCode	string	CAP.
countryIso	string	Codice Paese ISO 3166, ad esempio US.
countryName	string	Nome del Paese.
phone	string | null	Numero di telefono di contatto, se presente.
isDefault	boolean	Vero per il tuo indirizzo di spedizione predefinito.

Esempio di risposta

Copia

{
  "addresses": [
    {
      "id": "22",
      "name": "Jane Doe",
      "firstName": "Jane",
      "lastName": "Doe",
      "companyName": null,
      "addressLine1": "123 Main St",
      "addressLine2": null,
      "cityName": "Amsterdam",
      "stateName": null,
      "stateAbbreviation": null,
      "zipCode": "1000AA",
      "countryIso": "NL",
      "countryName": "Netherlands",
      "phone": "+31612345678",
      "isDefault": true
    }
  ]
}

GET /api/payments - Elenca metodi di pagamento

Restituisce i metodi di pagamento salvati, con quello predefinito per primo. Ogni ID è valido come paymentId al momento della creazione di un ordine.

GET /api/payments

Copia

curl https://www.stickermule.com/api/payments \
  -H "Authorization: Bearer YOUR_API_KEY"

Risposta

Campo	Tipo	Descrizione
id	string	Identificativo del metodo di pagamento. Utilizzalo come paymentId al momento della creazione dell'ordine.
ccType	string	Marchio della carta, come Visa o Mastercard.
lastDigits	string	Le ultime quattro cifre della carta.
expiration	object	Data di scadenza della carta (mese e anno).
isDefault	boolean	Vero per il tuo metodo di pagamento predefinito.

Esempio di risposta

Copia

{
  "payments": [
    {
      "id": "7",
      "ccType": "visa",
      "lastDigits": "1007",
      "expiration": { "month": 7, "year": 2028 },
      "isDefault": true
    }
  ]
}

GET /api/orders - Elenca ordini

Elenca gli ordini effettuati, a partire dal più recente. Il numero di ciascun ordine corrisponde a quello restituito da POST /api/orders.

GET /api/orders

Copia

curl "https://www.stickermule.com/api/orders?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parametri della ricerca

Parametro	Tipo	Predefinito	Descrizione
limit	number	10	Numero di ordini da restituire, da 1 a 50.
offset	number	0	Numero di ordini da saltare prima di visualizzare i risultati.

Risposta

I risultati sono impaginati con limitazione e offset, e canLoadMore è vero quando sono disponibili altri ordini. Poiché l'impaginazione è basata su offset, le pagine possono cambiare quando vengono effettuati nuovi ordini.

Campo	Tipo	Descrizione
number	string	Numero d'ordine. Lo stesso valore restituito da POST /api/orders.
state	"complete" | "canceled" | "gift_unclaimed" | "ready_for_production" | "in_production" | "ready_to_proof" | "awaiting_scheduled_date"	Lo stato dell'ordine.
paymentState	"paid" | "credit_owed" | "balance_due" | "failed" | "checkout" | "completed" | "pending" | "processing" | "void" | null	Lo stato di pagamento dell'ordine, oppure nullo.
shipmentState	"backorder" | "canceled" | "partial" | "pending" | "ready" | "shipped" | "returned_for_reship" | "reship" | "delivered"	Stato della spedizione dell'ordine. Il valore predefinito è "in sospeso".
placedAt	string	Quando è stato effettuato l'ordine, espresso come timestamp ISO 8601.
currency	string	Valuta ISO 4217 in cui è stato addebitato l'ordine.
itemTotal	number	Totale parziale degli articoli, al netto delle spese di spedizione, delle imposte e degli sconti.
total	number	Totale complessivo addebitato, comprensivo di spese di spedizione e imposte, al netto degli sconti.
expectedDeliveryDate	string | null	Data di consegna stimata espressa come timestamp ISO 8601, oppure nullo.
deliveredAt	string | null	Quando è stato consegnato l'ordine, espresso come timestamp ISO 8601, oppure nullo.

Esempio di risposta

Copia

{
  "orders": [
    {
      "number": "R286234605",
      "state": "complete",
      "paymentState": "paid",
      "shipmentState": "shipped",
      "placedAt": "2026-07-20T14:03:00.000Z",
      "currency": "USD",
      "itemTotal": 79,
      "total": 88.5,
      "expectedDeliveryDate": "2026-07-27T00:00:00.000Z",
      "deliveredAt": null
    }
  ],
  "canLoadMore": true
}

POST /api/orders - Crea un ordine

Effettua un ordine per uno o più articoli salvati, inviati a un indirizzo salvato e addebitati su un metodo di pagamento salvato.

POST /api/orders

Copia

curl -X POST https://www.stickermule.com/api/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "id": "456", "quantity": 50 }],
    "addressId": "22",
    "paymentId": "7"
  }'

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
items	array	Sì	Articoli da ordinare. Deve contenere almeno un articolo.
items[].id	string	Sì	Un ID articolo da GET /api/items.
items[].quantity	number	Sì	Quantità da ordinare per l'articolo.
items[].size	TShirtSize | HoodieSize | null	No	Taglia del capo di abbigliamento, necessaria quando si ordinano capi (magliette, magliette di cotone pesante e felpe). Usa i valori sottostanti che corrispondono al prodotto. Omettere per gli altri prodotti.
addressId	string	Sì	Un ID indirizzo da GET /api/addresses.
paymentId	string	Sì	Un ID del metodo di pagamento ottenuto tramite GET /api/payments.

Un ordine può contenere fino a 50 articoli. Ogni quantità deve rispettare il minimo, il massimo e l'incremento del prodotto da GET /api/items.

Taglie dei capi di abbigliamento

Le taglie valide dipendono dal taglio del prodotto:

• Magliette e magliette di cotone pesante (TShirtSize): "sizeYS" | "sizeYM" | "sizeYL" | "sizeS" | "sizeM" | "sizeL" | "sizeXL" | "size2XL" | "size3XL" | "size4XL" | "size5XL" | "size6XL" | "size7XL"
• Felpe (HoodieSize): "sizeS" | "sizeM" | "sizeL" | "sizeXL" | "size2XL"

Risposta

Esempio di risposta

Copia

{
  "order": { "number": "R286234605" }
}

Errori

Gli errori restituiscono lo stato HTTP corrispondente e un corpo JSON contenente un tipo e un messaggio.

{
  "type": "UserInputError",
  "message": "items is required and must be a non-empty array"
}

Come si integra il tutto

• Puoi ordinare solo articoli che hai già ordinato in precedenza. Gli articoli personalizzati, il nastro adesivo per pacchi e le scritte in vinile non sono disponibili tramite l'API.
• Inizia leggendo i tuoi articoli, indirizzi e metodi di pagamento, poi passa i loro ID a POST /api/orders.
• GET /api/orders elenca gli ordini effettuati, a partire dal più recente. Il numero di ciascun ordine corrisponde a quello restituito da POST /api/orders.
• Per la maggior parte dei prodotti, quando ripeti un ordine si applicano le dimensioni originali (larghezza e altezza in pollici). L'abbigliamento (magliette, magliette di cotone pesante e felpe) utilizza invece una taglia: GET /api/items la restituisce sotto size con isSizeRequired vero, e occorre selezionare items[].size per ordinare. Le taglie valide dipendono dal prodotto ed è possibile cambiarle quando si ripete un ordine, ad esempio ripetendo un ordine di una maglietta taglia M come taglia L.
• GET /api/items e GET /api/orders sono impaginate con limite e offset. Gli endpoint per indirizzi e pagamenti non lo sono.