Admin API

Esta API reúne ações administrativas. Ela nunca deve ser chamada pelo client-side.

Autenticação
Obter link de avaliação
Criar pedido
Criar pedido (V2)
Atualizar pedido
Obter avaliações
Obter perguntas
Obter respostas pesquisa NPS
Moderação de avaliações
Relatório de produtos
Listar grupos de produtos
Obter grupo de produtos
Criar grupo de produtos
Atualizar grupo de produtos
Deletar grupo de produtos

Autenticação

Você deve chamar a API de autenticação, para que possa utilizar os demais endpoints de nossa API administrativa

Obtendo chaves de autenticação

Acesse o Dashboard e navegue até Configurações > Integrações. Em seguida, clique em API. Você encontrará:

Customer key: seu identificador de cliente, utilizado como parâmetro {customer} nas URLs dos endpoints
Client ID: identificador da sua aplicação para autenticação
Client Secret: chave secreta para autenticação

`POST` https://reviews-api.konfidency.com.br/oauth/token

Campos do corpo da requisição (JSON)

Parâmetro	Descrição
audience	Fixo: `https://reviews-api.konfidency.com.br`
grant_type	Fixo: `client_credentials`
client_id	Client ID — consulte Obtendo chaves de autenticação
client_secret	Client Secret — consulte Obtendo chaves de autenticação

Exemplo de corpo da requisição

{
  "audience": "https://reviews-api.konfidency.com.br",
  "grant_type": "client_credentials",
  "client_id": "eSRTjDtxTaprkd6Yb97DouqFORbTT1dV",
  "client_secret": "cSrP6TF1ktSAH1IV1p24Vztd9Lc4AoLA62f0KIPU1vkymSjd7a5QzpTy0Tqo51PZ"
}

Exemplo de Resposta

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Campos

campo	descrição
access_token	token de acesso gerado
expires_in	tempo de validade do token
token_type	tipo de token, sempre será Bearer

Link de avaliação

Permite obter o link de avaliação para um pedido

`GET /{customer}/orders/{orderId}/ratelink`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação
orderId	número do pedido em sua plataforma

Exemplo de Resposta

{
  "link": "https://www.kfy.app/rate/konfidency/62b266a92bbbb599f720bb22/123456-1"
}

Campos da resposta

campo	descrição
link	URL única para avaliação do pedido

Criar Pedido

Integra um novo pedido na plataforma Konfidency Reviews

`POST /{customer}/orders`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação

Parâmetros do corpo da requisição

Parâmetro	Descrição
orderId	Número do pedido, identificação única na plataforma do cliente
createdDate	Data de criação do pedido
userId	ID do usuário na plataforma do cliente `não utilizar dados sensíveis`
status	Status do produto, `created`, `authorized`, `shipped` ou `delivered`
estimatedDeliveryDate	Data de entrega prevista do pedido
deliveredDate	Data da entrega do pedido
name	Nome do cliente
email	E-mail do cliente - obrigatório para notificações por e-mail
phone	Celular do cliente - obrigatório para notificações por SMS e WhatsApp
pointOfSale	Origem do pedido (ex: "Loja Física", "E-commerce", "Marketplace")
deliveryMethod	Método de entrega (ex: "Correios", "Transportadora", "Retirada")
optOutEmail	Indica se o cliente realizou opt-out para receber e-mails
optOutSMS	Indica se o cliente realizou opt-out para receber mensagens SMS
optOutWhatsApp	Indica se o cliente realizou opt-out para receber mensagens via WhatsApp
items.sku	SKU do produto

Exemplo de corpo da requisição

{
  "orderId": "P123456-1",
  "createdDate": "2022-06-01 12:34",
  "userId": "12345",
  "name": "João da Silva",
  "email": "[email protected]",
  "phone": "551191234-5678",
  "status": "created",
  "estimatedDeliveryDate": "2022-07-15",
  "pointOfSale": "E-commerce",
  "deliveryMethod": "Correios",
  "optOutEmail": false,
  "optOutWhatsApp": false,
  "optOutSMS": true,
  "items": [
    {
      "sku": "01001"
    }
  ]
}

Resposta

Esta API não gera um JSON de resposta, um status 200 significa que os dados foram salvos corretamente

Criar Pedido (V2)

Versão otimizada da API de integração de pedidos com suporte a marketplace, dados expandidos de produtos e atualização de pedidos existentes.

`POST /{customer}/orders`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação

Parâmetros do corpo da requisição

Parâmetro	Descrição
version	Deve ser `2` para usar esta versão da API
orderId	Número do pedido, identificação única na plataforma do cliente
userId	ID do usuário na plataforma do cliente `não utilizar dados sensíveis`
createdDate	Data de criação do pedido
authorizedDate	Data de autorização/pagamento do pedido (opcional)
estimatedDeliveryDate	Data de entrega prevista do pedido (opcional)
deliveredDate	Data de entrega efetiva do pedido (opcional)
modifiedDate	Data de última modificação do pedido (opcional)
name	Nome do cliente
email	E-mail do cliente - obrigatório para notificações por e-mail
phone	Celular do cliente - obrigatório para notificações por SMS e WhatsApp
pointOfSale	Origem do pedido (ex: "Loja Física", "E-commerce", "Marketplace") (opcional)
deliveryMethod	Método de entrega (ex: "Correios", "Transportadora", "Retirada") (opcional)
status	Status do pedido, `created`, `authorized`, `paid`, `invoiced`, `shipped`, `delivered` ou `cancelled`
optOutEmail	Indica se o cliente realizou opt-out para receber e-mails
optOutSMS	Indica se o cliente realizou opt-out para receber mensagens SMS
optOutWhatsApp	Indica se o cliente realizou opt-out para receber mensagens via WhatsApp
items	Array de itens do pedido (veja estrutura abaixo)

