Coleta de avaliações por push notification

Coletar avaliações via push notification do seu aplicativo é uma forma de aproveitar um canal que você já controla, com entrega imediata e sem custo por mensagem. Existem dois caminhos de implementação, e a escolha depende de quanto esforço de desenvolvimento você quer investir e de quanto controle quer ter sobre a experiência.

Comparativo rápido

Nos dois caminhos a avaliação fica vinculada ao pedido e é marcada como compra verificada. A diferença está em quem renderiza a tela de coleta.

Caminho 1 — Push que abre a interface de coleta da Konfidency

O push leva o consumidor para a página de avaliação da Konfidency, aberta no navegador ou em uma webview dentro do app. É a mesma interface usada na coleta por e-mail e WhatsApp, então tudo que já existe hoje (fotos, vídeos, atributos, tópicos, cupom de recompensa, avaliação de loja) funciona sem nenhum trabalho adicional — e novas funcionalidades entram em paridade com os demais canais.

Há duas variações. A primeira é a mais simples; a segunda é a recomendada quando você abre a tela em webview.

1a. Link direto pelo número do pedido (sem backend)

Use o formato de link documentado em Link para avaliar:

https://www.kfy.app/rate/{CUSTOMER KEY}/order?orderId={PEDIDO}&email={EMAIL}&source=push

Essa é a opção de menor esforço: basta montar a URL no payload do push. Em contrapartida, ela não aceita os parâmetros de refinamento da experiência (sku, ratingClicked, embedded) — eles são descartados no redirecionamento interno que resolve o pedido. Se você precisa de qualquer um deles, use a variação 1b.

1b. Link com token do pedido (recomendado para webview)

Aqui o seu app resolve antes o token do pedido e monta a URL final. São dois passos.

Passo 1 — obter o verificationTokenId:

POST https://reviews-api.konfidency.com.br/{customer}/orders/find

{
  "orderId": "ORD-12345",
  "email": "cliente@email.com"
}

Resposta:

{
  "verificationTokenId": "664a1b2c3d4e5f6a7b8c9d0e",
  "orderId": "ORD-12345"
}

email e userId são alternativos — envie ao menos um.

Passo 2 — montar a URL de avaliação:

https://www.kfy.app/rate/{customer}/{verificationTokenId}/{orderId}?source=push

Parâmetros opcionais aceitos nesse formato:

O ratingClicked combina muito bem com push: se a sua notificação exibe as estrelas como ação rápida ("Que nota você dá para o produto X?"), o toque já abre a tela com a nota selecionada e o consumidor só precisa complementar o texto.

Modo embarcado (embedded=1). Em webview, sempre use embedded=1. Além de ajustar o layout, ele faz a página emitir mensagens via postMessage para a janela pai, o que permite ao seu app detectar o envio da avaliação e fechar a tela automaticamente:

window.addEventListener('message', (event) => {
  if (event.data?.type === 'kfd:review-sent') {
    // avaliação enviada — fechar a webview / modal
  }
})

Os eventos emitidos são:

Sem embedded=1 não há esses avisos, e o consumidor fica preso numa tela que ele mesmo precisa fechar.

Sempre preencha o parâmetro source

Esse é o ponto mais importante do Caminho 1, e o mais fácil de esquecer.

Quando source não é informado, a avaliação é registrada como web — exatamente igual a quem chegou navegando pelo site. Na prática, você perde a capacidade de saber se o push funcionou: as avaliações geradas por ele ficam misturadas ao tráfego orgânico e não é possível medir a efetividade da campanha nem comparar o push com e-mail e WhatsApp.

Use um valor fixo e previsível, por exemplo:

• source=push — para tratar o canal como um só
• source=push-ios e source=push-android — se quiser separar por plataforma

O campo aceita qualquer texto, então valores próprios são bem-vindos. Só mantenha o padrão estável ao longo do tempo, senão a comparação histórica se perde. O source é preservado nas duas variações (1a e 1b).

Prós: baixo esforço de desenvolvimento; interface pronta e testada, a mesma da coleta por e-mail; novas funcionalidades entram em paridade com os outros canais, sem trabalho do seu time.

Contras: pouca margem de customização visual; se abrir no navegador em vez de webview, tira o consumidor de dentro do app.

Caminho 2 — Push que abre uma tela de coleta dentro do app

Aqui o push abre uma tela nativa do seu aplicativo e a avaliação é enviada pela API da Konfidency. Você controla 100% da experiência, e o vínculo com o pedido — e a marcação de compra verificada — é garantido pelo verificationTokenId.

A referência completa está em Enviar avaliação. Abaixo, o fluxo na ordem em que ele acontece.

Passo 1 — Obter o verificationTokenId

Para um pedido específico:

POST https://reviews-api.konfidency.com.br/{customer}/orders/find

{
  "orderId": "ORD-12345",
  "email": "cliente@email.com"
}

Para montar uma lista de "pedidos a avaliar" no app, existe a versão em lote, que resolve até 20 pedidos em uma única chamada e já devolve os dados de exibição do produto (name, brand, image, url):

POST https://reviews-api.konfidency.com.br/{customer}/orders/find-batch

{
  "orderIds": ["ORD-001", "ORD-002", "ORD-003"],
  "email": "cliente@email.com"
}

