Primeiros passosAutenticação

Autenticação na API eupreciso.com.br

Sequência de Autorização

A sequência de autorização tem início quando a aplicação do integrador redireciona o navegador para uma URL do eupreciso.com.br. Nesta URL serão incluídos alguns parâmetros que indicam o tipo de acesso que está sendo requerido. O eupreciso.com.br é o responsável pela autenticação do usuário e por confirmar a permissão de acesso a suas informações e recursos. Como resultado, o eupreciso.com.br retorna para a aplicação um código de autorização. Após receber o código de autorização, a aplicação poderá fornecê-lo (junto com sua identificação e senha) para obter em troca uma chave de acesso. A aplicação poderá então utilizar essa chave de acesso para acessar a API eupreciso.com.br.

Código de Autenticação

O código de autorização é obtido utilizando o servidor de autorização do eupreciso.com.br como intermediador entre o integrador/aplicação e o usuário.

O servidor de autenticação valida a requisição para certificar que todos os parâmetros obrigatórios estão validos e presentes. Se a requisição for válida, o servidor de autenticação tenta autenticar o usuário (pedindo seu login e senha) e obtém dele uma decisão de autorização.

Ao invés de solicitar a autorização diretamente ao usuário, o integrador o direciona para a página de autenticação do eupreciso.com.br que, após autenticar o usuário com seu login e senha, redireciona o usuário de volta ao integrador junto com o código de autorização.

Este código deverá ser utilizado logo em seguida para solicitar a chave de acesso que, caso seja aceita pelo usuário, permitirá o integrador a acessar suas informações através da API eupreciso.com.br. O código de autenticação é temporário e não pode ser reutilizado.

A URL usada para autenticar um usuário é https://www.eupreciso.com.br/auth/integradores/oauth

Os parâmetros HTTP GET suportados pelo servidor de autenticação do eupreciso.com.br para aplicações Web são:

ParâmetroValoresObrigatórioDescrição
response_typecodeSimDetermina que o valor esperado pela requisição será um código de autorização.
client_idA identificação do integrador que foi fornecida pelo eupreciso.com.br através do registro da aplicação.SimIdentifica o integrador que está enviando a requisição. O valor do parâmetro tem que ser idêntico ao valor fornecido pelo eupreciso.com.br durante o registro da aplicação.
redirect_uriO valor do parâmetro tem que ser idêntico a um dos URI cadastrados no registro da aplicação no eupreciso.com.br.Sim (se integrador cadastrou múltiplas URIs)Determina para qual servidor a resposta da requisição será enviada.
scopeConjunto de permissões que a aplicação solicita, separadas por espaço, não importa a ordem dos valores. Ver tópico Permissões.SimIdentifica o tipo de acesso à API eupreciso.com.br que a aplicação está requisitando. Os valores passados neste parâmetro serão os mesmos.
stateQualquer valor.NãoFornece qualquer valor que pode ser útil à aplicação ao receber a resposta de requisição.

Exemplo de URL:

https://www.eupreciso.com.br/auth/integradores/oauth?client_id=​1055d3e698d289f2af8663468127bd4b&redirect_uri=https://seuservidor.com.br/token&response_type=code&scope=autoupload&state=/profile

Permissões

Ao solicitar a chave de acesso, o integrador deve solicitar permissões através do parâmetro scope. Essas solicitações serão enviadas ao usuário para que ele possa permitir ou não o acesso.

O valor parâmetro scope é expressado como uma lista de valores (case sensitive) separados por espaços, não importando a ordem.

O servidor de autorização do eupreciso.com.br pode ignorar parcial ou totalmente as permissões solicitadas pelo integrador de acordo com as políticas do servidor de autenticação ou por instrução do usuário.

Segue abaixo a lista dos possíveis valores de permissão que podem ser solicitadas ao usuário:

Escopos em comum (imóveis, autos e marketplace)

ValorDescrição
basic_user_infoPermite o acesso às informações básicas do perfil do usuário, como nome, e-mail e dados de contato.
conversations-seller:writePermite o envio de mensagens via chat e marcação de conversas como lidas, possibilitando a interação com os clientes de forma automatizada.
conversations-seller:readPermite a visualização de conversas enviadas pelo chat, auxiliando no acompanhamento das interações com os clientes.

