Introdução

Seja bem-vindo(a) à documentação de referência das APIs ASA Investments.

Nossos Ambientes

Ambiente Endpoint

Sandbox: ambiente com mock e utilizado para acelerar o processo de onboarding, assim como o desenvolvimento de novas funcionalidades utilizando o processo API First.

https://api-sandbox.asa.com.br

Desenvolvimento: ambiente utilizado pelo time de desenvolvimento da API para a criação e correção.

https://api-dev.asa.com.br

Homologação: ambiente utilizado pelo time de desenvolvimento do consumidor da API, com uma versão estável e sem acesso ao ambiente produtivo.

https://api-qa.asa.com.br

Produção: ambiente utilizado pelo time consumidor da API, acessando ambiente produtivo. Não deve ser utilizado para teste.

https://api.asa.com.br

Autenticação

A autenticação das APIs do Marketplace é realizada com a informação de um token no cabeçalho (header) das requisições. O seguinte token é esperado em cada requisição:

Authorization: Basic [Code Base 64].


Obter credenciais do APP

Antes de iniciar as requisições para obter seu token de acesso, certifique-se de possuir o id (client id) e a senha do seu APP* (client secret) para utilizá-las. Caso não tenha esses dados anotados, você pode obtê-los neste portal, na página demonstrada na próxima imagem.

Imagem 1: Página onde é possível obter o Client Id e o Client secret neste portal.

Para criar sua primeira APP ou uma nova siga os próximos passos.


Obter um novo APP

Para obter um novo APP siga o passo a passo: Clique no botão Cadastrar Nova App

Imagem 2: Botão onde é possível criar seu APP.

Preencha os dados da APP, selecione as APIs que serão utilizadas e clique em Registrar. Considerar a lista de APIS AQUI

Imagem 3: Dados do seu APP.

Após a criação, enviar um e-mail (para o ponto focal ASA) solicitando autorização de acesso para o ambiente de homologação.


* Deverá ser criada uma App para acesso ao ambiente de testes e uma só para o ambiente de produção.


Fluxo de autenticação

Para exemplificarmos o fluxo de autenticação, utilizaremos o software Postman, amplamente utilizado para consumo e testes em APIs.

Poderá baixar a Collection de Authorization AQUI


Fluxo para obtenção de um token de acesso

Comece configurando a autenticação básica e a URL da requisição.

No postman, defina o método HTTP para POST e a URL como https://api-dev.asa.com.br/oauth2/v1/access-token. Em seguida, acesse a aba Authorization selecione o Type: Basic Auth e insira seu client_id no campo username e seu client_secret no campo password.

Imagem 4: Configuração da autorização para obter um token de acesso.


Na aba Body selecione x-www-form-urlencoded e passe a key grant_type com value client_credentials.

Imagem 5: Configuração do body.


Realizando a chamada teremos o seguinte retorno:

Imagem 6: access_token.


Chamada da API via Swagger

Ao realizar a chamada da API desejada via Swagger, no header Authorization devemos passar o Bearer + o access token gerado na chamada acima.

Imagem 7: Chamada da API via swagger.


Status Codes

Código Erro Descrição
200 OK

Sucesso.
400 Bad Request

A requisição possui parametro(s) inválido(s).
401 Unauthorized

O token de acesso não foi informado ou não possui acesso as APIs.
404 Not Found

O recurso informado no request não foi encontrado.
413 Request is to Large

A requisição está ultrapassando o limite permitido para o perfil do seu token de acesso.

422 Unprocessable Entity

A requisição possui erros de negócio.
429 Too Many Requests

O consumidor estourou o limite de requisições por tempo.
500 Internal Server Error

Erro não esperado, algo está quebrado na API.
Português, Brasil