Pular para o conteúdo principal

Autenticação

Ecommerce Carteira#

Bem-vindo à documentação do fluxo de autenticação da Carteira PicPay. Nesta página, explicaremos como autenticar e acessar nossos serviços utilizando o fluxo de autenticação OAuth 2.0 do Ecommerce Carteira com o grant type client_credentials. O protocolo OAuth 2.0 fornece uma maneira segura de conceder acesso a recursos protegidos em nome de um cliente. Para obter mais informações sobre o Ecommerce Carteira, consulte a RFC 6749.

Fluxo de Autorização com Grant Type client_credentials#

O grant type client_credentials é uma variante do fluxo OAuth 2.0. Ele foi escolhido como o método de autorização para proteger nossa API. Esse grant type é ideal para cenários em que a autenticação ocorre entre sistemas, sem envolver usuários finais. Para entender mais sobre o grant type client_credentials, consulte a seção correspondente na RFC 6749.

Etapas#

Para acessar nossos serviços protegidos, é necessário obter um token de acesso seguindo as seguintes etapas:

  1. Habilite o Ecommerce Carteira.
  2. Gere as credenciais no Painel Lojista.
  3. Realize a solicitação de autorização para obter um token de acesso e autenticar suas requisições.
  4. Utilize o token de acesso como um Bearer Token nas chamadas à API para autenticação.

Habilitando o Ecommerce Carteira#

Para obter as credenciais, será necessário ter o Ecommerce Carteira habilitado. Caso ainda não tenha habilitado, siga os passos abaixo:

  1. Acesse o Painel Lojista e faça o login;
  2. Navegue até a seção Integrações no menu lateral;
  3. Clique no botão "Habilitar" em Carteira Picpay Ecommerce;
Atenção!

Caso já possua o Ecommerce Carteira habilitado, passe para a próxima etapa.

Obtendo as Credenciais#

Carteira Picpay - Ecommerce#

Esse tipo de credencial é utilizada em integrações que se conectam diretamente à API PicPay. Ela é composta por um client_id, client_secret e x-seller-token. O client_id é um identificador único para o cliente, o client_secret é uma chave secreta que deve ser tratada com cuidado para evitar acesso não autorizado e o x-seller-token é o token enviado pelo Ecommerce Carteira ao fazer requisições ao cliente (webhook/callback). Siga os passos abaixo para obter suas credenciais:

  1. Acesse o Painel Lojista e faça o login;
  2. Navegue até a seção de Integrações no menu lateral;
  3. Localize a integração Carteira Picpay - Ecommerce;
  4. Clique no botão “Gerar credenciais”;
  5. Guarde com segurança o client_id, client_secret e x-seller-token que aparecem na tela;
Cuidado!

Este é o único momento em que o PicPay exibirá o campo client_secret. Portanto, é importante anotar essas credenciais em um local seguro antes de fechar a tela com as informações. Posteriormente, você poderá consultar essas credenciais na mesma aba, no entanto, apenas o campo client_id será exibido para fins de identificação das credenciais.

Atenção!

Caso já exista uma credencial gerada para a integração selecionada e você gere uma nova, a credencial anterior desta integração será revogada após um prazo de 7 dias.

Carteira Picpay - Ecommerce Plug-ins e Plataformas#

Essa credencial deve ser usada em integrações indiretas, por meio de plug–ins e plataformas de mercado. As credenciais são compostas por um x-picpay-token e um x-seller-token. O x-picpay-token é o token enviado pelo cliente ao Ecommerce Carteira quando efetuada as requisições.Siga os passos abaixo para obter suas credenciais:

  1. Acesse o Painel Lojista e faça o login;
  2. Navegue até a seção de Integrações no menu lateral;
  3. Localize a integração Carteira Picpay - Ecommerce Plug-ins e Plataformas;
  4. Clique no botão “Gerar credenciais”;
  5. Guarde com segurança o x-picpay-token e x-seller-token que aparecem na tela;
Informação

Com o Ecommerce Carteira habilitado e as credenciais geradas, a Carteira PicPay deverá aparecer desta forma:

img Imagem 1 - Exemplo do Carteira Picpay

Obtendo o Token de Acesso​#

Após obter suas credenciais, você poderá solicitar um token de acesso para autenticar suas requisições à nossa API. Para isso basta fazer uma requisição ao nosso servidor de autorização passando as credenciais adquiridas no passo anterior.

  • Endpoint de Autorização: https://api.picpay.com/oauth2/token
  • Parâmetros de Requisição: grant_type: Define o fluxo de concessão da autorização. Terá sempre o valor client_credentials;
  • client_id e client_secret: Obtidos na etapa anterior.

Segue um exemplo da requisição do Token de Acesso:

curl -X 'POST' \
'https://api.picpay.com/oauth2/token' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "client_credentials",
"client_id": "66b64c55-6ab9-4894-b2b0-4772472f4f72",
"client_secret": "n9CmYbIavNTadlYFCxBVbF2345ROPgzM4"
}'

Para mais detalhes sobre a requisição do Token de Acesso vide a sessão Auth da nossa API Reference.

DE SERVIDOR PARA SERVIDOR!

Essa requisição deve ser feita obrigatoriamente a partir de um sistema backend para o nosso sistema. Essa abordagem evita expor as credenciais de autenticação ao cliente final.

TEMPO DE EXPIRAÇÃO

Os tokens de acesso obtidos através desse fluxo têm uma validade de apenas 5 minutos. Após esse período, será necessário gerar um novo token, com as mesmas credenciais para continuar utilizando a API.

Concorrência#

Ao utilizar o fluxo OAuth 2.0 do Ecommerce Carteira para autenticação e autorização de acesso à nossa API, é importante considerar os desafios relacionados à concorrência durante o processo de obtenção e renovação dos tokens de acesso.

A RFC 6749 aborda alguns aspectos relevantes em relação à concorrência. Ela destaca que, durante a obtenção do token de acesso, uma solicitação simultânea de um mesmo cliente pode resultar na criação de tokens duplicados. Da mesma forma, a renovação simultânea de tokens também pode levar a problemas de concorrência.

Para lidar adequadamente com a concorrência, recomendamos seguir as melhores práticas citadas pela RFC 6749. Além disso, é importante considerar as seguintes diretrizes:

  • Utilize mecanismos de controle de concorrência em seu sistema para evitar que múltiplas solicitações criem ou renovem o mesmo token de acesso simultaneamente.
  • Implemente estratégias de armazenamento e gerenciamento de tokens que sejam eficientes e evitem conflitos durante o processo de obtenção e renovação.
  • Utilize mecanismos adequados de armazenamento em cache para minimizar as solicitações de token.

Lembramos que é responsabilidade do cliente garantir a implementação adequada de mecanismos de controle de concorrência durante o uso do fluxo Ecommerce Carteira. Ao seguir essas diretrizes, você ajudará a manter a consistência, segurança e integridade das operações realizadas em nossa API.

Se você tiver alguma dúvida adicional ou precisar de suporte técnico, nossa equipe estará pronta para ajudar. Entre em contato conosco através dos canais disponíveis no Portal de Suporte.