Escopos específicos (imóveis e autos)

ValorDescrição
autouploadPermite que o envio automático de anúncios para a plataforma, facilitando a automação do processo de publicação. (imóveis e veículos).

Escopos específicos (marketplace)

ValorDescrição
portfolio:writePermite a modificação de dados relacionados aos SKUs, incluindo inventários e preços, oferecendo controle total sobre o catálogo de produtos.
portfolio:readPermite que a consulta de dados de SKUs, inventários e preços, facilitando a visualização do catálogo de produtos.
order-order:writePermite a modificação de informações de pedidos, incluindo detalhes de entrega e atualizações de status.
order-order:readPermite a visualização de informações sobre pedidos, incluindo detalhes de entrega e status.
order-delivery:readPermite a visualização de informações sobre entregas, incluindo detalhes de rastreamento e status.
order-delivery:writePermite a modificação de informações sobre entregas, incluindo detalhes de rastreamento e status.
tickets-writePermite atualização ou edição tickets de suporte, possibilitando a gestão de solicitações de clientes.
tickets-readPermite a visualização de tickets de suporte abertos, facilitando o acompanhamento das solicitações de clientes.

Resposta da Requisição

A resposta será enviada para o redirect_uri, conforme especificado na URL da requisição. Se o usuário aprovar o acesso, a resposta conterá́ um código de autorização e o parâmetro state (se incluído na requisição). Se o usuário não aprovar, a resposta retornará uma mensagem de erro. Todas as respostas são retornadas ao servidor web por query string.

Confirmação da Autorização

Se o usuário conceder a permissão solicitada o servidor de autenticação gera um código de autorização e o envia para o integrador através dos seguintes parâmetros na URI de redirecionamento:

ParâmetroValoresObrigatórioDescrição
codeCódigo de autorização gerado pelo servidor de autenticação.SimCódigo de autorização utilizado para solicitar permissão de acesso a recursos de um usuário. Expira 10 minutos após ter sido gerado e não pode ser reutilizado.
stateMesmo valor enviado pelo integrador na requisição.Sim (se presente na requisição)Fornece qualquer valor que pode ser útil a aplicação ao receber a resposta de requisição.

Exemplo de resposta de confirmação: https://seuservidor.com.br/token?state=/profile&code=78dvsfb4ZdTpMllCgIEqUbWWiOhT

Erros de Autenticação

Se a requisição falhar devido a uma URI de redirecionamento inválida ou não enviada ou se o identificador do integrador (client_id) inválido ou não enviado o servidor de autenticação não irá redirecionar o usuário para o URI de redirecionamento.

Se o usuário negar acesso as permissões solicitadas ou se a requisição falhar por outros motivos o servidor de autenticação informa ao integrador qual foi o erro através de parâmetros enviados na URI de redirecionamento. Caso a URI passada seja diferente de uma das registradas no eupreciso.com.br, o servidor de autenticação responderá com um HTTP 400 (Bad Request).

Segue abaixo a lista dos parâmetros para erros de autenticação retornados pelo servidor de autenticação:

ParâmetroValoresObrigatórioDescrição
errorinvalid_requestSimA requisição tem parâmetro obrigatório faltando, inclui um parâmetro inválido ou está mal formatada por algum outro motivo.
errorunauthorized_clientSimO integrador não está autorizado a requisitar um código de autorização usando este método.
erroraccess_deniedSimO usuário ou servidor de autenticação negou a requisição ou o usuário não contratou um plano PRO.
errorunsupported_response_typeSimO servidor de autenticação não suporta obter um código de autorização utilizando este método.
errorinvalid_scopeSimA permissão solicitada é inválida, desconhecida ou mal formatada.
errortemporarily_unavailableSimNo momento, o servidor de autenticação está indisponível para receber requisições devido a uma manutenção ou sobrecarga temporária.
errorserver_errorSimO servidor de autenticação encontrou uma condição inesperada que impossibilitou a finalização da requisição.
stateMesmo valor enviado pelo integrador na requisição.Sim (se presente na requisição)Fornece qualquer valor que pode ser útil à aplicação ao receber a resposta de requisição.

Exemplo de resposta de erro: https://seuservidor.com.br/token?error=access_denied&state=/profile

Chave de Acesso