Estrutura de items (V2)

Parâmetro	Descrição
items.productId	SKU/ID principal do produto
items.sku	SKU da variante do produto (opcional)
items.skuName	Nome/descrição da variante (ex: "Tamanho P - Cor Azul") (opcional)
items.status	Status específico do item (opcional, usa status do pedido se omitido)
items.cancelled	Indica se o item foi cancelado (boolean) (opcional)
items.sellerInfo	Informações do seller/marketplace (opcional, veja estrutura abaixo)
items.productData	Dados completos do produto (opcional, veja estrutura abaixo)

Estrutura de items.sellerInfo (Marketplace)

Parâmetro	Descrição
items.sellerInfo.id	ID único do seller/vendedor
items.sellerInfo.name	Nome do seller/vendedor

Estrutura de items.productData

Parâmetro	Descrição
items.productData.name	Nome do produto
items.productData.productName	Nome do produto (alternativo)
items.productData.brand	Marca do produto
items.productData.brandName	Marca do produto (alternativo)
items.productData.mpn	Manufacturer Part Number (opcional)
items.productData.ean	Código EAN (opcional)
items.productData.gtin	Global Trade Item Number (opcional)
items.productData.url	URL da página do produto (será normalizada com a URL da loja)
items.productData.image	URL da imagem principal do produto
items.productData.categories	Array de categorias do produto
items.productData.categoryName	Nome da categoria (alternativo, será convertido em array)

Exemplo de corpo da requisição (V2)

{
  "version": 2,
  "orderId": "P123456-1",
  "userId": "12345",
  "name": "João da Silva",
  "email": "[email protected]",
  "phone": "551191234-5678",
  "createdDate": "2022-06-01 12:34",
  "authorizedDate": "2022-06-01 13:00",
  "estimatedDeliveryDate": "2022-06-15",
  "deliveredDate": "2022-06-14",
  "pointOfSale": "E-commerce",
  "deliveryMethod": "Transportadora",
  "status": "delivered",
  "optOutEmail": false,
  "optOutWhatsApp": false,
  "optOutSMS": true,
  "items": [
    {
      "productId": "CAM-001",
      "sku": "CAM-001-P-AZUL",
      "skuName": "Tamanho P - Cor Azul",
      "status": "authorized",
      "cancelled": false,
      "sellerInfo": {
        "id": "SELLER123",
        "name": "Loja Parceira ABC"
      },
      "productData": {
        "name": "Camiseta Básica",
        "brand": "Konfidency Store",
        "mpn": "CAM001",
        "ean": "7891234567890",
        "url": "/produtos/camiseta-basica",
        "image": "https://example.com/camiseta.jpg",
        "categories": ["Roupas", "Camisetas", "Masculino"]
      }
    }
  ]
}

Diferenças da V2

Característica	V1	V2
Atualização de pedidos existentes	Não (retorna duplicate)	Sim (atualiza dados)
Suporte a marketplace/sellers	Não	Sim
Dados expandidos de produtos	Não	Sim (productData)
Status por item	Não	Sim
Cancelamento por item	Não	Sim
Variantes de produto	Limitado	Completo (sku + skuName)
Normalização de URL de produtos	Não	Sim

Resposta

{
  "_id": "62b266a92bbbb599f720bb22",
  "customer": "konfidency",
  "orderId": "P123456-1",
  "userId": "12345",
  "name": "João S.",
  "createdDate": "2022-06-01T15:34:00.000Z",
  "authorizedDate": "2022-06-01T16:00:00.000Z",
  "email": "[email protected]",
  "phone": "551191234-5678",
  "status": "authorized",
  "optOutEmail": false,
  "optOutSMS": true,
  "optOutWhatsApp": false,
  "__v": 0
}

Atualizar Pedido

Atualiza o status do pedido na plataforma Konfidency Reviews

`PUT /{customer}/orders/{orderId}`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação
orderId	Número do pedido, identificação única na plataforma do cliente

Parâmetros do corpo da requisição

Parâmetro	Descrição
created	Data de criação do pedido
status	Status, `created`, `authorized`, `shipped` ou `delivered`
authorizedDate	Data de pagamento do pedido
deliveredDate	Data de entrega do pedido

Exemplo de corpo da requisição

{
  "status": "authorized",
  "authorizedDate": "2022-06-01 12:34"
}

Resposta

Esta API não gera um JSON de resposta, um status 200 significa que os dados foram salvos corretamente

Obter avaliações

Obtém as avaliações de acordo com os critérios de busca

`GET /{customer}/reviews/all`

`POST /{customer}/reviews/all`

O método POST permite filtros adicionais através do corpo da requisição (ver seção abaixo).

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação

Parâmetros de Query (todos opcionais)

