Encontrando as APIs do VTEX Commerce
Encontrando as APIs do VTEX Commerce
Introdução
Neste passo, você aprenderá como encontrar a documentação das APIs da VTEX, além de entender as diferenças para chamá-las através do VTEX IO.
Portal do Desenvolvedor
Antes de começar a desenvolver sua integração com as APIs de Commerce da VTEX, é fundamental que você possa descobrí-las e entender seu funcionamento. O Portal de Desenvolvedor da VTEX lista todas as APIs disponíveis, além de conter explicações sobre como usar cada um dos endpoints oferecidos.
A maioria das APIs seguem a especificação REST. Também é importante ressaltar que todas as chamadas operam sobre uma conta na VTEX.
Diferenças no VTEX IO
O VTEX IO é um first-class citizen para as APIs da VTEX e, por isso, existem algumas diferenças usando-as na sua aplicação. O Portal do Desenvolvedor recebe alguns parâmetros de identificação e autorização que não são necessários quando chamando os endpoints pelo VTEX IO.
Autenticação
Tradicionalmente, a VTEX autentica chamadas para rotas privadas (/pvt
) utilizando um par AppKey e AppToken, obtidos no painel de administração de uma conta. No VTEX IO não é recomendado que se use esse par de chave e token para se autenticar, já que a plataforma oferece outra maneira mais escalável e elegante.
Todas as apps que são desenvolvidas no VTEX IO representam um recurso na plataforma, o que possibilita uma aplicação interagir com outros sistemas em nome de si mesma, devidamente autorizada pelo administrador da conta. Fica a cargo do desenvolvedor da app declarar as permissões necessárias.
Na prática, isso significa duas coisas:
- Tanto o endpoint como o role necessários para acessar alguma API devem ser declarados no
manifest.json
da app. - As chamadas devem ser realizadas com um token do VTEX ID ao invés do par AppKey e AppToken.
Você aprenderá como realizar essas configurações logo mais!
O role, falando sobre autorização dentro da VTEX, representa um "papel" no License Manager, gerenciador de usuários e autorizações na plataforma. Alguns módulos da VTEX não requerem nenhum role específico, mas outros podem requerer e são necessários ao "caller" para conseguir acessar aquele recurso.
Token da app e Token do usuário
- Cada app no VTEX IO, automaticamente, recebe um
authToken
que pode ser utilizado para chamar APIs externas. Esse token, que pode ser obtido no objeto de contexto em qualquer requisição, tem todas as permissões que foram declaradas no campopolicies
do manifesto da aplicação. - É necessário verificar se faz sentido usar este token nas requisições, especialmente ao acessar sistemas críticos das contas. Caso você identifique uma situação assim, também é possível utilizar o token do usuário que está usando a app.
accountName
accountName
Como dito, todas as chamadas para módulos do Commerce da VTEX são relativas a alguma account
na VTEX, e tradicionalmente essa informação é passada através da query string ?an
. Porém, ao longo do curso, iremos apresentar abstrações criadas no VTEX IO que dispensam essa configuração manual.
Vale ressaltar que as apps que são desenvolvidas no VTEX IO devem funcionar independente da conta onde estão instaladas, por isso é importante que nenhuma destas informações críticas seja "hard-coded".
Atividade
- Para verificar o token que cada aplicação recebe da plataforma, no middleware de validação da app
service-example
, adicione o seguinte log:
node/middlewares/validate.ts
+ console.log(ctx.vtex.authToken)
console.log('Received params:', params)
const { code } = params
...
- Agora, linke sua app e acesse a URL pública fornecida no processo. A URL será algo como
https://{workspace}--{account}.myvtex.com/_v/status/:code
. Substitua:code
por200
e, após acessar a URL, verifique o conteúdo que foi loggado noconsole.log
através do processo dovtex link
.
Você pode verificar o conteúdo desse token no site https://jwt.io/. Ele é um token parecido com o seu token pessoal (rode o comando
vtex local token
), porém representa a aplicação que você está desenvolvendo e conterá as permissões que foram solicitadas por esta app nomanifest.json
.
Está com dúvidas?
Veja o gabarito para esta etapa ou acompanhe nosso [office hours] no canal VTEX Developers(https://www.youtube.com/c/VTEXDevelopers)
Ajude-nos a fazer este conteúdo melhor!
Os cursos do VTEX IO são de código aberto. Se você perceber algum problema, pode abrir um pull request!
Faça uma contribuiçãoUpdated 9 months ago