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 Estado de Evaluación de Pedido

• Cuándo usar cada endpoint
• Verificar estado de un pedido
• Verificar estado de múltiples pedidos (batch)

Redirigir al cliente para evaluar un pedido

• Parámetros opcionales
• Uso en modal (embedded)
• Ejemplos

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
sourceStore	Filtra evaluaciones por tienda de origen (syndication). Acepta un ID de tienda o múltiples separados por ;

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
  },
  "syndicationSources": ["tienda-abc", "tienda-xyz"]
}

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
syndicationSourceCustomer	ID de la tienda de origen — presente solo en evaluaciones sindicalizadas	string 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

syndicationSources

Lista de IDs de las tiendas de origen con evaluaciones sindicalizadas disponibles para el SKU. Retorna un array vacío cuando no hay evaluaciones sindicalizadas.

campo	descripción	tipo de datos
—	ID de la tienda de origen	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
verificationTokenId	token del ítem del pedido obtenido vía /orders/find o /orders/find-batch	string
orderId	ID del pedido — obligatorio cuando se envía verificationTokenId	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
source	canal de origen de la evaluación — ver valores estándar a continuación (opcional)	string

Valores estándar del campo source

Valor	Descripción
email	Evaluación iniciada mediante enlace en correo electrónico
sms	Evaluación iniciada mediante enlace en SMS
whatsapp	Evaluación enviada vía WhatsApp
sdk	Evaluación enviada por el SDK embarcado en la tienda
web	Evaluación enviada desde la interfaz web

tip

El campo source acepta cualquier valor string, no solo los listados anteriormente. Valores personalizados como "app" son totalmente compatibles para identificar canales propios de recolección.

info

Existen dos modos de autenticación del evaluador, usa uno u otro:

• userId + email: autenticación directa por el usuario de la plataforma.
• verificationTokenId + orderId: usa cuando el token ya fue resuelto vía /orders/find o /orders/find-batch. El nombre del evaluador se completa automáticamente a partir de los datos del pedido y la evaluación se marca como compra verificada.

info

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

Ejemplos de cuerpo de la solicitud

Vía userId + email:

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

Vía verificationTokenId + orderId:

{
  "verificationTokenId": "664a1b2c3d4e5f6a7b8c9d0e",
  "orderId": "ORD-12345",
  "rating": 5,
  "text": "Producto perfecto para mis necesidades",
  "source": "email"
}

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

Endpoints de Estado de Evaluación de Pedido

Permiten verificar si un pedido (o producto específico) ya fue evaluado por el usuario. Útiles para mostrar indicadores de evaluación en la página de pedidos del cliente.

Con el verificationTokenId en mano, tienes dos formas de llevar al consumidor a evaluar:

1. Redirección o modal — redirige al cliente a la página de evaluación de Konfidency. Consulta la sección Redirigir al cliente para evaluar un pedido.
2. Recolección vía API — envía la evaluación directamente desde tu propio formulario usando el verificationTokenId en el cuerpo de la solicitud POST /{customer}/{sku}/review. Consulta la sección Enviar evaluación.

El campo active es la clave de interpretación en todos los endpoints de esta sección:

• active: true — producto aún no evaluado
• active: false — producto ya evaluado

Cuándo usar cada endpoint

	Flujo individual	Batch
Cuándo usar	Página de detalle de un pedido específico	Historial de pedidos / múltiples pedidos
Llamadas HTTP	2 (POST find + GET products)	1 (POST find-batch)
Pedidos por llamada	1	Hasta 20
Datos del producto	Retornados en el GET (campos completos)	Incluidos en la respuesta (sku, name, brand, mpn, url, image)
Endpoints	POST /orders/find + GET /orders/:token/:orderId	POST /orders/find-batch

Verificar estado de un pedido (flujo individual)

Flujo de dos pasos indicado para la página de detalle de un pedido específico.

Paso 1 — Resolver el token del pedido

POST /{customer}/orders/find

Parámetros de URL

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

Campos del cuerpo de la solicitud (JSON)

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

info

email y userId son alternativos — al menos uno debe enviarse. La búsqueda intenta primero por email; si no encuentra, intenta por userId.

Respuesta 200

{
  "verificationTokenId": "664a1b2c3d4e5f6a7b8c9d0e",
  "orderId": "ORD-12345"
}

Retorna 404 si el pedido no se encuentra para el usuario informado.

---

Paso 2 — Obtener estado de los productos

GET /{customer}/orders/{verificationTokenId}/{orderId}

Parámetros de URL