Parâmetro	Tipo	Descrição
sku	string	SKU do produto que deseja buscar
status	string	Status das avaliações a serem buscadas (consulte tabela abaixo)
order	string	Ordenação dos resultados (consulte tabela abaixo)
rating	integer	Filtrar por nota específica (1 a 5)
skip	integer	Quantidade de registros a serem omitidos (paginação)
tags	string	Filtrar por tags de moderação
topics	string	Filtrar por tópicos
from	string	Data inicial em formato YYYY-MM-DD
to	string	Data final em formato YYYY-MM-DD
hasText	boolean	Filtrar avaliações que possuem texto
hasPicture	boolean	Filtrar avaliações que possuem fotos
hasVideo	boolean	Filtrar avaliações que possuem vídeos
hasReply	boolean	Filtrar avaliações que possuem resposta do lojista
complete	boolean	Filtrar avaliações completas
autoModerated	boolean	Filtrar por avaliações moderadas automaticamente
includeOrderData	boolean	Incluir dados do pedido e seller (orderId, sellerInfo, orderName, orderEmail, orderPhone)

Status de avaliações

Status	Descrição
	Omitir este campo ou enviar uma string vazia trará avaliações em qualquer status
`published`	Avaliações publicadas
`removed`	Avaliações reprovadas/removidas
`filtered`	Avaliações filtradas pelo filtro de palavras proibidas
`pending`	Avaliações na fila de moderação

Ordenação de resultados

A ordenação segue o padrão campo,ordem. A ordem pode ser 1 para ascendente ou -1 para descendente.

Campo	Descrição
`created`	Data de envio da avaliação
`moderatedAt`	Data de moderação da avaliação
`sku`	SKU do produto
`rating`	Nota da avaliação (1 a 5)
`helpful`	Mais marcadas como úteis
`unhelpful`	Mais marcadas como não úteis

Parâmetros adicionais do método POST (corpo da requisição)

Parâmetro	Tipo	Descrição
categories	array	Array de categorias de produtos para filtrar
sentiment	string	Filtrar por sentimento da avaliação (`positive`, `negative`, `neutral`)

Exemplo de chamada GET com filtros

GET /konfidency/reviews/all?status=published&rating=5&hasPicture=true&from=2024-01-01&to=2024-12-31&skip=0

Exemplo de chamada GET com dados de pedido e seller

GET /konfidency/reviews/all?status=published&includeOrderData=true

Exemplo de corpo da requisição POST

{
  "categories": ["Camisetas", "Masculino"],
  "sentiment": "positive"
}

Os parâmetros de query permanecem os mesmos para o método POST e podem ser combinados com o corpo da requisição.

Resposta

{
  "results": [
    {
      "_id": "630adeb56a21590014e4e200",
      "helpful": 0,
      "unhelpful": 0,
      "verified": true,
      "moderationTags": [],
      "status": "published",
      "created": "2022-08-28T03:19:17.374Z",
      "pictures": [
        {
          "_id": "629f79d569ede80012ca7172",
          "url": "https://uploads.konfidency.com.br/a98cd120-abe9-436f-b4de-78e8a0b52071"
        }
      ],
      "customer": "konfidency",
      "userId": "a6c42ec0-ed92-4464-8dfc-fd7593472767",
      "name": "Dominic T",
      "sku": "307645",
      "text": "Produto diferenciado. Do forno direto para a mesa. Lindíssimo. Não há quem não elogie à mesa.\nA comida servida nesta travessa fica até mais saborosa.😍",
      "recommended": true,
      "rating": 5,
      "source": "sdk",
      "__v": 1,
      "attributes": [
        {
          "_id": "61f7162480088014770d11af",
          "title": "Custo/benefício",
          "type": "stars",
          "scaleMin": 0,
          "scaleMax": 5,
          "value": 5
        },
        {
          "_id": "627da5f10d1b0c410a99a1eb",
          "title": "Qualidade",
          "type": "stars",
          "scaleMin": 0,
          "scaleMax": 5,
          "value": 5
        }
      ],
      "product": {
        "_id": "6284033fb0b7371985a42200",
        "customer": "konfidency",
        "sku": "307645",
        "name": "FOLHA TRAVESSA OVAL 33 CM X 23 CM",
        "categories": [
          "Ambientes",
          "Sala de Jantar",
          "Cozinha",
          "Acessórios para Servir",
          "Louças",
          "Louças",
          "Porcelana e cerâmica",
          "Acessórios",
          "Mesa",
          "Travessas para Servir",
          "Louças e Utensílios para Servir"
        ],
        "url": "https://www.site.com.br/travessa-oval-33-cm-x-23-cm-verde-folha",
        "image": "https://images.site.com.br/arquivos/ids/1857460-200-200/Travessa-Oval-33-Cm-X-23-Cm-Verde-Folha.jpg?v=637020162237200000"
      }
    }
  ],
  "total": 30958
}

Campos de resposta

