API da Sticker Mule

Início rápido

1. Gerar uma chave API

Abra as definições da sua conta e, em Definições da loja, gere uma chave de API. Copie-o de imediato, pois só é apresentado uma vez.

2. Chamar a API

Envie a sua chave como um token Bearer. Este exemplo cria uma encomenda para um artigo guardado:

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

Autenticação

Todos os pedidos devem incluir a sua chave API como um token Bearer no cabeçalho Autorização.

Authorization: Bearer YOUR_API_KEY

• A API está disponível apenas para contas pessoais, não para contas de equipa.
• Cada conta tem uma chave. Gerar uma nova chave substitui a antiga.
• Trate a chave como uma palavra-passe. Pode ser utilizada para fazer encomendas e aceder aos seus dados guardados.

URL base

Todos os endpoints são relativos a este URL base.

https://www.stickermule.com/api

Endpoints

GET /api/items - Listar artigos

Devolve os artigos que podem ser encomendados novamente. O ID de cada item é válido como items[].id ao criar uma encomenda.

GET /api/items

Copiar

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

Parâmetros de consulta

Parâmetro	Tipo	Predefinido	Descrição
limit	number	20	Número de artigos a devolver, de 1 a 50.
offset	number	0	Número de elementos a ignorar antes de devolver os resultados.
currency	string	USD	Código de moeda ISO 4217 utilizado para preços.
locale	string	en	Configuração regional utilizada para os nomes e preços dos produtos.

Resposta

Os resultados são paginados com limite (limit) e deslocamento (offset), e canLoadMore é verdadeiro quando existem mais elementos disponíveis. Como a paginação é baseada em offset, as páginas podem mudar de posição à medida que chegam novas encomendas.

Campo	Tipo	Descrição
id	string	Identificador do artigo. Utilize-o como items[].id ao criar uma encomenda.
name	string | null	Nome personalizado que atribuiu ao artigo, se aplicável.
productId	number	Identificador de produto Sticker Mule.
productName	string | null	Nome do produto, ou nulo se o produto já não estiver disponível.
quantity	number	Quantidade da encomenda original.
size	RegularItemDimensions | TShirtDimensions | HoodieDimensions	Tamanho do artigo. No caso das t-shirts e das t-shirts heavyweight, um objeto de tamanho de vestuário com __typename igual a TShirtDimensions e um tamanho. No caso das sweats, __typename HoodieDimensions e um tamanho. Para todos os outros produtos, as dimensões físicas em polegadas, com __typename RegularItemDimensions e os campos largura e altura.
isSizeRequired	boolean	Verdadeiro se o produto exigir a indicação de um tamanho de vestuário para uma nova encomenda (t-shirts, t-shirts heavyweight e sweats). Caso contrário, falso.
buyingOptions	object | null	Quantidades permitidas para novas encomendas: mínimo, máximo e incremento. Nulo se o produto não estiver disponível.
retailPrice	number | null	Preço para a quantidade mínima, ou nulo se o preço não estiver disponível.
artworkUrls	string[]	URLs da arte aprovada para o artigo.

Exemplo de resposta

Copiar

