Vai al contenuto principale

API Sticker Mule

L'API di Sticker Mule ti permette di riordinare i prodotti e di visualizzare gli articoli, gli indirizzi e i metodi di pagamento salvati dal tuo codice. Si tratta di una piccola API REST autenticata tramite una chiave API personale.

Cosa puoi fare

  • Rendi pubblici i tuoi articoli: qualsiasi articolo riordinabile dai tuoi ordini precedenti, con prezzi, grafiche e indicazioni relative alle quantità
  • Controlla la cronologia degli ordini per verificare se hai mai effettuato un ordine da un determinato negozio
  • Effettua ordini: l'addebito avverrà sul metodo di pagamento salvato e la spedizione sarà effettuata all'indirizzo salvato

Chiave API

Guida rapida

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

POST /api/orders
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

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

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

Parametri della ricerca

ParametroTipoPredefinitoDescrizione
limitnumber20Numero di articoli da restituire, da 1 a 50.
offsetnumber0Numero di elementi da saltare prima di visualizzare i risultati.
currencystringUSDCodice valuta ISO 4217 utilizzato per i prezzi.
localestringenLocalizzazione 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.

CampoTipoDescrizione
idstringIdentificativo dell'articolo. Utilizzalo come items[].id durante la creazione di un ordine.
namestring | nullNome personalizzato assegnato all'articolo, se presente.
productIdnumberIdentificativo prodotto Sticker Mule
productNamestring | nullNome del prodotto, oppure valore nullo se il prodotto non è più disponibile.
quantitynumberQuantità dell'ordine originale.
sizeRegularItemDimensions | TShirtDimensions | HoodieDimensionsTaglia 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.
isSizeRequiredbooleanVero se per il prodotto è necessario specificare una taglia di abbigliamento per riordinare (magliette, magliette di cotone pesante e felpe). Altrimenti falso.
buyingOptionsobject | nullQuantità di riordino consentite (minima, massima e incremento). Valore nullo se il prodotto non è disponibile.
retailPricenumber | nullPrezzo per la quantità minima, oppure valore nullo se il prezzo non è disponibile.
artworkUrlsstring[]URL delle grafiche approvate per l'articolo.
Esempio di risposta
{
  "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
}

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
curl https://www.stickermule.com/api/addresses \
  -H "Authorization: Bearer YOUR_API_KEY"

Risposta

CampoTipoDescrizione
idstringIdentificativo dell'indirizzo. Utilizzalo come addressId quando crei un ordine.
namestring | nullNome completo del destinatario.
firstNamestring | nullNome del destinatario.
lastNamestring | nullCognome del destinatario.
companyNamestring | nullNome dell'azienda, se presente.
addressLine1stringIndirizzo.
addressLine2string | nullEventuale riga aggiuntiva per l'indirizzo.
cityNamestringCittà.
stateNamestring | nullNome dello stato o della provincia, se presente.
stateAbbreviationstring | nullAbbreviazione dello stato o della provincia, se presente.
zipCodestringCAP.
countryIsostringCodice Paese ISO 3166, ad esempio US.
countryNamestringNome del Paese.
phonestring | nullNumero di telefono di contatto, se presente.
isDefaultbooleanVero per il tuo indirizzo di spedizione predefinito.
Esempio di risposta
{
  "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
    }
  ]
}

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
curl https://www.stickermule.com/api/payments \
  -H "Authorization: Bearer YOUR_API_KEY"

Risposta

CampoTipoDescrizione
idstringIdentificativo del metodo di pagamento. Utilizzalo come paymentId al momento della creazione dell'ordine.
ccTypestringMarchio della carta, come Visa o Mastercard.
lastDigitsstringLe ultime quattro cifre della carta.
expirationobjectData di scadenza della carta (mese e anno).
isDefaultbooleanVero per il tuo metodo di pagamento predefinito.
Esempio di risposta
{
  "payments": [
    {
      "id": "7",
      "ccType": "visa",
      "lastDigits": "1007",
      "expiration": { "month": 7, "year": 2028 },
      "isDefault": true
    }
  ]
}

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
curl "https://www.stickermule.com/api/orders?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parametri della ricerca

ParametroTipoPredefinitoDescrizione
limitnumber10Numero di ordini da restituire, da 1 a 50.
offsetnumber0Numero 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.

CampoTipoDescrizione
numberstringNumero 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" | nullLo 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".
placedAtstringQuando è stato effettuato l'ordine, espresso come timestamp ISO 8601.
currencystringValuta ISO 4217 in cui è stato addebitato l'ordine.
itemTotalnumberTotale parziale degli articoli, al netto delle spese di spedizione, delle imposte e degli sconti.
totalnumberTotale complessivo addebitato, comprensivo di spese di spedizione e imposte, al netto degli sconti.
expectedDeliveryDatestring | nullData di consegna stimata espressa come timestamp ISO 8601, oppure nullo.
deliveredAtstring | nullQuando è stato consegnato l'ordine, espresso come timestamp ISO 8601, oppure nullo.
Esempio di risposta
{
  "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
}

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

CampoTipoObbligatorioDescrizione
itemsarraySìArticoli da ordinare. Deve contenere almeno un articolo.
items[].idstringSìUn ID articolo da GET /api/items.
items[].quantitynumberSìQuantità da ordinare per l'articolo.
items[].sizeTShirtSize | HoodieSize | nullNoTaglia 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.
addressIdstringSìUn ID indirizzo da GET /api/addresses.
paymentIdstringSìUn ID del metodo di pagamento ottenuto tramite GET /api/payments.

Risposta

CampoTipoDescrizione
orderobjectL'ordine che è stato effettuato.
order.numberstringNumero d'ordine. Lo stesso valore riportato da GET /api/orders.
Esempio di risposta
{
  "order": { "number": "R286234605" }
}

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"

Errori

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

Esempio di risposta
{
  "type": "UserInputError",
  "message": "items is required and must be a non-empty array"
}
StatoTipoSignificato
400UserInputErrorLa richiesta non è valida, ad esempio a causa di un campo mancante o di un ID sconosciuto.
401UnauthorizedErrorL'intestazione Autorizzazione è mancante o non valida.
403ForbiddenErrorLa chiave API non è valida.
500—Qualcosa è andato storto da parte nostra, riprova più tardi.

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 millimetri). 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.

Domande

Invia un'e-mail a help@stickermule.com: leggiamo ogni messaggio.