La impresión suele ser lo último que se agrega a una aplicación y lo primero que falla. Integrarla mediante ezeep proporciona a tu aplicación renderizado en la nube, descubrimiento de impresoras y enrutamiento de trabajos sin tener que mantener una infraestructura de controladores.
Esta página está dirigida a desarrolladores. Para usar ezeep mediante un asistente en lugar de desarrollar directamente con él, comienza con Conecta ezeep MCP a tu cliente de IA en tres pasos.
¿Cuál es la diferencia entre el tiempo de desarrollo y el tiempo de ejecución?
Durante el desarrollo, una herramienta de IA lee la documentación de ezeep, genera el código de integración y ejecuta una impresión de prueba mientras trabajas. Luego, tu aplicación desplegada llama directamente a la API REST de ezeep, sin que MCP intervenga. Esta es la ruta normal y la que asume la guía del servidor.
Los frameworks de agentes son la excepción. En ellos, MCP permanece como interfaz permanente del agente para la impresión.
¿Qué modelo de autenticación necesitas?
Elige esto antes de escribir cualquier código, porque los dos modelos no son intercambiables y cambiar más adelante significa rehacer la capa de autenticación.
Cuenta compartida. Una identidad de ezeep imprime para toda la aplicación. Los quioscos, las herramientas internas, la automatización del lado del servidor y las integraciones de API encajan en este modelo. La configuración se realiza mediante el flujo de emparejamiento integrado en el servidor MCP: solicita un código de emparejamiento, inicia sesión en la URL que devuelve y, después, intercambia el código por tokens.
OAuth por usuario. Cada usuario final inicia sesión con su propia cuenta de ezeep, que es lo que necesitan los productos multiusuario. OAuth 2.0 Authorization Code estándar con PKCE. Reutiliza un cliente PKCE público existente si ya tienes uno, o haz que un administrador de la organización registre uno una sola vez.
No sustituyas OAuth por usuario por el flujo de emparejamiento. Cada usuario final tendría que ser redirigido a ezeep, iniciar sesión, generar un token y copiarlo de nuevo en tu aplicación, lo cual no ofrece una experiencia adecuada para un producto listo para usar.
Reglas que harán que tu integración falle si las ignoras
Los refresh tokens son de un solo uso. Cada intercambio devuelve un nuevo refresh token e invalida el que utilizaste.
Guarda los refresh tokens en una fila de base de datos que pueda modificarse, nunca en variables de entorno ni en un almacén de secretos de la plataforma. Esta es la forma más común en que estas integraciones fallan. Los almacenes de secretos no se pueden modificar desde la aplicación en ejecución, por lo que la primera rotación la deja inutilizable de forma permanente. Lee el token de la fila, intercámbialo y escribe el nuevo token de vuelta en la misma fila.
El client ID debe estar en un encabezado Authorization, no en el cuerpo de la solicitud. Crea una credencial Basic a partir del client ID seguido de dos puntos, sin secret.
Nunca pidas a un usuario un client ID, client secret o refresh token. El servidor MCP proporciona un client ID predeterminado, así que solicítaselo en lugar de codificar un valor de forma fija.
No reutilices el propio endpoint OAuth del servidor MCP dentro de tu aplicación. Existe para clientes host de MCP y para ninguna otra finalidad.
Registra un solo cliente OAuth por aplicación, no uno por cada build. Un nuevo client ID cambia la identidad de tu aplicación e invalida los refresh tokens de todos los usuarios existentes, porque cada refresh token está vinculado al cliente que lo emitió. Los nuevos clientes también cuentan para el límite de tu organización.
Elige cuidadosamente el modo de tenant. Un cliente single-tenant solo permite usuarios de la organización propietaria, mientras que un cliente multi-tenant permite usuarios de cualquier organización de ezeep. Esta elección queda fijada una vez creado el cliente, y single es lo que la mayoría de las aplicaciones necesitan.
¿Dónde se encuentran los endpoints de la API?
ezeep funciona en tres hosts y cada uno tiene un prefijo de ruta obligatorio. No existe una única URL base, y agregar nombres de operaciones a un solo host hará que la solicitud falle.
Las operaciones de impresión del usuario final se encuentran en printapi.ezeep.com en /sfapi/. La lista de impresoras que puede ver un usuario, las propiedades de las impresoras, la preparación de una carga, el envío de un trabajo, el estado del trabajo y los tipos de archivo compatibles se encuentran aquí.
La administración de impresoras, grupos y conectores se encuentra en api2.ezeep.com en /printing/v1/, con paginación.
Las operaciones de cuenta, usuario y OAuth se encuentran en account.ezeep.com en /v1/, /oauth/ o /auth/. La administración de usuarios se encuentra aquí e incluye la lista de usuarios, los detalles de los usuarios, el perfil del usuario que ha iniciado sesión y las invitaciones.
Tres detalles explican la mayoría de los primeros errores. Todas las rutas necesitan su barra diagonal final. La llamada de preparación de la carga es únicamente GET y utiliza el nombre del archivo como parámetro de consulta, por lo que un POST o un cuerpo JSON devuelve un error de método no permitido. Cada solicitud de impresión incluye el alias del archivo y un tipo de auto.
Patrones que debes evitar
Evita la biblioteca JavaScript de ezeep, el componente web de impresión y el paquete CDN para una integración construida de esta manera, ya que la ruta compatible consiste en utilizar REST directamente desde una función del lado del servidor. No pidas a un usuario que copie un refresh token desde la página del generador de tokens a tu configuración, ya que esa página existe para las pruebas de desarrolladores. Mantén las credenciales fuera del código del frontend.
¿Dónde se encuentran las instrucciones actuales?
Dentro del servidor. Incluye su propia guía de integración, referencia de API y ejemplos de código como herramientas que se pueden utilizar, y esa información es la fuente de verdad actual. Al desarrollar mediante un cliente de IA, haz que lea estos recursos en lugar de trabajar con conocimientos generales sobre ezeep, que envejecen más rápido que la plataforma.
Preguntas frecuentes
¿Necesito MCP en mi aplicación desplegada? Solo para frameworks de agentes. Una aplicación convencional utiliza MCP durante el desarrollo para generar la integración y después llama directamente a la API REST de ezeep durante la ejecución.
¿Por qué mi integración dejó de funcionar después de un día? Casi siempre se debe al refresh token. Los tokens se rotan en cada intercambio y almacenarlos en variables de entorno o en un almacén de secretos de la plataforma significa que el nuevo nunca se vuelve a escribir. Muévelos a una fila de base de datos que tu aplicación pueda sobrescribir.
¿Puedo reutilizar un cliente OAuth en varias aplicaciones? Reutilízalo para diferentes builds de la misma aplicación. Una aplicación independiente necesita su propio cliente, ya que los refresh tokens están vinculados al cliente que los emitió y rotar la identidad del cliente invalida a los usuarios existentes.
¿Qué scope debo solicitar? Printing cubre las operaciones de impresión y accounts cubre las operaciones administrativas. Solicita únicamente lo que la aplicación realmente utiliza.
¿Existe un límite de velocidad? Las llamadas pasan por la misma plataforma que la API REST y cuentan para la misma cuota, independientemente de si llegan mediante MCP o directamente.