A aplicação de integração — o par client_id e client_secret — normalmente é criada pela tela administrativa. Este artigo mostra como criá-la por chamada de API, útil quando você provisiona ambientes de forma automatizada.
Neste artigo
- Antes de começar
- Criar a aplicação
- O que a plataforma define por você
- No Postman
- Boas práticas
- Problemas comuns
Antes de começar
- Integrando um sistema só? O caminho pela tela é mais simples e está em Passo 1: credenciais para integrar com a API da Engage
- Você precisa de um
access_tokende um administrador com a permissão Gerenciar game. Como gerar o token está em Passo 4: Obtendo o access_token (POST /auth). - Faça primeiro em homologação:
https://sandbox.engage.bz/api/v1.
Criar a aplicação
1Envie a requisição
POST https://sandbox.engage.bz/api/v1/{customer_id}/integrations/integrate
Authorization: Bearer {access_token}
Content-Type: application/json
{
"client_application_id": "meusistema",
"name": "Integração do meu sistema",
"active": true
}| Campo | Obrigatório | Exemplo | Observação |
|---|---|---|---|
client_application_id | Sim | meusistema | É o client_id que você vai usar no POST /auth. Escolha um nome estável |
name | Sim | Integração do meu sistema | Nome exibido na tela de Integrações |
active | Sim | true | Sem ele, a aplicação é criada inativa |
Atenção
Envie sempre "active": true. A tela do Admin manda esse campo automaticamente, mas a API não assume nenhum valor: sem ele, a aplicação nasce inativa e o POST /auth passa a responder invalid_clientId.
2Guarde o client_secret
A resposta é HTTP 201 com a aplicação criada (valores ilustrativos):
{
"client_application_id": "meusistema",
"customer_id": "suainstancia",
"secret": "0000000000000000000000000000000a",
"name": "Integração do meu sistema",
"type_id": "NativeConfidential",
"active": true,
"access_token_life_time_in_minutes": 1440
}O campo secret é o seu client_secret. Guarde-o na hora, em local seguro.
Dica
Se perder o client_secret, consulte-o na tela administrativa: Outras Configurações › Integrações, abrindo a integração já cadastrada. Não existe reenvio por e-mail.
O que a plataforma define por você
Alguns valores são decididos pela plataforma e ignorados se vierem no corpo:
| Item | Valor | O que significa na prática |
|---|---|---|
secret | Gerado automaticamente, com 32 caracteres | Você não escolhe o client_secret |
type_id | Sempre NativeConfidential | O client_secret é obrigatório no POST /auth — o correto para integração servidor a servidor |
| Tempo de vida dos tokens | Definido no cadastro da aplicação | Não fixe número no código: use o expires_in da resposta do POST /auth |
No Postman
Abra a pasta 01 - Comece aqui, request Registrar aplicação de integração. Antes, gere o token pela pasta 02 - Autenticação — a chamada usa a variável accessToken.
Boas práticas
- Uma aplicação por sistema integrado. Assim é possível revogar uma sem afetar as outras.
- Escolha um
client_application_idestável. Ele também é usado nos vínculos de identificador do SSO; trocar de aplicação depois faz esses vínculos pararem de funcionar. - O
client_secretnunca sai do seu servidor. Nada de versionamento, log, código de navegador ou e-mail.
Problemas comuns
| O que aparece | Causa provável | O que fazer |
|---|---|---|
| HTTP 401 ou 403 | Token ausente, expirado ou de usuário sem a permissão Gerenciar game | Gere um novo token com um administrador que tenha a permissão, ou crie a aplicação pela tela |
| HTTP 400 | Corpo incompleto | Confira client_application_id, name e active |
invalid_clientId no POST /auth, logo depois de criar | Aplicação criada sem "active": true, ou client_id diferente do cadastrado | Ative a aplicação na tela de Integrações e confira se o client_id é exatamente o client_application_id |
Próximo passo
Com a aplicação criada, gere o token em Passo 4: Obtendo o access_token (POST /auth).
Precisa de ajuda?
Escreva para meajuda@engage.bz informando o customer_id, o ambiente e a mensagem de erro completa. Nunca envie o client_secret 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