# Atualizações de API Saiba como gerenciar versões de API e lidar com alterações importantes em nas principais versões. Confira o [Changelog do desenvolvedor](https://docs.stripe.com/changelog.md) para o registro completo de alterações na API da Stripe. Sua versão da API controla o comportamento da API e dos webhooks (por exemplo, quais parâmetros você pode incluir nas solicitações, quais propriedades aparecem nas respostas e assim por diante). Sua versão é definida na primeira vez em que você faz uma solicitação à API. Cada versão principal, como [Basil](https://docs.stripe.com/changelog/basil.md), inclui alterações que não são compatíveis com versões anteriores. Atualizar para uma nova versão principal pode exigir alterações no código existente. Cada versão mensal inclui apenas alterações compatíveis com versões anteriores e usa o mesmo nome da última versão principal. Você pode atualizar com segurança para uma nova versão mensal sem afetar o código existente. Para atualizar sua versão da API, siga [estas etapas](https://docs.stripe.com/upgrades.md#how-can-i-upgrade-my-api). Quando uma [plataforma Connect](https://stripe.com/connect) faz solicitações em nome de contas conectadas sem especificar uma versão API, a Stripe sempre usa a versão da API da plataforma. Seja qual for a versão da API da conta conectada, as solicitações da plataforma sempre retornam respostas correspondentes à versão da API da solicitação. ## Alterações compatíveis com versões anteriores A Stripe considera as seguintes alterações como compatíveis com versões anteriores: - Adicionar novos recursos de API. - Adicionar novos parâmetros de solicitação opcionais a métodos de API existentes. - Adicionar novas propriedades a respostas de API existentes. - Alterar a ordem de propriedades em respostas de API existentes. - Alterar o comprimento ou formato de strings opacas, como IDs de objeto, mensagens de erro e outras strings legíveis para humanos. - Isso inclui adicionar ou remover prefixos fixos (como `ch_` em IDs de cobranças). - Verifique se a integração consegue processar IDs de objetos gerados pela Stripe, que podem conter até 255 caracteres. Por exemplo, se você estiver usando MySQL, armazene os IDs em uma coluna `VARCHAR(255) COLLATE utf8_bin` (a configuração `COLLATE` garante a distinção entre maiúsculas e minúsculas nas buscas). - Adicionar novos tipos de eventos. - Verifique se o ouvinte de webhook gerencia tipos de eventos não familiares com cuidado. ## Atualize sua versão da API Se estiver executando uma versão mais antiga da API, atualize para a versão mais recente para aproveitar os novos recursos e as funções aprimoradas. A atualização de sua versão da API afeta: - As chamadas de API feitas por você sem um cabeçalho `Stripe-Version`: os parâmetros que você pode enviar e a estrutura de objetos retornados. - A estrutura de objetos recebidos com métodos do [Stripe.js](https://docs.stripe.com/payments/elements.md) como [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment). - A estrutura de objetos enviados aos seus endpoints de webhook (Account e [Connect](https://docs.stripe.com/connect/webhooks.md)). No entanto, se um endpoint tiver uma versão explícita definida, ele sempre usará essa versão. - As operações automatizadas do Billing realizadas pela Stripe (por exemplo, gerar uma *fatura* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) para um novo período de assinatura) usam a versão da API padrão da sua conta. Confira o log de alterações da API para obter detalhes sobre como sua versão padrão da API impacta essas operações. ### Veja a versão da sua API e a última atualização disponível no Workbench Veja a [versão da API usada por solicitações recentes](https://docs.stripe.com/workbench/guides.md#view-api-versions) na sua conta e a última atualização disponível na guia [Visão geral](https://dashboard.stripe.com/workbench/overview) do Workbench. Ao realizar uma atualização da API, especifique a versão da API que está sendo integrada em seu código para não depender da versão da API padrão da sua conta. Para testar uma versão mais recente de chamadas da API, defina o cabeçalho `Stripe-Version` (em ambientes de produção ou teste). Saiba como gerenciar o controle de versão em nossos [SDKs do lado do servidor](https://docs.stripe.com/sdks.md#server-side-libraries). ### Atualize e teste seus webhooks > [Eventos thin](https://docs.stripe.com/event-destinations.md#thin-events) de recursos da API v1 estão disponíveis em pré-visualização privada. Você pode usá-los para otimizar atualizações de integração sem alterar a configuração do seu webhook. Anteriormente, os eventos thin só eram compatíveis com recursos da API v2. [Saiba mais e solicite acesso](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Leia o nosso guia sobre [como lidar com o controle de versões de webhook](https://docs.stripe.com/webhooks/versioning.md). ### Faça a atualização Quando tiver certeza de que seu código funciona com a versão mais recente da API, faça o upgrade usando o Workbench: 1. Abra a guia [Visão geral](https://dashboard.stripe.com/workbench/overview) no Workbench. 2. Na seção **versões da API**, clique em **Atualização disponível**, que é visível se uma versão da API mais recente estiver disponível. 3. Revise qual versão da API será atribuída à sua conta e clique em **Atualizar**. Isso altera a versão usada pelas chamadas de API que não têm o cabeçalho `Stripe-Version` e também a versão usada para renderizar objetos enviados aos seus webhooks. > Os recursos dentro de [eventos recuperados da API](https://docs.stripe.com/api/events.md) são definidos pela versão padrão da API da sua conta no momento em que o evento ocorreu. Se o seu código recuperar eventos criados quando sua versão padrão da API era diferente, ele deve considerar quaisquer diferenças nas versões dos eventos. ### Reverter a versão da API Depois de atualizar a versão da sua API, você terá 72 horas para reverter à versão usada anteriormente pelo Workbench. Após esse retorno, os webhooks que foram enviados com a nova estrutura de objetos e falharam serão tentados novamente com a estrutura antiga. ## Informe-se [Changelog do desenvolvedor](https://docs.stripe.com/changelog.md): Registro completo de alterações na API da Stripe [Roteiro da Stripe](https://stripe.com/roadmap): Prévia dos próximos lançamentos de produtos da Stripe