Pular para o conteúdo principal

QA Score do Anúncio

Consulte a pontuação de qualidade (QA Score) de um anúncio específico ou liste os QA Scores de todos os anúncios de uma loja.

Endpoint​

GET /inventory/qa-score/{estoquelojaid}
GET /inventory/qa-score?dealer_id={dealer_id}

Método​

GET

Parâmetros​

Para Obter QA Score de um Anúncio Específico​

ParâmetroTipoDescrição
estoquelojaidintegerID do anúncio

Para Listar QA Scores de uma Loja​

ParâmetroTipoDescrição
dealer_idintegerID da loja (query parameter)

Autenticação​

Este endpoint requer autenticação via JWT. Inclua o token no header:

Authorization: Bearer {access_token}

Exemplo de Resposta​

QA Score de um Anúncio Específico​

Status Code: 200 OK

{
  "id": 1,
  "ad_id": 12345,
  "score": 0.85,
  "level": "Master",
  "photo": 0.2,
  "price": 0.2,
  "km": 0.2,
  "description": 0.25,
  "report": {
    "photo": {
      "score": 0.2,
      "max_score": 0.2,
      "status": "ok",
      "message": "Foto principal presente"
    },
    "price": {
      "score": 0.2,
      "max_score": 0.2,
      "status": "ok",
      "message": "Preço informado"
    },
    "km": {
      "score": 0.2,
      "max_score": 0.2,
      "status": "ok",
      "message": "Quilometragem informada"
    },
    "description": {
      "score": 0.25,
      "max_score": 0.25,
      "status": "ok",
      "message": "Descrição completa"
    }
  },
  "created_at": "2024-01-20T14:45:00Z"
}

Lista de QA Scores de uma Loja​

Status Code: 200 OK

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "ad_id": 12345,
      "score": 0.85,
      "level": "Master",
      "photo": 0.2,
      "price": 0.2,
      "km": 0.2,
      "description": 0.25,
      "report": {
        "photo": {
          "score": 0.2,
          "max_score": 0.2,
          "status": "ok",
          "message": "Foto principal presente"
        },
        "price": {
          "score": 0.2,
          "max_score": 0.2,
          "status": "ok",
          "message": "Preço informado"
        },
        "km": {
          "score": 0.2,
          "max_score": 0.2,
          "status": "ok",
          "message": "Quilometragem informada"
        },
        "description": {
          "score": 0.25,
          "max_score": 0.25,
          "status": "ok",
          "message": "Descrição completa"
        }
      },
      "created_at": "2024-01-20T14:45:00Z"
    },
    {
      "id": 2,
      "ad_id": 12346,
      "score": 0.6,
      "level": "Básico",
      "photo": 0.2,
      "price": 0.2,
      "km": 0.2,
      "description": 0.0,
      "report": {
        "photo": {
          "score": 0.2,
          "max_score": 0.2,
          "status": "ok",
          "message": "Foto principal presente"
        },
        "price": {
          "score": 0.2,
          "max_score": 0.2,
          "status": "ok",
          "message": "Preço informado"
        },
        "km": {
          "score": 0.2,
          "max_score": 0.2,
          "status": "ok",
          "message": "Quilometragem informada"
        },
        "description": {
          "score": 0.0,
          "max_score": 0.25,
          "status": "warning",
          "message": "Descrição muito curta ou ausente"
        }
      },
      "created_at": "2024-01-19T10:30:00Z"
    }
  ]
}

Estrutura de Dados​

Estrutura da Resposta Paginada (Lista)​

CampoTipoDescrição
countintegerTotal de QA Scores encontrados
nextstringURL da próxima página (null se não houver)
previousstringURL da página anterior (null se não houver)
resultsarrayArray com os resultados da página atual

Estrutura de um Item de QA Score​

CampoTipoDescrição
idintegerIdentificador único do registro de QA Score
ad_idintegerID do anúncio
scorefloatPontuação total (0.0 a 1.0)
levelstringNível de qualidade (ex: "Básico", "Intermediário", "Master")
photofloatPontuação da foto (0.0 a 0.2)
pricefloatPontuação do preço (0.0 a 0.2)
kmfloatPontuação da quilometragem (0.0 a 0.2)
descriptionfloatPontuação da descrição (0.0 a 0.25)
reportobjectRelatório detalhado com informações sobre cada critério (ver abaixo)
created_atstringData e hora de criação do QA Score

Estrutura do Objeto report​

O objeto report contém informações detalhadas sobre cada critério avaliado:

CampoTipoDescrição
photoobjectInformações sobre a avaliação da foto
priceobjectInformações sobre a avaliação do preço
kmobjectInformações sobre a avaliação da quilometragem
descriptionobjectInformações sobre a avaliação da descrição

Estrutura de um Item no report (exemplo: photo)​

CampoTipoDescrição
scorefloatPontuação obtida neste critério
max_scorefloatPontuação máxima possível neste critério
statusstringStatus da avaliação ("ok", "warning", "error")
messagestringMensagem descritiva sobre a avaliação

Query Parameters de Paginação (Lista)​

ParâmetroTipoDescrição
pageintegerNúmero da página
pageSizeintegerQuantidade de itens por página (padrão: definido nas configurações, máximo: 100)

Exemplos de Uso​

Obter QA Score de um Anúncio Específico​

GET /inventory/qa-score/12345

Listar QA Scores de uma Loja​

GET /inventory/qa-score?dealer_id=10

Listar com Paginação​

GET /inventory/qa-score?dealer_id=10&page=1&pageSize=20

Observações​

  • O QA Score é calculado automaticamente quando um anúncio é criado ou atualizado
  • O score total varia de 0.0 a 1.0 (0% a 100%)
  • A pontuação é composta por:
    • Foto: até 0.2 pontos (20%)
    • Preço: até 0.2 pontos (20%)
    • Quilometragem: até 0.2 pontos (20%)
    • Descrição: até 0.25 pontos (25%)
  • O nível de qualidade é determinado pelo score total:
    • Master: Score alto (geralmente acima de 0.8)
    • Intermediário: Score médio
    • Básico: Score baixo
  • Ao consultar um anúncio específico, retorna o QA Score mais recente (ordenado por data de criação decrescente)
  • Ao listar por loja, retorna apenas o QA Score mais recente de cada anúncio (um por anúncio)
  • O campo report pode estar vazio ({}) se não houver relatório disponível
  • O usuário deve ter permissão para acessar o anúncio específico (o anúncio deve pertencer a uma loja à qual o usuário tem acesso)
  • Este endpoint é somente leitura (apenas GET é permitido)

Possíveis Retornos de Erro​

400 Bad Request​

Retornado quando o parâmetro dealer_id não é fornecido na listagem.

{
  "dealer_id": ["Required filter 'dealer_id' is missing."]
}

401 Unauthorized​

Retornado quando o token de autenticação não foi fornecido ou é inválido.

{
  "detail": "As credenciais de autenticação não foram fornecidas."
}

ou

{
  "detail": "Token inválido ou expirado."
}

403 Forbidden​

Retornado quando o usuário autenticado não tem permissão para acessar o anúncio especificado.

{
  "detail": "Você não tem permissão para executar essa ação."
}

404 Not Found​

Retornado quando o QA Score do anúncio especificado não é encontrado.

{
  "detail": "Object does not exist."
}

405 Method Not Allowed​

Retornado quando um método HTTP diferente de GET é utilizado.

{
  "detail": "Método \"POST\" não é permitido."
}