Autenticações via API
Abordaremos abaixo os métodos de autenticação aceitos por nossa API Pública.
01 | Basic (Usuário/Senha)
Método simples de autenticação que precisará apenas do Usuário e Senha de um usuário previamente criado na base SGP. Os usuários podem ser criados no menu superior Sistema -> Usuários. Lembrando, alguns endpoints da API que façam uso desse método de autenticação, necessitam que o usuário possua liberações de permissão condizentes com a ação que desejem realizar no sistema.
Os dados de usuário e senha serão informados em Basic Auth e, com isso, irão informados no Header da requisição em Authorization, codificados em Base64.
Exemplificação:
O endpoint de listar Empresa pode ser utilizado com o método Basic. Esse endpoint possui parâmetros de filtragem não obrigatórios, que optei por não utilizar no exemplo abaixo, utilizando apenas o método de autenticação por usuário e senha, tendo sucesso no retorno.
02 | Token e App
Atualmente é o método mais seguro e recomendado para a API. O mesmo consiste em um Token e App gerados na plataforma SGP em Administração -> Integrações -> Tokens, e devem ser passados no body da requisição junto com os outros parâmetros/filtros necessários para o endpoint em questão.
Abaixo demonstraremos o método para criação desse token. Na página de gerenciamento de Tokens, selecione para Adicionar Token.
Na nova tela, defina um nome descrição para identificar mais fácil o Token que será gerado (esse nome não será utilizado na API). Logo abaixo, terá a opção de Definir ou Criar o nome da aplicação. Isso significa que você pode ter vários tokens com um mesmo App, ou um App para cada Token.
Em meu exemplo, criarei um novo App para esse token gerado, clicando no símbolo de + ao lado da lista seletora.
A descrição do App servirá, similarmente à do Token, apenas para identificação do App criado, que será o definido em Nome. Recomendamos que o mesmo seja um nome contínuo para facilidade de uso. No meu exemplo, defini o mesmo nome para a descrição e nome (app):
Abaixo terão algumas configurações opcionais para o Token, sendo elas:
- Hosts/Rotas permitidas: Restringir o recebimento de requisições desse Token apenas para os Hosts e Rotas definidos.
- Ativo: Ativar ou Inativar recebimentos por esse Token.
- Permite Baixar Título: Liberar a liquidação de títulos no sistema caso a requisição venha desse Token.
- Permite Cancelar Título: Liberar o cancelamento de títulos no sistema caso a requisição venha desse Token.
- Mapear Usuário: Alterações no SGP advindas desse token serão gravadas com o usuário definido nesse campo.
Por fim, meu token será criado dessa forma, e estará pronto para uso em minhas requisições:
Exemplificação:
O endpoint de Consultar Cliente da URA pode ser utilizado com o método Token/App. Esse endpoint possui parâmetros de filtragem obrigatórios e não obrigatórios. Em relação aos obrigatórios, além do Token/App, preciso mandar ao menos 1 dos filtros listados em nossa documentação do Postman, como cpf/cnpj, ou contrato, ou nome, ou login... etc. Em meu exemplo optarei apenas por passar o Token/App (obrigatórios) e CFP/CNPJ (obrigatório) para encontrar o cliente na base, obtendo êxito. OBS: O uso de form-data é opcional.
03 | CPF/CNPJ e Senha da Central
Esse método utiliza as credenciais do cliente final para realizar autenticação. Similarmente à Token/App, essas credenciais devem ser passadas no body da requisição também, sendo elas o CPF ou CNPJ do cliente e sua senha de acesso à Central de Assinante, que fica localizada dentro de algum de seus contratos de serviço, em específico ao que ele está se referindo ao enviar a requisição. Normalmente apenas os chamados da categoria Central em nossa API Pública aceitam esse tipo de chamado.
Se necessário, essa senha pode ser retornada utilizando o endpoint /api/ura/consultacliente/ da categoria URA, utilizando Token/App. Dado que, ao acessar o contrato do cliente, ele não possua esses dados, os mesmos podem ser criados ao final da página em Dados da Central do Assinante, conforme à seguir:
Exemplificação:
O endpoint Contrato - Listar da categoria central utiliza unicamente o CPF ou CNPJ do cliente e sua senha da central para encontrar os dados necessários. Assim, o request pode ser feito unicamente com esses dados:
 |
 |
 |
 |
 |
Acesso ao nosso site
www.tsmx.net.br