API SPIPRINT

Especificação completa em OpenAPI 3.1 — importe no Insomnia, Postman ou gere um cliente com o openapi-generator.

Autenticação

Token no cabeçalho, em toda requisição:

Authorization: Bearer sp_live_xxxx.xxxxxxxxxxxxxxxx

Tokens que começam com sp_test_ operam em sandbox: registram o pedido, mas não geram cobrança nem produção real. Tokens sp_live_ valem em produção.

Endpoints

GET /api/v1/catalog produtos disponíveis

GET /api/v1/catalog/{sku} detalhe, com áreas de impressão

POST /api/v1/quotes preço e prazo

GET /api/v1/orders seus pedidos

POST /api/v1/orders criar pedido

GET /api/v1/orders/{id} consultar pedido

POST /api/v1/webhooks assinar eventos

DELETE /api/v1/webhooks/{id} remover assinatura

Criando um pedido

POST /orders exige o cabeçalho Idempotency-Key. Repetir a mesma chave devolve o mesmo pedido, com Idempotent-Replay: true. Rede instável não vira pedido duplicado.

curl -X POST https://srv1923523.hstgr.cloud/api/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "reference": "LOJA-9911",
    "items": [{ "sku": "CART-9X5", "quantity": 1000 }],
    "recipient": {
      "name": "Ana Souza",
      "zip": "01310-100",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  }'

Valores monetários

Todo valor nesta API é inteiro, em centavos de Real. 26904 significa R$ 269,04. Nunca use ponto flutuante para dinheiro.

Prazos

O campo production_days é o prazo de produção, em dias úteis. O prazo que você exibe ao seu cliente deve somar o prazo de transporte até o CEP de destino.

Webhooks

Cada entrega traz a assinatura:

X-Spiprint-Signature: t=1740000000,v1=<hmac_sha256>

O HMAC é calculado sobre <timestamp>.<corpo> com o segredo devolvido na criação da assinatura. Rejeite entregas com timestamp muito antigo — é a proteção contra replay.

Evento	Quando dispara
`order.created`	pedido registrado
`order.paid`	pagamento confirmado
`artwork.approved`	arte passou no pré-flight
`artwork.rejected`	arte reprovada — produção parada
`production.stage_changed`	mudou de etapa na fábrica
`shipment.created`	etiqueta emitida
`shipment.delivered`	entregue
`fiscal.issued`	nota fiscal emitida

Erros

Padrão RFC 7807. O code é estável; o title pode melhorar.

{
  "type": "https://.../api/docs#escopo_insuficiente",
  "title": "Este token não tem o escopo obrigatório \"orders:write\".",
  "status": 403,
  "code": "escopo_insuficiente"
}

Código	HTTP	Significa
`token_invalido`	401	token ausente, expirado ou revogado
`escopo_insuficiente`	403	o token não tem permissão para este recurso
`nao_encontrado`	404	SKU ou pedido inexistente
`idempotency_key_obrigatoria`	400	falta o cabeçalho em POST /orders
`idempotency_key_reutilizada`	422	mesma chave, corpo diferente
`cep_invalido`	422	CEP do destinatário inválido
`sku_invalido`	422	SKU fora do catálogo
`limite_excedido`	429	rate limit; veja `Retry-After`