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"
    }
  ]
}
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.
Esta tabela contém os casos de teste para validação da API de Reviews V2.
#FuncionalidadeEndpointCenárioDescriçãoResultado esperadoCriticidade
1AutenticaçãoGET /v2/merchants/{id}/reviewsToken JWT inválidoValidar rejeição de tokens malformados401 UNAUTHORIZEDMáxima
2AutorizaçãoGET /v2/merchants/{id}/reviewsToken sem permissãoValidar isolamento entre merchants403 FORBIDDENMáxima
3Estrutura V2GET /v2/merchants/{id}/reviewsContrato V2 completoValidar novos campos: status, replies[], version, visibilityCampos V2 presentesMáxima
4Paginação com contagemGET /v2/merchants/{id}/reviews?addCount=trueContagem totalValidar campos total e pageCount quando solicitadostotal e pageCount populadosAlta
5Campo visibilityGET /v2/merchants/{id}/reviewsReviews públicas/privadasValidar visibility: "PUBLIC" ou "PRIVATE"visibility corretaAlta
6Status CREATEDGET /v2/merchants/{id}/reviewsReview recém-criadaValidar status para avaliação em processamento inicialstatus: "CREATED"Alta
7Status NOT_REPLIEDGET /v2/merchants/{id}/reviewsReview aguardando respostaValidar status para review com comentário sem respostastatus: "NOT_REPLIED"Máxima
8Status REPLIEDGET /v2/merchants/{id}/reviewsReview com respostaValidar status após parceiro responderstatus: "REPLIED"Alta
9Status PUBLISHEDGET /v2/merchants/{id}/reviewsReview publicadaValidar status final após processamentostatus: "PUBLISHED"Alta
10Filtros de dataGET /v2/merchants/{id}/reviews?dateFrom=2024-01-01&dateTo=2024-01-31Período válidoValidar filtros temporais funcionando corretamente200 OK com reviews filtradasMáxima
11Estrutura repliesGET /v2/merchants/{id}/reviews/{id}Review com respostaValidar array replies[] com from: "MERCHANT"/"CUSTOMER"replies[0].from: "MERCHANT"Máxima
12Merchant sem reviewsGET /v2/merchants/{merchantWithoutReviews}/reviewsCenário vazioValidar comportamento quando merchant não tem reviewsreviews: [], total: 0Média
13Resposta apenas NOT_REPLIEDPOST /merchants/{id}/reviews/{reviewId}/answersTentar responder PUBLISHEDValidar que só aceita resposta em NOT_REPLIED422 UNPROCESSABLE ENTITYMáxima
14Validação texto respostaPOST /merchants/{id}/reviews/{reviewId}/answersTexto 10-300 caracteresValidar limites mantidos do V1201 CREATED ou 422Máxima
15Listagem V2GET /v2/merchants/{id}/reviews?page=1&pageSize=10Happy pathValidar funcionamento básico da listagem200 OK com ReviewListV2Máxima
16Detalhes V2GET /v2/merchants/{id}/reviews/{reviewId}Review existenteValidar detalhes com campos V2 completos200 OK com ReviewV2Máxima
17Review inexistenteGET /v2/merchants/{id}/reviews/invalid-idID não encontradoValidar tratamento de erro404 NOT FOUNDAlta
18Page size limiteGET /v2/merchants/{id}/reviews?pageSize=51Limite máximoValidar proteção de performance400 BAD REQUESTAlta