Novo iFood Developer Portal
Acesse a nova versão do portal do desenvolvedor iFood
logo
logo

Fluxo de Avaliação V2 - Guia completo

Este guia descreve o funcionamento do fluxo de avaliações na versão V2 do iFood, destacando suas etapas, componentes e inovações em relação à versão anterior (V1). O V2 foi projetado para oferecer maior transparência, autonomia e eficiência para clientes, parceiros e a plataforma.
  • 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.
Uma avaliação V2 é considera pública, ou seja, visível para os consumidores, quando atende aos critérios de elegibilidade e o cliente escolhe visibilidade PUBLIC.Diferenças do V2:
  • 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
Avaliações com visibility: PRIVATE são visíveis apenas para o parceiro, não aparecem publicamente e não afetam estatísticas públicas, ainda assim o seu status será PUBLISHED.
Um texto que o consumidor anexa à avaliação, similar ao V1 mas com processamento aprimorado.Novidades no V2:
  • 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.
Comentários continuam podendo sofrer alterações por intervenção do iFood para remover conteúdo ofensivo ou proteger dados pessoais.
No V2, as respostas evoluíram de um campo único (reply) para uma lista (replies), visando um diálogo mais rico entre cliente e parceiro no futuro, embora atualmente o suporte seja limitado a uma resposta do parceiro.Principais mudanças:
  • 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.
Regras mantidas do V1:
  • Limite de 10 a 300 caracteres por resposta
Só é possível responder avaliações com status NOT_REPLIED. Após a publicação, não é possível registrar respostas.
Avaliações V2 que são automoderadas podem receber os status de INVALID ou DISCARDED quando são detectados fraude, conteúdo imprório ou violação da política de conteúdo. Avaliações em esses status não aparecem publicamente.Cenários de descarte no V2:
  • 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
O campo status: DISCARDED substitui a flag discarded: true do V1. O status INVALID não tem correspondência direta no V1, ele é um estado interno do processo de auto moderação, mas para efeitos práticos a avaliação pode ser considerada como descartada.
Os status expostos pela API V2 são:
  • 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.
  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: CREATEDNOT_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_REPLIEDREPLIED (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.
O ciclo de vida da avaliação V2 tem duração máxima de 10 dias, começando com a resposta do parceiro e finalizando com o aceite/rejeição do cliente ou expiração do prazo.
  • 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.
Removidos (V1): discarded, moderated, moderationStatus, reply, publishedAdicionados (V2): status, replies, version, visibility

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"
    }
  ]
}
Essa tabela contém exemplos de funcionalidades que podem ser usadas para testar a API de avaliações V2.
FuncionalidadeEndpointCenárioDescriçãoResultado esperado
Estrutura V2GET /v2/merchants/{id}/reviewsContrato V2 completoValidar novos campos: status, replies[], version, visibilityCampos V2 presentes
Paginação com contagemGET /v2/merchants/{id}/reviews?addCount=trueContagem totalValidar campos total e pageCount quando solicitadostotal e pageCount populados
Campo visibilityGET /v2/merchants/{id}/reviewsReviews públicas/privadasValidar visibility: "PUBLIC" ou "PRIVATE"visibility correta
Status CREATEDGET /v2/merchants/{id}/reviewsReview recém-criadaValidar status para avaliação em processamento inicialstatus: "CREATED"
Status NOT_REPLIEDGET /v2/merchants/{id}/reviewsReview aguardando respostaValidar status para review com comentário sem respostastatus: "NOT_REPLIED"
Status REPLIEDGET /v2/merchants/{id}/reviewsReview com respostaValidar status após parceiro responderstatus: "REPLIED"
Status PUBLISHEDGET /v2/merchants/{id}/reviewsReview publicadaValidar status final após processamentostatus: "PUBLISHED"
Filtros de dataGET /v2/merchants/{id}/reviews?dateFrom=2024-01-01&dateTo=2024-01-31Período válidoValidar filtros temporais funcionando corretamente200 OK com reviews filtradas
Estrutura repliesGET /v2/merchants/{id}/reviews/{id}Review com respostaValidar array replies[] com from: "MERCHANT"/"CUSTOMER"replies[0].from: "MERCHANT"
Merchant sem reviewsGET /v2/merchants/{merchantWithoutReviews}/reviewsCenário vazioValidar comportamento quando merchant não tem reviewsreviews: [], total: 0
Resposta apenas NOT_REPLIEDPOST /merchants/{id}/reviews/{reviewId}/answersTentar responder PUBLISHEDValidar que só aceita resposta em NOT_REPLIED422 UNPROCESSABLE ENTITY
Validação texto respostaPOST /merchants/{id}/reviews/{reviewId}/answersTexto 10-300 caracteresValidar limites mantidos do V1201 CREATED ou 422
Listagem V2GET /v2/merchants/{id}/reviews?page=1&pageSize=10Happy pathValidar funcionamento básico da listagem200 OK com ReviewListV2
Detalhes V2GET /v2/merchants/{id}/reviews/{reviewId}Review existenteValidar detalhes com campos V2 completos200 OK com ReviewV2
Review inexistenteGET /v2/merchants/{id}/reviews/invalid-idID não encontradoValidar tratamento de erro404 NOT FOUND
Page size limiteGET /v2/merchants/{id}/reviews?pageSize=51Limite máximoValidar proteção de performance400 BAD REQUEST
Para preparar o contrato para múltiplas respostas no futuro, embora atualmente apenas uma resposta do parceiro seja permitida.Benefícios: escalabilidade do contrato, preparação para diálogos bidirecionais futuros e estrutura mais flexível.
  • PUBLIC: visível publicamente e considerada em nota.
  • PRIVATE: não visível publicamente e fora das estatísticas públicas.
Para dar transparência ao ciclo de vida da avaliação em V2. Principais valores expostos pela 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.
Sim. O campo version identifica o motor que criou a avaliação (v1 ou v2).
Para o contrato completo dos endpoints V2, consulte a seção Referências.

Integrações

Importante:
Para validar a homologação, é preciso que existam solicitações recentes feita há pelo menos dois dias antes da data marcada.
  • 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.