{
  "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 - Listar moradas

Devolve as moradas de envio guardadas, com a morada predefinida em primeiro lugar. Cada ID é válido como addressId ao criar uma encomenda.

GET /api/addresses

Copiar

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

Resposta

Campo	Tipo	Descrição
id	string	Identificador de morada. Utilize-o como addressId ao criar uma encomenda.
name	string | null	Nome completo do destinatário.
firstName	string | null	Nome do destinatário.
lastName	string | null	Apelido do destinatário.
companyName	string | null	Nome da empresa, se aplicável.
addressLine1	string	Morada
addressLine2	string | null	Linha de morada adicional, se aplicável.
cityName	string	Cidade.
stateName	string | null	Nome do estado ou província, se aplicável.
stateAbbreviation	string | null	Abreviatura do estado ou província, se aplicável.
zipCode	string	Código postal.
countryIso	string	Código de país ISO 3166, como por exemplo, US (EUA).
countryName	string	Nome do país.
phone	string | null	Número de telefone de contacto, se aplicável.
isDefault	boolean	Isto aplica-se à sua morada de entrega predefinida.

Exemplo de resposta

Copiar

{
  "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 - Listar formas de pagamento

Devolve as suas formas de pagamento guardadas, com a morada predefinida em primeiro lugar. Cada ID é válido como paymentId ao criar uma encomenda.

GET /api/payments

Copiar

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

Resposta

Campo	Tipo	Descrição
id	string	Identificador da forma de pagamento. Utilize-o como paymentId ao criar uma encomenda.
ccType	string	Marca do cartão, como Visa ou Mastercard.
lastDigits	string	Últimos quatro dígitos do cartão.
expiration	object	Data de validade do cartão (mês e ano).
isDefault	boolean	Isto aplica-se ao seu método de pagamento predefinido.

Exemplo de resposta

Copiar

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

GET /api/orders - Listar encomendas

Lista as encomendas efetuadas, da mais recente para a mais antiga. O número de cada encomenda corresponde ao devolvido por POST /api/orders.

GET /api/orders

Copiar

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

Parâmetros de consulta

Parâmetro	Tipo	Predefinido	Descrição
limit	number	10	Número de encomendas a devolver, de 1 a 50.
offset	number	0	Número de encomendas a ignorar antes de apresentar os resultados.

Resposta

Os resultados são paginados com limit e offset, e canLoadMore é verdadeiro quando existem mais encomendas disponíveis. Como a paginação é baseada em offset, as páginas podem mudar de posição à medida que são efetuadas novas encomendas.

Campo	Tipo	Descrição
number	string	Número da encomenda. O mesmo valor devolvido por POST /api/orders.
state	"complete" | "canceled" | "gift_unclaimed" | "ready_for_production" | "in_production" | "ready_to_proof" | "awaiting_scheduled_date"	O estado da encomenda.
paymentState	"paid" | "credit_owed" | "balance_due" | "failed" | "checkout" | "completed" | "pending" | "processing" | "void" | null	O estado de pagamento da encomenda, ou nulo.
shipmentState	"backorder" | "canceled" | "partial" | "pending" | "ready" | "shipped" | "returned_for_reship" | "reship" | "delivered"	O estado de envio da encomenda. O valor predefinido é pendente.
placedAt	string	Data e hora em que a encomenda foi efetuada, no formato ISO 8601.
currency	string	Moeda, no formato ISO 4217, em que a encomenda foi cobrada.
itemTotal	number	Subtotal dos artigos, antes dos portes de envio, impostos e descontos.
total	number	Valor total cobrado, incluindo portes de envio e impostos, deduzidos os descontos.
expectedDeliveryDate	string | null	Data e hora estimadas de entrega, no formato ISO 8601 ou nulo.
deliveredAt	string | null	Data e hora em que a encomenda foi entregue, no formato de data e hora ISO 8601, ou nulo.

Exemplo de resposta

Copiar

{
  "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 - Criar uma encomenda

Efetua uma encomenda de um ou mais artigos guardados, com envio para uma morada guardada e pagamento através de um método de pagamento guardado.

POST /api/orders

Copiar

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 da solicitação

Campo	Tipo	Obrigatório	Descrição
items	array	Sim	Artigos a encomendar. Deve conter, pelo menos, um artigo.
items[].id	string	Sim	Um ID de um artigo proveniente de GET /api/items.
items[].quantity	number	Sim	Quantidade a encomendar deste artigo.
items[].size	TShirtSize | HoodieSize | null	Não	Tamanho da peça de vestuário, obrigatório ao encomendar vestuário (t-shirts, t-shirts heavyweight e sweats). Utilize os valores abaixo que correspondam ao produto. Omitir para outros produtos.
addressId	string	Sim	Um ID de morada proveniente de GET /api/addresses.
paymentId	string	Sim	Um ID de forma de pagamento proveniente de GET /api/payments.

Uma encomenda pode conter até 50 artigos. A quantidade de cada artigo tem de respeitar os valores mínimo, máximo e o incremento definidos para o produto em GET /api/items.

Tamanhos de vestuário

Os tamanhos válidos dependem do corte do produto:

• T-shirts e t-shirts heavyweight (TShirtSize): "sizeYS" | "sizeYM" | "sizeYL" | "sizeS" | "sizeM" | "sizeL" | "sizeXL" | "size2XL" | "size3XL" | "size4XL" | "size5XL" | "size6XL" | "size7XL"
• Sweats (HoodieSize): "sizeS" | "sizeM" | "sizeL" | "sizeXL" | "size2XL"

Resposta

Exemplo de resposta

Copiar

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

Erros

Os erros devolvem o estado HTTP correspondente e um corpo JSON com um tipo e uma mensagem.

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

Como tudo se encaixa

• Só é possível encomendar através da API artigos que já tenham sido encomendados anteriormente. Os artigos personalizados, a fita adesiva para embalagens e as letras em vinil não estão disponíveis através da API.
• Obtenha primeiro os seus artigos, moradas e métodos de pagamento e, em seguida, passe os respetivos IDs para POST /api/orders.
• O endpoint GET /api/orders lista as encomendas efetuadas, da mais recente para a mais antiga. O número de cada encomenda corresponde ao devolvido por POST /api/orders.
• A maioria dos produtos mantém as dimensões originais (largura e altura em polegadas) quando é encomendada novamente. No caso do vestuário (t-shirts, t-shirts heavyweight e sweats), é utilizado um tamanho de vestuário. O endpoint GET /api/items devolve esse tamanho no campo size, com isSizeRequired definido como verdadeiro, e deve enviar items[].size para efetuar a encomenda. Os tamanhos disponíveis dependem do produto e podem ser alterados ao encomendar novamente. Por exemplo, pode encomendar novamente uma t-shirt no tamanho sizeM como sizeL.
• Os endpoints GET /api/items e GET /api/orders utilizam paginação através dos parâmetros limit e offset; os endpoints de moradas e de pagamentos não.