Olá, meus queridos alunos e futuros mestres do Shopify! 👋 Sejam muito bem-vindos à nossa Aula 73!

Chegamos a um ponto crucial e extremamente poderoso do nosso curso. Até agora, exploramos o Shopify de ponta a ponta, desde a configuração inicial da loja até a personalização avançada de temas com Liquid, CSS e JavaScript. Agora, vamos elevar o nível e mergulhar no coração da interoperabilidade do Shopify: sua API REST.

Esta aula é para quem busca ir além do que o admin do Shopify oferece, integrando sua loja com sistemas externos, automatizando processos complexos ou construindo funcionalidades totalmente personalizadas fora do ambiente de tema. Preparem-se para abrir um mundo de possibilidades! 🚀

—

Aula 73 – Loja Shopify do Zero ao Avançado: API REST do Shopify – integração completa

📚 O que você vai aprender nesta aula

Nesta aula super importante, você vai desvendar os segredos da API REST do Shopify e aprender a integrá-la para construir soluções personalizadas e robustas:

• O que é a API REST do Shopify e por que ela é fundamental para integrações avançadas.
• Diferenças e casos de uso entre a API Admin (REST e GraphQL) e a API Storefront.
• Como criar e configurar um Custom App no Shopify para obter credenciais de acesso seguro.
• Autenticação e Scopes (Permissões): Entender como obter e gerenciar tokens de acesso e quais permissões são necessárias.
• Realizando Requisições HTTP (GET, POST, PUT, DELETE) para interagir com recursos da sua loja (produtos, pedidos, clientes, etc.).
• Estrutura de Requisição e Resposta: Trabalhando com JSON e entendendo os status codes.
• Gerenciamento de Versão da API e a importância de estar atualizado.
• Lidando com Rate Limits para garantir que suas integrações sejam estáveis e não bloqueadas.
• Boas Práticas de Desenvolvimento para criar integrações seguras, eficientes e escaláveis.

🔗 Conectando com aulas anteriores

Até agora, nossa jornada focou principalmente na criação de temas e customizações diretamente na interface da loja e no painel administrativo. Nas aulas de personalização de temas, aprendemos a usar Liquid, HTML, CSS e JavaScript para moldar a experiência do usuário (Aulas 40-60, por exemplo). Discutimos também o uso de Metafields (Aulas 65-67) para estender a capacidade de dados dos recursos do Shopify.

A API REST do Shopify é a ponte que nos permite manipular esses dados e recursos de forma programática, fora do admin ou do tema. Imagine que você precisa:

• Sincronizar produtos com um ERP externo.
• Criar um dashboard de vendas personalizado que puxe dados em tempo real.
• Automatizar a criação de pedidos ou a atualização de estoque a partir de um sistema de terceiros.
• Construir uma aplicação mobile que se conecte diretamente à sua loja.

Isso tudo é possível graças à API, que complementa e expande infinitamente o que aprendemos até agora sobre a estrutura e os dados do Shopify. Enquanto o Liquid {{ product.title }} mostra um título, a API REST permite que um sistema externo leia ou modifique esse product.title.

📖 Conteúdo Principal

A API REST do Shopify é um conjunto de endpoints HTTP que permite que você e seus sistemas interajam com os dados e funcionalidades da sua loja Shopify de forma programática. Pense nela como a “porta dos fundos” que permite que aplicações externas conversem com sua loja.

1. Tipos de APIs Shopify: Um Mapa Geral

Antes de mergulharmos fundo, é importante entender que o Shopify oferece algumas APIs com propósitos distintos:

• Admin API (REST & GraphQL):
• Propósito: Interagir com os recursos administrativos da sua loja (produtos, pedidos, clientes, estoque, configurações da loja, etc.). É a API que usamos para gerenciar a loja.
• Uso: Construção de aplicativos personalizados, integrações com ERPs, CRMs, sistemas de BI, etc.
• Foco desta aula: Admin API REST.
• Storefront API (GraphQL):
• Propósito: Construir experiências de compra totalmente personalizadas (custom storefronts) fora do tema padrão do Shopify. Permite acesso a dados de produtos, coleções, carrinho de compras, etc., para exibir ao cliente.
• Uso: E-commerces headless, aplicativos mobile, PWAs (Progressive Web Apps).

