Descontinuação do `workspaceId`

TL;DR — O identificador workspaceId foi renomeado para organizationId em toda a API V4 Marketing. O valor é exatamente o mesmo, muda só o nome do campo. Todas as chamadas que ainda usarem workspaceId passam a retornar HTTP 400 com o código WORKSPACE_ID_DEPRECATED.

Por que estamos fazendo essa mudança?

Estamos unificando o identity da plataforma V4. Antes, cada produto tinha seu próprio conceito de "workspace"; agora tudo passa a girar em torno de organização (organization), que é o conceito central do novo identity compartilhado entre todos os produtos V4.

Na prática, o identificador que você já usava continua o mesmo valor — só mudou o nome do campo para alinhar com o novo padrão.

O que muda exatamente?

Antes	Depois
Campo `workspaceId` (camelCase)	`organizationId`
Campo `workspace_id` (snake_case, em respostas)	`organization_id`

O que não muda:

Os valores continuam exatamente os mesmos. Se o seu workspaceId antes era abc-123, o novo organizationId também será abc-123.

A autenticação, headers e demais contratos da API continuam inalterados.

Quando entra em vigor?

A mudança é big bang, sem retrocompatibilidade. No momento do deploy combinado com os times de produto, a API passa a rejeitar qualquer chamada que ainda envie workspaceId.

O que você precisa fazer

1. Substituir `workspaceId` por `organizationId` em query strings

Antes:

Depois:

2. Atualizar a leitura das respostas

Antes:

{
  "customer_id": "12345",
  "workspace_id": "abc-123",
  "integration_name": "google_ads"
}

Depois:

{
  "customer_id": "12345",
  "organization_id": "abc-123",
  "integration_name": "google_ads"
}

Como saber se minha integração já foi atualizada?

Enquanto qualquer chamada da sua integração ainda enviar workspaceId, a API vai rejeitar o request com HTTP 400 e retornar:

{
  "code": "WORKSPACE_ID_DEPRECATED",
  "message": "O parâmetro \"workspaceId\" foi descontinuado. Com a unificação do identity do produto, o workspace agora é representado pelo \"organizationId\" (mesmo valor, novo nome). Consulte https://developers.v4.marketing/workspace-organization-2109239m0 para detalhes e instruções de migração."
}

Esse erro é a forma mais rápida de identificar pontos do seu código que ainda precisam ser atualizados — basta monitorar ocorrências do código WORKSPACE_ID_DEPRECATED no seu ambiente.

Quando todas as suas chamadas estiverem migradas, você para de receber esse erro e tudo volta a funcionar normalmente.

Checklist de migração

Antes de considerar sua integração migrada, verifique:

Todas as chamadas de query param ?workspaceId= foram trocadas por ?organizationId=

Qualquer código que lia response.workspace_id passou a ler response.organization_id

Seus testes automatizados passam contra a nova versão da API

Você não recebe mais o erro WORKSPACE_ID_DEPRECATED em nenhum ambiente

Dúvidas?

Se algo não ficou claro ou você encontrou um comportamento inesperado durante a migração, abra um chamado para o time V4 Marketing API ou entre em contato pelos canais oficiais de suporte a desenvolvedores.

Workspace <> Organization

Descontinuação do workspaceId#

Por que estamos fazendo essa mudança?#

O que muda exatamente?#

Quando entra em vigor?#

O que você precisa fazer#

1. Substituir workspaceId por organizationId em query strings#

2. Atualizar a leitura das respostas#

Como saber se minha integração já foi atualizada?#

Checklist de migração#

Dúvidas?#