campo	descrição
results._id	ID da avaliação
results._id	ID único da avaliação
results.sku	SKU do produto
results.name	nome do cliente que avaliou
results.rating	nota atribuída pelo cliente
results.text	texto de avaliação do cliente
results.helpful	quantidade de pessoas que consideraram a avaliação útil
results.unhelpful	quantidade de pessoas que não consideraram a avaliação útil
results.verified	indica se o cliente é um comprador verificado
results.created	data de envio da avaliação
results.recommended	indica se o cliente avaliou o produto positivamente
results.pictures	fotos enviadas com a avaliação
results.pictures._id	ID único da foto
results.pictures.url	URL da foto
results.orderId	número do pedido (apenas quando `includeOrderData=true`)
results.sellerInfo	informações do seller/marketplace (apenas quando `includeOrderData=true`)
results.sellerInfo.id	ID do seller (apenas quando `includeOrderData=true`)
results.sellerInfo.name	nome do seller (apenas quando `includeOrderData=true`)
results.orderName	nome do cliente no pedido (apenas quando `includeOrderData=true`)
results.orderEmail	e-mail do cliente no pedido (apenas quando `includeOrderData=true`)
results.orderPhone	telefone do cliente no pedido (apenas quando `includeOrderData=true`)
total	total de avaliações obtidas com os critérios de busca

Obter perguntas

Obtém as perguntas de acordo com os critérios de busca

GET `{customer}/questions/all`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação
sku	SKU do produto que deseja buscar
status	Status das avaliações a serem buscadas (consulte tabela abaixo)
order	Ordenação dos resultados (consulte tabela abaixo)
skip	Quantidade de registros a serem omitidos (paginação)

Status de perguntas

Status	Descrição
	Omitir este campo ou enviar uma string vazia trará perguntas publicadas
`all`	Perguntas em qualquer status
`published`	Perguntas publicadas
`removed`	Perguntas reprovadas/removidas
`filtered`	Perguntas filtradas pelo filtro de palavras proibidas
`sent`	Perguntas na fila de moderação

Resposta

{
    "results": [
        {
            "_id": "669daa280a3d4e00135eb618",
            "status": "published",
            "created": "2024-07-22T00:39:04.246Z",
            "customer": "demoshakers",
            "sku": "9311078449466",
            "name": "Tony S.",
            "text": "esse produto tem em qual cor?",
            "email": "[email protected]",
            "__v": 1,
            "reply": {
                "unhelpful": 0,
                "helpful": 0,
                "created": "2024-11-05T12:22:48.259Z",
                "text": "Tem azul, vermelha e amarela"
            },
            "product": {
                "_id": "669cfc8d64e4456616dd9a6d",
                "sku": "9311078449466",
                "customer": "demoshakers",
                "brand": "Bonne Soirée",
                "categories": [
                    "Blazer e Jaqueta"
                ],
                "image": "https://cdn.shopify.com/s/files/1/0875/0976/2362/files/BONNE_SOIREE-329.jpg?v=1716429969",
                "isKit": false,
                "modified": "2024-07-29T19:38:57-04:00",
                "name": "Blazer Jeans Isabelle",
                "url": "https://demo-shakers-pro.myshopify.com/products/blazer-jeans-isabelle-1",
                "variants": [
                    "85259071",
                    "85259072",
                    "85259073",
                    "85259074"
                ],
                "status": "active",
                "sumRatings": 234,
                "totalReviews": 51
            }
        }
    ],
    "total": 1
}

Obter respostas pesquisa NPS

Obtém as respostas à pesquisa NPS

GET `{customer}/nps/responses`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação
sku	SKU do produto que deseja buscar
type	Classificação de resposta (consulte tabela abaixo)
sort	Ordenação dos resultados (consulte tabela abaixo)
skip	Quantidade de registros a serem omitidos (paginação)
from	Data inicial em formato YYYY-MM-DD (opcional)
to	Data final em formato YYYY-MM-DD (opcional)

Classificação de respostas NPS

Status	Descrição
`all`	Todas as respostas
`promoters`	Promotores (9 e 10)
`neutral`	Neutros (7 e 8)
`detractors`	Detratores (0 a 6)

Ordenação de resultados

A ordenação segue o padrão campo,ordem. A ordem pode ser 1 para ascendente ou -1 para descendente.

Campo	Descrição
`created`	Data de envio da avaliação
`rating`	Nota da avaliação (1 a 5)

Resposta

{
    "result": [
        {
            "_id": "674dad491dceb80011018301",
            "customer": "stanley",
            "surveyId": "663d4588fe42f52137cfd3a2",
            "requestId": "6709e7cef1a3f86303b6242",
            "name": "Antony S.",
            "phone": "11912345678",
            "orderId": "12345678",
            "rating": 10,
            "comment": "",
            "partial": true,
            "created": "2024-12-02T12:51:21.037Z",
            "__v": 0
        },
        {
            "_id": "674d96411dceb80011005121",
            "customer": "stanley",
            "surveyId": "663d4588fe42f52137cfd3a2",
            "requestId": "6709e7cef1a3f86303b6241",
            "name": "Bruce B.",
            "phone": "11987654321",
            "orderId": "12345679",
            "rating": 10,
            "comment": "Entrega rápida. ",
            "partial": false,
            "created": "2024-12-02T11:13:05.762Z",
            "__v": 0,
            "sendDate": "2024-12-02T11:13:17.390Z"
        }
    ],
    "total": 12740
}

Campos de resposta

campo	descrição
results._id	ID da resposta
results.name	nome do cliente que respondeu
results.phone	telefone do cliente que respondeu
results.orderId	Número do pedido que gerou a pesquisa
results.partial	Indica se a resposta foi submetida ou se é parcial (gravada automaticamente)
results.rating	nota atribuída pelo cliente
results.comment	texto de comentário do cliente
results.created	data de primeiro envio da resposta
results.sendDate	data submissão da resposta final
total	total de respostas obtidas com os critérios de busca

