Nuvemshop do zero: aplicativo no Portal de Parceiros, permissão de leitura e vendas no AFK

Para que serve no AFK

• Pedido pago vira cliente no CRM. Entra com o nome, o telefone ou e-mail, o que comprou e o valor, na etapa "ganho". Cliente que já existe não é duplicado.
• Pedido pago vira receita nas Finanças, com a descrição Pedido 123 (Nuvemshop). Aparece em Finanças → Vendas por canal, no canal Nuvemshop.
• Sem venda em dobro. Com o Mercado Pago ou o Stripe ligados no AFK, o pedido vira só cliente, porque a venda já entra pelo meio de pagamento. Veja a tabela abaixo.
• Nada repete. O AFK guarda o número de cada pedido importado. Pode pedir de novo à vontade.

O que fica de fora: pedido não pago, pedido em outra moeda que não o real e pedido de valor zero.

O que o AFK não faz: não mexe em produto, estoque, preço ou pedido. Não lê a loja sozinho em rotina: só quando você pede.

Quando a venda vira receita:

Antes: grátis ou pago

Riscos.

• Com só leitura, o aplicativo não altera nada na loja. Quem tiver o Client secret e um código de instalação consegue o acesso. Guarde o secret como uma senha.
• O acesso que a Nuvemshop entrega não vence. Ele só para quando você desinstala o aplicativo ou gera um acesso novo.
• Os dados dos seus clientes passam a morar também no seu computador, no CRM do AFK. Trate como trata a planilha de clientes.

Parte 1: conta e segurança

1. Entre no admin da sua loja com a conta dona. Se a sua conta oferece verificação em duas etapas, ligue antes de seguir.
2. Abra partners.nuvemshop.com.br e crie a sua conta de parceiro. A Nuvemshop exige ser parceiro para criar aplicativo.
3. Complete os dados que o portal pedir no cadastro.

Parte 2: criar o aplicativo

1. No Portal de Parceiros, clique em Criar aplicativo.
2. Dê um nome, por exemplo AFK Minha Empresa.
3. Na distribuição, escolha Para Seus Clientes. Assim o aplicativo serve só à sua loja e não passa por homologação.
4. Em Dados Básicos, preencha a URL de redirecionamento com https://afk.ia.br/. É para lá que a Nuvemshop manda o código depois da instalação. A página não guarda nada: o código aparece no endereço do navegador.
5. Nas permissões, marque só a leitura de Pedidos e de Clientes. A permissão de Produtos vem marcada sozinha. O AFK não usa: se a tela deixar, desmarque. Se não deixar, deixe só a leitura.
6. Salve.
7. Copie o Client ID (o ID do aplicativo, só número) e o Client secret.

Se você mudar uma permissão depois, a Nuvemshop exige reinstalar o aplicativo. Aí repita a Parte 4.

Parte 3: colar no AFK

1. No painel do AFK, abra Conexões, clique no cartão Nuvemshop (loja online), cole em Client ID do aplicativo e em Client secret e clique em Salvar conexão.
2. Este cartão não tem botão Testar. Só salvar ainda não liga a loja: falta a Parte 4.

Parte 4: instalar na loja e entregar o código ao AFK

O código vale só 5 minutos. Deixe o AFK aberto antes de começar.

1. No navegador, abra o endereço do admin da sua loja seguido de /admin/apps/ + o Client ID + /authorize. Exemplo com Client ID fictício 12345:

   https://minhaempresa.lojavirtualnuvem.com.br/admin/apps/12345/authorize

2. Confira as permissões que a tela mostra e aceite a instalação.
3. O navegador vai para https://afk.ia.br/?code=.... Copie só o que vem depois de code=.
4. Diga ao AFK "conecta a nuvemshop com o código XXXX", trocando XXXX pelo código.
5. O AFK responde ✓ nuvemshop conectada.
6. Diga "importa as vendas da loja" para conferir.

Onde o acesso fica. O Client ID e o Client secret ficam no .env da pasta do AFK. O acesso que a Nuvemshop entrega, com o número da loja, fica em meu-negocio/credenciais/lojas.json, fora do git e da sincronização. Nunca cole nenhum deles no chat, no WhatsApp ou em print. O código de instalação pode ir no chat: ele vence em 5 minutos e só serve uma vez.

No dia a dia

Se o Client secret vazar (print, mensagem, arquivo enviado): desinstale o aplicativo da loja. O acesso para na hora. Depois gere outro secret, cole no AFK e repita a Parte 4.

Erros e soluções

Se nada funcionar

Veja Travou ou quero sugerir uma melhoria: o que mandar. Mande o texto do erro. Nunca mande o Client secret.

Fontes oficiais (conferido em 30/10/2026): tiendanube.github.io/devhub-apps/docs/applications/overview (Criar aplicativo; distribuição Loja de Aplicativos ou Para Seus Clientes, esta sem homologação; Produtos vem marcado; mudar permissão exige reinstalar; instalar em outra loja por /admin/apps/:app-id/authorize) · tiendanube.github.io/devhub-apps/docs/applications/authentication (URL de redirecionamento em Dados Básicos; código vale 5 minutos) · tiendanube.github.io/api-documentation/authentication (troca do código em /apps/authorize/token; o acesso não vence, só cai ao gerar outro ou desinstalar; volta com user_id, o número da loja) · tiendanube.github.io/api-documentation/intro (endereço api.nuvemshop.com.br/2025-03/{loja}; cabeçalho Authorization: Bearer; User-Agent obrigatório; 40 chamadas com vazão de 2 por segundo; até 200 por página) · tiendanube.github.io/api-documentation/versioning (versão estável 2025-03) · atendimento.nuvemshop.com.br/parceiros-tecnologicos/como-fazer-um-aplicativo-para-a-loja-de-aplicativos-nuvemshop (para criar integração é preciso ser parceiro Nuvemshop).