Não será o foco principal desta aula, mas é bom conhecer a diferença.*

• API App Proxy (Liquid/HTTP):
• Propósito: Criar páginas dentro da sua loja Shopify que são servidas pelo seu aplicativo externo. É uma “ponte” entre o tema da sua loja e um servidor externo.
• Uso: Adicionar funcionalidades de aplicativo diretamente no frontend da loja, sem redirecionar o cliente para fora.

Também não é o foco principal, mas é relevante para aplicações que integram o frontend.*

2. Casos de Uso Comuns da Admin API REST

A Admin API REST é incrivelmente versátil. Alguns exemplos práticos:

• Sincronização de Dados: Manter estoque, produtos e informações de clientes atualizados entre o Shopify e um sistema ERP, WMS ou CRM.
• Automação de Tarefas: Criar pedidos automaticamente, atualizar preços em massa, gerenciar fulfillment.
• Relatórios Personalizados: Extrair dados de vendas, produtos e clientes para análises e relatórios fora do Shopify Analytics.
• Integração com Plataformas de Marketing: Enviar dados de clientes e pedidos para plataformas de e-mail marketing ou automação.
• Desenvolvimento de Aplicativos Privados/Personalizados: Criar funcionalidades únicas que atendam às necessidades específicas da sua loja.

3. Criando um Custom App no Shopify

Para começar a interagir com a API, você precisará de credenciais. A forma mais segura e recomendada para integrações diretas com a sua própria loja é através de um Custom App.

Passo a passo:

1. Acesse o painel de administração da sua loja Shopify.

2. Vá em Apps (Aplicativos) no menu lateral.

3. Clique em Desenvolver apps (Develop apps).

4. Clique em Criar um app (Create an app).

5. Dê um Nome ao app (Ex: “Integração ERP”, “Dashboard Personalizado”, “Minha API de Teste”). Clique em “Criar app”.

Imagine uma screenshot aqui mostrando a tela de criação do Custom App.*

6. Após criar o app, você será direcionado para a página de visão geral do seu app. Aqui, o mais importante é a seção Configurar escopos da API Admin (Configure Admin API scopes). Clique nela.

7. Defina os Escopos (Permissões): Esta é a parte crítica! Você precisa conceder ao seu app apenas as permissões (scopes) que ele realmente precisa para funcionar. Dar permissões demais é um risco de segurança.

• Por exemplo, se você quer apenas ler produtos, marque read_products.
• Se você quer criar e atualizar produtos, marque read_products e write_products.
• Para esta aula, vamos marcar read_products e write_products para que possamos testar a leitura e a escrita. Você pode rolar a lista e selecionar as permissões relevantes.

Imagine uma screenshot aqui mostrando a lista de escopos da API Admin sendo selecionados.*

8. Clique em Salvar (Save).

9. Agora, vá para a aba Credenciais da API (API credentials) no topo.

10. Clique em Instalar app (Install app). Confirme a instalação.

11. Após a instalação, você verá o Token de acesso da API Admin (Admin API access token). Este token é exibido apenas uma vez! Copie-o imediatamente e guarde-o em um local seguro (um arquivo .env para projetos, ou um gerenciador de segredos). Nunca o exponha em código público!

• Você também verá o ID da chave da API (API key) e o Segredo da chave da API (API secret key), mas para Custom Apps, o token de acesso é o que será usado para a autenticação.

Imagine uma screenshot aqui mostrando o token de acesso da API Admin após a instalação.*

Ponto importante: Este token de acesso é de longa duração e concede acesso direto à sua loja com as permissões que você definiu. Ele é como uma senha mestra para o seu aplicativo.

4. Autenticação e Scopes

• Token de Acesso (Access Token): É uma string alfanumérica que comprova a identidade do seu aplicativo e suas permissões. Ele deve ser enviado em cada requisição à API Admin.
• Scopes (Permissões): São as autorizações que você concede ao seu aplicativo. Cada scope permite acesso a um conjunto específico de recursos ou ações.
• Ex: read_products (ler produtos), write_products (criar/atualizar/excluir produtos), read_orders (ler pedidos), write_customers (criar/atualizar clientes).
• Sempre use o princípio do menor privilégio: conceda apenas as permissões estritamente necessárias.

