Docs Avaliações

Avaliação

Representa a opinião de um consumidor sobre um pedido.

A entidade de avaliação possui:

metadados (data de criação e indicadores de status)
opcionalmente um comentário
opcionalmente uma resposta de comentário
as respostas de um questionário
uma nota de 1 a 5 para a experiência como um todo

Apresentação no portal do parceiro:

Mais sobre a modelagem na seção de detalhes.

Avaliações são válidas por 3 meses após criadas.

Publicação

Uma avaliação é considera pública, ou seja, visível para os consumidores, se atende a um dos critérios:

não possui um comentário
possui um comentário e decorreram 7 dias
possui um comentário e uma resposta
possui uma moderação não rejeitada

Além disso, é necessário que a avaliação seja válida (não descartada).

A modelagem apresenta essa interpretação na flag published.

Uma avaliação é visível para loja após passar pelas seguintes validações:

não possui um comentário contrário as políticas do iFood (linguagens impróprias como, racismo, ofensas e conteúdo político)
não é uma avaliação falsa:
- alavancagem: avaliações positivas criadas apenas para benefício da loja
- vandalismo: avaliações negativas criadas somente para prejudicar a nota da loja

Avaliações descartadas não são visíveis para o consumidor mas ainda podem ser visualizadas pela loja.

As validações que tornam a avaliação visível para loja podem levar até 24 horas. Desta forma a listagem de avaliações retornará as avaliações D-1.

Comentário

Um texto que o consumidor anexou à avaliação.

A presença de um comentário situa a avaliação em um período de contestação de 7 dias, em que a loja pode abrir um pedido de moderação se assim o desejar. Esse processo é conhecido por fluxo de moderação.

Comentários podem sofrer alterações por intervenção do iFood para, por exemplo, remover conteúdo ofensivo.

Resposta

A réplica da loja para uma avaliação do consumidor, em texto.

Uma avaliação pode receber uma resposta, desde que:

tenha um comentário
seja válida (não descartada)
dentro do período de triagem (7 dias após criação)

A resposta tem um limite mínimo de 10 e um máximo de 300 caracteres.

Respostas podem sofrer alterações por intervenção do iFood para, por exemplo, remover conteúdo ofensivo.

Descarte de avaliações

Avaliações que foram descartadas recebem a flag discarded=true e deixam de ser públicas.

Cenários de descarte:

expiração do período de validade de 3 meses
pedidos de moderação aceitos

Fluxo de moderação

Quando a loja não concorda com a avaliação de um consumidor, ela pode solicitar uma moderação do iFood para mediar a decisão de descarte.

No momento, o fluxo de moderação está disponível apenas no portal do parceiro

Tipos de status de moderação

Status	Descrição
REQUESTED	Estado inicial quando a loja solicitou a moderação
APPROVED	O pedido de moderação foi acatado, ou seja, a avaliação foi descartada.
DENIED	O pedido de moderação foi rejeitado, e a avaliação permanece válida.
MODERATED	A avaliação teve seu conteúdo alterado (i.e.: para proteger dados pessoais ou remover ofensas).

Questionário

Agrupamento de perguntas, contém uma versão (i.e.: v3) e um identificador único (UUID).

Note que a construção do questionário é dinâmica, perguntas poderão ser adicionadas ou removidas ao longo da existência de uma versão. Mais sobre versões na seção de detalhes.

O questionário é apresentado apenas no GET de uma única avaliação (omitido na listagem).

Pergunta

Elemento de um questionário, identificado pelo UUID e pelo título.

Ex:

{
  "questions": [
    {
      "id": "a1cdf161-62b9-4ccf-ad91-8e9898655e39",
      "type": "BINARY",
      "title": "Você gostou da entrega?"
    },
    {
      "id": "8e075d05-d1e3-49f4-b2b5-f11c58428852",
      "type": "CHOICE",
      "title": "Do que você gostou?"
    }
  ]
}

Tipos de perguntas

O tipo em uma pergunta define a resposta esperada.

Tipo	Descrição
RATING	Valor numérico
BINARY	Verdadeiro e falso
CHOICE	Seleção de tags
TEXT	Texto corrido

Respostas de uma pergunta

Lista de respostas para uma pergunta.

Ex:

{
  "answers": [
    {
      "id": "a441afc3-ab63-4254-8f00-219de3f916fd",
      "title": "Sim, gostei"
    }
  ]
}

{
  "answers": [
    {
      "id": "c05f04f8-4af4-42c7-bf57-6bc3392d1d4e",
      "title": "Bem temperada"
    },
    {
      "id": "6d579be3-68b8-454f-9a5f-f7b3aaed1a0f",
      "title": "Temperatura certa"
    },
    {
      "id": "83af4a03-f6d5-4a19-b918-64c195e0cf08",
      "title": "Saborosa"
    }
  ]
}

Sumário

Informações que compõem a nota da loja na plataforma.

Mais sobre o sumário na seção de detalhes.

Utilizando a API

Rate Limit Cada cliente da API de avaliações está limitado a 10 requests por segundo (para um mesmo token). Caso exceda o limite de requisições, o cliente pode ser bloqueado temporariamente. Nesses casos receberá como resposta o código 429.

Listando avaliações

Para obter avaliações utilize a API GET /merchants/{merchantId}/reviews

O filtro de período de data padrão da listagem de avaliações é de 7 dias atrás até a data de hoje (assim como no portal do parceiro).

As avaliações retornadas na listagem seguem as regras de publicação.

Requisição:

