Fluxo de Avaliação V2 - Guia completo

Visão geral

• Maior autonomia para clientes e parceiros, reduzindo intermediações.
• Validações automáticas com IA e integrações internas.
• Gestão granular de estados com maior controle de visibilidade e respostas.
• Transparência nos feedbacks e incentivo ao diálogo direto entre consumidores e parceiros.

Publicação

• O cliente controla a visibilidade através do campo visibility (PUBLIC/PRIVATE)
• Avaliações privadas não impactam a nota pública da loja
• O status PUBLISHED indica que a avaliação foi processada e está elegível para publicação
• As regras de validação automática (IA) substituem parte do processo manual de moderação

Comentário

• Validação automática por IA para identificar conteúdo impróprio
• Processamento mais rápido através de validações automatizadas
• O período de para resposta do parceiro passa a ser 5 dias.

Resposta

• Apenas uma resposta do parceiro é permitida (array replies com um item)
• Cada resposta identifica a origem (from: MERCHANT ou CUSTOMER)
• Preve suporte a conversas bidirecionais no futuro
• Validação automática de conformidade das respostas
• Uma resposta pode ser editada pelo parceiro dentro do período de 10 minutos desde sua criação.

• Limite de 10 a 300 caracteres por resposta

Auto moderação

• Expiração do período de validade de 3 meses
• Validação automática por IA identifica violação de diretrizes
• Detecção automatizada de fraude ou conteúdo impróprio
• Intervenção manual em casos específicos

Status da API

• CREATED: avaliação registrada e em processamento inicial.
• NOT_REPLIED: avaliação com comentário, ainda sem resposta do parceiro.
• REPLIED: avaliação com pelo menos uma resposta do parceiro.
• PUBLISHED: avaliação publicada (elegível para visibilidade pública conforme regras).
• INVALID: avaliação inválida por violação de diretrizes.
• DISCARDED: avaliação descartada (ex.: fraude, política).
• UNKNOWN: usado em casos raros/indeterminados.

Fluxo End-to-End

1. Criação de avaliação (Cliente)
   • Cliente avalia o pedido com comentário opcional.
   • Conteúdo passa por validações automáticas.
   • Status da API: CREATED.
2. Validações e publicação (Automatizadas)
   • Caso usa avaliação tenha nota 5 ou não tenha comentário, a avaliação é publicada imediatamente.
   • Caso contrário, a avaliação permanece em estado NOT_REPLIED até que o parceiro responda.
   • Status da API: CREATED → NOT_REPLIED ou PUBLISHED.
3. Resposta do parceiro (se houver comentário)
   • Parceiro pode responder; a resposta passa por validação de conformidade.
   • Status da API: NOT_REPLIED → REPLIED (ao registrar a resposta).
4. Interação direta
   • Cliente recebe a resposta e pode ajustar a nota (Caso sinta necessidade).
   • O status da API permanece entre NOT_REPLIED e REPLIED até a publicação; depois, PUBLISHED, conforme regras de elegibilidade.
   • Caso o cliente ignore a resposta, a avaliação é publicada normalmente após o período de 5 dias desde a resposta do parceiro.

Recursos da Avaliações do V2

• Feedback público ou privado: O cliente escolhe a visibilidade; avaliações privadas não impactam a nota pública.
• Resolução direta: Estimula interação cliente-parceiro, reduzindo a intermediação do iFood.
• IA no processo: Validações inteligentes para garantir conformidade e reduzir custos operacionais.
• Edição e ajustes: Clientes podem ajustar as notas com base nas respostas do parceiro.

FAQ - Mudanças V1 → V2

O que mudou no contrato de listagem e detalhes?

Exemplos de payload

{
  "page": 0,
  "size": 0,
  "reviews": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "score": 3.0,
      "status": "PUBLISHED",
      "comment": "Me iludi com a propaganda de açaí na quentinha",
      "replies": [
        {
          "createdAt": "2025-03-11T12:50:50.668Z",
          "text": "Oi, Lucca! Sentimos que sua experiência não foi a ideal. Vamos melhorar!",
          "from": "MERCHANT"
        }
      ],
      "order": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "shortId": "1234",
        "createdAt": "2025-03-11T12:05:26.916Z"
      },
      "surveyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": "v2",
      "visibility": "PUBLIC"
    }
  ]
}

Exemplos de funcionalidades

Por que reply virou replies?

O que significa visibility?

• PUBLIC: visível publicamente e considerada em nota.
• PRIVATE: não visível publicamente e fora das estatísticas públicas.

Por que o campo status foi adicionado?

• CREATED: avaliação registrada e em processamento inicial.
• NOT_REPLIED: avaliação com comentário, ainda sem resposta do parceiro.
• REPLIED: avaliação com pelo menos uma resposta do parceiro.
• PUBLISHED: avaliação publicada (elegível para visibilidade pública conforme regras).
• INVALID: avaliação inválida por violação de diretrizes.
• DISCARDED: avaliação descartada (ex.: fraude, política).
• UNKNOWN: usado em casos raros/indeterminados.

V2 pode retornar reviews criadas por V1?

Integrações

Critérios de homologação - v2

Funcionalidades

• Listar avaliações realizadas, fazendo requests no endpoint GET /merchants/{merchantId}/reviews validando:
  • Estrutura completa do contrato V2 com os campos: status, replies[], version e visibility
  • Paginação com contagem total quando addCount=true (campos total e pageCount populados)
  • Campo visibility com valores "PUBLIC" ou "PRIVATE" corretamente atribuídos
  • Diferentes status de avaliações: CREATED (processamento inicial), NOT_REPLIED (aguardando resposta), REPLIED (com resposta do parceiro), PUBLISHED (publicada)
  • Filtros de data funcionando corretamente (ex: dateFrom=2024-01-01&dateTo=2024-01-31)
  • Cenário vazio quando merchant não possui reviews (retorno: reviews: [], total: 0)
  • Limite de page size (valores acima de 50 devem retornar 400 BAD REQUEST)
• Obter detalhes das avaliações fazendo requests no endpoint GET /merchants/{merchantId}/reviews/{reviewId} validando:
  • Estrutura completa do array replies[] com campo from identificando origem ("MERCHANT" ou "CUSTOMER")
  • Campos V2 completos no detalhamento da avaliação
  • Tratamento de erro para review inexistente (404 NOT FOUND)
• Responder uma avaliação nova, fazendo requests no endpoint POST /merchants/{merchantId}/reviews/{reviewId}/answers validando:
  • Resposta apenas para avaliações com status NOT_REPLIED (tentativa de responder avaliação PUBLISHED deve retornar 422 UNPROCESSABLE ENTITY)
  • Validação de texto da resposta com limite de 10 a 300 caracteres (retorno: 201 CREATED para sucesso ou 422 para validação)
• Incluir documentação da Política de Avaliações. Consulte através do link.