A sua integração autentica na API com um usuário da plataforma — o usuário de serviço. Ele funciona como qualquer outro usuário, mas é dedicado ao sistema, não a uma pessoa. Este artigo mostra como criá-lo e validá-lo em poucos minutos.
Neste artigo
- Antes de começar
- Por que um usuário só para a integração
- Criar o usuário
- Validar o usuário
- Boas práticas
- Problemas comuns
Antes de começar
- Acesso de administrador à instância e o
customer_iddela. As credenciais estão em Comece por aqui: credenciais para integrar com a API da Engage. - Crie primeiro em homologação (
https://sandbox.one.engage.bz) e valide lá antes de repetir em produção.
Cuidado
A instância pode já ter usuários de integração criados pela Engage, como integration e integracaoscorm. Eles são usados por rotinas da própria plataforma — não altere a senha nem use esses usuários na sua integração. Crie um próprio.
Por que um usuário só para a integração
- Ele não depende de uma pessoa. Quando alguém sai da empresa e o acesso é desativado, uma integração presa ao login dessa pessoa para junto.
- O log de auditoria fica correto. As ações do sistema aparecem atribuídas ao usuário de serviço, não a um colaborador.
- Ele escapa das políticas de senha. Com perfil administrador, não cai na troca de senha no primeiro acesso nem na expiração periódica — que derrubariam a integração sem aviso.
Criar o usuário
Na área administrativa, abra Usuários e clique em + usuário. A tela Novo Usuário abre na aba Geral — tudo o que você precisa está nela.
1Campos obrigatórios
Em Campos Obrigatórios, preencha nome, login e senha.
Tela Novo Usuário, aba Geral: nome e login do usuário de serviço preenchidos
| Campo | Exemplo | Observação |
|---|---|---|
| Nome e Sobrenome | Integração Meu Sistema | Deixe claro que é um usuário de sistema |
| Login | integracaomeucliente | Use integracao seguido do seu customer_id. É o username do POST /auth |
| Senha | — | Misture maiúsculas, minúsculas, números e caracteres especiais |
2Perfil de administração e e-mail
Role a aba Geral para baixo:
- Deixe Usuário ativo ligado e Bloquear usuário desligado.
- Ligue Habilitar perfil de administração.
- Em Selecione o perfil de administração, escolha Administrador.
- Em Campos Complementares, informe o E-mail — uma caixa da equipe, não a de uma pessoa.
- Clique em confirmar.
Mesma tela, mais abaixo: perfil de administração habilitado com o perfil Administrador e o e-mail da equipe
Importante
Sem o perfil de administração, a integração não funciona — o usuário cai nas políticas de senha e não tem permissão para os recursos da API.
Validar o usuário
Gere um token com ele. No Postman, preencha adminUser e adminPass no Environment e rode a pasta 02 - Autenticação, request Obter access_token (grant_type=password). O passo a passo completo está em Passo 2 — Obtendo o access_token (POST /auth).
Sucesso
Resposta HTTP 200 com um access_token significa que o usuário está pronto. Para logins de integração, a resposta não traz os campos is_admin e is_blocked — é o comportamento esperado.
Boas práticas
- Não use esse usuário para entrar pela tela. Ele existe só para a API.
- Programe a troca de senha. Trocar a senha interrompe a autenticação da integração até o valor ser atualizado no seu servidor.
- A senha nunca viaja junto da documentação. Ela vai por canal seguro, em mensagem separada.
Problemas comuns
| O que aparece | Causa provável | O que fazer |
|---|---|---|
invalid_credentials | Login ou senha errados, ou usuário inativo | Confira o login e se o usuário está ativo |
change_password_on_first_access | Usuário sem perfil administrador caiu na política de primeiro acesso | Ligue Habilitar perfil de administração e escolha Administrador |
password_is_expired | Senha vencida pela política da instância | Sinal de usuário sem perfil administrador — ajuste o perfil e redefina a senha |
user_is_blocked | Usuário bloqueado na plataforma | Desbloqueie em Usuários |
max_attempts_reached | Muitas tentativas com senha errada | Aguarde alguns minutos ou redefina a senha |
Erros de aplicação (client_id, client_secret) e de instância (customer_id) estão em Comece por aqui: credenciais para integrar com a API da Engage.
Próximo passo
Com o usuário criado, gere o token de acesso em Passo 2 — Obtendo o access_token (POST /auth).
Precisa de ajuda?
Escreva para meajuda@engage.bz informando o customer_id e o ambiente. Nunca envie a senha do usuário de serviço por e-mail.
Este artigo foi útil?
Que bom!
Obrigado pelo seu feedback
Desculpe! Não conseguimos ajudar você
Obrigado pelo seu feedback
Feedback enviado
Agradecemos seu esforço e tentaremos corrigir o artigo