Documentación de woku - Guía para desarrolladores

Disponible en el plan Corporate. Esta funcionalidad forma parte de las capacidades empresariales de woku. Conversa con nuestro equipo comercial.

Esta guía te muestra cómo integrar la API de woku en tus propias aplicaciones para automatizar la creación de wokus, capturar reseñas, compartir por correo y enriquecer tus datos con identificadores de tus sistemas internos.

Esta guía aplica solo a la versión v1 de la API. Es el match exacto con la pestaña API Reference que ves en la parte superior de la documentación. Para el comportamiento histórico (rutas sin el prefijo /v1/), cambia el selector de versión a v0.

Referencia interactiva

Toda la API está documentada de forma interactiva en la pestaña API Reference de esta misma documentación. Allí puedes ver cada endpoint con su esquema completo, ejecutarlo en vivo desde el navegador y copiar ejemplos en tu lenguaje preferido. Esta guía es complementaria: te explica el flujo y el “por qué” de cada llamada para que la integración te tome el menor tiempo posible.

Introducción

La API de woku te permite gestionar wokus, NPS y trackers externos de forma programática. Los casos de uso típicos:

Crear wokus automáticamente cuando ocurre un evento en tu aplicación (por ejemplo, cierre de una venta, fin de una sesión de capacitación, entrega de un producto).
Capturar reseñas directamente desde tu interfaz, sin redirigir al cliente al sitio de woku.
Compartir wokus por correo a uno o varios destinatarios desde tu backend.
Etiquetar wokus con identificadores de tus sistemas (CRM, ERP, ticketing) para luego buscarlos cruzados.
Consultar reportes NPS desde tus dashboards internos.

Todas las llamadas son HTTP con JSON o multipart/form-data y responden con estructuras consistentes.

URL Base

https://clientapi.woku.app

Todos los endpoints v1 viven bajo el prefijo /v1/.

Autenticación

Cada empresa registrada en woku tiene una Clave de Compañía que se incluye en el header Authorization de cada solicitud:

Authorization: Bearer <Company-Key>

La clave la obtiene el propietario de la empresa desde la sección Información de la empresa, en la aplicación administrativa: https://admin.woku.app

Vista de la ventana de información de la empresa.

La misma clave que usabas en v0 funciona para v1. No necesitas regenerarla para migrar.

Compañía

Obtener la compañía actual

Recupera los datos de la empresa asociada a la Clave de Compañía. Útil para validar que tu integración esté autenticando con la cuenta correcta. Endpoint

GET /v1/companies/me

Headers

Authorization: Bearer <Company-Key>

Respuestas

200 OK: Devuelve el objeto de la compañía.
403 Forbidden: La clave no es válida o no tiene permiso.

Wokus

Las funciones de wokus te permiten crear, consultar, calificar y compartir wokus de forma programática.

Crear un woku con URL de archivo

Crea un woku usando una imagen o video alojado en una URL pública (CDN, S3, ImageKit, etc.). Endpoint

POST /v1/wokus

Headers

Content-Type: application/json
Authorization: Bearer <Company-Key>

Body

{
  "description": "Customer Service Experience - Store #123",
  "fileUrl": "https://cdn.example.com/images/product-image.jpg",
  "folderSecondaryKey": "store-123",
  "parentFolderSecondaryKey": "region-north",
  "clientEmail": "customer@example.com",
  "clientPhone": 56912345678
}

Campos

description (string, obligatorio): Entre 3 y 140 caracteres.
fileUrl (string, obligatorio): URL pública de una imagen o video (preferentemente .mp4).
folderSecondaryKey (string, opcional): Clave de la carpeta donde se almacena el woku.
parentFolderSecondaryKey (string, opcional): Clave de la carpeta padre. No puede ser la misma que folderSecondaryKey.
clientEmail (string, opcional): Email del cliente asociado.
clientPhone (number, opcional): Número de WhatsApp.

Respuestas

