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
• Atualizar pedido
• Obter avaliações
• Obter perguntas
• Obter respostas pesquisa NPS

Autenticação

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

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	ID de cliente enviado pelo time de integração
client_secret	Token secreto enviado pelo time de integraçã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	Fornecido pelo nosso time de integraçã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	Fornecido pelo nosso time de integração

Parâmetros do corpo da requisição

Parâmetro	Descrição
orderId	Número do pedido, identificação única na plataforma do cliente
created	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 produto
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
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",
  "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

Atualizar Pedido

Atualiza o status do pedido na plataforma Konfidency Reviews

PUT /{customer}/orders/{orderId}

Parâmetros de URL

Parâmetro	Descrição
customer	Fornecido pelo nosso time de integraçã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

Parâmetros de URL

Parâmetro	Descrição
customer	Fornecido pelo nosso time de integraçã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 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
sku	SKU do produto
rating	Nota da avaliação (1 a 5)
helpful	Mais marcadas como úteis
unhelpful	Mais marcadas como não úteis

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
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	Fornecido pelo nosso time de integraçã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	Fornecido pelo nosso time de integraçã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