CRM

Analítica comercial

Estas consultas de sólo lectura usan la sesión habitual del API en el encabezado token. /v4/analitica/capacidades informa las rutas, filtros y relaciones disponibles para esa sesión. No generan contenido ni envían comunicaciones.

Contactos en lote

/v4/analitica/contactos acepta hasta 100 identificadores en tkContactos, separados por coma. Un prospecto convertido en cliente conserva tkProspecto. esCliente=todos incluye ambos estados; también se incluyen contactos descartados y sin atribución. El acceso se calcula en cada solicitud. Los contactos sin asignaciones quedan fuera del alcance de la regla vigente y se advierte esta limitación en la cobertura.

incluir=atribucion,empresa agrega la atribución guardada del contacto y su empresa comercial. tkEmpresa identifica esa empresa comercial. La atribución del contacto no demuestra la atribución de cada captación histórica. Un campo null indica ausencia de dato; no equivale a consentimiento ni a un resultado negativo. Solicitar una empresa comercial sin permiso devuelve 403.

Captaciones

/v4/analitica/captaciones reúne solicitudes de integración y activaciones de widgets. Requiere un periodo de hasta 366 días o un lote en tkContactos. Cada solicitud o activación conserva su identidad aunque se repita el contacto. El rango se aplica a la fecha de la captación y permite encontrar activaciones recientes de contactos antiguos.

fuente=integracion usa identidades públicas de fuente con formato integracion:1; nunca devuelve el token autenticador ni la configuración de la integración. fuente=widget usa el token público del widget y permite filtrar paginaEntrada, independientemente del número de página. Las activaciones sin contacto vinculado conservan el alcance de la cuenta; las que tienen contacto requieren acceso a él. Los registros ligados a contactos eliminados o sin acceso quedan fuera y se declara la limitación.

existente=true sólo acredita preexistencia, no actualización. Las activaciones no prueban creación ni preexistencia: mantienen existente=null y resultado=desconocido. La atribución procede del registro consultado, sin completar sus huecos con UTMs actuales del contacto. Las fechas ausentes quedan desconocidas; el intervalo no incluye registros sin fecha.

Widgets requiere Engage habilitado para la cuenta y el usuario. Si no está habilitado en la cuenta, la fuente requerida devuelve 409. Con fuente=todas&permitirParciales=true se consultan integraciones y se declara la omisión. La falta de permiso del usuario sigue devolviendo 403. Las fechas de activación pueden haberse actualizado al vincular el contacto; no se promete una historia de cambios ni cobertura de rechazos no persistidos.

Actividades

/v4/analitica/actividades consulta seguimientos, correos del buzón de la sesión y mensajes COM autorizados. Requiere periodo de hasta 366 días o lote de contactos. Ver un contacto no concede acceso a otros buzones ni agentes COM; se vuelven a aplicar los permisos de cada fuente y canal.

Una nota interna no es un intento de contacto. Las llamadas y visitas usan el indicador de efectividad registrado; los automatismos conservan su origen. La ausencia de dirección o actor queda desconocida. El texto no se utiliza para deducir esas clasificaciones. Los extractos están acotados a 512 caracteres y se indica si se truncaron.

Cuando un correo y un seguimiento están enlazados explícitamente, el listado conjunto devuelve la evidencia del correo una vez. Al consultar sólo seguimientos, idComunicacion conserva el vínculo. No se deduplica por semejanza del texto. Mensajes recibidos, enviados, entregados o leídos son evidencias distintas; un envío no demuestra respuesta del contacto.

Las fechas de mensaje, registro y modificación permanecen separadas. COM conserva las fechas originales no convertibles y sus mensajes sin fecha sólo aparecen al consultar por lote sin intervalo. Los mensajes sin identificador persistido quedan fuera, con cobertura incompleta declarada. Los estados del proveedor se proyectan mediante nombres españoles, manteniendo sus tiempos originales sin atribuirles una zona no comprobada.

Pendientes y eventos

/v4/analitica/pendientes reúne agenda, tareas CRM/Flow y conversaciones COM. Cada fila representa un pendiente; varios responsables o contactos no multiplican la tarea ni la cita. Los filtros por responsable y grupo se aplican dentro del alcance autorizado. Flow y COM requieren sus propios permisos. Con fuente=todas&permitirParciales=true sólo se omiten módulos no habilitados en la cuenta, con advertencia; una denegación sigue siendo 403.

El estado de una cita inactiva queda desconocido. vencido=null indica que faltan fecha de vencimiento o estado fiable. Una conversación con turno del agente y sin archivar puede estar pendiente, pero el número de mensajes no leídos no basta para afirmarlo. COM no aporta vencimiento y queda fuera de un intervalo por vencimiento. fechaInicioPendiente permanece null; las fechas de completado o cancelación de Flow se conservan cuando están registradas.