201 Created: Devuelve el objeto del woku creado.
400 Bad Request: El body no pasó la validación.
403 Forbidden: Clave inválida.

Crear un woku con archivo (multipart)

Cuando el archivo está en tu propio storage o tu cliente sube la imagen directamente desde un formulario, usa el endpoint con multipart/form-data. Endpoint

POST /v1/wokus/form-data

Headers

Content-Type: multipart/form-data
Authorization: Bearer <Company-Key>

Form fields

file (binary, obligatorio): Archivo de imagen o video.
description (string, obligatorio): Entre 3 y 140 caracteres.
folderSecondaryKey (string, opcional).
parentFolderSecondaryKey (string, opcional).
clientEmail (string, opcional).
clientPhone (string, opcional).

Respuestas

201 Created: Woku creado.
400 Bad Request: Validación fallida (formato de archivo, tamaño, campos requeridos).
403 Forbidden: Clave inválida.

Obtener los datos de un woku

Recupera el woku junto con sus calificaciones y reseñas. Endpoint

GET /v1/wokus/{wokuId}/review

Headers

Authorization: Bearer <Company-Key>

Path params

wokuId (string, obligatorio): Identificador del woku.

Respuestas

200 OK: Objeto del woku con sus reseñas.
403 Forbidden: Clave inválida.
404 Not Found: No existe un woku con ese ID en tu empresa.

Calificar con una reseña en texto

Agrega una calificación de 1 a 5 estrellas con un comentario escrito. Endpoint

POST /v1/wokus/{wokuId}/textnotes

Headers

Content-Type: application/json
Authorization: Bearer <Company-Key>

Body

{
  "qualification": 5,
  "description": "Excellent service! The staff was very helpful.",
  "clientEmail": "customer@example.com",
  "clientPhone": 56912345678,
  "anonymous": false
}

Campos

qualification (integer, obligatorio): Valor entre 1 y 5.
description (string, obligatorio): Reseña en texto, máximo 3000 caracteres.
clientEmail (string, opcional): Si no se entrega, anonymous debe ser true.
clientPhone (number, opcional).
anonymous (boolean, opcional): Por defecto false.

Respuestas

201 Created: Reseña registrada.
400 Bad Request: Validación fallida.
403 Forbidden: Clave inválida.
404 Not Found: No existe el woku.

Calificar con una reseña en audio

Sube un archivo de audio junto con la calificación. Endpoint

POST /v1/wokus/{wokuId}/voicemails

Headers

Content-Type: multipart/form-data
Authorization: Bearer <Company-Key>

Form fields

file (binary, obligatorio): Audio. Recomendado .mp4 o .wav.
qualification (string "1", "5", obligatorio).
clientEmail (string, opcional).
clientPhone (string, opcional).
anonymous (string "true" o "false", opcional).

Respuestas

201 Created: Reseña registrada.
400 Bad Request: Validación fallida.
403 Forbidden: Clave inválida.
404 Not Found: No existe el woku.

Compartir un woku por correo

Envía el woku a uno o varios destinatarios. Es el mismo flujo que se gatilla desde la interfaz de compartir. Endpoint

POST /v1/wokus/{wokuId}/share

Headers

Content-Type: application/json
Authorization: Bearer <Company-Key>

Body (destinatario único)

{
  "clientEmail": "customer@example.com"
}

Body (múltiples destinatarios)

{
  "clientEmails": ["customer1@example.com", "customer2@example.com"]
}

Debes enviar uno u otro de los dos campos, no ambos.

Respuestas

200 OK: Envío encolado.
400 Bad Request: Validación fallida (correo mal formado, ambos campos vacíos, etc.).
403 Forbidden: Clave inválida.

Reportes NPS

Si tu empresa usa la herramienta NPS, puedes consultar los reportes agregados directamente desde la API para integrarlos en tus propios dashboards.

Reporte NPS de la compañía

Devuelve el reporte agregado de todos los NPS registrados para tu empresa. Endpoint

GET /v1/reports/company-nps

Headers

Authorization: Bearer <Company-Key>

