> ## Documentation Index
> Fetch the complete documentation index at: https://docs.speedsellx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# O que mudou

> Para quem já integrava com o endereço antigo

A API do Painel do Seller passou a ser servida pela plataforma nova. **O endereço mudou. A sua chave de API não.**

## O que fazer agora

<Steps>
  <Step title="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`.

    ```diff theme={null}
    - https://api.speedsellx.io/seller/v1/products
    + https://api.speedsellx.io/v2/public/products
    ```
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Confirme com o ping">
    ```bash theme={null}
    curl https://api.speedsellx.io/v2/public/ping \
      -H "Authorization: Bearer $SPEEDSELLX_API_KEY"
    ```

    `200` com `{"data":{"status":"ok"}}` significa que a chave está válida no endereço novo.
  </Step>
</Steps>

O caminho dos endpoints não mudou dentro da API: o que era `/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.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

    | Campo                                 | Onde era enviado          |
    | ------------------------------------- | ------------------------- |
    | `secondary_color`                     | `PUT /checkouts/{id}`     |
    | `accept_redirect`, `refuse_redirect`  | `POST` e `PUT` de upsell  |
    | Flags de meio de pagamento no produto | `POST` e `PUT` de produto |

    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.
  </Accordion>

  <Accordion title="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](/apps/seller/guias/paginacao).
  </Accordion>

  <Accordion title="O envelope de erro mudou de forma">
    Era `{"error":{"type":"...","message":"..."}}`. Agora é:

    ```json theme={null}
    { "status": "error", "error": "insufficient_scope" }
    ```

    O código que você trata está em `error`, no primeiro nível, e não há mais campo `message` descritivo. Veja [Erros](/apps/seller/guias/erros).
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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}`](/apps/seller/reference/checkouts/obter-por-sku), que é a consulta de quem guardou o link público.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Um evento novo de webhook">
    O conjunto de eventos ganhou `order_subscription_trial_started`. São dez agora, contra nove antes.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## O que ficou de fora

Duas coisas que a documentação antiga descrevia e que não têm equivalente aqui:

<ResponseField name="Upload de imagem por URL externa">
  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.
</ResponseField>

<ResponseField name="Limite de requisições diferente por modo">
  O limite é o mesmo para uma chave `sk_live_` e para uma `sk_test_`: 120 requisições por minuto, por chave. Veja [Rate limits](/apps/seller/guias/rate-limits).
</ResponseField>

## O que ganhou

Endpoints que a API antiga não tinha:

<CardGroup cols={2}>
  <Card title="Reembolsos" icon="rotate-left" href="/apps/seller/reference/reembolsos/listar">
    Liste e consulte os pedidos de reembolso da conta.
  </Card>

  <Card title="Chargebacks" icon="scale-balanced" href="/apps/seller/reference/chargebacks/listar">
    Liste e consulte os chargebacks abertos contra a conta.
  </Card>

  <Card title="Webhooks" icon="satellite-dish" href="/apps/seller/reference/webhooks/listar">
    Registre, edite, silencie e remova destinos de webhook.
  </Card>

  <Card title="Checkout por sku" icon="magnifying-glass" href="/apps/seller/reference/checkouts/obter-por-sku">
    Encontre um checkout pelo identificador que aparece na URL pública.
  </Card>
</CardGroup>