curl --location --request GET 'https://merchant-api.ifood.com.br/review/v1.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/reviews?addCount=true' \
--header 'Authorization: Bearer TOKEN

Resposta:

{
  "page": 1,
  "size": 3,
  "total": 3,
  "pageCount": 1,
  "reviews": [
    {
      "id": "a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a",
      "comment": "Muito bom, adorei!",
      "createdAt": "2021-04-07T01:46:59.722169Z",
      "discarded": false,
      "moderated": false,
      "published": false,
      "order": {
        "id": "bbec78f9-d579-414b-9120-37fda7968824",
        "shortId": "1234",
        "createdAt": "2021-04-07T00:39:30.902486Z"
      },
      "score": 5.0,
      "surveyId": "2c35c485-9f23-464d-bd83-cf6ecd1c71e0"
    },
    {
      "id": "38db7090-c13f-48a3-9431-7a11beb89730",
      "createdAt": "2021-04-08T14:11:14.333868Z",
      "discarded": false,
      "moderated": false,
      "published": true,
      "order": {
        "id": "67f2d08c-9b2f-4cee-87cd-57ae87a40d03",
        "shortId": "1235",
        "createdAt": "2021-03-29T00:20:00.830751Z"
      },
      "score": 5.0,
      "surveyId": "2c35c485-9f23-464d-bd83-cf6ecd1c71e0"
    },
    {
      "id": "2841b0ca-c474-4580-81cc-82cb9b36d184",
      "createdAt": "2021-02-07T22:46:52.221000Z",
      "comment": "Tive um problema com o pedido!",
      "discarded": false,
      "moderated": false,
      "published": true,
      "order": {
        "id": "1cfbb732-d787-411e-a891-5ed15b1e4716",
        "shortId": "1236",
        "createdAt": "2021-02-07T12:01:00.231445Z"
      },
      "score": 3.0,
      "surveyId": "2c35c485-9f23-464d-bd83-cf6ecd1c71e0"
    }
  ]
}

Obtendo detalhes de uma avaliação

Utilizando o id de uma avaliação obtida na listagem, é possível obter informações mais detalhadas pela API GET /merchants/{merchantId}/reviews/{reviewId}

Requisição:

curl --location --request GET 'https://merchant-api.ifood.com.br/review/v1.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/reviews/a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a' \
--header 'Authorization: Bearer TOKEN

Resposta:

{
  "id": "a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a",
  "comment": "Muito bom, adorei!",
  "createdAt": "2021-04-07T01:46:59.722169Z",
  "customerName": "Consumidor teste 1",
  "discarded": false,
  "moderated": false,
  "published": true,
  "order": {
    "id": "c0acd22a-27c2-4556-8b50-4b4eb2948882",
    "shortId": "1234",
    "createdAt": "2021-04-07T00:39:30.902486Z"
  },
  "questions": [
    {
      "id": "7e7346ca-b24e-46c9-bda4-62411a8eb2fe",
      "type": "CHOICE",
      "title": "Do que você mais gostou?"
      "answers": [
        {
          "id": "7a1ad2b3-21ba-4978-9313-8cfac19b5f84",
          "title": "Dentro do prazo"
        }
      ]
    },
    {
      "id": "a1cdf161-62b9-4ccf-ad91-8e9898655e39",
      "type": "BINARY",
      "title": "Você gostou da entrega?"
      "answers": [
        {
          "id": "a441afc3-ab63-4254-8f00-219de3f916fd",
          "title": "Sim, gostei"
        }
      ]
    },
    {
      "id": "8e075d05-d1e3-49f4-b2b5-f11c58428852",
      "type": "CHOICE",
      "title": "Do que você gostou?"
      "answers": [
        {
          "id": "ac8cce95-c69d-4668-bb8b-1f41d1518f73",
          "title": "Bons ingredientes"
        }
      ]
    }
  ],
  "score": 5.0,
  "surveyId": "2c35c485-9f23-464d-bd83-cf6ecd1c71e0"
}

Respondendo a uma avaliação

Utilizando o id de uma avaliação ainda não publicada, a resposta pode ser enviada pela API POST /merchants/{merchantId}/reviews/{reviewId}/answers

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/review/v1.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/reviews/a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a/answers' \
--header 'Authorization: Bearer TOKEN \
--header 'Content-Type: application/json' \
--data-raw '{
	"text": "Obrigado por seu feedback!"
}'

Resposta:

{
  "text": "Obrigado por seu feedback!",
  "createdAt": "2021-04-08T15:04:30.902322Z",
  "reviewId": "a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a"
}

Obtendo um sumário

Para obter as agregações do sumário, utilize a API GET /merchants/{merchantId}/summary

Requisição:

curl --location --request GET 'https://merchant-api.ifood.com.br/review/v1.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/summary' \
--header 'Authorization: Bearer TOKEN

Resposta:

{
  "totalReviewsCount": 138,
  "validReviewsCount": 65,
  "score": 4.4
}

Definições

Critérios de homologação

Importante: Para validar a homologação, é preciso que existam solicitações recentes feitas pelo menos dois dias antes da data marcada.

Listar avaliações realizadas, fazendo requests no endpoint GET /merchants/{merchantId}/reviews.
Obter detalhes das avaliações fazendo requests no endpoint GET /merchants/{merchantId}/reviews/{reviewId} para obter os detalhes de uma avaliação específica.
Responder uma avaliação nova, fazendo requests no endpoint POST /merchants/{merchantId}/reviews/{reviewId}/answers.
Consultar sumário fazendo requests no endpoint GET /merchants/{merchantId}/summary.
Incluir documentação da Política de Avaliações. Consulte através do link.