Client API

La API REST puede ser utilizada en tu aplicación móvil o para permitir una mayor personalización de la solución en tu comercio electrónico o aplicación de ventas.

Endpoints

Endpoints de evaluaciones de producto

• Obtener evaluaciones
• Enviar evaluación
• Marcar evaluación como útil
• Marcar evaluación como no útil

Endpoints de evaluaciones de la tienda

• Resumen de las evaluaciones de la tienda
• Listar evaluaciones de la tienda
• Carrusel de evaluaciones de la tienda

Endpoints de Productos Top Rated

• Obtener productos Top Rated activos

Endpoints de evaluaciones de producto

Obtener evaluaciones

Obtiene los datos agregados totales y los datos detallados de las primeras 50 evaluaciones de un producto.

GET /{customer}/{sku}/summary/{sortField,sortOrder}?page={page}&pageSize={pageSize}

Parámetros de URL

Parámetro	Descripción
customer	Proporcionado por nuestro equipo de integración
sku	SKU del producto
sortField	Campos para ordenación (tabla a continuación)
sortOrder	Dirección de la ordenación (asc o desc)

Campos para ordenación

| Campo | Descripción | | helpfulScore | Puntuación de ordenación (algoritmo predeterminado - más útiles). | | created | Fecha de la evaluación | | rating | Puntuación de la evaluación (de 1 a 5) |

Parámetros de Query String

Parámetro	Descripción
page	Página a obtener
pageSize	Cantidad de evaluaciones por página
filterMedia	Filtra evaluaciones por tipo de medio: pictures, videos, any (cualquier medio), none (sin medio)
hasText	Cuando es true, retorna solo las evaluaciones que contienen texto

tip

Si los parámetros page y pageSize no se envían, se retornarán todas las evaluaciones para el SKU

Respuesta

