Se você já perdeu uma madrugada entendendo por que a integração com HubSpot parou de funcionar depois de um deprecation aviso de 90 dias, pode respirar. A partir de março de 2026, a plataforma abandona o velho esquema v1, v2, v3, v4 e passa a versionar suas APIs públicas por data, no formato /AAAA-MM/. A primeira versão oficial sob o novo modelo é a /2026-03/, e ela chega com algo que faltava há anos: previsibilidade.
O problema silencioso que ninguém queria admitir
Quem mantém integração com HubSpot há tempo sabe: o versionamento era uma bagunça elegante. Partes diferentes da API conviviam em números de versão diferentes, sem correspondência clara entre elas. Um endpoint de CRM estava na v3, outro relacionado estava na v4, e entender qual usar exigia abrir três abas de documentação e uma thread no fórum de desenvolvedores.
Pior: breaking changes podiam cair com aviso mínimo de 90 dias. Três meses é pouco para qualquer equipe que mantém múltiplas integrações em produção, ainda mais quando essa equipe também está lidando com o roadmap do próprio produto. O resultado era manutenção reativa, sprints interrompidas e aquele backlog de “atualizar integração HubSpot” que nunca saía do lugar até virar urgência.
Como funciona o versionamento baseado em data
A lógica é simples e se inspira em padrões já consolidados (Stripe e Shopify fazem algo parecido há anos). Cada versão carrega no nome o mês e ano do lançamento. A primeira é /2026-03/, a próxima será /2026-09/, depois /2027-03/, e assim por diante.
Três regras definem o novo contrato:
Cadência fixa semestral. Novas versões saem em março e setembro, acompanhando o ritmo de lançamentos da plataforma HubSpot. Nada de surpresas no meio do trimestre.
Versões imutáveis. Uma vez publicada, a versão não recebe breaking changes. Se algo incompatível precisa entrar, espera a próxima janela. O que você integrou hoje vai se comportar igual daqui a um ano.
Suporte mínimo de 18 meses. Esse é o ponto mais relevante para quem planeja ciclos longos. Saímos dos 90 dias de aviso para uma janela de seis versões à frente antes que algo saia de suporte.
Na prática, migrar do modelo antigo é uma substituição de path. Onde você tinha:
https://api.hubapi.com/crm/v3/objects/contactspassa a ter:
https://api.hubapi.com/crm/objects/2026-03/contactsA /2026-03/ cobre as superfícies mais recentes da API e é construída sobre os endpoints v3 e v4 atuais. Se você já está na versão mais nova de cada recurso, a migração é quase mecânica.
O cronograma de depreciação que você precisa colar no Jira
As versões antigas não somem de um dia para o outro, mas há prazos concretos:
As APIs de CRM /2025-09/, anunciadas no INBOUND 2025, continuam suportadas até o lançamento da /2027-03/. As APIs v4 atuais seguem vivas até março de 2027. Já as v1 a v3 permanecem funcionais por enquanto, mas a HubSpot já começou o processo de sunset, a API de Listas de Contatos v1, por exemplo, é desativada em 30 de abril de 2026.
Se sua integração ainda depende de algo em v1, isso é tarefa para este sprint, não para o próximo trimestre.
Por que a cadência importa mais que o formato
A mudança de nomenclatura é o que chama atenção, mas o ganho real está na cadência. Antes, o trabalho de manter uma integração com HubSpot era de vigilância permanente sobre o changelog. Qualquer deprecation anunciado virava uma corrida de três meses.
Com março e setembro como marcos fixos, as equipes podem alinhar migrações aos próprios ciclos de release. Você sabe, em janeiro, o que precisa fazer até agosto. Isso muda completamente como a integração entra no planning: deixa de ser emergência recorrente e vira item previsível de roadmap.
No entanto a plataforma de desenvolvedores seguiu a mesma convenção em paralelo. A versão 2026.03 dos Projetos da Plataforma de Desenvolvedores entrou em disponibilidade geral em 30 de março de 2026, usando o mesmo padrão de nomenclatura, sem criar dependência funcional entre as duas linhas, mas mantendo consistência mental para quem trabalha nos dois lados.
O bônus que interessa a quem está construindo agentes de IA
Na mesma atualização do Spring Spotlight 2026, saiu outra notícia relevante: o servidor MCP remoto da HubSpot saiu do beta e está agora em disponibilidade geral para todas as contas.
Para quem não acompanhou, MCP (Model Context Protocol) virou rapidamente o padrão de fato para conectar agentes de IA a ferramentas e fontes de dados. A versão GA do servidor MCP da HubSpot adiciona recursos de gravação, histórico de engajamento, objetos de conteúdo de marketing e contexto organizacional.
Visto que a combinação dos dois anúncios não é coincidência. Um agente de IA navegando por endpoints precisa da mesma previsibilidade que um desenvolvedor humano, talvez mais, porque não tem bom senso para interpretar um changelog ambíguo. Versionamento baseado em data é machine-readable de forma trivial: um agente consegue consultar, comparar e planejar migrações com lógica simples, sem precisar decifrar que “v3 da API de Contacts” é diferente de “v3 da API de Deals”.
Nos siga em nosso Instagram clicando aqui!