/v4/analitica/eventos devuelve sucesos CRM persistidos, con identidad y relaciones autorizadas, por periodo o lote. tipoEvento, entidad y tkEntidad permiten acotar la consulta. No incluye resúmenes de actividad, exportaciones, sesiones ni sucesos de otros módulos. El usuario asociado al registro y el usuario de token de origen no acreditan siempre al actor; se publican como procedencia y el actor queda desconocido. En reasignaciones se devuelve el destino persistido, sin sustituir el responsable anterior por el actual.

Las transiciones individuales de fase se conservan; los acumulados de fases no se convierten en eventos. Un token absorbido sin alias durable devuelve una consulta sin resolución y cobertura insuficiente, sin buscar una coincidencia por nombre o correo. La ausencia de eventos no prueba que el hecho nunca ocurrió.

Resumen persistido

/v4/analitica/contactos?tkContactos=P-EJEMPLO&incluir=resumen devuelve el último resumen guardado de cada contacto autorizado, o null si no existe. Conserva su fecha de actualización original, aunque haya actividades posteriores. idUltimoEventoResumido queda null cuando no está registrado. El contenido se proyecta por campos permitidos, sin configuración interna. Esta lectura no genera IA, refresca contenido ni consume créditos.

Resultados y relaciones financieras

/v4/analitica/oportunidades incluye abiertas, ganadas y perdidas con estado=todos. fechaBase=ganada encuentra una oportunidad antigua ganada dentro del periodo; fechaBase=creacion responde una pregunta distinta. /ventas distingue creación y cierre, y separa la actualización de la venta de la del contacto. Una conversión manual a cliente no inventa una venta causal.

incluir=productos devuelve una colección con datos, pagina, cantidadRegistros, totalRegistros y hayMas. Su tamaño máximo es 100 y su default es 20. Para continuar con paginaRelacion=2 se debe indicar un único tkOportunidad o tkVenta. El importe del padre aparece una vez, independientemente de sus líneas.

/v4/analitica/relaciones-financieras conserva una fila por vínculo. origen.importe y destino.importe son montos de entidades y no deben sumarse por enlace. importeAplicado sólo existe para un cobro pagado ligado a su venta o una aplicación documentada; queda null cuando sólo existe el vínculo. Los estados de cancelación se conservan y no convierten una aplicación cancelada en ingreso vigente. Un movimiento bancario publica su abono menos cargo como importe propio, sin repartirlo entre sus relaciones.

ERP debe estar habilitado en la empresa y concedido al usuario. Actualmente ese permiso abarca todas las razones sociales y cuentas bancarias de la empresa; el acceso a contacto y venta sigue siendo obligatorio. fuente=cobros usa CRM. Con fuente=todas&permitirParciales=true puede omitirse ERP si no está habilitado en la empresa; una denegación individual sigue siendo 403. Los movimientos que sólo guardan día conservan fechaOriginal y no inventan un instante; quedan fuera de filtros temporales de instantes.

Calificación, preferencias y secuencias

incluir=calificacion agrega puntuación, componentes BANT/manual/origen, etiquetas y personalizados con definiciones y opciones accesibles. Los componentes BANT son puntos del formulario guardados, no presupuesto monetario ni fechas. Una opción de catálogo se identifica y decodifica sin tratar su código como puntuación. El responsable actual no sustituye al actor ausente de una calificación; fecha, versión de reglas y clasificaciones no demostradas quedan null.

incluir=preferencias conserva recibirCorreos del contacto y los bloqueos conocidos de COM. Requiere permiso COM; si COM no está habilitado en la cuenta se puede usar permitirParciales=true y recibir cobertura explícita sin bloqueos. La ausencia de un bloqueo visible no prueba ausencia global. La preferencia de correo tampoco acredita propósito, fecha o consentimiento verificable.

/v4/analitica/secuencias distingue elegibilidad, inscripcion y comunicacion. Una coincidencia de etiqueta y tipo de contacto puede existir aunque la secuencia esté pausada, deshabilitada o el contacto dado de baja. inscripcion muestra registros de participación/control; estadoInscripcion permanece desconocido sin estado durable. tkPiezaSiguienteRegistrada sólo se llena cuando existe un vínculo explícito al catálogo; no calcula próxima ejecución. Un envío no implica entrega y una apertura no equivale a respuesta humana.

Para una política de candidatos, consultar contactos con calificacion,preferencias, actividades del periodo, pendientes y secuencias usando el mismo lote. Por ejemplo: excluir un contacto con recibirCorreos=false, bloqueo observado o cita próxima; evaluar por separado la interacción reciente y los pendientes comerciales. Si no existe evidencia de consentimiento o una fuente queda fuera del alcance, conservar la condición como desconocida y enviarla a revisión según la política del consumidor. Estas consultas no producen una autorización implícita de envío ni inscriben al contacto.

Fechas y paginación

