Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Endpoints

Referência completa da API Review V2. Todos os endpoints requerem autenticação JWT e retornam JSON.Base URL: https://merchant-api.ifood.com.br/review/v2.0

Overview

Método	Endpoint	Descrição
`GET`	`/merchants/{id}/reviews`	Lista avaliações com filtros e paginação
`GET`	`/merchants/{id}/reviews/{reviewId}`	Obtém detalhes de uma avaliação
`POST`	`/merchants/{id}/reviews/{reviewId}/answers`	Responde uma avaliação
`GET`	`/merchants/{id}/summary`	Consulta estatísticas e média de notas

Autenticação

Todos os endpoints requerem token OAuth 2.0 no header Authorization:

Authorization: Bearer {JWT_TOKEN}

Para detalhes sobre autenticação e gerenciamento de tokens, consulte a documentação de autenticação.

Listar avaliações

GET /merchants/{merchantId}/reviewsRetorna lista paginada de avaliações, com suporte a filtros por data e ordenação.

Parâmetros da requisição

Path:

merchantId (required) - ID da loja (UUID)

Query:

Parâmetro	Tipo	Padrão	Valores	Descrição
`page`	integer	1	-	Número da página (começa em 1)
`pageSize`	integer	10	Máx: 50	Itens por página
`addCount`	boolean	false	true/false	Incluir total e pageCount na resposta
`dateFrom`	datetime	-	ISO 8601	Filtro: data início (ex: `2025-01-01T00:00:00Z`)
`dateTo`	datetime	-	ISO 8601	Filtro: data fim
`sort`	string	DESC	ASC, DESC	Ordenação: crescente ou decrescente
`sortBy`	string	`CREATED_AT`	`CREATED_AT`, `ORDER_DATE`	Campo para ordenação

Exemplo cURL

curl -X GET "https://merchant-api.ifood.com.br/review/v2.0/merchants/550e8400-e29b-41d4-a716-446655440000/reviews?page=1&pageSize=10&addCount=true" \
  -H "Authorization: Bearer {JWT_TOKEN}"

Ou com filtro de data:

curl -X GET "https://merchant-api.ifood.com.br/review/v2.0/merchants/550e8400-e29b-41d4-a716-446655440000/reviews?page=1&pageSize=20&dateFrom=2025-01-01T00:00:00Z&dateTo=2025-03-31T23:59:59Z" \
  -H "Authorization: Bearer {JWT_TOKEN}"

Resposta (200 OK)

{
  "page": 1,
  "size": 10,
  "reviews": [
    {
      "id": "a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a",
      "comment": "Lanche gostoso e saboroso.",
      "score": 5.0,
      "status": "PUBLISHED",
      "visibility": "PUBLIC",
      "version": "v2",
      "createdAt": "2021-04-07T01:46:59.722169Z",
      "replies": [
        {
          "text": "Obrigado! Volte sempre.",
          "from": "MERCHANT",
          "createdAt": "2021-04-07T15:30:00.000000Z"
        }
      ],
      "order": {
        "id": "bbec78f9-d579-414b-9120-37fda7968824",
        "shortId": "1234",
        "createdAt": "2021-04-07T00:39:30.902486Z"
      },
      "surveyId": "2c35c485-9f23-464d-bd83-cf6ecd1c71e0"
    }
  ],
  "total": 142,
  "pageCount": 15
}

Obter detalhes

GET /merchants/{merchantId}/reviews/{reviewId}Retorna informações completas de uma avaliação, incluindo questionário respondido e histórico de respostas.

Parâmetros da requisição

Path:

merchantId (required) - ID da loja (UUID)
reviewId (required) - ID da avaliação (UUID)

Exemplo cURL

curl -X GET "https://merchant-api.ifood.com.br/review/v2.0/merchants/550e8400-e29b-41d4-a716-446655440000/reviews/a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a" \
  -H "Authorization: Bearer {JWT_TOKEN}"

Resposta (200 OK)

