Este tópico visa fomentar o conhecimento na nossa comunidade, principalmente no que tange ao uso de nossas APIs públicas e fornecer um passo a passo inicial para os nossos clientes e parceiros que ainda não possuem conhecimento técnico sobre o assunto.
Cabe ressaltar que nós temos uma documentação em inglês com um tutorial semelhante no Developers:
O que são APIs?
API significa Application Programming Interface, ou seja, Interface de Programação de Aplicação. As APIs são um conjunto de serviços/funções que foram implementadas em um programa de computador que são disponibilizados para que outros programas/aplicativos possam utilizá-los diretamente de forma simplificada.
Como as APIs funcionam?
A arquitetura da API geralmente é explicada em termos de cliente e servidor. A aplicação que envia a solicitação é chamada de cliente e a aplicação que envia a resposta é chamada de servidor.
Aqui na VTEX, utilizamos atualmente as APIs REST, essas são as APIs mais populares e flexíveis encontradas na Web atualmente. O cliente envia solicitações ao servidor como dados. O servidor usa essa entrada do cliente para iniciar funções internas e retorna os dados de saída ao cliente.
Como utilizar essas APIs?
Bom, para utilizar as APIs disponíveis no Developers será necessário ter uma plataforma que execute essas APIs, aqui na VTEX usamos normalmente o Postman, mas existem diversas outras formas de rodar as APIs, sinta-se livre para utilizar a que achar mais conveniente.
Nossas APIs públicas ficam disponíveis na guia API Reference na nossa página no Developers, divididas por assunto:
Aqui vamos utilizar a API Get Order como exemplo, mas estas instruções se aplicam a qualquer endpoint que você quiser experimentar.
Primeiro Passo: Importar o cURL da requisição para o seu programa
Para isso, primeiramente vai ser necessário acessar a página da API que você desejar utilizar no Developers e copiar o cURL da requisição dela:
Após isso, vai ser necessário importar esse mesmo cURL no Postman:
Segundo Passo: Ajustar os headers
Tendo já executado o passo anterior, vai ser necessário ajustar os parâmetros do endpoint e de autenticação. A maioria de nossas APIs possuem o seguinte formato:
https://{{accountName}}.{{environment}}.com.br/api...
Onde:
-
{{accountName}}é o nome da sua conta na VTEX (O que é account name? | VTEX Help Center); -
{{environment}}deve ser substituído porvtexcommercestable
Além disso, é necessário se autenticar, isso é feito através de um par de AppKey e AppToken que podem ser gerados conforme a seguinte documentação: Chaves de aplicação | VTEX Help Center. Entretanto, cabe aqui ressaltar que essa ação pode ser executada apenas por usuários que possuam o perfil de acesso User Administrator - RESTRICTED (Dúvidas Frequentes: Porque não consigo adicionar novos usuários na plataforma? | Community VTEX).
Portanto, antes de prosseguir, certifique-se de ter um par válido de appKey e appToken com as permissões necessárias para executar as solicitações desejadas.
Terceiro passo: Substituir as variáveis e executar a requisição
Cada API pode ter variáveis especificas atreladas ao seu uso, nesse caso precisamos substituir o número do pedido no campo {orderId} e então clicar em SEND:
Quarto passo: Status de retorno.
Tendo enviado a requisição iremos então receber um retorno de como foi essa execução.
Se você receber um retorno do tipo 401 - Unauthorized, revise a AppKey e AppToken e tente novamente. Certifique-se de que as permissões corretas estejam definidas nas funções e de que você copiou a chave exata e os valores de token nos cabeçalhos da solicitação (é importante tomar cuidados com possíveis espaços inseridos antes ou após algum desses campos).
Se você recebeu um retorno 200 OK, significa que sua solicitação às APIs VTEX foi bem-sucedida.
Algumas solicitações de API podem retornar outros códigos de status em caso de sucesso, como
201 Createdou204 No Content.
Caso você deseje ter mais informações sobre como funcionam as APIs, seus métodos e funcionamento, recomendo o seguinte tópico: Dúvidas Frequentes: O que são APIs, quais seus métodos e como funcionam?
Caso ainda tenha alguma dúvida sobre o assunto, sinta-se à vontade para perguntar por aqui! 
Karina Mota
Field Software Engineer | VTEX
Fontes:
https://developers.vtex.com/
https://aws.amazon.com/pt/what-is/api/