Inicia aquí

Bienvenida

Te damos la bienvenida a la API de Upnify. Esta guía reúne los conceptos y recomendaciones que conviene conocer antes de comenzar una integración.

Conocimientos previos

Para desarrollar una integración con mayor seguridad y rapidez, te recomendamos contar con experiencia en:

• El protocolo HTTP y servicios REST. Si necesitas reforzar estos conceptos, consulta la sección REST.
• El funcionamiento del proceso y la cuenta de Upnify que integrarás.
• Un lenguaje de programación, por ejemplo Node.js, C#, Go, Python, PHP, Java, Perl o Ruby.
• Un cliente HTTP como Postman o Insomnia para explorar y probar solicitudes.

Cómo funciona la API de Upnify

La API usa un estilo REST y JSON para intercambiar información. Cada módulo documenta las rutas disponibles, los parámetros que debes enviar y el formato de sus respuestas.

Para realizar solicitudes autenticadas necesitas un token. Puedes obtenerlo con el recurso /login usando un usuario activo, aunque para integraciones de larga duración es preferible utilizar una URL de integración. Consulta las secciones Autenticación e Integraciones para elegir el mecanismo adecuado.

Trata los tokens y las credenciales como secretos: no los incluyas en código fuente, repositorios, registros de aplicación ni interfaces de usuario. Guárdalos en la configuración segura de tu aplicación y sustitúyelos si sospechas que fueron expuestos.

Consideraciones para tu integración

• Consulta los estándares del API antes de implementar. Te ayudarán a interpretar solicitudes, respuestas y códigos HTTP de forma consistente.
• Respeta el límite de 100 solicitudes por minuto. Si lo superas, la API puede responder con el código HTTP 429. Implementa espera y reintentos graduales; no repitas la solicitud de inmediato ni aumentes la frecuencia de llamadas.
• Cuando estén disponibles para el evento que necesitas, utiliza webhooks en lugar de consultar periódicamente la información. Upnify puede notificar a tu sistema eventos como la creación de un prospecto, cliente o venta, evitando sincronizaciones innecesarias y acercando la integración al tiempo real.
• Prueba los flujos completos: solicitudes correctas, datos faltantes, errores de autenticación, límites de consumo y reintentos. Registra solo la información necesaria y nunca tokens, contraseñas ni datos personales completos.

Automatizaciones sin código

También puedes conectar Upnify con otras aplicaciones mediante herramientas como Integromat o Zapier. Estas plataformas pueden ayudarte a crear automatizaciones como:

• Agregar un cliente nuevo a una hoja de cálculo.
• Notificar un prospecto nuevo a un grupo de Telegram.
• Crear un cliente a partir de una venta de WooCommerce.

Antes de activar una automatización en producción, valida los campos que se comparten, los permisos del usuario o integración y el tratamiento de información sensible.

REST y servicios RESTful

REST significa Representational State Transfer. Es un estilo de arquitectura para diseñar servicios web sencillos, mantenibles y escalables. Una API que sigue estos principios se conoce como API RESTful.

REST no es un protocolo ni una tecnología específica: aprovecha las convenciones de HTTP para que una aplicación cliente pueda solicitar o modificar información de un servicio web de forma predecible.

Recursos y URL

En REST, la información se organiza como recursos: por ejemplo, clientes, prospectos, ventas o productos. Cada recurso se identifica mediante una URL.

https://api.upnify.com/v4/clientes

Una URI identifica un recurso; una URL es un tipo de URI que además indica cómo localizarlo. En esta documentación usamos “URL” para referirnos a las direcciones que debes invocar.

Las rutas pueden incluir:

• Parámetros de ruta, que identifican un recurso concreto, como /clientes/:tkCliente.
• Parámetros de consulta, después de ?, para filtrar, ordenar o paginar resultados.
• Un cuerpo JSON, normalmente al crear o actualizar información.

JSON: el formato de intercambio

La API intercambia datos mediante JSON (JavaScript Object Notation), un formato de texto legible por personas y fácil de procesar en la mayoría de los lenguajes.

{
  "nombre": "Usuario de ejemplo",
  "apellido": "Pérez",
  "edad": 38,
  "correo": "usuario@upnify.com"
}

Al enviar un cuerpo JSON, incluye el encabezado Content-Type: application/json. Revisa siempre la ficha del endpoint para conocer los campos requeridos, sus tipos y restricciones.

HTTP y sus métodos

HTTP define la comunicación entre tu aplicación y la API. Cada solicitud usa un método —también llamado verbo— que expresa la operación deseada sobre un recurso.

Una solicitud HTTP incluye una URL, un método, encabezados y, cuando aplica, un cuerpo. La respuesta contiene un código de estado HTTP y, normalmente, datos JSON.

Códigos de respuesta

Como guía general, los códigos HTTP se agrupan así:

• 2xx: la solicitud se procesó correctamente.
• 4xx: la solicitud requiere corrección, autenticación o permisos adicionales. Por ejemplo, 401 y 403 se relacionan con acceso, y 429 indica que superaste el límite de solicitudes.
• 5xx: ocurrió un problema en el servidor. Conserva un identificador de seguimiento si la respuesta lo proporciona y reintenta solo cuando sea apropiado.

No supongas que todas las rutas devuelven la misma estructura. Consulta la sección Respuesta de cada endpoint antes de procesar los datos.

Recomendaciones prácticas

• Usa siempre HTTPS y conserva el token de sesión como un secreto. No lo incluyas en repositorios, registros ni URLs compartidas.
• Envía únicamente los encabezados y parámetros documentados para cada endpoint.
• Implementa tiempos de espera, manejo de errores y reintentos graduales. Ante un 429, espera antes de reintentar.
• Pagina los listados y usa filtros para reducir el volumen de datos.
• Cuando un evento admita webhooks, prefírelos a consultar la API de forma repetitiva.

Continúa con Autenticación para obtener un token y con Integraciones para conocer opciones de conexión de larga duración.

Autenticación

Este apartado nos permitirá obtener el token de Autenticación de la sesión, el cual garantiza el acceso al API de Upnify, y es requerido para realizar las diversas operaciones permitidas por el API de Upnify

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

Integraciones

¿Qué son las integraciones?

Las integraciones de Upnify permiten realizar operaciones comunes de una forma simplificada, como son recibir prospectos, importar facturas, así como generar u obtener un token de sesión para realizar cualquier otra operación en el API.

Para poder utilizar una integración es necesario darla de alta primero dentro de la cuenta de Upnify para obtener un URL de integración válido. Cabe señalar que este URL de integración permanecerá activo hasta que sea eliminado del sistema por un adiministrador.

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.