{
  "id": "a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a",
  "comment": "Chegou muito rápido, ingredientes de qualidade.",
  "score": 5.0,
  "status": "PUBLISHED",
  "visibility": "PUBLIC",
  "version": "v2",
  "customerName": "Elisa",
  "createdAt": "2021-03-30T00:32:32.820884Z",
  "replies": [
    {
      "text": "Obrigado Elisa! Ficamos felizes.",
      "from": "MERCHANT",
      "createdAt": "2021-03-30T10:15:00.000000Z"
    }
  ],
  "order": {
    "id": "23651b6d-042e-4c66-8e1a-ee2a92544e4f",
    "shortId": "1234",
    "createdAt": "2021-03-29T03:10:28.552082Z"
  },
  "questions": [
    {
      "id": "7e7346ca-b24e-46c9-bda4-62411a8eb2fe",
      "type": "CHOICE",
      "title": "Do que você mais gostou?",
      "answers": [
        {
          "id": "05e8622f-be9f-4692-b087-25a06d02cc59",
          "title": "Educação"
        }
      ]
    }
  ],
  "surveyId": "2c35c485-9f23-464d-bd83-cf6ecd1c71e0"
}

Responder avaliação

POST /merchants/{merchantId}/reviews/{reviewId}/answersCria uma resposta para uma avaliação. Apenas reviews com status: NOT_REPLIED aceitam respostas.

Você tem 5 dias para responder uma avaliação. Após esse prazo, a avaliação é publicada automaticamente. Respostas podem ser editadas em até 10 minutos após envio.

Parâmetros da requisição

Path:

merchantId (required) - ID da loja (UUID)
reviewId (required) - ID da avaliação (UUID)

Body:

{
  "text": "Obrigado pelo feedback! Vamos melhorar."
}

Campo	Tipo	Obrigatório	Restrições	Descrição
`text`	string	Sim	10-300 caracteres	Texto da resposta. Sem xingamentos, dados pessoais do cliente, links ou promoções não autorizadas. Veja validação de respostas

Exemplo cURL

curl -X POST "https://merchant-api.ifood.com.br/review/v2.0/merchants/550e8400-e29b-41d4-a716-446655440000/reviews/a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a/answers" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Obrigado pelo feedback! Vamos melhorar nosso atendimento."
  }'

Para editar uma resposta (dentro de 10 minutos):

# Enviar novo POST com texto atualizado na mesma rota
curl -X POST "https://merchant-api.ifood.com.br/review/v2.0/merchants/550e8400-e29b-41d4-a716-446655440000/reviews/a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a/answers" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Texto atualizado da resposta"
  }'

Resposta (201 Created)

{
  "createdAt": "2021-04-07T15:30:00.000000Z",
  "reviewId": "a26c8718-b1f5-44a0-8f06-ecc71ddfcd5a",
  "text": "Obrigado pelo feedback! Vamos melhorar nosso atendimento."
}

Obter resumo

GET /merchants/{merchantId}/summaryRetorna estatísticas agregadas: contagem total, contagem válida e nota média.

Parâmetros da requisição

Path:

merchantId (required) - ID da loja (UUID)

Exemplo cURL

curl -X GET "https://merchant-api.ifood.com.br/review/v2.0/merchants/550e8400-e29b-41d4-a716-446655440000/summary" \
  -H "Authorization: Bearer {JWT_TOKEN}"

Resposta (200 OK)

{
  "totalReviewsCount": 142,
  "validReviewsCount": 53,
  "score": 4.3
}

Campo	Tipo	Descrição
`totalReviewsCount`	integer	Total de avaliações (todas as épocas)
`validReviewsCount`	integer	Avaliações que contam no score
`score`	number	Média aritmética das avaliações válidas (1.0-5.0)

Como o score é calculado

O score é a média aritmética de todas as avaliações válidas.Avaliações são válidas quando:

Status é PUBLISHED (e não DISCARDED ou INVALID)
Criadas nos últimos 3 meses
Visibilidade é PUBLIC (não PRIVATE)

Exemplo prático:

Campo	Valor
Total de avaliações	142 (todas as épocas)
Avaliações válidas	53 (últimos 3 meses + PUBLIC)
Score exibido	4.3 (média das 53 válidas)

Avaliações antigas (> 3 meses) continuam no histórico mas não afetam o score. Avaliações privadas (PRIVATE) são visíveis para você mas não contam na nota pública.

Rate limiting

Todos os endpoints de Reviews respeitam os mesmos limites de requisição. Consulte a documentação de rate limit para detalhes sobre como lidar com erro 429.

Endpoint	Limite
GET /merchants/{merchantId}/reviews	2000 req/min
GET /merchants/{merchantId}/reviews/{reviewId}	2000 req/min
POST /merchants/{merchantId}/reviews/{reviewId}/answers	2000 req/min
GET /merchants/{merchantId}/summary	2000 req/min

Referência de Códigos HTTP

