Portal de Developers

Este guia cobre autorização OAuth e tokens usados pela Application. Para quem é Partner, Application (Client) e User, consulte Partner, aplicação e utilizador.

Fluxo de autorização

Quando a Application precisa de agir em nome de um User, o User deve conceder acesso via OAuth:

sequenceDiagram
    actor User
    participant App as Application
    participant OLX as OLX
    App->>User: 1. Mostra link de autenticação OLX
(/oauth/authorize)
    User->>OLX: 2. Abre o link no browser, inicia sessão
e aceita a Application
    OLX->>User: 3. Redirecionamento do browser com authorization_code
    User->>App: 4. O browser segue redirect_uri
com authorization_code
    App->>OLX: 5. Troca authorization_code por tokens
(grant_type: authorization_code)
    OLX->>App: access_token, refresh_token
    Note over App: Guarda tokens apenas para este User.
User não os vê.

Operações

Após autorização, o User trabalha apenas com a Application. A Application chama a API OLX com o access_token guardado. O User nunca envia nem recebe esse token:

sequenceDiagram
    actor User
    participant App as Application
    participant API as OLX API
    User->>App: 1. Inicia uma ação
(sem access_token OLX)
    Note right of User: ex. publicar esta oferta na OLX
    App->>API: 2. Pedido API com access_token
ex. POST /adverts
    Note over App,API: access_token usado aqui
(apenas Application ↔ API OLX)
Token fica na Application
User não o envia nem recebe
    API->>App: 3. Resposta API
sucesso / erro
    App->>User: 4. Mostra resultado ao User
(sem access_token OLX)

Tokens usados pela Application

No processo de autorização aparecem os seguintes elementos:

Contexto User — token no contexto de um User específico

Usado quando a Application age em nome de um User (vendedor / lister).

• authorization_code — código único que a Application recebe depois de o User conceder acesso à conta OLX. A Application troca este código por um access_token e um refresh_token.
• access_token — token que a Application envia com pedidos API em nome desse User. Tem duração limitada (veja expires_in na resposta do token). Quando expira, a Application usa o refresh_token para um novo access_token. Com access_token de User, a Application pode publicar anúncios, ler estados, receber mensagens e fazer outras ações no scope do utilizador. Um token do User John Doe não pode ser usado para o User Jane Humbug — o inventário de cada User permanece separado.
• refresh_token — token usado no contexto User para obter um novo access_token após expirar o anterior. Vive mais tempo que o access token. Pode ser usado até expirar ou ser invalidado. O fluxo de refresh pode devolver um novo refresh_token — guarde-o e use o mais recente. Se o refresh_token expirar ou ficar inválido, o User deve passar novamente pela autorização para um novo authorization_code e novos access_token e refresh_token.

Contexto Client — token no contexto da Application

Obtido com grant type client_credentials. Estes tokens não têm contexto de User. São usados para operações que não precisam de dados de User — por exemplo categorias, localizações e outros dados partilhados entre Users.

• access_token — token que a Application envia com pedidos API no contexto da Application (Client). Também tem duração limitada; ao expirar, a Application pede um novo com client_id / client_secret e grant_type: client_credentials. Não há refresh_token neste fluxo. Este token não pode agir em nome de um User — apenas acede a recursos partilhados.
• client_id / client_secret — credenciais da Application no Developer Portal. Juntamente com grant_type: client_credentials são usadas para obter um token em contexto Client. (client_credentials é o nome do grant type, não o segredo em si.)

Para detalhes sobre pedidos, endpoints e scopes, consulte a secção Authentication na documentação da API.

Para se registar como Partner e criar uma Application, siga Obter acesso à API.