{
  "reviews": [
    {
      "_id": "337892",
      "aggregateRating": 4.6,
      "recommendedPercentage": 100,
      "reviewCount": 13,
      "reviews": [
        {
          "_id": "612a928939ff8f181675bae8",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Phillip Long",
          "rating": 5,
          "helpful": 4,
          "unhelpful": 0,
          "verified": false,
          "created": "2020-08-30T11:32:11.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-01T23:08:09.432Z"
        },
        {
          "_id": "612a928939ff8f181675baff",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Walquiria Santos",
          "rating": 5,
          "helpful": 8,
          "unhelpful": 0,
          "verified": false,
          "created": "2019-05-07T11:20:34.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.712Z"
        },
        {
          "_id": "612a928939ff8f181675bb1d",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Elaine Durães",
          "rating": 5,
          "helpful": 5,
          "unhelpful": 0,
          "verified": false,
          "created": "2019-06-30T21:29:58.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.715Z"
        },
        {
          "_id": "612a928939ff8f181675bb29",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Sandra Lopes",
          "rating": 5,
          "helpful": 4,
          "unhelpful": 1,
          "verified": false,
          "created": "2020-08-07T01:46:37.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.713Z"
        },
        {
          "_id": "612a928939ff8f181675bb41",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Vanessa Begalli Martins",
          "rating": 5,
          "helpful": 3,
          "unhelpful": 0,
          "verified": false,
          "created": "2019-10-07T21:51:11.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.712Z"
        },
        {
          "_id": "612a928939ff8f181675bb40",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Jessica Fontes",
          "rating": 4,
          "helpful": 6,
          "unhelpful": 0,
          "verified": false,
          "created": "2020-09-14T21:38:49.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.711Z"
        },
        {
          "_id": "612a928939ff8f181675bb50",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Fabiana Aquim",
          "rating": 4,
          "helpful": 4,
          "unhelpful": 0,
          "verified": false,
          "created": "2021-03-20T22:22:17.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.709Z"
        },
        {
          "_id": "612a928939ff8f181675bb61",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Fernanda Correia",
          "rating": 5,
          "helpful": 4,
          "unhelpful": 0,
          "verified": false,
          "created": "2020-07-12T16:11:20.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.714Z"
        },
        {
          "_id": "612a928939ff8f181675bb62",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Rodrigo JN",
          "rating": 3,
          "helpful": 3,
          "unhelpful": 0,
          "verified": false,
          "created": "2021-06-15T23:34:11.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-09-17T17:07:29.170Z"
        },
        {
          "_id": "612a928939ff8f181675bb6f",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Helen Evangelista",
          "rating": 5,
          "helpful": 7,
          "unhelpful": 5,
          "verified": false,
          "created": "2018-08-22T02:37:32.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.708Z"
        },
        {
          "_id": "61452dd5856d062c0f8ee0cf",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Felipe Censi",
          "rating": 5,
          "helpful": 2,
          "unhelpful": 0,
          "verified": false,
          "created": "2021-06-26T12:59:56.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.709Z"
        },
        {
          "_id": "617f3efa63278dc79120e89e",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Elenivalda Teixeira",
          "rating": 4,
          "helpful": 3,
          "unhelpful": 0,
          "verified": false,
          "created": "2021-01-22T13:16:26.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-01T23:08:09.433Z"
        },
        {
          "_id": "61a862cde3cabb8625858fb9",
          "customer": "tokstok",
          "sku": "337892",
          "name": "Fabiane de Moraes",
          "rating": 5,
          "helpful": 2,
          "unhelpful": 0,
          "verified": false,
          "created": "2021-05-28T17:31:13.000Z",
          "status": "published",
          "recommended": true,
          "updated": "2021-12-12T11:07:54.716Z",
          "pictures": [
            {
              "_id": "629f79d569ede80012ca7172",
              "url": "https://uploads.konfidency.com.br/a98cd120-abe9-436f-b4de-78e8a0b52071",
              "thumb": "https://uploads.konfidency.com.br/thumbs/a98cd120-abe9-436f-b4de-78e8a0b52071.jpg"
            }
          ],
          "attributes": [
            {
              "title": "Calidad",
              "value": 5,
              "type": "stars",
              "scaleMin": 1,
              "scaleMax": 5
            },
            {
              "title": "Talla",
              "value": 1,
              "type": "multiple-choice",
              "response": "Igual"
            }
          ],
          "reply": {
            "created": "2021-12-15T10:00:00.000Z",
            "text": "¡Gracias por tu comentario! Nos alegra que hayas disfrutado el producto.",
            "helpful": 1,
            "unhelpful": 0
          },
          "productReviewed": {
            "sku": "337892-P",
            "name": "Camiseta Minimal - Talla S",
            "url": "https://tienda.com/camiseta-minimal-s"
          }
        }
      ]
    }
  ],
  "composition": [
    {
      "_id": 3,
      "count": 1
    },
    {
      "_id": 4,
      "count": 3
    },
    {
      "_id": 5,
      "count": 9
    }
  ],
  "customerSettings": {
    "minStarsHighlightPDP": 3.5
  }
}

Campos

reviews[] (datos agregados por SKU)

campo	descripción	tipo de datos
_id	SKU del producto	string
aggregateRating	calificación promedio del producto	float
recommendedPercentage	porcentaje de usuarios que calificaron el producto positivamente	double
reviewCount	cantidad total de evaluaciones	integer

reviews.reviews[] (lista de evaluaciones individuales)

campo	descripción	tipo de datos
_id	ID único de la evaluación	string
sku	SKU del producto	string
name	nombre del cliente que evaluó	string
rating	calificación otorgada por el cliente	integer
text	texto de la evaluación del cliente	string
helpful	cantidad de personas que consideraron útil la evaluación	integer
unhelpful	cantidad de personas que no consideraron útil la evaluación	integer
verified	indica si el cliente es un comprador verificado	boolean
created	fecha de envío de la evaluación	string (fecha en formato ISO-8601)
recommended	indica si el cliente calificó el producto positivamente	boolean
updated	última fecha de actualización de la evaluación	string (fecha en formato ISO-8601)
pictures	fotos enviadas con la evaluación	array
video	video enviado con la evaluación	objeto
attributes	atributos completados por el cliente en esta evaluación	array
reply	respuesta de la tienda a esta evaluación (cuando existe)	objeto o null
productReviewed	producto específico evaluado — presente solo en evaluaciones de productos que forman parte de un grupo o kit	objeto o null
syndicationDisplaySource	nombre de visualización de la tienda de origen — presente solo en evaluaciones sindicalizadas	string o null
syndicationSourceLogo	URL del logotipo de la tienda de origen — presente solo en evaluaciones sindicalizadas	string o null
syndicationSourceProductUrl	URL del producto en la tienda de origen — presente solo en evaluaciones sindicalizadas	string o null
syndicationOriginalText	texto original de la evaluación antes de la traducción — presente solo cuando se aplicó traducción	string o null