Respuestas

200 OK: Reporte con distribución de promotores, pasivos y detractores, y el puntaje NPS resultante.
403 Forbidden: Clave inválida.

Reporte NPS de una herramienta

Devuelve el reporte de un NPS Tool específico (por ejemplo, “NPS post-evento” o “NPS post-compra”). Endpoint

GET /v1/reports/nps-tool/{npsToolId}

Headers

Authorization: Bearer <Company-Key>

Path params

npsToolId (string, obligatorio): Identificador del NPS Tool.

Respuestas

200 OK: Reporte del NPS Tool.
400 Bad Request: npsToolId mal formado.
403 Forbidden: Clave inválida.
404 Not Found: El NPS Tool no existe o no pertenece a tu empresa.

Trackers Externos

Los trackers externos te permiten asociar identificadores de tus sistemas (CRM, ERP, ticketing, OMS) a tus wokus para luego buscarlos cruzados. Por ejemplo: vincular un woku al transaction_id de tu CRM o al order_id de tu ERP.

Modelo

Tracker definition: Una entrada de catálogo a nivel de empresa, como { name: "trr", system: "crm interno", description: "..." }. Se define en el panel administrativo de woku.
Tracker value: Un valor string ligado a un par (Woku, Tracker). Varios wokus pueden compartir el mismo valor.

Listar trackers activos de la empresa

Endpoint

GET /v1/external-trackers

Query params

page (number, opcional).
limit (number, opcional).

Respuestas

200 OK: Lista paginada de definiciones de trackers.
403 Forbidden: Clave inválida.

Listar trackers asignados a un woku

Endpoint

GET /v1/external-trackers/wokus/{wokuId}

Respuestas

200 OK: Trackers asignados al woku.
403 Forbidden: Clave inválida.

Asignar un valor de tracker a un woku

Crea o actualiza (upsert) el valor de un tracker en un woku. Endpoint

POST /v1/external-trackers/wokus/{wokuId}

Body

{
  "name": "trr",
  "value": "TX-2026-00043"
}

Campos

name (string, obligatorio, máx 60): Nombre del tracker definido en tu empresa.
value (string, obligatorio, máx 500): Valor del identificador externo (siempre se almacena como string).

Respuestas

201 Created: Valor asignado o actualizado.
400 Bad Request: Validación fallida.
403 Forbidden: Clave inválida.
404 Not Found: El woku o el tracker no existen.

Eliminar un valor de tracker de un woku

Endpoint

DELETE /v1/external-trackers/wokus/{wokuId}/{trackerName}

Respuestas

200 OK: Eliminado.
403 Forbidden: Clave inválida.
404 Not Found: El woku o el tracker no existen.

Buscar wokus por tracker

Encuentra todos los wokus que tienen un determinado (name, value). Útil para volver desde tu CRM al woku correspondiente. Endpoint

GET /v1/external-trackers/search?name=<tracker>&value=<value>

Query params

name (string, obligatorio): Nombre del tracker.
value (string, obligatorio): Valor a buscar.
page (number, opcional).
limit (number, opcional).

Respuestas

200 OK: Lista paginada de wokus con sus tracker values.
403 Forbidden: Clave inválida.
404 Not Found: No existen coincidencias.

Límites de ingesta y extracción

La API REST está documentada de forma interactiva en la pestaña API Reference y aplica límites de tasa y de volumen tanto para la ingesta (creación de wokus, reseñas, NPS, asignación de trackers) como para la extracción (consulta de wokus, reportes y búsquedas). Los límites cubren los dos modos de operación: por evento (una llamada por registro) y por lote (cargas batch). Los límites se aplican por Clave de Compañía:

Operación	Modo	Límite
Ingesta por evento	Evento	600 solicitudes/minuto · hasta 50 eventos/seg
Ingesta por lote	Lote	Hasta 5.000 registros por lote · 60 lotes/minuto
Volumen diario de ingesta	Evento + lote	1.000.000 registros/día
Extracción (lectura)	Evento	300 solicitudes/minuto
Extracción paginada	Lote	Hasta 200 registros por página