5. Realizando Requisições HTTP

A API REST do Shopify segue os princípios RESTful, o que significa que você interage com recursos (como produtos, pedidos, clientes) usando métodos HTTP padrão:

• GET: Para recuperar recursos (ler dados).
• POST: Para criar novos recursos.
• PUT: Para atualizar recursos existentes (geralmente substitui o recurso inteiro).
• DELETE: Para remover recursos.

Estrutura de uma Requisição:

Cada requisição precisará de:

1. URL Base da Loja: https://SUA_LOJA.myshopify.com

2. Caminho da API: /admin/api/VERSAO_API/RECURSO.json

• VERSAO_API: Ex: 2023-10, 2024-01, 2024-04. O Shopify lança novas versões a cada 3 meses.
• RECURSO: Ex: products, orders, customers, collections.

3. Cabeçalhos (Headers):

• X-Shopify-Access-Token: O token de acesso que você gerou.
• Content-Type: application/json (para requisições POST/PUT que enviam um corpo JSON).

4. Corpo da Requisição (Body): Para POST e PUT, você enviará os dados em formato JSON.

Exemplo de Endpoint para Produtos:

• GET /admin/api/2023-10/products.json: Lista todos os produtos.
• GET /admin/api/2023-10/products/{product_id}.json: Obtém um produto específico.
• POST /admin/api/2023-10/products.json: Cria um novo produto.
• PUT /admin/api/2023-10/products/{product_id}.json: Atualiza um produto existente.
• DELETE /admin/api/2023-10/products/{product_id}.json: Exclui um produto.

6. Estrutura de Resposta e Códigos de Status

As respostas da API virão em formato JSON. Elas geralmente incluem o recurso solicitado ou uma mensagem de sucesso/erro.

• Códigos de Status HTTP:
• 200 OK: A requisição foi bem-sucedida.
• 201 Created: O recurso foi criado com sucesso (para POST).
• 204 No Content: A requisição foi bem-sucedida, mas não há conteúdo para retornar (para DELETE).
• 400 Bad Request: Requisição inválida (JSON malformado, parâmetros ausentes).
• 401 Unauthorized: O token de acesso é inválido ou ausente.
• 403 Forbidden: O token de acesso não tem permissão para a ação solicitada (scopes insuficientes).
• 404 Not Found: O recurso não existe.
• 429 Too Many Requests: Limite de taxa excedido.
• 500 Internal Server Error: Erro interno no servidor do Shopify.

7. Versionamento da API

O Shopify lança novas versões da Admin API a cada 3 meses (ex: 2023-10, 2024-01, 2024-04). É crucial especificar a versão da API na sua URL de requisição (/admin/api/2023-10/products.json). Isso garante que sua integração continue funcionando mesmo que futuras versões introduzam mudanças que possam ser “quebradoras” (breaking changes).

Dica: Sempre use a versão mais recente estável disponível quando iniciar uma nova integração. Fique atento às notas de lançamento para saber quando e como migrar para novas versões.

8. Lidando com Rate Limits (Limites de Taxa)

Para proteger seus servidores, o Shopify impõe limites de taxa no número de requisições que um aplicativo pode fazer em um determinado período.

• Admin API Rate Limits: Geralmente, você pode fazer 40 requisições por app por loja por segundo, com um “bucket” de recarga.
• Headers de Resposta: O Shopify envia cabeçalhos na resposta para ajudar você a gerenciar isso:
• X-Shopify-Shop-Api-Call-Limit: Mostra o número de chamadas feitas e o limite (ex: 1/40).
• Retry-After: (Quando um 429 ocorre) Indica quantos segundos esperar antes de tentar novamente.

Como gerenciar:

• Exponential Backoff: Se você receber um erro 429 Too Many Requests, espere um tempo e tente novamente. Aumente o tempo de espera a cada nova tentativa falha.
• Filas e Processamento Assíncrono: Para operações em massa, use filas (queues) para processar as requisições gradualmente, respeitando os limites.
• Webhook First: Para receber atualizações de dados (ex: produto atualizado), prefira usar Webhooks (que abordaremos na próxima aula!) em vez de ficar “checando” a API constantemente.

