Empresa, permissões e módulos

A conta vem do token

A TAI é multiempresa: cada cliente tem a sua conta, isolada das demais. A conta não é um parâmetro da chamada — ela vem do token. Todo registro que você lê, cria ou altera pertence à conta do usuário autenticado, e um id de outra conta se comporta como inexistente.

Para agir em outra conta em que o mesmo usuário tem acesso, troque de conta com POST /auth/switch-tenant/{tenantId}.

Dentro da conta, empresas (/empresa) são os estabelecimentos — cada CNPJ, matriz ou filial. Setores, colaboradores, folha e ponto apontam para a empresa a que pertencem.

As três verificações

Cada rota passa, nesta ordem, por até três portões. A referência mostra os portões de cada operação no bloco Autorização.

Portão	Pergunta	Recusa
Papel	O usuário tem o papel exigido?	403 Acesso negado. Role insuficiente.
Módulo	A conta contratou o módulo da rota?	403 Módulo não habilitado para este tenant.
Permissão	O colaborador tem a funcionalidade, no nível exigido?	403 Funcionalidade não habilitada para este colaborador.

Papéis

Papel	Quem é
CUSTOMER_OWNER	Titular da conta. Tem acesso a todas as funcionalidades dos módulos contratados.
CUSTOMER_EMPLOYEE	Demais usuários. O acesso vem dos perfis de acesso e das exceções da pessoa.

Nível de acesso

Cada funcionalidade é concedida como somente leitura ou edição:

• rotas GET aceitam qualquer um dos dois níveis;
• rotas POST, PUT, PATCH e DELETE exigem edição.

As permissões se dão por perfil, na tela Configurações → Permissões. A API respeita exatamente o que está configurado ali — a mesma regra da tela, da Tali e do servidor MCP.

Usuário de integração precisa ser colaborador

A permissão por funcionalidade é verificada no colaborador ligado ao usuário. Um usuário sem colaborador vinculado recebe 403 em toda rota que exige funcionalidade. Cadastre o usuário de integração como colaborador (por exemplo, “Integração ERP”) e dê a ele um perfil com só o que a integração usa.

Conferir antes de chamar

GET /auth/me devolve os módulos da conta e as permissões efetivas do usuário. Compare com o bloco Autorização da operação na referência para saber, antes de chamar, se a rota vai responder.