OAuth de Terceiros

Visão Geral

O módulo de OAuth de Terceiros é o componente de segurança responsável por padronizar e gerenciar o ciclo de vida da autenticação OAuth 2.0 entre a plataforma Uappi e integradores externos. 🔐

Este fluxo permite que a plataforma obtenha de forma segura as credenciais de autorização (como access_token e refresh_token) necessárias para realizar operações em nome da loja em serviços parceiros, como gateways de pagamento, transportadoras e marketplaces.

O processo é desenhado para ser transparente e seguro, utilizando um fluxo dividido em duas etapas fundamentais:

1. Redirecionamento (Redirect): A Uappi gera um State Token único para preservar o contexto e a segurança da sessão, redirecionando o lojista para o ambiente de autorização do parceiro externo. ➡️

2. Confirmação (Confirmation): Após a aprovação no parceiro, o lojista retorna à plataforma Uappi. O sistema valida o State Token, processa a troca de códigos por tokens de acesso e persiste as credenciais de forma criptografada para uso futuro. ⬅️

O acesso às rotas de configuração deste fluxo requer autenticação administrativa (UserAuth) ou pública (PublicAuth) dependendo da etapa do redirecionamento, garantindo que apenas usuários autorizados iniciem vínculos de integração. 🔒

Entidades Envolvidas

• Integração (Integration): Define as regras e endpoints específicos de cada parceiro, identificados por um integrationCode único. 🧩
• Credenciais da Loja (Credentials): Local onde são armazenados os segredos de aplicação (Client ID, Client Secret) e os tokens resultantes do fluxo OAuth. 🔑
• State Token: Token temporário de alta segurança, armazenado em cache (Redis), que protege contra ataques de CSRF e vincula o início e o fim da autenticação. 🛡️
• Localização Original (Original Location): A URL de destino para onde o lojista deve retornar após a conclusão bem-sucedida de todo o fluxo. 📍

Notas e Considerações

A segurança do fluxo OAuth depende da integridade do State Token. Este token possui uma validade máxima de 30 minutos; se o lojista demorar mais do que este tempo para completar a autorização no parceiro, o fluxo expirará por segurança e precisará ser reiniciado. ⏳

Uma regra de negócio importante é a unicidade da credencial: o sistema valida se a integração já possui tokens ativos antes de processar uma nova confirmação, evitando a duplicidade de vínculos e garantindo que o token mais recente seja sempre o válido. ⚠️

Ao final do processamento, a plataforma garante o redirecionamento automático do lojista de volta ao seu contexto original de trabalho, proporcionando uma experiência de integração fluida e sem interrupções. ✅

Redirecionamento OAuth

Descrição

Este endpoint representa a primeira etapa (Etapa 1) do fluxo de autenticação OAuth 2.0 para integrações de terceiros.

Sua principal função é preparar o ambiente para a autenticação, gerando um token de estado (state token) que é armazenado em cache por 30 minutos.

Este token contém informações cruciais como o ID da credencial, a localização original do usuário e dados específicos da integração.

Para utilizar este endpoint, é necessário possuir estar autenticado como administrador UserAuth.

Após processar a solicitação, o endpoint retorna uma URL de redirecionamento para o integrador externo, já incluindo o token de estado gerado como um parâmetro de consulta.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/third-party/mercado-livre/oauth/redirect?credentialStoreId=123&originalLocation=https://minhaloja.com.br/admin/integracoes \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "redirectTo": "https://auth.integrador.com.br/oauth/authorize?client_id=...&state=oauthtoken-1-123-65f1a2b3"
3}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Confirmação OAuth

Descrição

Este endpoint representa a segunda etapa (Etapa 2) e final do fluxo de autenticação OAuth 2.0.

Ele é chamado pelo integrador externo após o usuário autorizar a aplicação. Sua função é validar o token de estado (state token) recebido, recuperar o contexto da autenticação e processar os dados enviados pelo integrador (como códigos de autorização ou tokens).

Durante o processamento, o sistema: 1. Valida se o token de estado ainda é válido e se existe no cache. 2. Decodifica o token para obter os dados originais da solicitação. 3. Comunica-se com o integrador para converter o código de autorização em tokens de acesso definitivos. 4. Salva ou atualiza as credenciais da loja no banco de dados.

Ao final, o usuário é redirecionado automaticamente para a URL definida no parâmetro originalLocation fornecido na etapa de redirecionamento.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/third-party/mercado-livre/oauth/confirmation?state=oauthtoken-1-123-65f1a2b3&code=TG-65f1a2b3c4d5e6

✅ Resposta de Sucesso

HTTP Status: 302 Found

Este endpoint não retorna um corpo de resposta JSON. Em caso de sucesso, o usuário é redirecionado automaticamente para a URL definida no parâmetro originalLocation (armazenado durante a etapa de redirecionamento).

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Autorização Appmax

Descrição

Este endpoint é utilizado durante o fluxo de integração com a Appmax.

Sua principal função é fornecer um identificador externo único (UUID) que é utilizado para identificar a transação ou o processo de autorização.

Diferente de outros endpoints da API, este retorna uma resposta pura, ou seja, sem o embrulho (envelope) padrão de status e dados da Uappi, contendo diretamente o objeto com o external_id.

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/third-party/appmax-api/oauth/authorize

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "external_id": "550e8400-e29b-41d4-a716-446655440000"
3}