> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://supr-bundles-and-subscriptions.crisp.help/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Usar a API A API permite que seus próprios sistemas leiam e alterem assinaturas sem que ninguém abra o app, e avisa você sempre que uma assinatura muda, para que você não precise ficar consultando. Ela é útil se você tem uma loja headless, sincroniza assinaturas com um ERP ou um sistema de estoque, ou quer receber uma mensagem no Slack quando alguém cancelar. Enquanto a API é nova, nós a ativamos loja por loja. Se em **Configurações > Integrações > API** aparecer "Fale com o suporte para ativar a API nesta loja", envie uma mensagem no chat e ativaremos na sua. ## Como obter um token Acesse [**Supr Bundles & Subscriptions > Configurações > Integrações > API**](https://admin.shopify.com/apps/super-subscriptions/app/settings/integrations/api). No card **Tokens de API**: Dê ao token um **Nome** que descreva o que vai usá-lo, para que um token vazado possa ser rastreado, e escolha o que ele pode fazer: - **Ler assinaturas**, para um sistema que só gera relatórios. - **Alterar assinaturas**, para um que pausa, cancela ou reagenda. - **Ler endpoints de webhook** e **Gerenciar endpoints de webhook**, para configurar notificações de eventos a partir do seu próprio código, em vez de por esta página. Depois, clique em **Criar token**. Dê a cada sistema o próprio token, para poder desativar um sem mexer nos demais. **O token é exibido uma única vez.** Copie-o imediatamente. Nós não o armazenamos, então, se você o perder, será necessário criar um novo. **Revogar** interrompe imediatamente tudo o que usa esse token. ## Como chamar a API Envie o token como bearer token: ``` curl https://subscriptions.super-simple.co/api/v1/subscriptions \ -H "Authorization: Bearer sss_live_..." ``` Você pode listar assinaturas, buscar uma e, depois, pausar, retomar, cancelar, pular ou desfazer o pulo de um pedido, alterar a próxima data de cobrança ou a opção de assinatura, e adicionar, alterar ou remover os produtos dela. Cada alteração responde com a assinatura como ela está agora, então você nunca precisa consultar de novo logo em seguida. A API foi feita para ser chamada pelos seus próprios servidores. Não coloque um token em um navegador, em um app de celular ou em qualquer outro lugar que um cliente possa ver, porque qualquer pessoa que o encontrar poderá alterar suas assinaturas. ### Como repetir chamadas com segurança Se uma chamada expirar, não dá para saber se ela foi executada. Envie um cabeçalho `Idempotency-Key` com um valor seu em tudo que altera uma assinatura e, se você repetir a chamada com a mesma chave, devolvemos a primeira resposta em vez de executar duas vezes: ``` curl -X POST https://subscriptions.super-simple.co/api/v1/subscriptions/123/pause \ -H "Authorization: Bearer sss_live_..." \ -H "Idempotency-Key: 9f1c2a7e-4b0d-4f2a-9c3e-8a1b2c3d4e5f" ``` As chaves valem por um dia. Reutilizar uma chave com uma requisição diferente é recusado em vez de respondido, para que você não receba a resposta errada por engano. ### Quantas chamadas você pode fazer Toda loja começa com a cota padrão, exibida na lista **Limite de requisições** ao criar um token. Se sua integração precisar de mais, fale com a gente e aumentaremos, e as opções maiores passarão a aparecer nessa lista. Cada resposta traz `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`. Ao ultrapassar o limite, você recebe um `429` com um `Retry-After` indicando quantos segundos esperar. Também existe um limite somado para todos os tokens da sua loja, porque cada chamada também consome a cota da Shopify da sua loja. Se uma integração der errado, esse limite impede que ela deixe seu admin e sua loja virtual lentos. ## Notificações de eventos Em vez de nos pedir as alterações, faça com que nós avisemos você. Em **Supr Bundles & Subscriptions > Configurações > Integrações > API**, no card **Notificações de eventos**, informe uma **URL**, marque os eventos desejados e clique em **Adicionar endpoint**. Enviamos um POST para ela sempre que um evento acontece, e o corpo contém a assinatura exatamente como a API a retornaria. Os eventos disponíveis incluem uma assinatura ser criada, pausada, retomada, cancelada, renovada ou falhar, a próxima data de cobrança mudar, um pedido ser pulado ou ter o pulo desfeito, os produtos ou a opção de assinatura mudarem, e a forma de pagamento ou o endereço de entrega serem atualizados. Sua URL precisa usar https e estar acessível pela internet. ### Como conferir se uma notificação realmente veio de nós Quando você adiciona um endpoint, mostramos um segredo de assinatura, uma única vez. Cada entrega traz estes cabeçalhos: ``` X-SSS-Topic: subscription.paused X-SSS-Shop-Domain: your-store.myshopify.com X-SSS-Timestamp: 1758300000 X-SSS-Hmac-SHA256: ``` A assinatura é o HMAC SHA256 em base64 do timestamp, um ponto final e o corpo exato que enviamos, usando o seu segredo. Confira-a antes de confiar em qualquer coisa: ```js const crypto = require("crypto"); const expected = crypto .createHmac("sha256", YOUR_SECRET) .update(`${req.headers["x-sss-timestamp"]}.${rawBody}`) .digest("base64"); const ok = crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(req.headers["x-sss-hmac-sha256"]) ); ``` `YOUR_SECRET` é a string inteira que mostramos, começando com `sss_whsec_`. Use-a exatamente como está, incluindo esse prefixo. Use o corpo bruto exatamente como chegou, e não uma versão recodificada do JSON já interpretado, ou a assinatura não vai bater. Rejeite também qualquer entrega cujo timestamp tenha mais de cinco minutos. O timestamp faz parte do que é assinado, e é isso que impede que alguém reenvie uma entrega capturada antes. Você pode renovar o segredo de um endpoint a qualquer momento com **Novo segredo** na mesma página. Isso altera apenas aquele endpoint. **Desativar** pausa as entregas para um endpoint e **Remover** o exclui. ### Quando seu endpoint está fora do ar Uma entrega que falha é repetida com intervalos crescentes por cerca de um dia antes de desistirmos. Se um endpoint recusar 20 vezes seguidas, nós o desativamos e mostramos o motivo, para que uma URL desativada não continue sendo tentada para sempre. Clicar em **Ativar** limpa isso. ## Como obter ajuda Se algo não estiver funcionando, cada resposta traz um `X-Request-Id`. Informe-o ao suporte e conseguimos encontrar exatamente aquela chamada. ## Perguntas frequentes - **Existe uma API para assinaturas?** Sim, esta. Ela é ativada loja por loja enquanto é nova, então fale com o suporte para ativá-la. - **Preciso da API para alterar muitas assinaturas de uma vez, por exemplo mudar as datas de renovação?** Não para uma alteração pontual. Em **Assinaturas**, filtre a lista, marque as assinaturas e use a ação em massa **Reagendar**. A API é para alterações que seus próprios sistemas fazem com regularidade. - **Outro app (por exemplo, de afiliados ou ERP) pode ler os dados das assinaturas?** A Shopify só permite que o app que criou uma assinatura a leia, então outros apps não veem nossas assinaturas diretamente. Conecte seu sistema a esta API ou faça o outro app ler as tags de pedido e de cliente que o app pode adicionar, veja [Configurações de tags](https://supr-bundles-and-subscriptions.crisp.help/pt-br/article/tag-settings-1p7ox3c/). - **Perdi meu token.** Não podemos mostrá-lo de novo. **Revogue** o antigo e crie um novo token. - **Posso colocar o token no tema da loja ou em um app de celular?** Não. Qualquer pessoa que o veja poderia alterar suas assinaturas. Chame a API somente a partir do seu próprio servidor.