Analítica

Contactos en lote

GET/analitica/contactos

Consulta contactos autorizados con estados, fechas y relaciones opcionales. Devuelve [filas, [metadatos]] y el encabezado Row-Count. Los filtros no publicados se rechazan con 409.

Parámetros

Nombre	Tipo	Validación	Descripción
`params`	varchar
`pagina`	varchar	Requerido	Entero entre 1 y 2147483647. Página de resultados; no admite descarga ilimitada.
`cantidadRegistros`	varchar	Requerido	Entero de 1 a 200. Cantidad máxima de filas de la página.
`tkContactos`	varchar		Hasta 100 tokens separados por coma, máximo 128 caracteres cada uno y 8192 en total. Los duplicados no multiplican resultados.
`tkUsuario`	varchar		Token del responsable asignado. No amplía los permisos de la sesión.
`tkGrupo`	varchar		Token del grupo de un responsable asignado.
`tkFase`	varchar		Token de la fase actual del contacto.
`tkOrigen`	varchar		Token del origen actual del contacto.
`tkEtiqueta`	varchar		Token de una etiqueta del contacto.
`esCliente`	varchar	Requerido	Estado del contacto: todos, true o false.
`asignacion`	varchar	Requerido	todos, asignados o sinAsignar. La regla vigente requiere una asignación autorizable; sinAsignar devuelve vacío con advertencia de cobertura.
`fechaInicio`	varchar		Inicio incluido, ISO 8601 con offset; requiere fechaFin.
`fechaFin`	varchar		Fin excluido, ISO 8601 con offset, posterior al inicio; requiere fechaInicio.
`fechaBase`	varchar	Requerido	Base del filtro temporal. Único valor habilitado: creacion.
`orden`	varchar	Requerido	ascendente o descendente por creación, con desempate estable por identidad.
`incluir`	varchar		Lista separada por coma: atribucion, empresa, resumen, calificacion y preferencias. preferencias requiere acceso a COM para sus bloqueos; no regenera IA ni ejecuta envíos.
`permitirParciales`	varchar	Requerido	true admite preferencias sin bloqueos cuando COM no está habilitado en la cuenta, con advertencia; falta de permiso individual sigue siendo 403.

Respuesta