Chaves de acesso são credenciais usadas para acessar recursos protegidos de um usuário. É uma string que representa uma autorização emitida ao integrador. Esta chave representa permissões específicas, concedidas pelo usuário e emitida pelo servidor de autorização.

Segue um exemplo de requisição de chave de acesso.

POST /v1.0/integradores/oauth/token HTTP/1.1
Host: apps.eupreciso.com.br
Content-Type: application/x-www-form-urlencoded
 
code=4/P7q7W91aoMsCeLvIaQm6bTrgtp7&client_id=1055d3e698d289f2af8663725127bd4b&client_secret={sua_chave_de_segurança}&redirect_uri=https://seuservidor.com.br/token&grant_type=authorization_code

Requisição da Chave de Acesso

A URL usada para solicitar a chave de acesso será https://apps.eupreciso.com.br/v1.0/integradores/oauth/token

Após receber o código de autorização, o integrador poderá trocá-lo por uma chave de acesso através de uma nova requisição. Esta requisição deverá ser um POST HTTPS e conter os seguintes parâmetros: code, client_id, client_secret, redirect_uri e grant_type.

Resposta da Requisição

Se a solicitação da chave de acesso for válida e autorizada, o servidor de autenticação retorna um HTTP 200 (OK) com valor da chave de acesso. Se a solicitação falhar, o servidor de autenticação retorna um erro conforme tabela dos Erros de Autenticação.

Segue um exemplo de resposta bem-sucedida em formato JSON retornada pelo servidor de autenticação.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
 "access_token": "8/5VLTrMv2gLK8dqokN7xT",
 "token_type": "Bearer"
}

Resposta bem-sucedida

O servidor de autenticação gera uma chave de acesso e constrói a resposta adicionando os seguintes parâmetros no corpo da resposta HTTP 200 (OK):

ParâmetroValoresObrigatórioDescrição
access_tokenA chave de acesso retornada pelo servidor de autenticação.SimA chave de acesso que será utilizada para utilizar a API eupreciso.com.br.
token_typeBearerSimDefine o tipo de chave gerada.

Segue abaixo um exemplo de resposta de erro na requisição de uma chave de acesso:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
  "error": "invalid_request"
}

Resposta de Erro

O servidor de autenticação retorna um HTTP 400 (Bad Request) e inclui um dos seguintes valores na resposta:

ParâmetroValoresObrigatórioDescrição
errorinvalid_requestSimFalta de parâmetro obrigatório na requisição, inclui um parâmetro não suportado, inclui um parâmetro repetido, inclui múltiplas credenciais ou mal formato por algum outro motivo.
errorinvalid_clientSimFalha na autorização do integrador.
errorinvalid_grantSimCódigo de autorização inválido, expirado ou revogado, URI não é a mesma que a URI usada na requisição de autorização ou foi emitido para outro integrador.
errorunauthorized_clientSimO integrador autenticado não está autorizado a utilizar este tipo de autorização (grant_type).
errorunsupported_grant_typeSimO tipo de autorização (grant_type) não é suportado pelo servidor.
errorinvalid_scopeSimA solicitação de permissão enviada é inválida, desconhecida ou excede as permissões concedidas pelo usuário. Pode ocorrer essa resposta se o integrador estiver cadastrado com o tipo “autos” e solicitar escopo específico de marketplace (p. ex. order-order:read)

API eupreciso.com.br

Acesso à API

O integrador acessa os recursos protegidos do usuário apresentando a chave de acesso a API eupreciso.com.br. O servidor valida a chave de acesso e garante que as permissões concedidas são suficientes para acessar o recurso solicitado.

Segue abaixo um exemplo de como utilizar a API eupreciso.com.br para obter as informações básicas de um usuário:

POST /v1.0/integradores/basic_user_info HTTPS/1.1
Host: apps.eupreciso.com.br
User-Agent: Mozilla/5.0
Content-Type: application/json;charset=UTF-8
Authorization: Bearer 8/5VLTrMv2gLK8dqokN7xT

Ou utilizando uma aplicação por linha de comando como, por exemplo, o CURL:

curl -X POST https://apps.eupreciso.com.br/v1.0/integradores/basic_user_info \
-H 'Authorization: Bearer 8/5VLTrMv2gLK8dqokN7xT' \
-H 'User-Agent: Mozilla/5.0'

Recursos

