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âmetro | Valores | Obrigatório | Descrição |
|---|---|---|---|
response_type | code | Sim | Determina que o valor esperado pela requisição será um código de autorização. |
client_id | A identificação do integrador que foi fornecida pelo eupreciso.com.br através do registro da aplicação. | Sim | Identifica 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_uri | O 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. |
scope | Conjunto de permissões que a aplicação solicita, separadas por espaço, não importa a ordem dos valores. Ver tópico Permissões. | Sim | Identifica o tipo de acesso à API eupreciso.com.br que a aplicação está requisitando. Os valores passados neste parâmetro serão os mesmos. |
state | Qualquer valor. | Não | Fornece 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)
| Valor | Descrição |
|---|---|
basic_user_info | Permite o acesso às informações básicas do perfil do usuário, como nome, e-mail e dados de contato. |
conversations-seller:write | Permite 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:read | Permite a visualização de conversas enviadas pelo chat, auxiliando no acompanhamento das interações com os clientes. |
Escopos específicos (imóveis e autos)
| Valor | Descrição |
|---|---|
autoupload | Permite 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)
| Valor | Descrição |
|---|---|
portfolio:write | Permite a modificação de dados relacionados aos SKUs, incluindo inventários e preços, oferecendo controle total sobre o catálogo de produtos. |
portfolio:read | Permite que a consulta de dados de SKUs, inventários e preços, facilitando a visualização do catálogo de produtos. |
order-order:write | Permite a modificação de informações de pedidos, incluindo detalhes de entrega e atualizações de status. |
order-order:read | Permite a visualização de informações sobre pedidos, incluindo detalhes de entrega e status. |
order-delivery:read | Permite a visualização de informações sobre entregas, incluindo detalhes de rastreamento e status. |
order-delivery:write | Permite a modificação de informações sobre entregas, incluindo detalhes de rastreamento e status. |
tickets-write | Permite atualização ou edição tickets de suporte, possibilitando a gestão de solicitações de clientes. |
tickets-read | Permite 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âmetro | Valores | Obrigatório | Descrição |
|---|---|---|---|
code | Código de autorização gerado pelo servidor de autenticação. | Sim | Có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. |
state | Mesmo 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âmetro | Valores | Obrigatório | Descrição |
|---|---|---|---|
error | invalid_request | Sim | A requisição tem parâmetro obrigatório faltando, inclui um parâmetro inválido ou está mal formatada por algum outro motivo. |
error | unauthorized_client | Sim | O integrador não está autorizado a requisitar um código de autorização usando este método. |
error | access_denied | Sim | O usuário ou servidor de autenticação negou a requisição ou o usuário não contratou um plano PRO. |
error | unsupported_response_type | Sim | O servidor de autenticação não suporta obter um código de autorização utilizando este método. |
error | invalid_scope | Sim | A permissão solicitada é inválida, desconhecida ou mal formatada. |
error | temporarily_unavailable | Sim | No momento, o servidor de autenticação está indisponível para receber requisições devido a uma manutenção ou sobrecarga temporária. |
error | server_error | Sim | O servidor de autenticação encontrou uma condição inesperada que impossibilitou a finalização da requisição. |
state | Mesmo 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_codeRequisiçã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âmetro | Valores | Obrigatório | Descrição |
|---|---|---|---|
access_token | A chave de acesso retornada pelo servidor de autenticação. | Sim | A chave de acesso que será utilizada para utilizar a API eupreciso.com.br. |
token_type | Bearer | Sim | Define 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âmetro | Valores | Obrigatório | Descrição |
|---|---|---|---|
error | invalid_request | Sim | Falta 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. |
error | invalid_client | Sim | Falha na autorização do integrador. |
error | invalid_grant | Sim | Có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. |
error | unauthorized_client | Sim | O integrador autenticado não está autorizado a utilizar este tipo de autorização (grant_type). |
error | unsupported_grant_type | Sim | O tipo de autorização (grant_type) não é suportado pelo servidor. |
error | invalid_scope | Sim | A 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/5VLTrMv2gLK8dqokN7xTOu 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 basic_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 oaccess_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>