Nombre	Tipo	Descripción
`tkProspecto`	String	Identificador estable del contacto, también después de convertirse en cliente.
`fuente`	String	Fuente del registro; crm para contactos.
`idRegistroFuente`	String	Identidad opaca del registro, estable dentro de la cuenta.
`nombre`	String	Nombre del contacto.
`apellidos`	String	Apellidos del contacto.
`esCliente`	Boolean	Indica el estado actual de cliente.
`esOportunidad`	Boolean	Indicador actual de oportunidad del contacto.
`descartado`	Boolean	Indica que el contacto está descartado.
`tkUsuario`	String	Token del responsable principal almacenado; puede ser null.
`tkFase`	String	Token de fase actual; puede ser null.
`tkOrigen`	String	Token de origen; puede ser null.
`fechaCreacion`	String	Instante de creación con zona explícita; puede ser null.
`fechaOriginal`	String	Fecha de creación original sin zona; puede ser null.
`baseTemporal`	String	Procedencia de fechaOriginal: creacion.
`fechaActualizacion`	String	Modificación del contacto con zona explícita; puede ser null.
`fechaActualizacionOriginal`	String	Fecha de modificación original sin zona; puede ser null.
`responsables`	Array<Object>	Asignaciones actuales con tkUsuario, nombre, apellidos, principal y activo.
`atribucion`	Object	Objeto solicitado con incluir=atribucion; de otro modo null. Los campos sin evidencia son null.
`empresa`	Object	Empresa comercial solicitada con incluir=empresa; de otro modo null. Sus campos pueden ser null si no hay relación.
`cobertura`	Object	Estado, fuentes consultadas, capacidadesFaltantes e integridadHistorica.
`advertencias`	Array<Object>	Lista de objetos con codigo, mensaje y fuente que explican límites de cobertura.
`consistencia`	String	Siempre sinInstantanea; los cambios concurrentes pueden alterar la navegación.
`fechaGeneracion`	String	Instante de generación de la respuesta, con zona explícita.
`Row-Count`	Integer	Total del conjunto autorizado y filtrado, antes de paginar.
`atribucion.alcanceAtribucion`	String	contactoGuardado: evidencia del contacto, no de cada captación.
`atribucion.utmFuente`	String	Valor de utmFuente guardado en la atribución; null si no está registrado.
`atribucion.utmMedio`	String	Valor de utmMedio guardado en la atribución; null si no está registrado.
`atribucion.utmCampania`	String	Valor de utmCampania guardado en la atribución; null si no está registrado.
`atribucion.utmTermino`	String	Valor de utmTermino guardado en la atribución; null si no está registrado.
`atribucion.utmContenido`	String	Valor de utmContenido guardado en la atribución; null si no está registrado.
`atribucion.utmGclid`	String	Valor de utmGclid guardado en la atribución; null si no está registrado.
`atribucion.utmGbraid`	String	Valor de utmGbraid guardado en la atribución; null si no está registrado.
`atribucion.utmWbraid`	String	Valor de utmWbraid guardado en la atribución; null si no está registrado.
`atribucion.utmFbclid`	String	Valor de utmFbclid guardado en la atribución; null si no está registrado.
`atribucion.utmReferente`	String	Valor de utmReferente guardado en la atribución; null si no está registrado.
`atribucion.utmCampoPersonalizado1`	String	Valor de utmCampoPersonalizado1 guardado en la atribución; null si no está registrado.
`atribucion.utmCampoPersonalizado2`	String	Valor de utmCampoPersonalizado2 guardado en la atribución; null si no está registrado.
`atribucion.utmCampoPersonalizado3`	String	Valor de utmCampoPersonalizado3 guardado en la atribución; null si no está registrado.
`atribucion.utmCampoPersonalizado4`	String	Valor de utmCampoPersonalizado4 guardado en la atribución; null si no está registrado.
`atribucion.utmCampoPersonalizado5`	String	Valor de utmCampoPersonalizado5 guardado en la atribución; null si no está registrado.
`atribucion.utmFecha`	String	Instante del registro de atribución con zona explícita; puede ser null.
`atribucion.utmFechaOriginal`	String	Fecha original del registro de atribución sin zona; puede ser null.
`atribucion.baseTemporal`	String	registroAtribucion: fecha del registro de atribución.
`empresa.tkEmpresa`	String	Token de la empresa comercial.
`empresa.nombre`	String	Nombre del contacto.
`empresa.esCliente`	Boolean	Indica el estado actual de cliente.
`resumen`	Object	Resumen persistido o null. Incluye tkResumen, fuente, fechaCreacion, fechaActualizacion, fechaActualizacionOriginal, baseTemporal, idUltimoEventoResumido=null, formatoFuente, textoOriginal y contenido. contenido proyecta contextoGeneral, resumenUltimaConversacion, estadoActual, intencionDetectada, nivelInteres, sentimiento, temasPrincipales, objeciones, compromisosPendientes, siguientePasoRecomendado, canalPreferido, estiloComunicacion, hechosParaUsar y hechosNoInventar; los datos ausentes permanecen null o lista vacía. No adjunta configuración ni metadatos privados.
`calificacion`	Object	Objeto o null si no se solicita. puntuacion y origen/manual.puntuacion conservan valores guardados. bant incluye puntuacion y puntosPresupuesto, puntosAutoridad, puntosNecesidad, puntosPlazo (contribuciones del formulario BANT). tkActor, fechaCalificacion, versionReglas, validezComercial, esPrueba, esCorreoNoDeseado y esDuplicado permanecen null sin evidencia. estadoCorreoFuente y correoVerificado describen correo, no validez comercial. etiquetas incluye tkEtiqueta, nombre y fechaEtiquetado. personalizados contiene definiciones de contacto accesibles con tkCampo, clave, nombre, descripcion, tipoCampoFuente, valorOriginal, tipoValor y opciones (tkOpcion, nombre, estadoFuente, seleccionada). Los valores originales de listas/objetos permanecen como texto JSON; no son puntuaciones.
`preferencias`	Object	Objeto o null si no se solicita. recibirCorreos es la preferencia del contacto, con recibirCorreosFuente original. fechaPreferencia, idioma, horario, consentimientoVerificable, propositoConsentimiento y fechaConsentimiento quedan null sin evidencia. coberturaBloqueos es parcial o noDisponible. bloqueos contiene tkBloqueo, canal y bloqueado=true sólo para identidades coincidentes de conversaciones autorizadas; una lista vacía no acredita ausencia global de bloqueos. Sin COM consultable bloqueos=null.

Solicitud

curl --request GET --url 'https://api.upnify.com/v4/analitica/contactos?tkContactos=P-EJEMPLO&incluir=atribucion%2Cempresa' --header 'token: 00000000-0000-4000-8000-000000000001'const respuesta = await fetch("https://api.upnify.com/v4/analitica/contactos?tkContactos=P-EJEMPLO&incluir=atribucion%2Cempresa", { headers: { token: "00000000-0000-4000-8000-000000000001" } });
console.log(await respuesta.json());const respuesta = await fetch("https://api.upnify.com/v4/analitica/contactos?tkContactos=P-EJEMPLO&incluir=atribucion%2Cempresa", { headers: { token: "00000000-0000-4000-8000-000000000001" } });
console.log(await respuesta.json());import requests

respuesta = requests.get("https://api.upnify.com/v4/analitica/contactos?tkContactos=P-EJEMPLO&incluir=atribucion%2Cempresa", headers={"token": "00000000-0000-4000-8000-000000000001"})
respuesta.raise_for_status()
print(respuesta.json())package main

import (
 "net/http"
 "io"
 "os"
)