A versão atual da API EU PRECISO fornece acesso aos seguintes recursos:

basic_user_info

Retorna uma lista com as informações básicas do usuário.

basic_user_info - Acesso

POST /v1.0/integradores/basic_user_info HTTPS/1.1
Host: apps.eupreciso.com.br

(b) Permissões

Qualquer chave de acesso com a permissão b​asic_user_info.

(c) Campos

basic_user_info - Chamada

POST /v1.0/integradores/basic_user_info HTTPS/1.1
Host: apps.eupreciso.com.br
Content-Type: application/json;charset=UTF-8
Authorization: Bearer 8/5VLTrMv2gLK8dqokN7xT

(e) Retorno

basic_user_info - Retorno

{
  "user_name": "João de Souza",
  "user_email": "[email protected]"
}

autoupload

Sistema de envio de anúncios de forma automática. Para mais informações, consultar o manual de Autoupload do eupreciso.com.br

Exemplos de Utilização

Ao lado podemos ver alguns exemplos de como se autenticar por esse nosso fluxo.

Exemplo de autenticação em Python

from fastapi import FastAPI
from fastapi.requests import Request
from fastapi.responses import RedirectResponse
import httpx
 
app = FastAPI()
 
@app.get("/")
 
async def home(request: Request):
     client_id = "6532fc73be26a0762f678a31"
     response_type = "code"
     scope = "basic_user_info"
     redirect_uri = "http://127.0.0.1:8000/oauth"
     state = "test"
     auth_host = "www.eupreciso.com.br"
     url = (f"https://{auth_host}/auth/integradores/oauth?client_id={client_id}&"
     f"response_type={response_type}&scope={scope}&redirect_uri={redirect_uri}&state={state}")
 
     return RedirectResponse(url)
 
@app.get("/oauth")
 
async def oauth(request: Request, code: str):
      client_id = "6532fc73be26a0762f678a31"
     client_secret = "c3vcFX6zMmmWeWRCCHWdc6obBFQ5jOlQ"
     grant_type = "authorization_code"
     redirect_uri = "http://127.0.0.1:8000/oauth"
     apps_host = "apps.eupreciso.com.br"
 
async with httpx.AsyncClient() as client:
      payload = {
          "code": code,
          "client_id": client_id,
          "client_secret": client_secret,
          "redirect_uri": redirect_uri,
          "grant_type": grant_type,
      }
      headers = {"Content-Type": "application/x-www-form-urlencoded"}
 
      response = await client.post(
          f"https://{apps_host}/v1.0/integradores/oauth/token", data=payload,
          headers=headers
      )
      data = response.json()
      access_token = data["access_token"]
 
    # Instead of sending the access_token in the payload, you will send it in the Authorization header.
    headers = {"Authorization": f"Bearer {access_token}"}
 
    return {"message": "Token retrieved and added to the Authorization header!", "headers": headers}

Python

A primeira função home é onde iremos montar uma URL para autenticação da conta EU PRECISO, usamos os seguintes dados:

  • client_id: Token fornecido pelo EU PRECISO que representa sua aplicação.
  • client_secret: Token fornecido pelo EU PRECISO que garante as credenciais da sua aplicação.
  • redirect_uri: Uma das URLs que você cadastrou na sua aplicação no EU PRECISO.

Após a autenticação ser bem-sucedida, iremos redirecionar para o redirect_uri enviado na requisição, enviando dois query parameters:

  • state: Valor escolhido e enviado, caso sua aplicação precise de algum dado extra.
  • code: O código retornado pelo EU PRECISO após autenticação para que possa ser obtido o access_token.

A segunda função oauth vai receber esse redirecionamento com os dados e irá realizar a requisição para obter o access_token e assim finalizando o nosso fluxo de autenticação.

Java

Selecione a aba Java para ver um exemplo de autenticação em Java.

Um exemplo em Java (com Spring, OkHttp3, Gson) de como utilizar nosso sistema de OAuth:

package com.oauth.tutorialoauth;
 
import com.google.gson.Gson;
import com.google.gson.annotations.SerializedName;
import okhttp3.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.view.RedirectView;
 
import java.io.IOException;
 
@RestController
public class OauthController {
 
