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

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"
            }
          ]
        }
      ]
    }
  ],
  "composition": [
    {
      "_id": 3,
      "count": 1
    },
    {
      "_id": 4,
      "count": 3
    },
    {
      "_id": 5,
      "count": 9
    }
  ],
  "customerSettings": {
    "minStarsHighlightPDP": 3.5
  }
}

Campos

campo	descripción	tipo de datos
_id	SKU del producto	string
aggregateRating	calificación media del producto	float
recommendedPercentage	porcentaje de usuarios que calificaron el producto positivamente	double
reviewCount	cantidad total de evaluaciones	integer
reviews._id	ID único de la evaluación	string
reviews.sku	SKU del producto	string
reviews.name	nombre del cliente que evaluó	string
reviews.rating	calificación otorgada por el cliente	integer
reviews.text	texto de la evaluación del cliente	string
reviews.helpful	cantidad de personas que consideraron útil la evaluación	integer
reviews.unhelpful	cantidad de personas que no consideraron útil la evaluación	integer
reviews.verified	indica si el cliente es un comprador verificado	boolean
reviews.created	fecha de envío de la evaluación	string (fecha en formato ISO-8601)
reviews.recommended	indica si el cliente calificó el producto positivamente	boolean
reviews.update	última fecha de actualización de la evaluación	string (fecha en formato ISO-8601)
reviews.pictures	fotos enviadas con la evaluación	array
reviews.pictures._id	ID único de la foto	string
reviews.pictures.url	URL da foto	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