Relatório de produtos

Retorna uma lista paginada de produtos com seus respectivos dados de avaliações, permitindo análise de desempenho por produto.

`GET /{customer}/products/report`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação

Parâmetros de query (todos opcionais)

Parâmetro	Tipo	Descrição
order	string	Ordenação dos resultados (consulte tabela abaixo)
limit	integer	Quantidade máxima de registros a retornar (padrão: `100`)
skip	integer	Quantidade de registros a omitir para paginação (padrão: `0`)
category	string	Filtrar por categoria de produto (pode ser repetido para múltiplas categorias)
dateFrom	string	Data de início do período em formato `YYYY-MM-DD`
dateTo	string	Data de fim do período em formato `YYYY-MM-DD`
onlyPublished	boolean	Quando `true`, considera apenas avaliações com status `published` (padrão: `false`)

Opções de ordenação (`order`)

Valor	Descrição
`MoreReviews`	Produtos com mais avaliações primeiro
`LessReviews`	Produtos com menos avaliações primeiro
`MostPositive`	Produtos com melhor nota média primeiro
`MostNegative`	Produtos com pior nota média primeiro
`PositiveMoreReviews`	Melhores avaliados com mais avaliações primeiro
`PositiveLessReviews`	Melhores avaliados com menos avaliações primeiro
`NegativeMoreReviews`	Piores avaliados com mais avaliações primeiro
`NegativeLessReviews`	Piores avaliados com menos avaliações primeiro

Comportamento por período

Quando dateFrom e dateTo são fornecidos, o relatório é calculado dinamicamente a partir das avaliações no intervalo de datas indicado. Quando omitidos, os dados são obtidos dos agregados pré-computados, representando o histórico completo do produto.

Exemplo de chamada

GET /konfidency/products/report?order=PositiveMoreReviews&limit=50&skip=0&dateFrom=2024-01-01&dateTo=2024-12-31&onlyPublished=true

Exemplo de resposta

{
  "result": [
    {
      "customer": "konfidency",
      "sku": "CAM-M-AZUL",
      "name": "Camiseta Masculina Azul",
      "categories": ["Roupas", "Camisetas", "Masculino"],
      "url": "https://example.com/camiseta-masculina-azul",
      "image": "https://example.com/camiseta-masculina-azul.jpg",
      "reviews": {
        "reviewCount": 42,
        "aggregateRating": 4.7
      }
    }
  ],
  "total": 150
}

Campos de resposta

campo	descrição
result.customer	Identificador do cliente
result.sku	SKU do produto
result.name	Nome do produto
result.categories	Categorias do produto
result.url	URL da página do produto
result.image	URL da imagem principal do produto
result.reviews.reviewCount	Quantidade de avaliações no período ou no total
result.reviews.aggregateRating	Nota média das avaliações
total	Total de produtos encontrados com os critérios de busca

Moderação de Avaliações

Permite aprovar ou reprovar uma avaliação.

PUT `/{customer}/reviews/{id}/moderate`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação
id	ID da avaliação a ser moderada

Parâmetros do corpo da requisição

Parâmetro	Descrição
approved	Valor booleano: `true` para aprovar, `false` para reprovar

Exemplo de corpo da requisição

{
  "approved": true
}

Resposta

Esta API não gera um JSON de resposta. Um status 200 significa que a moderação foi registrada com sucesso.

Listar grupos de produtos

Obtém todos os grupos de produtos cadastrados.

`GET /{customer}/products/groups/all`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação

Parâmetros de query (opcionais)

Parâmetro	Descrição
skip	Quantidade de registros a serem omitidos (paginação)
limit	Quantidade máxima de registros a serem retornados

Exemplo de resposta

{
  "result": [
    {
      "_id": "6284033fb0b7371985a42200",
      "customer": "konfidency",
      "name": "Camiseta Masculina",
      "skus": ["CAM-M-AZUL", "CAM-M-PRETA"],
      "__v": 0,
      "products": [
        {
          "_id": "6284033fb0b7371985a42300",
          "customer": "konfidency",
          "sku": "CAM-M-AZUL",
          "brand": "Konfidency Store",
          "categories": ["Roupas", "Camisetas", "Masculino"],
          "image": "https://example.com/camiseta-masculina-azul.jpg",
          "name": "Camiseta Masculina Azul",
          "url": "https://example.com/camiseta-masculina-azul",
          "variants": ["CAM-M-AZUL-P", "CAM-M-AZUL-M", "CAM-M-AZUL-G", "CAM-M-AZUL-GG"]
        },
        {
          "_id": "6284033fb0b7371985a42301",
          "customer": "konfidency",
          "sku": "CAM-M-PRETA",
          "brand": "Konfidency Store",
          "categories": ["Roupas", "Camisetas", "Masculino"],
          "image": "https://example.com/camiseta-masculina-preta.jpg",
          "name": "Camiseta Masculina Preta",
          "url": "https://example.com/camiseta-masculina-preta",
          "variants": ["CAM-M-PRETA-P", "CAM-M-PRETA-M", "CAM-M-PRETA-G", "CAM-M-PRETA-GG"]
        }
      ]
    },
    {
      "_id": "6284033fb0b7371985a42201",
      "customer": "konfidency",
      "name": "Camiseta Feminina",
      "skus": ["CAM-F-ROSA", "CAM-F-BRANCA"],
      "__v": 0,
      "products": [
        {
          "_id": "6284033fb0b7371985a42302",
          "customer": "konfidency",
          "sku": "CAM-F-ROSA",
          "brand": "Konfidency Store",
          "categories": ["Roupas", "Camisetas", "Feminino"],
          "image": "https://example.com/camiseta-feminina-rosa.jpg",
          "name": "Camiseta Feminina Rosa",
          "url": "https://example.com/camiseta-feminina-rosa",
          "variants": ["CAM-F-ROSA-P", "CAM-F-ROSA-M", "CAM-F-ROSA-G"]
        },
        {
          "_id": "6284033fb0b7371985a42303",
          "customer": "konfidency",
          "sku": "CAM-F-BRANCA",
          "brand": "Konfidency Store",
          "categories": ["Roupas", "Camisetas", "Feminino"],
          "image": "https://example.com/camiseta-feminina-branca.jpg",
          "name": "Camiseta Feminina Branca",
          "url": "https://example.com/camiseta-feminina-branca",
          "variants": ["CAM-F-BRANCA-P", "CAM-F-BRANCA-M", "CAM-F-BRANCA-G"]
        }
      ]
    }
  ],
  "total": 2
}