Estos son los límites por defecto del plan Corporate. Si tu integración necesita ventanas mayores (picos estacionales, migraciones masivas), escríbenos para ampliarlos.

Manejo de 429 (Too Many Requests)

Cuando superas un límite de tasa, la API responde con 429 Too Many Requests e incluye encabezados que te indican cuándo reintentar:

Retry-After: segundos a esperar antes del siguiente intento.
X-RateLimit-Limit: tope de la ventana actual.
X-RateLimit-Remaining: solicitudes restantes en la ventana.
X-RateLimit-Reset: marca de tiempo en que se reinicia la ventana.

Implementa reintentos con backoff exponencial respetando Retry-After. Para cargas batch, divide los lotes que excedan el máximo de registros en lugar de reintentar el lote completo.

Paginación en la extracción

Los endpoints de extracción que devuelven colecciones son paginados. Controla la página con los query params page y limit (por ejemplo, en GET /v1/external-trackers o GET /v1/external-trackers/search). Para extraer grandes volúmenes, recorre las páginas de forma secuencial respetando el límite de extracción por minuto y el máximo de registros por página.

GET /v1/external-trackers/search?name=trr&value=TX-2026-00043&page=1&limit=200

Errores comunes

URL de archivo inaccesible

Si usas POST /v1/wokus con fileUrl, asegúrate de que la URL sea públicamente accesible. Nuestro servicio descarga el archivo antes de crear el woku.

Clave secundaria duplicada

folderSecondaryKey se usa para identificar una carpeta dentro de tu empresa. No pueden existir dos carpetas con la misma clave en una misma empresa. Si necesitas reutilizar una clave, primero elimina la carpeta existente desde el panel administrativo.

403 en todas las llamadas

Casi siempre significa que la clave es incorrecta, está caducada o pertenece a otra empresa. Vuelve a obtener la clave desde admin.woku.app → Información de la empresa → Obtener Clave.

Contacto y soporte

Diego Orrego Brito, CTO de woku.
Correo: diego@woku.app (incluye el nombre de la empresa en el asunto y menciona que se trata de la API).

​Referencia interactiva

​Introducción

​URL Base

​Autenticación

​Compañía

​Obtener la compañía actual

​Wokus

​Crear un woku con URL de archivo

​Crear un woku con archivo (multipart)

​Obtener los datos de un woku

​Calificar con una reseña en texto

​Calificar con una reseña en audio

​Compartir un woku por correo

​Reportes NPS

​Reporte NPS de la compañía

​Reporte NPS de una herramienta

​Trackers Externos

​Modelo

​Listar trackers activos de la empresa

​Listar trackers asignados a un woku

​Asignar un valor de tracker a un woku

​Eliminar un valor de tracker de un woku

​Buscar wokus por tracker

​Límites de ingesta y extracción

​Manejo de 429 (Too Many Requests)

​Paginación en la extracción

​Errores comunes

​URL de archivo inaccesible

​Clave secundaria duplicada

​403 en todas las llamadas

​Contacto y soporte

Referencia interactiva

Introducción

URL Base

Autenticación

Compañía

Obtener la compañía actual

Wokus

Crear un woku con URL de archivo

Crear un woku con archivo (multipart)

Obtener los datos de un woku

Calificar con una reseña en texto

Calificar con una reseña en audio

Compartir un woku por correo

Reportes NPS

Reporte NPS de la compañía

Reporte NPS de una herramienta

Trackers Externos

Modelo

Listar trackers activos de la empresa

Listar trackers asignados a un woku

Asignar un valor de tracker a un woku

Eliminar un valor de tracker de un woku

Buscar wokus por tracker

Límites de ingesta y extracción

Manejo de 429 (Too Many Requests)

Paginación en la extracción

Errores comunes

URL de archivo inaccesible

Clave secundaria duplicada

403 en todas las llamadas

Contacto y soporte