Código	Status	Quando ocorre	Ação
200	OK	Sucesso em GET	Processar response
201	Created	Resposta criada com sucesso	Processar response
400	Bad Request	Parâmetros inválidos	Validar entrada e retry
401	Unauthorized	Token expirado/ausente	Renovar token e retry
403	Forbidden	Sem permissão nesta loja	Verificar acesso e cancelar
404	Not Found	Recurso não existe	Validar IDs e cancelar
409	Conflict	Conflito de estado	Verificar status e retry ou cancelar
422	Unprocessable Entity	Validação falhou	Revisar dados e retry
429	Too Many Requests	Rate limit excedido	Aguardar e retry com backoff
500	Internal Server Error	Erro no servidor	Retry com backoff exponencial
503	Service Unavailable	Serviço temporariamente indisponível	Retry com backoff exponencial

Referência de objetos

Review

Objeto principal retornado pelos endpoints.

Campo	Tipo	Descrição
`id`	uuid	Identificador único da avaliação
`score`	number	Nota de 1.0 a 5.0
`status`	enum	`CREATED`, `NOT_REPLIED`, `REPLIED`, `PUBLISHED`, `INVALID`, `DISCARDED`
`visibility`	enum	`PUBLIC` ou `PRIVATE`
`version`	string	Versão da API que criou (`v1` ou `v2`)
`comment`	string	Comentário do cliente (opcional)
`customerName`	string	Nome do cliente
`createdAt`	datetime	Timestamp ISO 8601
`replies`	array	Lista de respostas (veja Reply)
`order`	object	Pedido avaliado (veja Order)
`questions`	array	Questionário respondido (veja Question)
`surveyId`	uuid	ID da versão do questionário

Reply

Resposta à avaliação.

Campo	Tipo	Descrição
`text`	string	Texto da resposta (10-300 caracteres)
`from`	enum	`MERCHANT` (você) ou `CUSTOMER` (cliente)
`createdAt`	datetime	Timestamp ISO 8601

Order

Pedido que foi avaliado.

Campo	Tipo	Descrição
`id`	uuid	ID único do pedido
`shortId`	string	Código curto para exibição
`createdAt`	datetime	Quando o pedido foi criado

Question

Pergunta do questionário dinâmico.

Campo	Tipo	Descrição
`id`	uuid	ID da pergunta
`type`	enum	`RATING`, `CHOICE` ou `BINARY`
`title`	string	Texto da pergunta
`answers`	array	Respostas selecionadas (`id`, `title`)

Summary

Estatísticas agregadas (endpoint /summary).

Campo	Tipo	Descrição
`totalReviewsCount`	integer	Total de avaliações
`validReviewsCount`	integer	Avaliações que contam no score
`score`	number	Média das avaliações válidas (1.0-5.0)

Enums

Status: Ciclo de vida da avaliação.

Valor	Descrição	Sua ação	Impacto no score
`CREATED`	Em processamento (minutos)	Aguarde	Não contabilizado
`NOT_REPLIED`	Aguardando sua resposta (5 dias)	Responda via API	Não contabilizado
`REPLIED`	Respondida, cliente pode reagir (5 dias)	Aguarde reação	Não contabilizado
`PUBLISHED`	Publicada (permanente)	Nenhuma	Sim (se `visibility: PUBLIC`)
`INVALID`	Violou diretrizes iFood	Nenhuma	Não
`DISCARDED`	Removida automaticamente	Nenhuma	Não

Avaliações em status CREATED são processadas automaticamente em alguns minutos. Após triagem, passam para NOT_REPLIED (se requerem resposta) ou PUBLISHED (se não requerem).

Visibility: Quem pode ver a avaliação.

Valor	Quem vê	Afeta score	Caso de uso
`PUBLIC`	Todos (página da loja)	Sim	Padrão - visível publicamente
`PRIVATE`	Você + cliente	Não	Feedback confidencial

Version: Indica qual API criou a avaliação.

Valor	Significado
`v1`	Criada pela API Review V1 (legado)
`v2`	Criada pela API Review V2 (atual)

O endpoint V2 retorna avaliações de ambas as versões (v1 e v2). Use o campo version para detectar origem.

Próximos passos

Fluxo de avaliação — Entenda o ciclo de vida completo
Tratamento de erros — Códigos de erro e soluções
Homologação — Valide sua integração

¿Esta página fue útil?

Evalúa tu experiencia en el nuevo portal de desarrolladores: