Apps Privados na NuvemShop: Como Desenvolver Funcionalidades Sem Taxa de Parceiro

Apps públicos vs apps privados: quando cada modelo faz sentido

A NuvemShop tem dois modelos de apps. Os apps públicos ficam disponíveis na App Store da plataforma, podem ser instalados por qualquer loja e geralmente são monetizados com mensalidade. Para publicar um app público, você precisa se tornar parceiro oficial da NuvemShop, o que envolve aprovação, contrato e repasse de percentual das receitas à plataforma.

Os apps privados são criados para uma única loja específica. Eles têm acesso completo à API REST da NuvemShop sem precisar passar pelo processo de aprovação da App Store, sem taxa de parceiro e sem limitações de publicação. São instalados diretamente via token de acesso gerado no painel da loja.

Apps privados são a solução ideal para:

• Integrações customizadas com ERPs, CRMs ou sistemas legados internos
• Funcionalidades específicas do negócio que não existem em nenhum app do mercado
• Automatizações internas: sincronização de estoque, regras de precificação, relatórios customizados
• Webhooks para notificações em tempo real sem depender de polling

A limitação principal é que um app privado não pode ser distribuído para outras lojas. Se você quer vender a solução, precisa publicar na App Store. Se é uso exclusivo, app privado é mais rápido, mais barato e sem burocracia.

Autenticação OAuth e geração de token de acesso

A API da NuvemShop usa OAuth 2.0 para autenticação. Para apps privados, o fluxo é simplificado — você gera um token de acesso permanente diretamente no painel administrativo da loja, sem precisar implementar o fluxo completo de autorização OAuth com redirect URI.

Para gerar o token de acesso de um app privado:

1. Acesse o painel da loja NuvemShop → Configurações → Apps → Meus apps
2. Clique em Criar app
3. Preencha nome e descrição do app (visíveis apenas para o administrador da loja)
4. Selecione os escopos de permissão necessários (produtos, pedidos, clientes, estoque, etc.)
5. Clique em Gerar token
6. Copie e armazene o token com segurança — ele só é exibido uma vez

O token gerado é usado em todas as chamadas à API como header de autenticação:

curl -X GET "https://api.tiendanube.com/v1/{store_id}/products" \
  -H "Authentication: bearer {access_token}" \
  -H "User-Agent: MeuApp (contato@exemplo.com.br)"

O campo User-Agent é obrigatório e deve conter uma string identificável com informações de contato. Chamadas sem User-Agent são rejeitadas pela API.

Endpoints principais da API REST

A API da NuvemShop (também chamada de Tiendanube API) segue convenções REST padrão. Os recursos mais utilizados em integrações são:

• GET /v1/{store_id}/products — listar produtos com suporte a paginação e filtros
• GET /v1/{store_id}/products/{product_id}/variants — variantes de um produto (cor, tamanho, etc.)
• PUT /v1/{store_id}/products/{product_id}/variants/{variant_id} — atualizar estoque de uma variante
• GET /v1/{store_id}/orders — listar pedidos com filtros por status, data e cliente
• GET /v1/{store_id}/customers — listar clientes com histórico de pedidos
• POST /v1/{store_id}/webhooks — registrar webhook para eventos em tempo real

A API tem limite de rate: 500 requisições por hora para apps privados. Para operações em lote (sincronização de estoque de centenas de produtos), use chamadas paralelas com controle de throttling e implemente retry com exponential backoff para erros 429.

# Exemplo: listar pedidos pendentes do último dia
curl -X GET "https://api.tiendanube.com/v1/1234567/orders?status=open&since=2025-04-09T00:00:00-03:00" \
  -H "Authentication: bearer SEU_TOKEN" \
  -H "User-Agent: Integracao-ERP (erp@empresa.com.br)"

Webhooks: configuração e validação de payload

Webhooks permitem que a NuvemShop notifique seu app em tempo real quando eventos acontecem na loja, sem necessidade de polling. Eventos disponíveis incluem criação de pedido, atualização de status, alteração de estoque, novo cliente e abandono de carrinho.

Para registrar um webhook via API:

POST /v1/{store_id}/webhooks
Content-Type: application/json

{
  "event": "order/created",
  "url": "https://seuservidor.com/webhooks/nuvemshop/order-created"
}

Sua URL de webhook precisa:

• Aceitar requisições POST com payload JSON
• Retornar HTTP 200 em até 10 segundos
• Validar a assinatura HMAC-SHA256 do header X-Linkedstore-Signature para confirmar autenticidade

Validação da assinatura em Node.js:

const crypto = require('crypto');

function validateWebhook(body, signature, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return hmac === signature;
}

Deploy e monitoramento do app privado

Apps privados para NuvemShop são serviços backend independentes. Você pode hospedá-los em qualquer infraestrutura: VPS, containers, funções serverless (Vercel, Cloudflare Workers, AWS Lambda) ou servidores dedicados.

Para integrações simples que rodam periodicamente (sincronização de estoque a cada 30 minutos, por exemplo), funções serverless com agendamento via cron são a opção mais econômica e de menor manutenção. Para integrações em tempo real via webhook, um servidor sempre disponível com PM2 ou container Docker garante maior controle sobre uptime e logs.

Monitore sua integração rastreando: taxa de sucesso das chamadas API, tempo médio de resposta por endpoint, erros 429 (rate limit) e falhas de webhook. Um dashboard simples com esses dados em ferramentas como Grafana ou Datadog evita que problemas silenciosos acumulem por dias sem percepção.