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": "[email protected]",
      "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": "[email protected]", "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": "[email protected]",
    "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.