💻 Exemplos Práticos

Vamos colocar a mão na massa! Usaremos um ambiente Node.js simples, mas os conceitos se aplicam a qualquer linguagem de programação (Python, PHP, Ruby, etc.).

Pré-requisitos:

• Node.js e npm instalados.
• Um Custom App criado na sua loja Shopify com as permissões read_products e write_products.
• Seu Admin API Access Token salvo.
• (Opcional) Postman ou Insomnia para testar as requisições manualmente.

Cenário: Gerenciar Produtos da Loja

Vamos criar um pequeno script para:

1. Listar os primeiros 5 produtos da loja.

2. Criar um novo produto.

3. Atualizar o preço de um produto existente.

4. Excluir um produto recém-criado.

1. Configuração do Ambiente

Crie um novo diretório para o seu projeto e inicialize-o:

bash

mkdir shopify-api-integration
cd shopify-api-integration
npm init -y
npm install dotenv node-fetch # Para gerenciar variáveis de ambiente e fazer requisições HTTP

Crie um arquivo .env na raiz do seu projeto e adicione suas credenciais:

SHOPIFY_STORE_URL=sua-loja.myshopify.com
SHOPIFY_API_VERSION=2023-10
SHOPIFY_ACCESS_TOKEN=shpat_SEU_TOKEN_AQUI # O token que você copiou do Custom App

LEMBRE-SE: sua-loja.myshopify.com é a URL completa da sua loja, sem https://. Substitua SEU_TOKEN_AQUI pelo seu Admin API Access Token real.

Crie um arquivo index.js:

javascript

// index.js
require('dotenv').config(); // Carrega as variáveis de ambiente do .env
const fetch = require('node-fetch'); // Usaremos node-fetch para fazer as requisições HTTP
const SHOPIFY_STORE_URL = process.env.SHOPIFY_STORE_URL;
const SHOPIFY_API_VERSION = process.env.SHOPIFY_API_VERSION;
const SHOPIFY_ACCESS_TOKEN = process.env.SHOPIFY_ACCESS_TOKEN;
if (!SHOPIFY_STORE_URL || !SHOPIFY_ACCESS_TOKEN || !SHOPIFY_API_VERSION) {
console.error('ERRO: Por favor, configure SHOPIFY_STORE_URL, SHOPIFY_ACCESS_TOKEN e SHOPIFY_API_VERSION no arquivo .env');
process.exit(1);
}
const API_BASE_URL = https://${SHOPIFY_STORE_URL}/admin/api/${SHOPIFY_API_VERSION};
// Função auxiliar para fazer requisições à API
async function shopifyRequest(endpoint, method = 'GET', data = null) {
const url = ${API_BASE_URL}${endpoint};
const headers = {
'X-Shopify-Access-Token': SHOPIFY_ACCESS_TOKEN,
'Content-Type': 'application/json',
};
const options = {
method,
headers,
};
if (data) {
options.body = JSON.stringify(data);
}
try {
console.log(n--- ${method} ${url} ---);
const response = await fetch(url, options);
const limitHeader = response.headers.get('X-Shopify-Shop-Api-Call-Limit');
console.log(Limite de Chamadas da API: ${limitHeader});
if (!response.ok) {
const errorText = await response.text();
throw new Error(Erro na Requisição: ${response.status} ${response.statusText} - ${errorText});
}
if (response.status === 204) { // No Content para DELETE
return null;
}
return await response.json();
} catch (error) {
console.error('Falha na Requisição Shopify:', error.message);
throw error;
}
}
// 1. Listar os primeiros 5 produtos
async function listProducts() {
try {
console.log('Buscando produtos...');
const data = await shopifyRequest('/products.json?limit=5');
if (data && data.products) {
console.log('Produtos encontrados:');
data.products.forEach(product => {
console.log(  - ID: ${product.id}, Título: ${product.title}, Preço: ${product.variants[0]?.price || 'N/A'});
});
return data.products;
} else {
console.log('Nenhum produto encontrado.');
return [];
}
} catch (error) {
console.error('Erro ao listar produtos:', error);
return [];
}
}
// 2. Criar um novo produto
async function createProduct() {
try {
console.log('nCriando um novo produto...');
const newProduct = {
product: {
title: 'Caneca Exclusiva do Curso Shopify',
body_html: 'Uma caneca especial para quem domina o Shopify!',
vendor: 'Professor Shopify',
product_type: 'Decoração',
status: 'active',
variants: [
{
price: '29.99',
sku: 'SHP-MUG-001',
inventory_management: 'shopify',
inventory_quantity: 100
}
]
}
};
const data = await shopifyRequest('/products.json', 'POST', newProduct);
if (data && data.product) {
console.log(Produto criado com sucesso! ID: ${data.product.id}, Título: ${data.product.title});
return data.product;
}
} catch (error) {
console.error('Erro ao criar produto:', error);
}
return null;
}
// 3. Atualizar o preço de um produto existente
async function updateProductPrice(productId, newPrice) {
try {
console.log(nAtualizando preço do produto ID: ${productId} para ${newPrice}...);
const updateData = {
product: {
id: productId,
variants: [{
id: null, // Shopify inferirá o variant id se só houver um
price: newPrice
}]
}
};
const data = await shopifyRequest(/products/${productId}.json, 'PUT', updateData);
if (data && data.product) {
console.log(Preço do produto ID: ${data.product.id} atualizado para ${data.product.variants[0].price});
return data.product;
}
} catch (error) {
console.error('Erro ao atualizar produto:', error);
}
return null;
}
// 4. Excluir um produto
async function deleteProduct(productId) {
try {
console.log(nExcluindo produto ID: ${productId}...);
await shopifyRequest(/products/${productId}.json, 'DELETE');
console.log(Produto ID: ${productId} excluído com sucesso.);
} catch (error) {
console.error('Erro ao excluir produto:', error);
}
}
// Função principal para executar todas as operações
async function runOperations() {
let createdProduct = null;
try {
const products = await listProducts();
createdProduct = await createProduct();
if (createdProduct) {
await updateProductPrice(createdProduct.id, '39.99');
await deleteProduct(createdProduct.id);
}
} catch (error) {
console.error('Um erro inesperado ocorreu:', error);
}
}
runOperations();

