Workspace <> Organization

Por que estamos fazendo essa mudança?Copiar link da seção

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?Copiar link da seção

Esta página cobre a API pública documentada neste site. Todos os endpoints públicos são consultas GET, então a mudança aparece só no parâmetro de query e nos campos das respostas: nenhum endpoint público teve o caminho alterado nem recebe workspaceId no corpo da requisição. Rotas internas usadas apenas pela plataforma V4MOS.AI não fazem parte desta API.

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?Copiar link da seção

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 fazerCopiar link da seção

1. Substituir workspaceId por organizationId em query stringsCopiar link da seção

Antes:

GET /v1/google/accounts?workspaceId=abc-123

Depois:

GET /v1/google/accounts?organizationId=abc-123

2. Atualizar a leitura das respostasCopiar link da seção

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?Copiar link da seção

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.v4mos.ai/pt/essentials/workspace-organization/ 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çãoCopiar link da seçã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?Copiar link da seção

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