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 forma automática, sin que nadie tenga que tocar el panel. Es una API REST: haces solicitudes HTTP y recibes respuestas en JSON. Todo está en la página Integraciones, disponible en el plan Business.

Visión general

• Base de la URL: https://api.wisedatanps.com
• 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 hoy: listar, crear, consultar, actualizar y eliminar contactos, y listar tus listas de contactos

Paso 1 — Crea un token

En la página Integraciones, haz clic en Nuevo Token, ponle un nombre que ayude a identificar la integración (ej.: "Integración CRM") y confirma. El token se muestra una sola vez: cópialo y guárdalo en un lugar seguro, porque no se mostrará de nuevo. Después, la lista solo muestra una vista previa (los últimos dígitos), la fecha de creación y el último uso.

Si un token se filtra o ya no se usa, revócalo — cualquier sistema que lo use pierde el acceso de inmediato. Consejo: 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:

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

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

Endpoints

Listar todas las listas

GET /api/v1/contact-lists/all — devuelve todas tus listas de contactos.

Listar los contactos de una lista

GET /api/v1/contact-lists/{listId}/contacts — devuelve los contactos de una lista, de forma paginada. Parámetros de consulta aceptados:

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

La respuesta viene paginada, con los datos en data y la información de paginación en meta:

{   "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": 15, "total": 42, "last_page": 3 } }

Crear un contacto

POST /api/v1/contact-lists/{listId}/contacts — 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).
• phone — opcional, de 8 a 20 caracteres.

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

Nota: el correo y el teléfono empiezan con estado pending y pasan por una verificación automática en segundo plano — el estado cambia a válido (u otro) poco después.

Consultar un contacto

GET /api/v1/contacts/{contactId} — devuelve los detalles de un contacto en data.

Actualizar un contacto

PUT /api/v1/contacts/{contactId} — actualiza name, email y/o phone. La respuesta trae un message y el contacto actualizado en data.

Eliminar un contacto

DELETE /api/v1/contacts/{contactId} — elimina el contacto permanentemente. La respuesta es solo un message de confirmación.

Cómo leer las respuestas

Las respuestas siguen un patrón simple: un único recurso viene dentro de data; cuando hay una acción, viene también un message; y las listas vienen paginadas, con data (los elementos) y meta (página actual, total, etc.).

Errores comunes

• 401 — token ausente o inválido. Revisa el encabezado Authorization.
• 403 — sin permiso para el recurso (por ejemplo, un plan sin acceso a la API).
• 404 — la lista o el contacto indicado no existe (o no es de tu cuenta).
• 422 — datos inválidos. El cuerpo trae un message y un objeto errors que indica cada campo con problema.
• 429 — superaste el límite de solicitudes (mira abajo).

Límites de uso

• Lectura (GET): hasta 60 solicitudes por minuto (varía según el plan).
• Escritura (POST/PUT/DELETE): hasta 30 solicitudes por minuto.
• Al alcanzar el límite, la API responde 429 con el encabezado Retry-After, indicando cuántos segundos esperar antes de reintentar.

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.
• Maneja el estado 429 esperando el tiempo del Retry-After antes de repetir la solicitud.
• Mantén un token por integración y revoca de inmediato cualquier token que pueda haberse filtrado.

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