O que fazer agora
1
Troque o prefixo das chamadas
O que era
https://api.speedsellx.io/seller/v1 agora é https://api.speedsellx.io/v2/public. O endereço antigo saiu do ar e responde 404.2
Mantenha a sua chave
O formato
sk_live_{prefixo}.{segredo} é o mesmo, os escopos são os mesmos e a chave que você já tem continua valendo. Não é preciso gerar uma chave nova nem trocar o header Authorization.3
Confirme com o ping
200 com {"data":{"status":"ok"}} significa que a chave está válida no endereço novo./products continua sendo /products, agora depois de /v2/public.
O que mudou no comportamento
Estas são as diferenças que podem quebrar uma integração que já funcionava. Confira cada uma antes de subir a troca.PUT de checkout e PUT de upsell fazem merge, não substituição
PUT de checkout e PUT de upsell fazem merge, não substituição
Uma requisição que envia só um campo altera só aquele campo. O resto da configuração fica como está: os meios de pagamento, o backredirect e os scripts customizados do checkout; os textos dos botões e o
product_link_id do upsell.Se a sua integração reenviava a representação inteira para “não perder nada”, ela continua funcionando. O que mudou é que não é mais necessário.O PUT /public/products/{id} continua sendo substituição: envie todos os campos obrigatórios.Campos que a API antiga aceitava e esta recusa com 422
Campos que a API antiga aceitava e esta recusa com 422
Não são mais aceitos e derrubam a requisição inteira, em vez de serem ignorados em silêncio:
Nenhum deles tinha onde ser gravado, então recusar é o comportamento honesto. Remova-os do corpo da requisição.
accept_redirect e refuse_redirect continuam aparecendo na leitura de um upsell. Só não podem ser escritos por aqui.Listagens vêm de 15 em 15, não de 100 em 100
Listagens vêm de 15 em 15, não de 100 em 100
O
per_page padrão passou de 100 para 15. Se você percorria páginas contando com 100 itens, envie per_page explicitamente. Veja Paginação.O envelope de erro mudou de forma
O envelope de erro mudou de forma
Era O código que você trata está em
{"error":{"type":"...","message":"..."}}. Agora é:error, no primeiro nível, e não há mais campo message descritivo. Veja Erros.Pedidos filtram por type, não por status
Pedidos filtram por type, não por status
GET /public/orders aceita type (main, upsell, subscription_renewal). Não há filtro por status: filtre no seu lado, pelo campo status de cada pedido.Os campos de valor do pedido também mudaram de nome: settlement_total e settlement_seller, com settlement_currency, no lugar de amount e amount_seller.Listar checkouts não recebe mais product_id
Listar checkouts não recebe mais product_id
GET /public/checkouts lista os checkouts da conta inteira, paginados. Não aceita product_id, status nem search.Para chegar em um checkout específico, use GET /public/checkouts/{id} ou o novo GET /public/checkouts/by-sku/{sku}, que é a consulta de quem guardou o link público.Upsell nasce publicado
Upsell nasce publicado
Sem
status no corpo, um upsell criado agora nasce published. Antes nascia draft, o que criava ofertas que o funil pulava. Envie status: "draft" se você dependia do comportamento antigo.Editar um webhook não liga nem desliga entregas
Editar um webhook não liga nem desliga entregas
O
PUT /public/webhooks/{id} não lê mais active: uma edição de rotina não pode silenciar as entregas por acidente. Para ligar ou desligar, use PATCH /public/webhooks/{id}/toggle.O POST /public/webhooks continua aceitando active, então dá para registrar uma assinatura já muda.Um evento novo de webhook
Um evento novo de webhook
O conjunto de eventos ganhou
order_subscription_trial_started. São dez agora, contra nove antes.Produto aceita três campos novos
Produto aceita três campos novos
sku, trial_days e deliverable_content podem ser escritos na criação e na substituição. A leitura já respondia os três; antes não havia como defini-los pela API.Upsell responde product_link_id
Upsell responde product_link_id
A leitura de um upsell agora inclui
product_link_id, que é o produto que a oferta cobra quando não é o próprio produto do funil. É o campo que torna o merge do PUT possível sem perder o que a oferta vende.Alterar preço sem moeda pode responder 422
Alterar preço sem moeda pode responder 422
PATCH /public/products/{id}/price sem currency, em um produto que ainda não tem moeda gravada, responde 422. A API não escolhe por você em que moeda o comprador será cobrado. Em um produto que já tem moeda, currency continua opcional.O que ficou de fora
Duas coisas que a documentação antiga descrevia e que não têm equivalente aqui:O campo
image do produto e os cinco slots de imagem do checkout aceitam um data URI base64 (data:image/...;base64,...) ou o valor já gravado, devolvido como veio. Uma URL externa não é baixada. Se você enviava a URL de uma imagem hospedada em outro lugar, baixe o arquivo e envie o base64.O limite é o mesmo para uma chave
sk_live_ e para uma sk_test_: 120 requisições por minuto, por chave. Veja Rate limits.O que ganhou
Endpoints que a API antiga não tinha:Reembolsos
Liste e consulte os pedidos de reembolso da conta.
Chargebacks
Liste e consulte os chargebacks abertos contra a conta.
Webhooks
Registre, edite, silencie e remova destinos de webhook.
Checkout por sku
Encontre um checkout pelo identificador que aparece na URL pública.