Integraciones vía API: guía completa de uso

La API de WiseData NPS permite que otro sistema — tu CRM, e-commerce o ERP — lea y mantenga tus contactos y listas de contactos de forma automática, sin que nadie tenga que tocar el panel. Es una API REST: haces solicitudes HTTP y recibes respuestas en JSON. El ejemplo de esta guía es un CRM que añade cada cliente nuevo a la lista "Clientes activos".

Los tokens están en Recolección › Integraciones, disponible a partir del plan Pro — Free y la prueba gratuita de 14 días no incluyen API. Solo los administradores de la cuenta crean y revocan tokens: para los demás miembros, la pantalla no muestra el botón Nuevo Token ni la papelera para revocar, y avisa que solo los administradores crean y revocan tokens. Si la cuenta vuelve a un plan sin API, los tokens dejan de funcionar: la primera llamada con cada uno responde 403 y el token se revoca.

Visión general

• Base de la URL: https://api.wisedatanps.com (todas las rutas empiezan con /api/v1)
• Autenticación: token en el encabezado Authorization: Bearer TU_TOKEN
• Formato: JSON en las solicitudes (con Content-Type: application/json) y en las respuestas
• Qué puedes hacer: listar, crear, consultar, actualizar y eliminar contactos; listar, crear, consultar, renombrar y eliminar listas de contactos
• Qué no: el token solo alcanza contactos y listas. Encuestas, respuestas e informes no están en la API — una llamada a ellos con token responde 403.

Paso 1 — Crea un token

En Recolección › Integraciones, haz clic en Nuevo Token. Completa el Nombre del token (de 3 a 100 caracteres, ej.: "Integración CRM") y, en Qué puede hacer este token, marca solo lo que la integración necesita:

• Leer contactos — consultar contactos y sus datos.
• Crear y editar contactos — añadir, editar y eliminar contactos.
• Leer listas de contactos — consultar las listas existentes.
• Crear y editar listas — crear, renombrar y eliminar listas.

El formulario abre con los dos permisos de lectura marcados, y al menos uno debe quedar marcado. Al marcar un permiso de escritura, la pantalla avisa que modifica y elimina datos de tu cuenta. El CRM del ejemplo necesita Leer listas de contactos (para encontrar la lista) y Crear y editar contactos (para añadir personas). Los permisos no se editan después: para cambiarlos, crea un token nuevo y revoca el anterior.

Haz clic en Crear Token. El token se muestra una sola vez: cópialo y guárdalo en un lugar seguro antes de hacer clic en Entendido, ya lo copié. Usa el valor completo, tal como aparece — empieza con un número y una barra (12|...), y esa parte pertenece al token.

El token vale 365 días. En la lista, cada token muestra sus permisos, los últimos dígitos, Creado por, Creado, Último uso y Vence el (la fecha se destaca cuando está cerca de vencer). Un token vencido responde 401: crea otro y cámbialo en la integración antes de la fecha. El administrador ve y revoca los tokens de toda la cuenta.

Si un token se filtra o ya no se usa, revócalo — cualquier sistema que lo use pierde el acceso de inmediato. Usa un token por integración, para revocar solo lo que necesites.

Paso 2 — Autentica tus solicitudes

Envía el token en todas las llamadas, en el encabezado de autorización:

Authorization: Bearer TU_TOKEN Content-Type: application/json

Paso 3 — Tu primera solicitud

Empieza listando tus listas de contactos para descubrir el id de cada una (permiso Leer listas de contactos):

curl https://api.wisedatanps.com/api/v1/contact-lists/all \ -H "Authorization: Bearer TU_TOKEN"

{ "data": [ { "id": 1, "name": "Clientes activos", "description": null, "contactsCount": 42, "createdAt": "2026-06-05T13:40:00.000000Z", "updatedAt": "2026-06-05T13:40:00.000000Z" } ] }

Con el id de la lista en mano, ya puedes consultar o añadir contactos a ella.

Endpoints de listas

Listar todas las listas

GET /api/v1/contact-lists/all — Leer listas de contactos. Devuelve todas las listas, en orden alfabético y sin paginación.

Listar listas con paginación

GET /api/v1/contact-lists — Leer listas de contactos. Parámetros opcionales: search (busca en el nombre), sort (name, created_at, updated_at o contacts_count), order (asc o desc), page y per_page (de 1 a 100; por defecto 10). Sin sort, vienen primero las más recientes.

Consultar una lista

GET /api/v1/contact-lists/{listId} — Leer listas de contactos. Devuelve la lista en data.

Crear una lista

POST /api/v1/contact-lists — Crear y editar listas. Campos: name (obligatorio, de 2 a 100 caracteres, sin repetir el nombre de otra lista de la cuenta) y description (opcional, hasta 500 caracteres). Responde 201 con message y la lista en data.

Actualizar una lista

PUT /api/v1/contact-lists/{listId} — Crear y editar listas. Los mismos campos de la creación; name también es obligatorio aquí.

Eliminar una lista

DELETE /api/v1/contact-lists/{listId} — Crear y editar listas. Elimina la lista y sus contactos. Una lista usada por una encuesta activa no se elimina: la respuesta es 409, y hay que pausar la encuesta antes.

Endpoints de contactos

Listar los contactos de una lista

GET /api/v1/contact-lists/{listId}/contacts — Leer contactos. Devuelve los contactos de la lista, de forma paginada. Parámetros opcionales:

• search — búsqueda por nombre, correo o teléfono.
• sort — name, email, phone o created_at (por defecto).
• order — asc o desc (por defecto).
• page — número de página.
• per_page — elementos por página, de 1 a 100 (por defecto 10).

