Criar o usuário de integração

As chamadas REST de um sistema precisam de um usuário. Use um usuário dedicado — por exemplo, “Integração ERP” — em vez do login de uma pessoa: a integração não para quando alguém troca de senha ou sai da empresa, só enxerga o que precisa e aparece com o próprio nome no histórico de alterações.

Quando usar	Antes de qualquer integração REST de sistema
Porta	REST
Você vai precisar	Para montar: permissão COLABORADOR (edição) para cadastrar e PERMISSAO (edição) para dar o perfil — ou ser o dono da conta. Uma caixa de e-mail que receba a senha

Como funciona

A permissão por funcionalidade é conferida no colaborador ligado ao usuário, por isso o usuário de integração é um colaborador como os outros, com um perfil de acesso próprio.

POST /colaborador ("Integração ERP")  ──► usuário criado, senha por e-mail
POST /perfil-acesso ("Integração ERP")  ──► só as funcionalidades da integração
PUT  /perfil-acesso/colaborador/{id}    ──► o colaborador passa a ter só esse perfil
POST /auth                              ──► token JWT para as chamadas

O mesmo pode ser feito na tela: Organização → Colaboradores para o cadastro e Configurações → Permissões para o perfil.

Passo a passo

1. Cadastre o colaborador da integração. O login do usuário é o emailCorporativo; com "enviarEmail": true, a senha inicial chega nessa caixa.

   curl -X POST https://api.taitecnologia.com/colaborador \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "nome": "Integração ERP",
       "emailCorporativo": "integracao.erp@suaempresa.com.br",
       "empresa": { "id": 3 },
       "enviarEmail": true
     }'

   Guarde o id da resposta — é o colaboradorId da integração.

2. Monte o perfil de acesso. Liste em itens só as funcionalidades da jornada, cada uma com SOMENTE_LEITURA ou EDICAO. Os códigos são os que aparecem no bloco Autorização de cada operação na referência; GET /funcionalidade lista todos.

   POST /perfil-acesso
   Content-Type: application/json
   
   {
     "nome": "Integração ERP",
     "descricao": "Sincronização de colaboradores e estrutura com o ERP",
     "itens": [
       { "codigo": "COLABORADOR", "tipoAcesso": "EDICAO" },
       { "codigo": "SETOR", "tipoAcesso": "EDICAO" },
       { "codigo": "DEPARTAMENTO", "tipoAcesso": "EDICAO" },
       { "codigo": "SUBDEPARTAMENTO", "tipoAcesso": "EDICAO" },
       { "codigo": "CARGO", "tipoAcesso": "EDICAO" },
       { "codigo": "CENTRO_CUSTO", "tipoAcesso": "SOMENTE_LEITURA" },
       { "codigo": "TOKEN_API", "tipoAcesso": "EDICAO" }
     ]
   }

   Guarde o id do perfil. Só entram funcionalidades que quem cria o perfil já tem, no mesmo nível — o dono da conta concede tudo.

3. Dê o perfil ao colaborador da integração. O corpo é a lista completa de perfis que a pessoa passa a ter.

   PUT /perfil-acesso/colaborador/412
   Content-Type: application/json
   
   [27]

4. Confira o acesso efetivo.

   GET /perfil-acesso/colaborador/412/efetivo

   A resposta lista cada funcionalidade, o nível e de onde vem (perfil, exceção ou hierarquia).

5. Crie o token de integração. Entre na plataforma com o e-mail e a senha recebidos e, em Perfil → Meu Perfil, aba Integrações (API), crie um token. Para isso o colaborador da integração precisa da permissão TOKEN_API — inclua-a no perfil do passo 2. Guarde o token no cofre de segredos do seu sistema e envie-o em toda chamada; detalhes em Token de integração.

   GET /colaborador/page
   Authorization: Bearer tai_api_…

   O login por senha com Token JWT continua funcionando, se preferir.

Pelo seu agente de IA

O agente conectado por MCP responde perguntas como “o que o usuário Integração ERP pode acessar?” — é uma leitura do acesso efetivo. Criar perfil e conceder acesso são escritas: exigem credencial com escopo de escrita e a aprovação no seu cliente de IA.

Cuidados

• Módulo também conta. A permissão só vale se a conta contratou o módulo da rota. Confira em GET /auth/me os modulosHabilitados — veja Empresa e permissões.
• Não use o papel de dono da conta para a integração: ele acessa tudo, independentemente do perfil.
• O colaborador da integração aparece na lista de colaboradores e entra nas contagens da conta. Dê a ele um nome que deixe claro o que é.
• Mudar o perfil muda o acesso na hora, para todos que o têm. Uma integração nova pede um perfil novo, não o alargamento de um perfil que outras pessoas usam.
• POST /user/reset-password com {"identifier": "integracao.erp@suaempresa.com.br"} gera uma senha nova e a envia para a caixa da integração.