reviews.pictures[]

campo	descripción	tipo de datos
_id	ID único de la foto	string
url	URL de la foto	string
thumb	URL de la miniatura	string

reviews.video

campo	descripción	tipo de datos
url	URL del video	string
thumb	URL de la miniatura	string

reviews.reviews[].attributes[] (atributos por evaluación)

Atributos completados por el cliente al enviar la evaluación. A diferencia de reviews[].attributes (resumen agregado), este array contiene los valores individuales de cada evaluador.

campo	descripción	tipo de datos
title	título del atributo	string
value	valor numérico asignado (1–5 para stars)	integer
type	tipo del atributo: stars o multiple-choice	string
response	texto de la respuesta seleccionada (solo para atributos multiple-choice)	string
scaleMin	valor mínimo de la escala (solo para atributos stars)	integer
scaleMax	valor máximo de la escala (solo para atributos stars)	integer

reviews.reviews[].reply

Respuesta de la tienda a la evaluación. Este campo estará ausente o será null cuando la tienda aún no haya respondido.

campo	descripción	tipo de datos
created	fecha en que se publicó la respuesta	string (fecha en formato ISO-8601)
text	texto de la respuesta de la tienda	string
helpful	cantidad de personas que consideraron útil la respuesta	integer
unhelpful	cantidad de personas que no consideraron útil la respuesta	integer

reviews.reviews[].productReviewed

Presente solo cuando la evaluación pertenece a un producto que forma parte de un grupo o kit. Identifica el producto específico evaluado dentro del conjunto.

campo	descripción	tipo de datos
sku	SKU del producto evaluado	string
name	nombre del producto evaluado	string
url	URL del producto evaluado	string

tip

Para obtener el número total de páginas, tu aplicación debe calcularlo basado en el campo reviewCount

Enviar evaluación

Permite enviar una evaluación sobre un producto.

POST /{customer}/{sku}/review

Parámetros de URL

Parámetro	Descripción
customer	Proporcionado por nuestro equipo de integración
sku	SKU del producto

Campos del cuerpo de la solicitud (JSON)

campo	descripción	tipo de datos
userId	ID del usuario en tu plataforma	string
email	correo electrónico del usuario en tu plataforma	string
rating	número de estrellas otorgado por el usuario al producto	integer
text	texto de la evaluación del cliente	string
recommended	indica si el cliente califica el producto positivamente	boolean

info

Los campos userId y email se utilizarán como clave compuesta para garantizar que el usuario esté autenticado correctamente en la plataforma y evitar que se asignen evaluaciones a otros usuarios

info

Las evaluaciones deben ser aprobadas a través de nuestro panel de control antes de ser publicadas en tu tienda

Ejemplo de cuerpo de la solicitud

{
  "userId": "12345678-1234-1234-1234-123456789012",
  "email": "[email protected]",
  "rating": 5,
  "text": "Producto perfecto para mis necesidades"
}

Respuesta

{
  "helpful": 0,
  "unhelpful": 0,
  "verified": false,
  "status": "sent",
  "_id": "61b6084bbe562d0018e43cac",
  "created": "2021-12-12T14:33:47.749Z",
  "customer": "tokstok",
  "userId": "12345678-1234-1234-1234-123456789012",
  "name": "Tony S",
  "sku": "337892",
  "text": "Producto perfecto para mis necesidades",
  "recommended": true,
  "rating": 5
}

Campos