func main() {
 solicitud, err := http.NewRequest(http.MethodGet, "https://api.upnify.com/v4/analitica/contactos?tkContactos=P-EJEMPLO&incluir=atribucion%2Cempresa", nil)
 if err != nil { panic(err) }
 solicitud.Header.Set("token", "00000000-0000-4000-8000-000000000001")
 respuesta, err := http.DefaultClient.Do(solicitud)
 if err != nil { panic(err) }
 defer respuesta.Body.Close()
 io.Copy(os.Stdout, respuesta.Body)
}using System;
using System.Net.Http;

using var cliente = new HttpClient();
using var solicitud = new HttpRequestMessage(HttpMethod.Get, "https://api.upnify.com/v4/analitica/contactos?tkContactos=P-EJEMPLO&incluir=atribucion%2Cempresa");
solicitud.Headers.Add("token", "00000000-0000-4000-8000-000000000001");
using var respuesta = await cliente.SendAsync(solicitud);
respuesta.EnsureSuccessStatusCode();
Console.WriteLine(await respuesta.Content.ReadAsStringAsync());

Respuesta

[
  [
    {
      "tkProspecto": "P-EJEMPLO",
      "fuente": "crm",
      "idRegistroFuente": "contacto:1",
      "nombre": "Contacto",
      "apellidos": "Sintetico",
      "esCliente": false,
      "esOportunidad": false,
      "descartado": false,
      "tkUsuario": "U-EJEMPLO",
      "tkFase": "PFAS-EJEMPLO",
      "tkOrigen": "ORIG-EJEMPLO",
      "fechaCreacion": "2026-09-01T16:00:00Z",
      "fechaOriginal": "2026-09-01T10:00:00",
      "baseTemporal": "creacion",
      "fechaActualizacion": "2026-09-01T16:00:00Z",
      "fechaActualizacionOriginal": "2026-09-01T10:00:00",
      "responsables": [
        {
          "tkUsuario": "U-EJEMPLO",
          "nombre": "Prueba",
          "apellidos": "Analitica",
          "principal": false,
          "activo": true
        }
      ],
      "atribucion": {
        "alcanceAtribucion": "contactoGuardado",
        "utmFuente": "fuente-sintetica",
        "utmMedio": null,
        "utmCampania": null,
        "utmTermino": null,
        "utmContenido": null,
        "utmGclid": null,
        "utmGbraid": "GBRAID-EJEMPLO",
        "utmWbraid": "WBRAID-EJEMPLO",
        "utmFbclid": null,
        "utmReferente": null,
        "utmCampoPersonalizado1": null,
        "utmCampoPersonalizado2": null,
        "utmCampoPersonalizado3": null,
        "utmCampoPersonalizado4": null,
        "utmCampoPersonalizado5": null,
        "utmFecha": "2026-09-01T16:00:00Z",
        "utmFechaOriginal": "2026-09-01T10:00:00",
        "baseTemporal": "registroAtribucion"
      },
      "empresa": {
        "tkEmpresa": "COM-EJEMPLO",
        "nombre": "Empresa comercial sintetica",
        "esCliente": false
      },
      "resumen": null,
      "calificacion": null,
      "preferencias": null
    }
  ],
  [
    {
      "cobertura": {
        "estado": "parcial",
        "fuentes": [
          "crm"
        ],
        "capacidadesFaltantes": [
          "historialCompletoAsignaciones",
          "contactosSinAsignacionAutorizable"
        ],
        "integridadHistorica": "desconocida"
      },
      "advertencias": [
        {
          "codigo": "ASIGNACION_REQUERIDA_PARA_ACCESO",
          "mensaje": "Los contactos sin asignaciones no tienen un alcance autorizable mediante la regla vigente; su ausencia no acredita que no existan.",
          "fuente": "crm"
        }
      ],
      "consistencia": "sinInstantanea",
      "fechaGeneracion": "2026-09-21T18:00:00Z"
    }
  ]
]

[
  [],
  [
    {
      "cobertura": {
        "estado": "parcial",
        "fuentes": [
          "crm"
        ],
        "capacidadesFaltantes": [
          "historialCompletoAsignaciones",
          "contactosSinAsignacionAutorizable"
        ],
        "integridadHistorica": "desconocida"
      },
      "advertencias": [
        {
          "codigo": "ASIGNACION_REQUERIDA_PARA_ACCESO",
          "mensaje": "Los contactos sin asignaciones no tienen un alcance autorizable mediante la regla vigente; su ausencia no acredita que no existan.",
          "fuente": "crm"
        }
      ],
      "consistencia": "sinInstantanea",
      "fechaGeneracion": "2026-09-21T18:00:00Z"
    }
  ]
]

[
  {
    "code": 2,
    "msg": "Existen errores de validación.",
    "details": {
      "codigo": "FILTRO_INVALIDO",
      "parametro": "pagina"
    }
  }
]

Contactos en lote

Parámetros

Respuesta

Solicitud

Consultar contactos y relaciones

Respuesta

HTTP 200; Row-Count: 1

HTTP 200 sin coincidencias; Row-Count: 0

HTTP 409: filtro inválido