Principais diferenças e FAQ sobre V1 → V2

Mudanças no contrato

Campos removidos (V1)

discarded → substituído por status: DISCARDED
moderated → não existe mais moderação prévia
moderationStatus → substituído por status
reply → substituído por replies (array)
published → substituído por status: PUBLISHED

Campos adicionados (V2)

status → ciclo de vida completo da avaliação
replies → array preparado para múltiplas respostas
version → identifica versão do motor (v1/v2)
visibility → controle de visibilidade (PUBLIC/PRIVATE)

Comparação de payloads

{
  "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

Essa tabela contém exemplos de funcionalidades que podem ser usadas para testar a API de avaliações V2.

Funcionalidade	Endpoint	Cenário	Descrição	Resultado esperado
Estrutura V2	GET /v2/merchants/{id}/reviews	Contrato V2 completo	Validar novos campos: status, replies[], version, visibility	Campos V2 presentes
Paginação com contagem	GET /v2/merchants/{id}/reviews?addCount=true	Contagem total	Validar campos total e pageCount quando solicitados	total e pageCount populados
Campo visibility	GET /v2/merchants/{id}/reviews	Reviews públicas/privadas	Validar visibility: "PUBLIC" ou "PRIVATE"	visibility correta
Status CREATED	GET /v2/merchants/{id}/reviews	Review recém-criada	Validar status para avaliação em processamento inicial	status: "CREATED"
Status NOT_REPLIED	GET /v2/merchants/{id}/reviews	Review aguardando resposta	Validar status para review com comentário sem resposta	status: "NOT_REPLIED"
Status REPLIED	GET /v2/merchants/{id}/reviews	Review com resposta	Validar status após parceiro responder	status: "REPLIED"
Status PUBLISHED	GET /v2/merchants/{id}/reviews	Review publicada	Validar status final após processamento	status: "PUBLISHED"
Filtros de data	GET /v2/merchants/{id}/reviews?dateFrom=2024-01-01&dateTo=2024-01-31	Período válido	Validar filtros temporais funcionando corretamente	200 OK com reviews filtradas
Estrutura replies	GET /v2/merchants/{id}/reviews/{id}	Review com resposta	Validar array replies[] com from: "MERCHANT"/"CUSTOMER"	replies[0].from: "MERCHANT"
Merchant sem reviews	GET /v2/merchants/{merchantWithoutReviews}/reviews	Cenário vazio	Validar comportamento quando merchant não tem reviews	reviews: [], total: 0
Resposta apenas NOT_REPLIED	POST /merchants/{id}/reviews/{reviewId}/answers	Tentar responder PUBLISHED	Validar que só aceita resposta em NOT_REPLIED	422 UNPROCESSABLE ENTITY
Validação texto resposta	POST /merchants/{id}/reviews/{reviewId}/answers	Texto 10-300 caracteres	Validar limites mantidos do V1	201 CREATED ou 422
Listagem V2	GET /v2/merchants/{id}/reviews?page=1&pageSize=10	Happy path	Validar funcionamento básico da listagem	200 OK com ReviewListV2
Detalhes V2	GET /v2/merchants/{id}/reviews/{reviewId}	Review existente	Validar detalhes com campos V2 completos	200 OK com ReviewV2
Review inexistente	GET /v2/merchants/{id}/reviews/invalid-id	ID não encontrado	Validar tratamento de erro	404 NOT FOUND
Page size limite	GET /v2/merchants/{id}/reviews?pageSize=51	Limite máximo	Validar proteção de performance	400 BAD REQUEST

Perguntas frequentes

Por que `reply` virou `replies`?

Para preparar o contrato para suporte futuro a múltiplas respostas e diálogos bidirecionais.Atualmente:

Apenas uma resposta do parceiro permitida
Array replies com um único item

Benefícios:

Escalabilidade do contrato
Preparação para conversas cliente-parceiro
Estrutura mais flexível

O que significa `visibility`?

Controla como a avaliação aparece na plataforma.

Valor	Descrição
`PUBLIC`	Visível publicamente e considerada no cálculo de nota da loja
`PRIVATE`	Visível apenas para o parceiro, não afeta estatísticas públicas

O que é o campo `status`?

Representa o ciclo de vida completo da avaliação no V2.

Status	Descrição
`CREATED`	Registrada e em processamento inicial
`NOT_REPLIED`	Com comentário, aguardando resposta do parceiro
`REPLIED`	Com pelo menos uma resposta do parceiro
`PUBLISHED`	Publicada e elegível para visibilidade pública
`INVALID`	Inválida por violação de diretrizes
`DISCARDED`	Descartada (fraude, política ou expiração)
`UNKNOWN`	Estado indeterminado (raro)

O que é o campo `version`?

Identifica qual versão do motor criou a avaliação.Valores possíveis:

v1 → criada pela versão legada
v2 → criada pela versão atual

Uso: Permite que endpoints V2 retornem avaliações criadas por ambas as versões, garantindo retrocompatibilidade.

V2 retorna avaliações criadas em V1?

Sim. O endpoint V2 retorna avaliações de ambas as versões.Como identificar:

Use o campo version para distinguir a origem
Avaliações V1 terão version: "v1"
Avaliações V2 terão version: "v2"

Migração de integrações

Mapeamento de campos

V1	V2	Observação
`discarded: true`	`status: DISCARDED`	Lógica booleana virou enum
`moderationStatus`	`status`	Estados mais granulares
`reply`	`replies[0].text`	String virou array de objetos
N/A	`replies[0].from`	Campo novo identifica origem
N/A	`visibility`	Campo novo controla visibilidade
N/A	`version`	Campo novo identifica versão