Los elementos vienen en data; meta trae la paginación (entre otros campos, current_page, per_page, total y last_page) y links trae las direcciones de las páginas. Fragmento de la respuesta:

{ "data": [ { "id": 123, "name": "Juan Pérez", "email": "juan@empresa.com", "phone": "+5215555555555", "emailStatus": "valid", "phoneStatus": "valid", "createdAt": "2026-06-05T13:40:00.000000Z" } ], "meta": { "current_page": 1, "per_page": 10, "total": 42, "last_page": 5 } }

Crear un contacto

POST /api/v1/contact-lists/{listId}/contacts — Crear y editar contactos. Crea un contacto y lo añade a la lista indicada. Campos del cuerpo:

• name — obligatorio, de 2 a 100 caracteres.
• email — opcional, debe ser un correo válido. Los correos descartables se rechazan, y el mismo correo no se repite dentro de una lista.
• phone — opcional, de 8 a 20 caracteres. Usa el formato internacional, como +5215555555555.

curl -X POST https://api.wisedatanps.com/api/v1/contact-lists/1/contacts \ -H "Authorization: Bearer TU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Juan Pérez", "email": "juan@empresa.com", "phone": "+5215555555555" }'

En caso de éxito, la respuesta es 201 con el contacto creado:

{ "message": "Contacto creado con éxito.", "data": { "id": 123, "name": "Juan Pérez", "email": "juan@empresa.com", "phone": "+5215555555555", "emailStatus": "pending", "phoneStatus": "pending", "createdAt": "2026-06-05T13:40:00.000000Z" } }

El correo y el teléfono empiezan con estado pending y pasan por una verificación automática enseguida. El emailStatus pasa a valid, invalid, catch_all, disposable o unknown; el phoneStatus pasa a valid cuando el número tiene WhatsApp, o a not_whatsapp. Consulta el contacto después para ver el resultado.

Consultar un contacto

GET /api/v1/contacts/{contactId} — Leer contactos. Devuelve el contacto en data.

Actualizar un contacto

PUT /api/v1/contacts/{contactId} — Crear y editar contactos. Envía solo lo que cambia entre name, email y phone (mismas reglas de la creación). Cambiar el correo o el teléfono vuelve su estado a pending y repite la verificación. La respuesta trae un message y el contacto actualizado en data.

Eliminar un contacto

DELETE /api/v1/contacts/{contactId} — Crear y editar contactos. Quita el contacto de la lista. La respuesta es solo un message de confirmación.

Cómo leer las respuestas

Un único recurso viene dentro de data; cuando hay una acción (crear, actualizar, eliminar), viene también un message; y los listados paginados traen data, meta y links. Los campos de los recursos vienen en camelCase (emailStatus, createdAt); los parámetros que envías son los de arriba (per_page, created_at).

Errores comunes

Todo error viene en JSON con message.

• 401 — token ausente, inválido, revocado o vencido. Revisa el encabezado Authorization y que el valor se haya copiado completo.
• 402 — la cuenta tiene un pago pendiente o la suscripción bloqueada. La API vuelve cuando se regulariza el cobro.
• 403 — el token no tiene el permiso de la llamada (la respuesta trae missing_abilities, por ejemplo ["contacts:write"]); la llamada es a un recurso fuera de la API (solo contactos y listas); el plan no incluye API (y el token se revoca); o quien creó el token debe entrar al panel para aceptar términos actualizados.
• 404 — la lista o el contacto indicado no existe (o no es de tu cuenta).
• 409 — intento de eliminar una lista usada por una encuesta activa.
• 422 — datos inválidos, incluido un correo que ya está en la lista o un nombre de lista repetido. El cuerpo trae un message y un objeto errors que indica cada campo con problema.
• 429 — superaste el límite de solicitudes; espera los segundos indicados en el encabezado Retry-After (mira abajo).

Límites de uso

• Todas las solicitudes: hasta 120 por minuto en Pro, 300 en Business y 600 en Enterprise (o lo que fije el contrato). El límite se cuenta por usuario que creó el token, sumando todos sus tokens.
• Crear, actualizar y eliminar contactos: además del límite anterior, hasta 30 por minuto.
• Al alcanzar un límite, la API responde 429 con el encabezado Retry-After, que indica cuántos segundos esperar antes de reintentar. Usa ese valor en tu integración en lugar de un intervalo fijo. La misma respuesta trae X-RateLimit-Limit (el límite) y X-RateLimit-Remaining (cuántas llamadas quedan).

Buenas prácticas y seguridad

• Nunca expongas el token en código que se ejecuta en el navegador ni en repositorios públicos — úsalo solo desde tu servidor.
• Dale al token solo los permisos que la integración usa: un token de lectura entregado a un proveedor no puede borrar nada.
• Para cargas grandes, respeta los 30 contactos por minuto: envía a ritmo constante en lugar de dispararlo todo de una vez.
• Anota la fecha de Vence el y cambia el token antes de ella.

La propia página de Integraciones trae ejemplos listos en cURL, JavaScript y PHP para que los copies y adaptes.

A dónde ir después

• Contactos y listas — las mismas listas y contactos, vistos y gestionados desde el panel.
• Integrando la encuesta en tu aplicación — la encuesta dentro de la app, que usa llamadas públicas y no necesita token.

En resumen: un administrador crea en Recolección › Integraciones un token con solo los permisos necesarios, tu integración envía ese token en el encabezado Authorization y usa los endpoints de listas y contactos, respetando los límites por minuto y cambiando el token antes de que venza.