Autenticação v1

Todas as chamadas para a API devem ser autenticadas através do header x-api-key.

O token de acesso é gerado utilizando informações disponíveis do painel do cliente e um token de integração, único por software house integrada. Esse token é disponibilizado após a homologação do sistema.

No proceso de autenticação serão retornados dois tokens (authToken e refreshToken), para que a software house utilize-os nas chamadas subsequentes.

O authToken deve ser enviado no header x-api-key em todas as chamadas para a API. Este token possui tempo de vida de 6 horas.

O refreshToken deve ser armazenado em local seguro e persistente (preferencialmente em um banco de dados) para ser utilizado quando o o authToken expirar. A automação deve tratar o erro de autenticação de código 401, atualizar o par de tokens utilizando refreshToken e refazer a chamada para a API com o novo authToken.

Na figura abaixo exibe o fluxo de autorização e uso do token nas chamadas subsequentes.

Autorização e uso do authToken

A figura abaixo exibe o fluxo de renovação de tokens, após a expiração do authToken.

Fluxo de renovação de tokens utilizando o refreshToken

Geração de tokens de acesso

Esta rota deve ser utilizada para gerar o primeiro par de tokens de acesso. Por questões de segurança é recomendado chamá-la apenas uma vez, durante o processo de ativação da integração, e armazenar os tokens retornados em banco de dados.

Utilizar essa rota para gerar os tokens durante a operação pode comprometer a integração.

A renovação dos tokens é feita utilizando o refreshToken retornado.

O refreshToken não possui prazo de validade. Ele se torna inválido apenas quando é feita a renovação dos tokens pela rota /auth/v1/refresh ou quando é feita uma nova autorização pela rota /auth/v1/authorize.

auth/v1/authorize

POST https://api-integration.goomer.app/auth/v1/authorize

content-type: application/json

Request Body

Name	Type	Description
integrationToken	string	Token de integração, único por software house, fornecido pela Goomer
storeId	string	Código da loja (ex.: G-1234) (disponível no painel do cliente)
clientSecret	string	Chave de integração (disponível no painel do cliente)
clientId	string	Id de integração (disponível no painel do cliente)

200 Se a autorização for realizada com sucesso, a API retornará o novo par de authToken e refreshToken para ser armazenado e utilizado pela software house.

{
    "authToken": "3TcR1ioGwZnpTHJDkAJqXafIT7k3hodO",
    "refreshToken": "g11sNjDn69pOqIf181aYoJ6aEePJnK9t"
}

400 Caso o alguma informação obrigatória não seja informada ou corpo da requisição não seja um JSON válido, a API retornará um erro de código 400.

Missing parameters!

401 Se as credenticiais informadas forem inválidas será retornado um erro 401, indicando que as informações de autenticação enviadas são inválidas.

Invalid credentials!

404 Se a loja informada não for encontrada será retornado um erro 404. Indicando que o parâmetro storeId deve ser verificado.

Store Not Found!

Atualização de tokens

Quando o authToken expira as chamadas para a API passam a retornar 401 Unauthorized, indicando que o token enviado é inválido. A software house deve chamar esta rota para gerar um novo par de tokens, armazenar o novo refreshToken, descartando o anterior, que foi invalidado, e refazer a chamada com o novo authToken recebido.

O authToken possui prazo de validade de 6 horas.

O refreshToken não possui prazo de validade, ele expira somente quando é substituído.

/v1/refresh

POST https://api-integration.goomer.app/auth/v1/refresh

content-type: application/json

Request Body

Name	Type	Description
refreshToken	string	último refreshToken recebido pela automação

200 Se o par de tokens for renovado com sucesso, a API retornará o novo par de authToken e refreshToken para ser armazenado e utilizado pela software house.

{
    "authToken": "3TcR1ioGwZnpTHJDkAJqXafIT7k3hodO",
    "refreshToken": "g11sNjDn69pOqIf181aYoJ6aEePJnK9t"
}

400 Caso o refreshToken não seja informado ou corpo da requisição não seja um JSON válido, a API retornará um erro de código 400.

Missing refreshToken parameter!

401 Se o refreshToken enviado for inválido a reposta será um 401. Neste caso será necessário fazer a autorização novamente a partir das informações do cliente e do token da software house.

Unauthorized