Campos de resposta

campo	descrição
result._id	ID único do grupo
result.customer	Cliente ao qual o grupo pertence
result.name	Nome do grupo de produtos
result.skus	Array com os SKUs dos produtos do grupo
result.__v	Versão do documento
result.products	Array com dados completos dos produtos do grupo
result.products._id	ID único do produto
result.products.sku	SKU do produto
result.products.name	Nome do produto
result.products.brand	Marca do produto
result.products.categories	Categorias do produto
result.products.image	URL da imagem principal do produto
result.products.url	URL da página do produto
result.products.variants	Variantes/SKUs filhos do produto
total	Total de grupos cadastrados

Obter grupo de produtos

Obtém os detalhes de um grupo de produtos específico.

`GET /{customer}/products/groups/{id}`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação
id	ID do grupo de produtos

Exemplo de resposta

{
  "_id": "6284033fb0b7371985a42200",
  "customer": "konfidency",
  "name": "Camiseta Masculina",
  "skus": ["CAM-M-AZUL", "CAM-M-PRETA"],
  "__v": 0,
  "products": [
    {
      "_id": "6284033fb0b7371985a42300",
      "customer": "konfidency",
      "sku": "CAM-M-AZUL",
      "brand": "Konfidency Store",
      "categories": ["Roupas", "Camisetas", "Masculino"],
      "image": "https://example.com/camiseta-masculina-azul.jpg",
      "name": "Camiseta Masculina Azul",
      "url": "https://example.com/camiseta-masculina-azul",
      "variants": ["CAM-M-AZUL-P", "CAM-M-AZUL-M", "CAM-M-AZUL-G", "CAM-M-AZUL-GG"]
    },
    {
      "_id": "6284033fb0b7371985a42301",
      "customer": "konfidency",
      "sku": "CAM-M-PRETA",
      "brand": "Konfidency Store",
      "categories": ["Roupas", "Camisetas", "Masculino"],
      "image": "https://example.com/camiseta-masculina-preta.jpg",
      "name": "Camiseta Masculina Preta",
      "url": "https://example.com/camiseta-masculina-preta",
      "variants": ["CAM-M-PRETA-P", "CAM-M-PRETA-M", "CAM-M-PRETA-G", "CAM-M-PRETA-GG"]
    }
  ]
}

Campos de resposta

campo	descrição
_id	ID único do grupo
customer	Cliente ao qual o grupo pertence
name	Nome do grupo de produtos
skus	Array com os SKUs dos produtos do grupo
__v	Versão do documento
products	Array com dados completos dos produtos do grupo
products._id	ID único do produto
products.sku	SKU do produto
products.name	Nome do produto
products.brand	Marca do produto
products.categories	Categorias do produto
products.image	URL da imagem principal do produto
products.url	URL da página do produto
products.variants	Variantes/SKUs filhos do produto (ex: tamanhos)

Criar grupo de produtos

Cria um novo grupo de produtos.

`POST /{customer}/products/groups`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação

Parâmetros do corpo da requisição

Parâmetro	Descrição
name	Nome do grupo de produtos
skus	Array com os SKUs dos produtos a serem agrupados

Exemplo de corpo da requisição

{
  "name": "Camiseta Masculina",
  "skus": ["CAM-M-AZUL", "CAM-M-PRETA"]
}

Exemplo de resposta

