Para utilizar as APIs da Assertiva, é necessário criar as credenciais de acesso — Client ID e Secret — e, em seguida, gerar um token OAuth 2.0. Esse token deverá ser enviado nas requisições realizadas aos produtos da Assertiva.
1. Pré-requisitos
Antes de iniciar, verifique se:
Você possui um usuário com perfil administrativo no painel da Assertiva.
Sua empresa possui permissão para utilizar as APIs.
Você tem acesso ao Postman ou a outra ferramenta para realizar requisições HTTP.
O produto que será utilizado está habilitado para a sua empresa.
A documentação técnica das APIs está disponível em:
2. Criar as credenciais da API
As credenciais são compostas por:
Client ID: identifica a aplicação ou integração.
Secret: chave secreta utilizada junto ao Client ID para autenticação.
Passo a passo
Acesse o painel da Assertiva:
Faça login utilizando um usuário administrador.
Acesse a área API.
Selecione a opção para gerar uma nova credencial de API.
Selecione o usuário que ficará associado à credencial.
Clique em Gerar credencial.
Salve o Client ID e o Secret apresentados na tela.
Atenção: o Secret deve ser armazenado com segurança. Por motivos de segurança, ele pode não ficar disponível novamente após a criação. Não compartilhe essa informação nem a envie em chamados, mensagens ou repositórios públicos.
3. Gerar o token de acesso
Depois de criar o Client ID e o Secret, utilize essas credenciais para solicitar um token de acesso.
A autenticação utiliza o padrão OAuth 2.0, com o fluxo Client Credentials.
Dados da requisição
Método:
POSTURL:
https://api.assertivasolucoes.com.br/oauth2/v3/token
Autenticação:
Basic AuthFormato do corpo:
application/x-www-form-urlencodedParâmetro obrigatório:
Chave | Valor |
|
|
4. Gerar o token pelo Postman
4.1 Configurar a autenticação
Abra o Postman.
Crie uma nova requisição.
Selecione o método POST.
Informe a URL:
https://api.assertivasolucoes.com.br/oauth2/v3/token
Acesse a aba Authorization.
No campo Type, selecione Basic Auth.
Informe:
Username: Client ID
Password: Secret
O Postman deverá gerar automaticamente o cabeçalho de autorização correspondente.
4.2 Configurar o corpo da requisição
Acesse a aba Body.
Selecione o formato x-www-form-urlencoded.
Adicione o seguinte parâmetro:
Key | Value |
|
|
Envie a requisição clicando em Send.
5. Resposta de sucesso
Quando as credenciais estiverem corretas e a empresa possuir permissão para utilizar as APIs, a resposta será retornada no formato JSON, contendo o token de acesso.
Exemplo:
{ "access_token": "seu_token_de_acesso", "token_type": "bearer", "expires_in": 1800, "scope": "ALL" }
Campos da resposta
Campo | Descrição |
| Token que deverá ser utilizado nas requisições às APIs da Assertiva. |
| Tipo de autenticação do token. Normalmente, o valor retornado é |
| Tempo de validade do token, em segundos. |
| Escopos ou permissões disponíveis para a credencial. |
6. Utilizar o token nas requisições
Após gerar o token, inclua-o nas chamadas aos produtos da Assertiva utilizando o esquema Bearer Token.
O cabeçalho da requisição deve ser enviado no seguinte formato:
Authorization: Bearer SEU_TOKEN_DE_ACESSO
No Postman, essa configuração pode ser feita pela aba Authorization, selecionando:
Type:
Bearer TokenToken: informe o valor retornado no campo
access_token
Não inclua a palavra Bearer dentro do campo do token quando o Postman já estiver configurado para utilizar o tipo Bearer Token. Nesse caso, a ferramenta adicionará o prefixo automaticamente.
7. Validade do token
O token possui validade limitada por motivos de segurança. Conforme as orientações de integração, o token deve ser renovado periodicamente — normalmente, após 30 minutos.
A validade efetiva deve ser verificada no campo expires_in da resposta. Quando o token expirar, será necessário gerar um novo token utilizando o mesmo Client ID e Secret.
Não é necessário gerar um novo Client ID e Secret a cada renovação do token.
8. Principais erros
Erro 400 — Bad Request
Ocorre quando há algum problema na solicitação, como:
Parâmetro
grant_typeausente.Valor incorreto para
grant_type.Formato inadequado do corpo da requisição.
Exemplo de resposta:
{ "error": "unsupported_grant_type", "error_description": "Tipo de concessão inválido ou não permitido." }
Como corrigir:
Confirme se o corpo está configurado como
x-www-form-urlencoded.Verifique se foi informado:
Chave:
grant_typeValor:
client_credentials
Erro 401 — Unauthorized
Indica que as credenciais informadas são inválidas ou estão incorretas.
Exemplo de resposta:
{ "error": "invalid_request", "error_description": "Credenciais de acesso estão inválidas ou incorretas." }
Como corrigir:
Confirme o Client ID.
Confirme o Secret.
Verifique se não há espaços adicionais nos valores.
Certifique-se de que o Client ID foi informado como usuário e o Secret como senha no Basic Auth.
Gere novas credenciais caso o Secret tenha sido perdido.
Erro 403 — Forbidden
Indica que a empresa ou o usuário não possui permissão para utilizar a API.
Exemplo de resposta:
{ "error": "access_denied", "error_description": "Sua empresa não tem permissão para utilizar o portal via API." }
Como corrigir:
Entre em contato com o suporte ou atendimento da Assertiva para solicitar a liberação do acesso à API.
9. Boas práticas de segurança
Nunca compartilhe o Secret.
Não armazene credenciais diretamente no código-fonte.
Evite salvar o Secret em repositórios públicos.
Utilize variáveis de ambiente ou um gerenciador seguro de segredos.
Não registre o token completo em logs de aplicação.
Gere um novo token somente quando necessário.
Renove o token antes ou depois do término da validade.
Se houver suspeita de exposição do Secret, solicite a criação de uma nova credencial.
10. Resumo da configuração
Item | Valor |
Método |
|
Endpoint |
|
Autenticação |
|
Usuário | Client ID |
Senha | Secret |
Tipo do corpo |
|
Parâmetro |
|
Uso do token |
|
Para consultar os endpoints específicos de cada produto, parâmetros, exemplos de resposta e demais códigos de erro, acesse a: