Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Fluxo de avaliação

Uma avaliação passa por diferentes estados desde sua criação até a publicação. Entenda como funciona cada etapa e quando você precisa agir.

Quando usar

Use este guia para:

Entender os estados de uma avaliação (CREATED, NOT_REPLIED, REPLIED, PUBLISHED)
Identificar quando responder a um cliente
Saber quanto tempo você tem para cada ação
Maximizar suas chances de melhorar a nota do restaurante

Como funciona

Estados da avaliação

Estado	Descrição	Quem age	Prazo
`CREATED`	Avaliação recebida (espera interna de 24h já passou, transparente)	Sistema	Segundos para aparecer
`NOT_REPLIED`	Avaliação com nota < 5 e comentário aguardando sua resposta	Você	5 dias
`REPLIED`	Você respondeu, aguardando reação do cliente	Cliente	5 dias
`PUBLISHED`	Avaliação visível publicamente (se `visibility: PUBLIC`)	—	Permanente

Regras de triagem automática

Após a criação, o sistema decide automaticamente:

Condição	Resultado	Motivo
Nota 5 estrelas	`PUBLISHED` (imediato)	Avaliação positiva não requer resposta
Nota < 5 sem comentário	`PUBLISHED` (imediato)	Sem contexto para resposta
Nota < 5 com comentário	`NOT_REPLIED`	Feedback negativo merece atenção

Validação: Comentários passam por análise automática de IA antes de serem processados.

Prazos e ações

Ação	Prazo	Impacto
Responder avaliação	5 dias	Sem resposta, a avaliação é publicada sem seu comentário
Editar resposta	10 minutos após envio	Depois desse prazo, a resposta não pode ser alterada
Cliente reagir	5 dias após resposta	Cliente pode ajustar nota (score PODE melhorar, mas é uma média)
Validade da nota	3 meses	Notas antigas não afetam cálculo do score atual

Avaliações não respondidas em 5 dias são publicadas automaticamente. O cliente nunca verá sua resposta se você perder o prazo.

Como responder em cada estado

Estado	O que fazer	Prazo	Links úteis
`NOT_REPLIED`	Envie resposta via API	5 dias	POST /answers
`REPLIED`	Editar resposta (10 min)	10 minutos	POST /answers (editar)
`PUBLISHED`	Nenhuma ação	—	Saiba mais

Detalhamento por etapa

Criação

Cliente avalia um pedido com nota de 1 a 5 estrelas e comentário opcional. Por natureza, toda avaliação passa por um período de espera interno de 24 horas antes de ficar disponível para resposta. Quando aparece para você no status CREATED, essa espera já ocorreu e é completamente transparente — você não precisa aguardar.Status: CREATED Duração: Imediata (você verá em segundos) — a espera interna de 24h já terá passado

Processamento

Sistema aplica regras de triagem e define próximo estado.Status: CREATED → NOT_REPLIED ou PUBLISHED
Duração: Alguns minutos

Aguardando resposta

Avaliação entra na sua fila. Você tem 5 dias para responder via API para engajar o cliente.Status: NOT_REPLIEDAções disponíveis:

Enviar resposta via API (10-300 caracteres)
Editar resposta (até 10 minutos após envio)
Visualizar comentário e questionário

Prazo: 5 diasO que pode dar errado:

Esquecer de responder → Publica automaticamente sem sua resposta
Responder após 5 dias → Review já está publicada, não aceita mais
Resposta com tamanho inválido (< 10 ou > 300 chars) → Erro 400
Resposta com conteúdo ofensivo, dados pessoais ou links não autorizados → Erro 422 (veja Tratamento de erros)

Próximo passo: Enviar resposta

Resposta enviada

Cliente recebe sua resposta e tem 5 dias para reagir (ajustar nota ou ignorar).Status: REPLIEDPossíveis reações do cliente:

Aumenta nota (exemplo: de 2 para 4 estrelas) → Score PODE melhorar (é uma média, precisaria de muitas alterações de nota para surtir efeito notável)
Ignora (nota permanece igual) → Score mantém original
Prazo expira (nota permanece igual) → Score mantém original

Prazo: 5 dias para reaçãoO que pode dar errado:

Resposta com linguagem agressiva → Cliente se ofende, não ajusta nota
Resposta genérica → Cliente não se sente ouvido, ignora
Não responder em tempo (anterior) → Esta etapa nunca é alcançada

Dica: Uma resposta rápida, específica e respeitosa aumenta chances de melhoria.

Publicação

Avaliação é publicada com nota final e comentários.Status: PUBLISHED
Conteúdo publicado:

Comentário do cliente (original ou modificado pela IA)
Sua resposta (se enviada dentro do prazo)
Nota final (original ou ajustada pelo cliente)

Visibilidade: Depende do campo visibility (PUBLIC ou PRIVATE)

Exemplo prático de sucesso

Passo	O que acontece	Timing	Resultado
1	Cliente avalia: 2 estrelas "Comida chegou fria"	T+0h	Status: `NOT_REPLIED`
2	Você responde em 2 dias: "Desculpas. Implementamos melhorias no tempo e embalagem"	T+2d	Status: `REPLIED`
3	Cliente vê resposta em 30 minutos	T+2d 30m	Cliente considerando
4	Cliente aumenta para 4 estrelas (satisfeito)	T+3d	Score sobe
5	Avaliação publica com 4 estrelas + sua resposta	T+5d	Status: `PUBLISHED`

Resultado: +2 estrelas — Sua resposta rápida e específica melhorou a experiência do cliente.

Automoderação automática

Avaliações passam por validação com IA antes de serem processadas:

Cenário	Causa	Status final	Score
Conteúdo válido	Avaliação legítima	`CREATED` → `NOT_REPLIED` ou `PUBLISHED`	Contabilizado
Conteúdo impróprio	Profanidade, spam	`DISCARDED`	Não
Fraude detectada	Padrão suspeito, repetição	`DISCARDED`	Não
Violação de diretrizes	Desinformação, ódio	`INVALID`	Não
Expiração (> 3 meses)	Muito antiga	Removida do cálculo	Não

Como comentários são processados

Comentários são validados automaticamente no recebimento. Nós não fazemos alterações em comentários.Se a avaliação contiver:

Dados pessoais do cliente (nome, endereço, telefone)
Linguagem ofensiva
Erros de formatação críticos

...a avaliação é automaticamente invalidada e não será publicada.Normalmente: Você verá o conteúdo original na API e pode responder normalmente, pois a avaliação passou na validação automática.

Validação de respostas inadequadas

Suas respostas são validadas automaticamente através de um processo assíncrono. Você deve evitar:

Xingamentos ou agressividade
Dados pessoais do cliente (nome, endereço, telefone)
Links ou promoções não autorizadas
Conteúdo discriminatório

Como funciona: Você pode receber erro 422 imediatamente no envio, ou a validação pode detectar a violação após o envio ter sido aceito.Resultado: Se sua resposta violar essas regras, a avaliação será marcada como inválida e não será publicada. Você e o cliente não verão a resposta publicada.