Pedidos que não pertencerem ao cliente informado são simplesmente ignorados na resposta.

Passo 2 — Verificar o que ainda falta avaliar

GET https://reviews-api.konfidency.com.br/{customer}/orders/{verificationTokenId}/{orderId}

{
  "products": [
    { "sku": "PROD-001", "active": false, "review": { "rating": 5 } },
    { "sku": "PROD-002", "active": true, "review": null }
  ]
}

O campo active é a chave de leitura: true significa ainda não avaliado, false significa já avaliado.

Esse passo não é opcional. Ofereça o formulário apenas para os itens com active: true — o envio de uma avaliação para um item já avaliado é recusado com 400 e errorCode: AlreadyRatedOrInvalidToken, e exibir a tela para só depois recusar o envio é uma experiência ruim.

Passo 3 — Enviar a avaliação

POST https://reviews-api.konfidency.com.br/{customer}/{sku}/review

{
  "verificationTokenId": "664a1b2c3d4e5f6a7b8c9d0e",
  "orderId": "ORD-12345",
  "rating": 5,
  "text": "Produto perfeito para o que eu precisava",
  "recommended": true,
  "source": "app"
}

Enviando verificationTokenId + orderId, o nome do avaliador é preenchido automaticamente a partir dos dados do pedido e a avaliação é vinculada à compra. Use um source próprio (app, push-app) pelo mesmo motivo explicado no Caminho 1.

A resposta traz dois campos que você vai precisar guardar:

• _id — o ID da avaliação, usado nos endpoints complementares
• updateToken — token que autoriza complementar essa avaliação com fotos, vídeo e atributos

E traz também availableAttributes: a lista de atributos configurados para aquele produto, com type (stars ou multiple-choice), title, description e choices. Renderize essa lista dinamicamente, em vez de fixar os atributos no código do app — assim, quando a sua equipe criar ou alterar atributos no dashboard, o app acompanha sem precisar de nova versão publicada na loja.

Se a sua loja usa cupom de recompensa por avaliação, a resposta também traz o cupom elegível — lembre de exibi-lo, senão o app perde um benefício que o e-mail entrega.

Passo 4 — Complementos (atributos, fotos e vídeo)

Todos usam o updateToken retornado no passo anterior:

• Atributos: POST /{customer}/{sku}/review/{reviewId}/attributes
• Fotos: POST /{customer}/{sku}/review/{reviewId}/pictures/presign → PUT do arquivo na uploadUrl retornada → POST .../pictures/confirm com as fileKeys
• Vídeo: POST /{customer}/{sku}/review/{reviewId}/video/presign → PUT do arquivo → POST .../video/confirm

O upload é feito diretamente para o armazenamento, sem passar pela sua infraestrutura.

Limites e tratamento de erros

Envie a avaliação a partir do dispositivo do consumidor, não do seu backend. O controle de abuso é feito por IP de origem. Se todas as avaliações do app saírem do servidor da sua loja, todos os usuários compartilham o mesmo IP e você começa a receber 429 em massa. Se a sua arquitetura exigir passar por um backend próprio, fale com o time da Konfidency antes de subir para produção.

Prós: maior nível de customização; experiência nativa, sem tirar o consumidor do app; controle total sobre layout, copy e momento de exibição.

Contras: exige esforço de desenvolvimento maior; cada funcionalidade precisa ser implementada por você (fotos, vídeos, atributos, tópicos), inclusive as que forem lançadas no futuro — os outros canais recebem essas novidades automaticamente.

Recomendações válidas para os dois caminhos

Não coloque o verificationTokenId no payload do push. Ele é uma credencial de acesso ao pedido. Resolva o token no momento do toque, a partir da sessão autenticada do app.

Coordene a cadência com os demais canais. Diferente do e-mail e do WhatsApp, que são disparados pelos gatilhos configurados na Konfidency, o push é agendado pela sua loja. Sem alinhamento, o mesmo consumidor pode receber e-mail e push para o mesmo pedido no mesmo dia. Combine com o time da Konfidency qual canal fala primeiro e com qual intervalo.

Peça a avaliação no momento certo. O push deve sair depois da entrega e com o produto já em uso — a mesma lógica de timing aplicada aos demais canais.

Toda avaliação passa pela moderação. Independentemente do caminho, ela só é publicada na loja após aprovação no dashboard.

Checklist de implementação

1. Definir o caminho: interface da Konfidency (1a ou 1b) ou coleta nativa via API
2. Obter a chave única da loja em Configurações > API no dashboard
3. Definir e padronizar o valor de source (push, push-ios, push-android, app)
4. Em webview, incluir embedded=1 e tratar o evento review-sent
5. Na coleta nativa, filtrar os itens por active: true antes de exibir o formulário
6. Na coleta nativa, renderizar availableAttributes dinamicamente
7. Alinhar a cadência do push com os gatilhos de e-mail e WhatsApp
8. Testar com um pedido real antes de disparar para a base

Links úteis

• Link para avaliar
• Referência da API — Enviar avaliação
• Referência da API — Status de avaliação de pedido

Ficou com dúvida sobre qual caminho faz mais sentido para o seu app? Fale com o time da Konfidency pelo chat — ajudamos a dimensionar o esforço junto com o seu time de desenvolvimento.

Atualizado em: 20/08/2026