> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.konfidency.cx/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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

| | Caminho 1 — Interface da Konfidency | Caminho 2 — Coleta nativa via API |
| --- | --- | --- |
| Esforço de desenvolvimento | Baixo | Alto |
| Interface | Pronta e testada (a mesma do e-mail) | Você constrói |
| Novas funcionalidades | Chegam automaticamente | Precisam ser implementadas por você |
| Customização visual | Limitada | Total |
| Experiência | Navegador ou webview | 100% nativa, dentro do app |
| Compra verificada | Sim | Sim |

**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://help.konfidency.cx/pt-br/article/link-para-avaliar-x2q3tu/):

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

| Parâmetro | Descrição | Obrigatório |
| --- | --- | --- |
| `{CUSTOMER KEY}` | Chave única da sua loja, em Configurações > API no dashboard | Sim |
| `orderId` | Número do pedido na sua plataforma | Sim |
| `email` | E-mail do cliente associado ao pedido | Sim |
| `source` | Origem da avaliação | Sim, na prática — veja abaixo |

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:

```json
{
  "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:

| Parâmetro | Descrição |
| --- | --- |
| `sku` | Abre a avaliação já focada em um produto específico do pedido |
| `ratingClicked` | Pré-seleciona uma nota de 1 a 5 ao abrir a página |
| `embedded` | Quando `1`, ativa o modo embarcado para uso em webview, iframe ou modal |
| `source` | Identificador de origem para rastreamento |

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:

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

Os eventos emitidos são:

| Evento | Quando ocorre | Payload |
| --- | --- | --- |
| `kfd:review-sent` | O consumidor enviou uma avaliação | — |
| `kfd:close` | O consumidor tocou no botão de fechar | — |
| `kfd:resize` | A altura do conteúdo mudou | `height` em pixels |

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](https://docs.konfidency.com.br/docs/konfidency-reviews/api/reference#enviar-avalia%C3%A7%C3%A3o). 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}
```

```json
{
  "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

| Situação | Resposta |
| --- | --- |
| Muitos envios em sequência a partir do mesmo IP | `429` com `errorCode: TooManyRequests` |
| Item já avaliado ou token inválido | `400` com `errorCode: AlreadyRatedOrInvalidToken` |
| Campos obrigatórios faltando ou pedido inválido | `400` com `errorCode` |

**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](https://help.konfidency.cx/pt-br/article/link-para-avaliar-x2q3tu/)
- [Referência da API — Enviar avaliação](https://docs.konfidency.com.br/docs/konfidency-reviews/api/reference#enviar-avalia%C3%A7%C3%A3o)
- [Referência da API — Status de avaliação de pedido](https://docs.konfidency.com.br/docs/konfidency-reviews/api/reference)

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.