Parámetro	Descripción
customer	Proporcionado por nuestro equipo de integración
verificationTokenId	Token obtenido en el Paso 1
orderId	ID del pedido

Respuesta 200

{
  "products": [
    {
      "sku": "PROD-001",
      "active": false,
      "review": {
        "rating": 5,
        "text": "¡Excelente producto!",
        "created": "2024-03-15T10:00:00.000Z"
      }
    },
    {
      "sku": "PROD-002",
      "active": true,
      "review": null
    }
  ]
}

Campos

campo	descripción	tipo de datos
sku	SKU del producto	string
active	false si ya evaluado, true si aún no	boolean
review	datos de la evaluación enviada (null si no evaluado)	objeto o null
review.rating	calificación otorgada (1 a 5)	integer
review.text	texto de la evaluación	string
review.created	fecha de envío de la evaluación	string (ISO-8601)

---

Verificar estado de múltiples pedidos (batch)

Flujo de una sola llamada indicado para la página de historial de pedidos. Resuelve los tokens y retorna los productos de hasta 20 pedidos simultáneamente.

POST /{customer}/orders/find-batch

Parámetros de URL

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

Campos del cuerpo de la solicitud (JSON)

campo	descripción	tipo de datos
orderIds	lista de IDs de pedidos (máx. 20)	array de strings
email	correo electrónico del usuario	string
userId	ID del usuario en la plataforma	string

info

Los pedidos del array orderIds que no pertenezcan al email/userId informado son ignorados silenciosamente — no generan error, simplemente no aparecen en la respuesta.

Ejemplo de cuerpo de la solicitud

{
  "orderIds": ["ORD-001", "ORD-002", "ORD-003"],
  "email": "[email protected]",
  "userId": "usr_abc123"
}

Respuesta 200

{
  "orders": [
    {
      "orderId": "ORD-001",
      "verificationTokenId": "664a...",
      "products": [
        {
          "sku": "PROD-A",
          "active": false,
          "review": { "rating": 4 },
          "product": {
            "sku": "PROD-A",
            "name": "Nombre del Producto",
            "brand": "Marca",
            "mpn": "REF-123",
            "url": "https://...",
            "image": "https://..."
          }
        }
      ],
      "sellers": []
    }
  ]
}

Campos

campo	descripción	tipo de datos
orderId	ID del pedido	string
verificationTokenId	token de acceso al pedido	string
products	lista de productos del pedido con estado de evaluación	array
products[].sku	SKU del ítem en el pedido	string
products[].active	false si ya evaluado, true si aún no	boolean
products[].review	datos de la evaluación enviada (null si no evaluado)	objeto o null
products[].review.rating	calificación otorgada (1 a 5)	integer
products[].product	datos del producto registrado	objeto
products[].product.sku	SKU del producto	string
products[].product.name	nombre del producto	string
products[].product.brand	marca del producto	string
products[].product.mpn	código MPN del producto	string
products[].product.url	URL del producto en la tienda	string
products[].product.image	URL de la imagen del producto	string

---

Redirigir al cliente para evaluar un pedido

Para llevar al cliente directamente a la página de evaluación, utiliza el verificationTokenId obtenido vía POST /orders/find o POST /orders/find-batch:

https://www.kfy.app/rate/{customer}/{verificationTokenId}/{orderId}

Parámetros opcionales

Parámetro	Descripción
sku	Abre la evaluación enfocada en un producto específico del pedido
ratingClicked	Pre-selecciona una calificación (1 a 5) al abrir la página
embedded	Cuando es 1, activa el modo embebido para uso dentro de un <iframe> o modal
source	Identificador de origen para seguimiento (ej: email, whatsapp, site)

Uso en modal (embedded)

Al agregar embedded=1, la página envía mensajes vía postMessage a la ventana padre, permitiendo que tu código detecte eventos como el envío de una evaluación y cierre el modal.

<iframe
  src="https://www.kfy.app/rate/{customer}/{verificationTokenId}/{orderId}?embedded=1"
  style="border: none; width: 100%; height: 600px"
/>

window.addEventListener('message', (event) => {
  if (event.data?.type === 'review-sent') {
    // cerrar el modal
  }
})

Ejemplos

Redirigir para evaluación completa del pedido:

https://www.kfy.app/rate/mi-tienda/664a1b2c3d4e5f6a7b8c9d0e/ORD-123

Abrir directamente en el producto con calificación pre-seleccionada:

https://www.kfy.app/rate/mi-tienda/664a1b2c3d4e5f6a7b8c9d0e/ORD-123?sku=PROD-001&ratingClicked=5