campo	descripción	tipo de datos
_id	ID único de la evaluación enviada	string
status	Status de la evaluación, normalmente será "enviado" en este momento.	string
created	Fecha de envío de la evaluación	string (fecha en formato ISO-8601)
userId	ID del usuario que realizó la evaluación	string
name	nombre del cliente que realizó la evaluación	string
sku	SKU del producto	string
rating	número de estrellas otorgado por el usuario al producto	integer
text	texto de la evaluación del cliente	string
recommended	indica si el cliente califica el producto positivamente	boolean
verified	indica si el cliente es un comprador verificado	boolean
helpful	cantidad de personas que consideraron útil la evaluación	integer
unhelpful	cantidad de personas que no consideraron útil la evaluación	integer

Marcar evaluación como útil (dar me gusta)

Permite marcar una evaluación como útil. Este dato se utiliza para que los propios clientes elijan cuáles evaluaciones son más útiles y se ayuden mutuamente.

POST /{customer}/{sku}/review/{reviewId}/like

Parámetros de URL

Parámetro	Descripción
customer	Proporcionado por nuestro equipo de integración
sku	SKU del producto
reviewId	ID único de la evaluación

Campos del cuerpo de la solicitud (JSON)

campo	descripción	tipo de datos
userId	ID del usuario en tu plataforma	string
email	correo electrónico del usuario en tu plataforma	string

Ejemplo de cuerpo de la solicitud

{
  "userId": "12345678-1234-1234-1234-123456789012",
  "email": "[email protected]"
}

Respuesta

{
  "helpful": 1,
  "unhelpful": 0,
  "verified": false,
  "status": "published",
  "_id": "61b6084bbe562d0018e43cac",
  "created": "2021-12-12T14:33:47.749Z",
  "customer": "tokstok",
  "userId": "12345678-1234-1234-1234-123456789012",
  "name": "Tony S",
  "sku": "337892",
  "text": "Producto perfecto para mis necesidade",
  "recommended": true,
  "rating": 4,
  "__v": 0
}

Campos

campo	descripción	tipo de datos
_id	ID único de la evaluación enviada	string
status	Status de la evaluación, normalmente será "enviado" en este momento.	string
created	Fecha de envío de la evaluación	string (fecha en formato ISO-8601)
userId	ID del usuario que realizó la evaluación	string
name	nombre del cliente que realizó la evaluación	string
sku	SKU del producto	string
rating	número de estrellas otorgado por el usuario al producto	integer
text	texto de la evaluación del cliente	string
recommended	indica si el cliente califica el producto positivamente	boolean
verified	indica si el cliente es un comprador verificado	boolean
helpful	cantidad de personas que consideraron útil la evaluación	integer
unhelpful	cantidad de personas que no consideraron útil la evaluación	integer

Marcar evaluación como no útil (no me gusta)

Permite marcar una evaluación como no útil. Este dato se utiliza para que los propios clientes elijan cuáles evaluaciones no son útiles y se ayuden mutuamente.

POST /{customer}/{sku}/review/{reviewId}/dislike

Parámetros de URL

Parámetro	Descripción
customer	Proporcionado por nuestro equipo de integración
sku	SKU del producto
reviewId	ID único de la evaluación

Campos do corpo da requisição (JSON)

campo	descripción	tipo de datos
userId	ID del usuario en tu plataforma	string
email	correo electrónico del usuario en tu plataforma	string

Ejemplo de cuerpo de la solicitud

{
  "userId": "12345678-1234-1234-1234-123456789012",
  "email": "[email protected]"
}

Respuesta

{
  "helpful": 1,
  "unhelpful": 0,
  "verified": false,
  "status": "published",
  "_id": "61b6084bbe562d0018e43cac",
  "created": "2021-12-12T14:33:47.749Z",
  "customer": "tokstok",
  "userId": "12345678-1234-1234-1234-123456789012",
  "name": "Tony S",
  "sku": "337892",
  "text": "Producto perfecto para mis necesidade",
  "recommended": true,
  "rating": 4,
  "__v": 0
}

Campos

