Introducción

Las APIs de wolkvox CRM permiten consultar, insertar, actualizar o eliminar información de módulos (predeterminados o personalizados) a través de solicitudes POST. Cuando se trabaja con grandes volúmenes de datos, es clave aplicar paginación, respetar los límites de registros por página y tener en cuenta el control de solicitudes (rate limiting) por IP.

Este artículo explica, de forma funcional, cómo realizar el consumo de APIs en Postman y cómo interpretar la respuesta para navegar página por página sin exceder los estándares definidos.

Pasos para el consumo de APIs

Ubica la documentación oficial de APIs (Postman)

1. Entra al workspace de Postman: Clic aquí.
2. Abre la colección en el idioma que necesites: wolkvox APIs (EN) o wolkvox APIs (ES).
   • Ingresa a la carpeta CRM (N) (el número puede variar, porque corresponde al total de requests dentro de la carpeta).
   • Selecciona la API que vas a consumir. En el ejemplo de las capturas se usa la API: Consultar registros por fechas.
     • Documentación: Clic aquí.
     • Endpoint: https://{{crm_server}}/server/API/v2/custom/queryDates.php
   • Nota funcional: en wolkvox CRM, generalmente todas las APIs se consumen por método POST, incluso cuando la acción sea consultar, insertar, actualizar o eliminar.
3. En la pestaña “Overview” puedes ver la documentación de la API.
4. También puedes ir al menú lateral derecho de Postman y dar clic en el botón “Documentation” para ver la documentación.

Configura el método y la URL del servicio

1. En Postman, pega la URL del servicio en la barra de endpoint.
   • En documentación verás el placeholder {{crm_server}}.
   • En un consumo real, se reemplaza por el servidor de tu operación, por ejemplo: https://crm01.wolkvox.com/server/API/v2/custom/queryDates.php
2. Confirma que el método esté en POST.

Si deseas saber cuál es el servidor de tu operación de wolkvox CRM, debes ingresar a wolkvox CRM y revisar la URL una vez hayas iniciado sesión. El servidor de tu operación es el que está entre ‘https://’ y la barra inclinada ‘/’ después del .com

Agrega el Header de autenticación (Wolkvox-Token)

1. Ve a la pestaña “Headers”.
2. Crea/valida el header:
   • Key: Wolkvox-Token
   • Value: el token generado para tu operación (puede estar como variable de entorno tipo {{Wolkvox-Token}} o escrito directamente).
     • Consulta la documentación acerca de la creación de tokens para wolkvox CRM en este help center.

Configura el Body en formato JSON (raw)

1. Entra a la pestaña “Body”.
2. Selecciona “raw” y el tipo JSON.
3. Pega el JSON de la solicitud según la API. Para el ejemplo de “Consultar registros por fechas”, el body incluye los parámetros funcionales del rango de fechas y paginación:
   • Qué hacen los parámetros de paginación:
     • page: número de página a consultar (por defecto 1; funcionalmente no tiene un límite máximo).
     • limit: cantidad de registros por página (por defecto 15000; máximo 15000).

{
  "operation": "wolkvox",
  "module": "contacts",
  "date": true,
  "from": "2026-01-01 00:00",
  "to": "2026-01-23 23:59",
  "limit": "250",
  "page": "1"
}

Envía la solicitud respetando el rate limiting

1. Haz clic en “Send”.
   • Recuerda el criterio funcional de control de solicitudes:
     • Máximo 2 solicitudes por segundo por IP.
     • Esto evita bloqueos y mantiene estabilidad del sistema. En consumos automatizados, el comportamiento esperado es aplicar pausas entre requests para no superar ese umbral.
2. Interpreta la respuesta y confirma paginación.
   • En el panel de respuesta (Response Body), la API devolverá indicadores que te permiten controlar el avance:
     • code: código de resultado (por ejemplo, 200 cuando es exitoso).
     • page: página actual retornada.
     • Total records: total de registros encontrados.
     • Total pages: total de páginas disponibles según limit.
     • msg: mensaje funcional (por ejemplo, cuántos registros se encontraron).
     • data: arreglo con los registros de la página consultada.
   • Ejemplo funcional observado en las capturas:
     • page: 1
     • Total records: 1003
     • Total pages: 5
     • msg: "250 records were found"

Consulta la siguiente página (navegación page a page)

Para traer el siguiente bloque de información:

1. Mantén el mismo body.
   1. Cambia únicamente el parámetro: "page": "2"
   2. Presiona “Send” de nuevo.
2. La respuesta debería reflejar el cambio (por ejemplo, page: 2) y mantener coherencia con Total records y Total pages. Repite el proceso hasta llegar a la última página.

Buenas prácticas funcionales para un consumo controlado

• Ajusta el limit según necesidad: usa valores más bajos (ej. 250) para pruebas o QA, y valores más altos para extracción controlada (sin superar 15000).
• No dispares requests en ráfaga: si vas a recorrer muchas páginas, implementa una espera para respetar 2 req/seg por IP.
• Valida siempre “Total pages” antes de iterar: así defines cuántas páginas debes consultar y evitas solicitudes innecesarias.
• Confirma el estándar de registros por página: identifica si la API que estás usando soporta paginación y responde con métricas de totalización (records/pages), para asegurar que cumple el comportamiento esperado.