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:
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/apiEndpoint
Restituisce gli articoli che puoi riordinare. L'ID di ciascun articolo è valido come items[].id quando crei un ordine.
GET /api/itemscurl "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{ "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/addressescurl 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{ "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/paymentscurl 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{ "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/orderscurl "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{ "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/orderscurl -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. Risposta
Campo Tipo Descrizione order object L'ordine che è stato effettuato. order.number string Numero 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.
{
"type": "UserInputError",
"message": "items is required and must be a non-empty array"
}| Stato | Tipo | Significato |
|---|---|---|
| 400 | UserInputError | La richiesta non è valida, ad esempio a causa di un campo mancante o di un ID sconosciuto. |
| 401 | UnauthorizedError | L'intestazione Autorizzazione è mancante o non valida. |
| 403 | ForbiddenError | La 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.