Los filtros fechaInicio y fechaFin se envían juntos en ISO 8601 con offset. El inicio se incluye y el fin se excluye. En contactos se filtra por creación; las fechas originales se interpretan en CDMX con desfase fijo -06:00. Las fechas normalizadas llevan offset o Z para el instante equivalente en UTC. fechaOriginal conserva la fecha fuente sin zona.

pagina comienza en 1 y cantidadRegistros acepta 1 a 200, con valor predeterminado 50. El orden predeterminado es descendente por fecha, con desempate por identidad. La respuesta contiene dos arrays: filas y una fila de metadatos. El encabezado Row-Count indica el total autorizado y filtrado antes de paginar. Una página vacía conserva metadatos y total.

consistencia=sinInstantanea significa que los cambios concurrentes pueden alterar el recorrido. Esta consulta no es una sincronización de cambios y no acredita un histórico completo. fechaGeneracion corresponde a la respuesta, no a la modificación de las entidades.

Errores

Los errores conservan el array habitual con code y msg, más fields o details cuando proceda: 401 para sesión inválida, 403 para falta de permiso y 409 para entradas inválidas o filtros no publicados. Un fallo inesperado responde 500 y no se convierte en una lista vacía.

Catálogos

Esta documentación especifica todo relacionado a los catálogos del sistema. Recordemos que los catálogos tienen básicamente las siguientes operaciones:

1. Lista - Regresa la lista de registros existentes en el catálogo.
2. Detalle - Regresa toda la información a detalle de cierto registro, normalmente identificado por un ID.
3. Creación - Alta de un nuevo registro en el catálogo.
4. Modificación - Edita la información de un registro existente en el catálogo.
5. Eliminación - Elimina un registro del catálogo.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify.

Clientes

Un cliente es aquella persona que ya nos ha hecho al menos una compra alguna vez. En Upnify® los prospectos y clientes son personas ya que son estas (y no las empresas) las que nos hacen compras. Por esta razón siempre capturaremos contactos como clientes y prospectos.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify®

Acciones comunes

Este apartado te permitirá realizar todas las acciones relacionadas a las Acciones comunes, utilizando el API de Upnify Como obtener los catalogos de paises, estados, etc.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify

Comunicaciones

Este apartado te permitirá realizar todas las acciones relacionadas a las Comunicaciones, utilizando el API de Upnify ^® Como enviar un correo, crear campañas y administrar tu bandeja de correos.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify ^®

Empresas

Este apartado te permitirá realizar todas las acciones relacionadas a las Empresas, utilizando el API de Upnify Como crear una nueva empresa, visualizar facturas o consultar ventas asociadas.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify

Facturación

Este apartado te permitirá realizar todas las acciones relacionadas a la Faturación, utilizando el API de Upnify. Como dar de alta facturas, gestionar folios o administrar las razones sociales.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify.

Oportunidades

Este apartado te permitirá realizar todas las acciones relacionadas a las Oportunidades, utilizando el API de Upnify. Como crear una nueva oportunidad, realizar seguimientos o reasignar una oportunidad.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify.

Prospectos

Un prospecto es un posible cliente, o dicho de otra forma, aquel que coincide con el perfil del cliente o mercado meta que tiene el negocio.

Consideraciones:

• Un prospecto es una PERSONA (en caso de las empresas, la persona con quien tenemos contacto).
• Un prospecto tiene nombre y apellidos.
• Al menos un dato de contacto es deseable al ingresar un prospecto.
• Con la primer venta que realiza un prospecto, este se convierte en cliente.
• Un prospecto se le asocia: seguimiento, recordatorios, archivos y oportunidades.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify.

Reportes

Este apartado te ayudará a consultar la información de los Reportes utilizando el API de Upnify. Con ellos podrás obtener la información que se utiliza para construir los reportes del sistema.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify.

Resúmenes

Este apartado te permitirá consultar los Resúmenes de actividad y productividad utilizando el API de Upnify. Con ellos podrás obtener información concentrada de lo que está sucediendo en tu cuenta. Cabe señalar que todas estas rutas se introducen en la versión 4 del API, por lo que no estarán disponibles para versiones anteriores.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify.

Sistema

Este apartado te permitirá realizar todas las acciones relacionadas a el sistema, utilizando el API de Upnify. Como realizar búsquedas, crear campos personalizados, establecer metas, o modificar los datos de la cuenta.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify.

Ventas

Este apartado te permitirá realizar todas las acciones relacionadas a las Ventas, utilizando el API de Upnify. Como administrar las ventas, crear seguimientos, o ver las facturas asociadas.

Notas generales

• Recuerda que la entrada y salida de datos en el API están en formato JSON.
• El Token identifica de manera única tu sesión dentro del CRM y es requerido para cada petición.

Consulta la documentación para conocer los métodos que te permitirán tener acceso al API de Upnify.