    private static final String CLIENT_ID = "6532fc73be26a0762f678a31";
    private static final String CLIENT_SECRET = "c3vcFX6zMmmWeWRCCHWdc6obBFQ5jOlQ";
    private static final String AUTH_HOST = "www.eupreciso.com.br";
    private static final String APPS_HOST = "apps.eupreciso.com.br";
    private static final String REDIRECT_URI = "http://127.0.0.1:8080/oauth";
    private static final String GRANT_TYPE = "authorization_code";
    private static final String RESPONSE_TYPE = "code";
    private static final String SCOPE = "basic_user_info";
    private static final String STATE = "test";
 
    @GetMapping("/")
    public RedirectView home() {
        String url = String.format("https://%s/auth/integradores/oauth?client_id=%s&response_type=%s&scope=%s&redirect_uri=%s&state=%s",
                AUTH_HOST, CLIENT_ID, RESPONSE_TYPE, SCOPE, REDIRECT_URI, STATE);
        return new RedirectView(url);
    }
 
    @ResponseBody
    @GetMapping("/oauth")
    public Object oauth(@RequestParam("code") String code) throws IOException {
        OkHttpClient client = new OkHttpClient();
        Gson gson = new Gson();
 
        MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
        RequestBody body = okhttp3.RequestBody.create(
                "code=" + code +
                        "&client_id=" + CLIENT_ID +
                        "&client_secret=" + CLIENT_SECRET +
                        "&redirect_uri=" + REDIRECT_URI +
                        "&grant_type=" + GRANT_TYPE,
                mediaType
        );
 
        Request request = new Request.Builder()
                .url("https://" + APPS_HOST + "/v1.0/integradores/oauth/token")
                .post(body)
                .addHeader("Content-Type", "application/x-www-form-urlencoded")
                .build();
 
        try (Response response = client.newCall(request).execute()) {
            assert response.body() != null;
            String responseBody = response.body().string();
 
            // Deserialize the JSON response into an instance of AccessTokenResponse
            AccessTokenResponse accessTokenResponse = gson.fromJson(responseBody, AccessTokenResponse.class);
 
            // Return the whole AccessTokenResponse object
            return accessTokenResponse;
        }
    }
 
    public static class AccessTokenResponse {
        @SerializedName("access_token")
        private String accessToken;
 
        public String getAccessToken() {
            return accessToken;
        }
    }
}

PHP

Selecione a aba PHP para ver um exemplo de autenticação em PHP.

Um exemplo em PHP de como utilizar nosso sistema de OAuth:

<?php
 
# antes de usar este script, você deve registrar sua aplicação no Eu Preciso
 
$client_id = '6532fc73be26a0762f678a31';
$client_secret = 'c3vcFX6zMmmWeWRCCHWdc6obBFQ5jOlQ';
$response_type = 'code';
$scope = 'basic_user_info';
$redirect_uri ='http://127.0.0.1/oauth.php';
$state = 'bla';
$grant_type = 'authorization_code';
$auth_host = 'www.eupreciso.com.br';
$apps_host = 'apps.eupreciso.com.br';
 
$url = "https://{$auth_host}/auth/integradores/oauth?client_id={$client_id}&response_type={$response_type}&scope={$scope}&redirect_uri={$redirect_uri}&state={$state}";
 
# isso só deve ocorrer após o recebimento do 'code' no redirect do oauth
if (isset($_GET['code'])) {
    $code = $_GET['code'];
    $fields = array(
        'code' => $code,
        'client_id' => $client_id,
        'client_secret' => $client_secret,
        'redirect_uri' => $redirect_uri,
        'grant_type' => $grant_type
    );
 
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "https://{$apps_host}/v1.0/integradores/oauth/token");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);
 
    $data = json_decode($response);
 
    echo "access_token: {$data->access_token}<br />";
 
    // Exemplo de método para salvar o token
    //$generic_database->saveAccessToken($data->access_token);
 
    $request_data = array('access_token' => $data->access_token);
 
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "https://{$apps_host}/v1.0/integradores/basic_user_info");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request_data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Authorization: Bearer ' . $data->access_token,
        'Content-Type: application/json'
    ));
    $response = curl_exec($ch);
    curl_close($ch);
 
    echo "basic_user_info: {$response}";
}
 
?>
 
<a href="<?php echo $url; ?>">Fazer login no eupreciso.com.br</a><br><br>