2. Executando o Script

No seu terminal, execute:

bash

node index.js

O que você deve observar na saída:

• Listagem de produtos: O script buscará e imprimirá os 5 primeiros produtos da sua loja.
• Criação de produto: Um novo produto (“Caneca Exclusiva do Curso Shopify”) será criado. Você verá o ID do produto.
• Atualização de produto: O preço da caneca será atualizado.
• Exclusão de produto: A caneca criada será excluída.
• Cabeçalho X-Shopify-Shop-Api-Call-Limit: Observe como ele muda a cada requisição, mostrando o consumo do seu limite.

Verificação Manual:

Após a execução do script, acesse o admin da sua loja Shopify (/admin/products). Você deve ter visto a “Caneca Exclusiva do Curso Shopify” aparecer e depois desaparecer.

Exemplo de Uso com Postman (ou Insomnia)

Para entender a requisição “pura”, você pode usar ferramentas como Postman.

GET Products:

• Method: GET
• URL: https://SUA_LOJA.myshopify.com/admin/api/2023-10/products.json?limit=5
• Headers:
• X-Shopify-Access-Token: shpat_SEU_TOKEN_AQUI
• Content-Type: application/json (embora não estritamente necessário para GET, é uma boa prática)
• Body: none

POST Product:

• Method: POST
• URL: https://SUA_LOJA.myshopify.com/admin/api/2023-10/products.json
• Headers:
• X-Shopify-Access-Token: shpat_SEU_TOKEN_AQUI
• Content-Type: application/json
• Body (raw, JSON):

json

{
"product": {
"title": "Produto Teste Postman",
"body_html": "Criado via Postman para a aula.",
"vendor": "Professor Shopify",
"product_type": "Digital",
"status": "active",
"variants": [
{
"price": "10.00",
"sku": "PTM-001"
}
]
}
}

Imagine uma screenshot aqui mostrando a interface do Postman com a requisição POST configurada.*