{
  "_id": "6284033fb0b7371985a42200",
  "customer": "konfidency",
  "name": "Camiseta Masculina",
  "skus": ["CAM-M-AZUL", "CAM-M-PRETA"],
  "__v": 0,
  "products": [
    {
      "_id": "6284033fb0b7371985a42300",
      "customer": "konfidency",
      "sku": "CAM-M-AZUL",
      "brand": "Konfidency Store",
      "categories": ["Roupas", "Camisetas", "Masculino"],
      "image": "https://example.com/camiseta-masculina-azul.jpg",
      "name": "Camiseta Masculina Azul",
      "url": "https://example.com/camiseta-masculina-azul",
      "variants": ["CAM-M-AZUL-P", "CAM-M-AZUL-M", "CAM-M-AZUL-G", "CAM-M-AZUL-GG"]
    },
    {
      "_id": "6284033fb0b7371985a42301",
      "customer": "konfidency",
      "sku": "CAM-M-PRETA",
      "brand": "Konfidency Store",
      "categories": ["Roupas", "Camisetas", "Masculino"],
      "image": "https://example.com/camiseta-masculina-preta.jpg",
      "name": "Camiseta Masculina Preta",
      "url": "https://example.com/camiseta-masculina-preta",
      "variants": ["CAM-M-PRETA-P", "CAM-M-PRETA-M", "CAM-M-PRETA-G", "CAM-M-PRETA-GG"]
    }
  ]
}

Resposta de erro (409 - Conflito)

Caso algum SKU já pertença a outro grupo, a API retornará status 409 com os SKUs conflitantes:

{
  "message": "Alguns SKUs já pertencem a outros grupos",
  "conflictingSkus": ["CAM-M-AZUL"]
}

Campos de resposta

campo	descrição
_id	ID único do grupo criado
customer	Cliente ao qual o grupo pertence
name	Nome do grupo de produtos
skus	Array com os SKUs dos produtos do grupo
__v	Versão do documento
products	Array com dados completos dos produtos do grupo
products._id	ID único do produto
products.sku	SKU do produto
products.name	Nome do produto
products.brand	Marca do produto
products.categories	Categorias do produto
products.image	URL da imagem principal do produto
products.url	URL da página do produto
products.variants	Variantes/SKUs filhos do produto (ex: tamanhos)

Atualizar grupo de produtos

Atualiza um grupo de produtos existente.

`PUT /{customer}/products/groups/{id}`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação
id	ID do grupo de produtos a ser atualizado

Parâmetros do corpo da requisição

Parâmetro	Descrição
name	Nome do grupo de produtos
skus	Array com os SKUs dos produtos a serem agrupados

Exemplo de corpo da requisição

{
  "name": "Camiseta Masculina",
  "skus": ["CAM-M-AZUL", "CAM-M-PRETA", "CAM-M-VERDE"]
}

Exemplo de resposta

{
  "_id": "6284033fb0b7371985a42200",
  "customer": "konfidency",
  "name": "Camiseta Masculina",
  "skus": ["CAM-M-AZUL", "CAM-M-PRETA", "CAM-M-VERDE"],
  "__v": 0,
  "products": [
    {
      "_id": "6284033fb0b7371985a42300",
      "customer": "konfidency",
      "sku": "CAM-M-AZUL",
      "brand": "Konfidency Store",
      "categories": ["Roupas", "Camisetas", "Masculino"],
      "image": "https://example.com/camiseta-masculina-azul.jpg",
      "name": "Camiseta Masculina Azul",
      "url": "https://example.com/camiseta-masculina-azul",
      "variants": ["CAM-M-AZUL-P", "CAM-M-AZUL-M", "CAM-M-AZUL-G", "CAM-M-AZUL-GG"]
    },
    {
      "_id": "6284033fb0b7371985a42301",
      "customer": "konfidency",
      "sku": "CAM-M-PRETA",
      "brand": "Konfidency Store",
      "categories": ["Roupas", "Camisetas", "Masculino"],
      "image": "https://example.com/camiseta-masculina-preta.jpg",
      "name": "Camiseta Masculina Preta",
      "url": "https://example.com/camiseta-masculina-preta",
      "variants": ["CAM-M-PRETA-P", "CAM-M-PRETA-M", "CAM-M-PRETA-G", "CAM-M-PRETA-GG"]
    },
    {
      "_id": "6284033fb0b7371985a42305",
      "customer": "konfidency",
      "sku": "CAM-M-VERDE",
      "brand": "Konfidency Store",
      "categories": ["Roupas", "Camisetas", "Masculino"],
      "image": "https://example.com/camiseta-masculina-verde.jpg",
      "name": "Camiseta Masculina Verde",
      "url": "https://example.com/camiseta-masculina-verde",
      "variants": ["CAM-M-VERDE-P", "CAM-M-VERDE-M", "CAM-M-VERDE-G", "CAM-M-VERDE-GG"]
    }
  ]
}

Resposta de erro (409 - Conflito)

Caso algum SKU já pertença a outro grupo, a API retornará status 409 com os SKUs conflitantes:

{
  "message": "Alguns SKUs já pertencem a outros grupos",
  "conflictingSkus": ["CAM-M-VERDE"]
}

Campos de resposta

campo	descrição
_id	ID único do grupo
customer	Cliente ao qual o grupo pertence
name	Nome atualizado do grupo de produtos
skus	Array atualizado com os SKUs do grupo
__v	Versão do documento
products	Array com dados completos dos produtos do grupo
products._id	ID único do produto
products.sku	SKU do produto
products.name	Nome do produto
products.brand	Marca do produto
products.categories	Categorias do produto
products.image	URL da imagem principal do produto
products.url	URL da página do produto
products.variants	Variantes/SKUs filhos do produto (ex: tamanhos)

Deletar grupo de produtos

Remove um grupo de produtos.