campo	descripción	tipo de datos
_id	ID único de la evaluación enviada	string
status	Status de la evaluación, normalmente será "enviado" en este momento.	string
created	Fecha de envío de la evaluación	string (fecha en formato ISO-8601)
userId	ID del usuario que realizó la evaluación	string
name	nombre del cliente que realizó la evaluación	string
sku	SKU del producto	string
rating	número de estrellas otorgado por el usuario al producto	integer
text	texto de la evaluación del cliente	string
recommended	indica si el cliente califica el producto positivamente	boolean
verified	indica si el cliente es un comprador verificado	boolean
helpful	cantidad de personas que consideraron útil la evaluación	integer
unhelpful	cantidad de personas que no consideraron útil la evaluación	integer

Endpoints de evaluaciones de la tienda

Resumen de las evaluaciones de la tienda

Obtiene los datos resumidos de las evaluaciones de la tienda, como la cantidad total de evaluaciones y la calificación promedio.

GET /{customer}/store-reviews/summary

Parámetros de URL

Parámetro	Descripción
customer	Proporcionado por nuestro equipo de integración

Respuesta

[
  {
    "_id": "konfidency",
    "count": 2904,
    "avgRating": 4.747245179063361,
    "enableStoreReview": true
  }
]

Campos

campo	descripción	tipo de datos
_id	ID del cliente	string
count	cantidad de evaluaciones de la tienda	integer
avgRating	calificación promedio de la tienda	float
enableStoreReview	indica si las evaluaciones de la tienda están activas para la tienda	boolean

Listar evaluaciones de la tienda

Obtiene los datos detallados de las evaluaciones de la tienda

GET /{customer}/store-reviews/published/{sort}

Parámetros de URL

Parámetro	Descripción
customer	Proporcionado por nuestro equipo de integración
sort	Ordenación de los resultados (ver tabla a continuación)

Ordenación de los resultados

La ordenación sigue el patrón campo,orden. El orden puede ser 1 para ascendente o -1 para descendente.

Campo	Descripción
created	Fecha de envío de la evaluación
sku	SKU del producto
rating	Calificación de la evaluación (de 1 a 5)
helpful	Las más marcadas como útiles
unhelpful	Las más marcadas como no útiles

Respuesta

{
  "results": [
    {
      "_id": "658310dd5c26870012a0d06a",
      "created": "2023-12-20T16:05:49.246Z",
      "customer": "konfidency",
      "rating": 5,
      "text": "Productos de excelente calidad y excelente atención.",
      "name": "Tony S"
    }
  ]
}

Campos

campo	descripción	tipo de datos
_id	ID único de la evaluación
created	Fecha de envío de la evaluación	string (fecha en formato ISO-8601)
customer	ID del cliente	string
rating	Calificación de la evaluación.	integer
text	Texto de la evaluación del cliente	string
name	Nombre del consumidor	string

Carrusel de evaluaciones de la tienda

Obtiene los datos para la visualización del carrusel de evaluaciones de la tienda (las últimas 10 evaluaciones más positivas).

GET /{customer}/store-reviews/carousel

Parámetros de URL

Parámetro	Descripción
customer	Proporcionado por nuestro equipo de integración

Respuesta

[
  {
    "_id": "658310dd5c26870012a0d06f",
    "created": "2023-12-20T16:05:49.246Z",
    "customer": "utilplast",
    "rating": 5,
    "text": "Productos de excelente calidad y excelente atención.",
    "name": "Tony S"
  }
]

Campos

campo	descripción	tipo de datos
_id	ID único de la evaluación
created	Fecha de envío de la evaluación	string (fecha en formato ISO-8601)
customer	ID del cliente	string
rating	Calificación de la evaluación.	integer
text	Texto de la evaluación del cliente	string
name	Nombre del consumidor	string

Endpoints de Productos Top Rated

Obtener productos Top Rated activos

Retorna la lista de SKUs que están actualmente activos como productos Top Rated, de acuerdo con las configuraciones definidas en el panel de control. Utilizado por el SDK para mostrar el badge de destaque en los productos elegibles.

GET /{customer}/top-rated/active

Parámetros de URL

Parámetro	Descripción
customer	Proporcionado por nuestro equipo de integración

Respuesta

{
  "skus": ["12345", "67890", "11223"],
  "badgeLabel": "Top Rated"
}

Campos

campo	descripción	tipo de datos
skus	lista de SKUs de los productos activos como Top Rated	array de strings
badgeLabel	texto del badge a mostrar en los productos destacados	string