PUT Product:

• Method: PUT
• URL: https://SUA_LOJA.myshopify.com/admin/api/2023-10/products/ID_DO_PRODUTO.json (substitua ID_DO_PRODUTO pelo ID de um produto existente)
• Headers:
• X-Shopify-Access-Token: shpat_SEU_TOKEN_AQUI
• Content-Type: application/json
• Body (raw, JSON):

json

{
"product": {
"id": ID_DO_PRODUTO,
"title": "Produto Teste Postman (Atualizado)",
"tags": "aula, api, atualizado"
}
}

Imagine uma screenshot aqui mostrando a interface do Postman com a requisição PUT configurada.*

DELETE Product:

• Method: DELETE
• URL: https://SUA_LOJA.myshopify.com/admin/api/2023-10/products/ID_DO_PRODUTO_PARA_DELETAR.json
• Headers:
• X-Shopify-Access-Token: shpat_SEU_TOKEN_AQUI
• Content-Type: application/json
• Body: none

🎯 Exercícios e Desafios

1. Crie e Configure um Custom App: Se você ainda não fez isso durante a aula, crie seu próprio Custom App na sua loja Shopify. Conceda as permissões read_customers e write_customers.

2. Explore a Documentação: Visite a documentação oficial da Shopify Admin API (link na seção de Recursos). Encontre o endpoint para listar clientes (/customers.json).

3. Script de Clientes: Modifique o script index.js que criamos para:

• Listar os primeiros 3 clientes da sua loja.
• Criar um novo cliente (com nome, sobrenome, e-mail e endereço).
• Atualizar o e-mail desse cliente recém-criado.
• Excluir o cliente após a atualização.

4. Tratamento de Erros: Propositalmente, tente fazer uma requisição com um token inválido ou um endpoint errado para ver como seu script lida com os erros. Adicione um console.warn ou console.error mais específico para diferentes códigos de status HTTP (ex: 401, 403, 404).

📝 Resumo da Aula

Nesta aula intensa e prática, você:

• Compreendeu o papel vital da API REST do Shopify para integrações e automação.
• Diferenciou as APIs Admin e Storefront.
• Dominou a criação e configuração de Custom Apps e a gestão de tokens de acesso e scopes.
• Realizou requisições HTTP (GET, POST, PUT, DELETE) para interagir com recursos como produtos.
• Aprendeu sobre versionamento da API e a importância de gerenciar rate limits.
• Colocou a mão na massa com um exemplo de código Node.js e entendeu como testar com ferramentas como Postman.

Agora você tem o poder de conectar sua loja Shopify a praticamente qualquer outro sistema, transformando-a em um hub central para suas operações! ✨

🚀 Preparação para próxima aula

A interação com a API REST é fantástica, mas muitas vezes, você não quer ficar “perguntando” para a API se algo mudou. É aí que entram os Webhooks!

Na próxima aula, vamos explorar:

Aula 74 – Loja Shopify do Zero ao Avançado: Webhooks do Shopify – Reações em tempo real

Você aprenderá a configurar Webhooks para que o Shopify “avise” seu sistema sobre eventos importantes (novo pedido, produto atualizado, cliente criado), permitindo que suas integrações reajam em tempo real, de forma eficiente e escalável. Prepare-se para um controle ainda maior sobre o fluxo de dados!

📚 Recursos Adicionais

• Documentação Oficial da Shopify Admin API (REST):
• shopify.dev/docs/api/admin-rest (Visite esta página para navegar por todos os recursos e endpoints, como produtos, pedidos, clientes, etc.)
• Documentação sobre Custom Apps:
• shopify.dev/docs/apps/custom-apps
• Informações sobre Rate Limits da Admin API:
• shopify.dev/docs/api/admin-rest/latest/getting-started/rate-limits
• Postman: Ferramenta para testar APIs.
• www.postman.com/downloads/
• Insomnia: Outra excelente ferramenta para testar APIs.
• insomnia.rest/download

Parabéns por chegar até aqui! A integração via API é uma habilidade de alto valor no mundo do e-commerce. Vejo vocês na próxima aula para mergulharmos nos Webhooks! Até lá! 👋