`DELETE /{customer}/products/groups/{id}`

Parâmetros de URL

Parâmetro	Descrição
customer	Seu Customer key — consulte Obtendo chaves de autenticação
id	ID do grupo de produtos a ser deletado

Resposta

Esta API não gera um JSON de resposta. Um status 200 significa que o grupo foi deletado com sucesso.

Autenticação​

Obtendo chaves de autenticação​

POST https://reviews-api.konfidency.com.br/oauth/token​

Campos do corpo da requisição (JSON)​

Exemplo de corpo da requisição​

Exemplo de Resposta​

Campos​

Link de avaliação​

GET /{customer}/orders/{orderId}/ratelink​

Parâmetros de URL​

Exemplo de Resposta​

Campos da resposta​

Criar Pedido​

POST /{customer}/orders​

Parâmetros de URL​

Parâmetros do corpo da requisição​

Exemplo de corpo da requisição​

Resposta​

Criar Pedido (V2)​

POST /{customer}/orders​

Parâmetros de URL​

Parâmetros do corpo da requisição​

Estrutura de items (V2)​

Estrutura de items.sellerInfo (Marketplace)​

Estrutura de items.productData​

Exemplo de corpo da requisição (V2)​

Diferenças da V2​

Resposta​

Atualizar Pedido​

PUT /{customer}/orders/{orderId}​

Parâmetros de URL​

Parâmetros do corpo da requisição​

Exemplo de corpo da requisição​

Resposta​

Obter avaliações​

GET /{customer}/reviews/all​

POST /{customer}/reviews/all​

Parâmetros de URL​

Parâmetros de Query (todos opcionais)​

Status de avaliações​

Ordenação de resultados​

Parâmetros adicionais do método POST (corpo da requisição)​

Exemplo de chamada GET com filtros​

Exemplo de chamada GET com dados de pedido e seller​

Exemplo de corpo da requisição POST​

Resposta​

Campos de resposta​

Obter perguntas​

GET {customer}/questions/all​

Parâmetros de URL​

Status de perguntas​

Resposta​

Obter respostas pesquisa NPS​

GET {customer}/nps/responses​

Parâmetros de URL​

Classificação de respostas NPS​

Ordenação de resultados​

Resposta​

Campos de resposta​

Relatório de produtos​

GET /{customer}/products/report​

Parâmetros de URL​

Parâmetros de query (todos opcionais)​

Opções de ordenação (order)​

Comportamento por período​

Exemplo de chamada​

Exemplo de resposta​

Campos de resposta​

Moderação de Avaliações​

PUT /{customer}/reviews/{id}/moderate​

Parâmetros de URL​

Parâmetros do corpo da requisição​

Exemplo de corpo da requisição​

Resposta​

Listar grupos de produtos​

GET /{customer}/products/groups/all​

Parâmetros de URL​

Parâmetros de query (opcionais)​

Exemplo de resposta​

Campos de resposta​

Autenticação

Obtendo chaves de autenticação

`POST` https://reviews-api.konfidency.com.br/oauth/token

Campos do corpo da requisição (JSON)

Exemplo de corpo da requisição

Exemplo de Resposta

Campos

Link de avaliação

`GET /{customer}/orders/{orderId}/ratelink`

Parâmetros de URL

Exemplo de Resposta

Campos da resposta

Criar Pedido

`POST /{customer}/orders`

Parâmetros de URL

Parâmetros do corpo da requisição

Exemplo de corpo da requisição

Resposta

Criar Pedido (V2)

`POST /{customer}/orders`

Parâmetros de URL

Parâmetros do corpo da requisição

Estrutura de items (V2)

Estrutura de items.sellerInfo (Marketplace)

Estrutura de items.productData

Exemplo de corpo da requisição (V2)

Diferenças da V2

Resposta

Atualizar Pedido

`PUT /{customer}/orders/{orderId}`

Parâmetros de URL

Parâmetros do corpo da requisição

Exemplo de corpo da requisição

Resposta

Obter avaliações

`GET /{customer}/reviews/all`

`POST /{customer}/reviews/all`

Parâmetros de URL

Parâmetros de Query (todos opcionais)

Status de avaliações

Ordenação de resultados

Parâmetros adicionais do método POST (corpo da requisição)

Exemplo de chamada GET com filtros

Exemplo de chamada GET com dados de pedido e seller

Exemplo de corpo da requisição POST

Resposta

Campos de resposta

Obter perguntas

GET `{customer}/questions/all`

Parâmetros de URL

Status de perguntas

Resposta

Obter respostas pesquisa NPS

GET `{customer}/nps/responses`

Parâmetros de URL

Classificação de respostas NPS

Ordenação de resultados

Resposta

Campos de resposta

Relatório de produtos

`GET /{customer}/products/report`

Parâmetros de URL

Parâmetros de query (todos opcionais)

Opções de ordenação (`order`)

Comportamento por período

Exemplo de chamada

Exemplo de resposta

Campos de resposta

Moderação de Avaliações

PUT `/{customer}/reviews/{id}/moderate`

Parâmetros de URL

Parâmetros do corpo da requisição

Exemplo de corpo da requisição

Resposta

Listar grupos de produtos

`GET /{customer}/products/groups/all`

Parâmetros de URL

Parâmetros de query (opcionais)

Exemplo de resposta

Campos de resposta