Conecta tu aplicación con OAuth de Zonitel
Elige OAuth o una integración privada, registra tu app, solicita los permisos adecuados y conecta la empresa correcta. Incluye capturas de Office y soluciones para desarrolladores.
Usa Connect with Zonitel (OAuth) cuando desarrolles software que tus clientes conectarán a su empresa de Zonitel. Cada usuario revisa los permisos solicitados. Para un servicio interno de tu propia empresa, empieza con Integraciones Privadas.
Esta guía explica la pantalla de registro y el flujo para desarrolladores de la documentación oficial de la API. Registrar una aplicación no conecta a un cliente ni autoriza el acceso por sí solo.
1. Registra la aplicación en Office
- Abre Settings → My apps → Register an application. Completa Identity: nombre, editor, descripción breve, página web, correo de soporte y URL de privacidad. Usa tu propia identidad; el nombre no puede contener “Zonitel” ni imitar otra empresa.
- Elige Client type. Una Web app en tu servidor puede proteger un secreto de cliente y es el tipo que permite solicitar permisos sensibles. Una Mobile or desktop app usa PKCE sin secreto. Native app with a loopback redirect permite además la dirección de retorno local documentada.
- En Who can connect it, elige el público: Only your company, Companies that enable it (un administrador del cliente habilita el identificador de tu app) o Anyone on Zonitel (requiere revisión de Zonitel y una URL de privacidad).

- Agrega las Redirect URIs exactas. Las direcciones habituales usan HTTPS, sin comodines ni fragmentos. Utiliza la excepción de retorno local solo con el tipo de cliente nativo correspondiente.
- Selecciona únicamente los Permissions this app may request necesarios. Son el máximo permitido: el usuario aprueba un subconjunto y sus roles pueden limitarlo más. Consultar historial, grabaciones, transcripciones y enviar mensajes son permisos separados.
- Revisa la información y selecciona Register application. Guarda el identificador asignado y, si es una app de servidor, el secreto de cliente de forma segura. La documentación indica que el secreto se muestra una vez. No lo incluyas en el navegador, una app móvil, capturas ni mensajes a soporte.
2. Implementa el flujo de conexión
Tu desarrollador debe abrir OAuth — Connect with Zonitel en la documentación de la API para seguir el protocolo completo. La secuencia esencial es:
- Inicia solo cuando el usuario elija conectar. Genera un
statey un par PKCE nuevos, de un solo uso, para cada intento. S256 es obligatorio; no se acepta PKCE plain. - Envía al usuario al punto de autorización documentado con el retorno registrado y los permisos necesarios. Al volver, valida
statey el emisor exactoiss; procesa una denegación sin volver a abrir el consentimiento repetidamente. - Canjea el código de autorización enseguida. Los códigos son de un solo uso. El secreto de una app de servidor permanece en su servidor; una app pública no debe incluirlo.
- Consulta
GET /api/v3/oauth/contextpara identificar la empresa conectada. Muestra su nombre antes de confirmar. Guarda una relación explícita entre esa empresa de Zonitel y la ubicación del cliente en tu sistema; el correo electrónico por sí solo no basta. - Llama a la API con
Authorization: Bearer TU_TOKEN_OAUTH. No envíesX-Client-Idni unclient_idde empresa en el cuerpo de las peticiones a la API. OAuth obtiene la empresa de la autorización; esos selectores adicionales se rechazan con HTTP 400. - Renueva según
expires_iny reemplaza siempre el token de renovación guardado. Coordina las renovaciones para no reutilizar un token anterior: hacerlo puede revocar toda la autorización. Trata los tokens de acceso como valores opacos y no los incluyas en URLs ni registros.
El identificador de cliente OAuth identifica a la aplicación durante la autorización. No es el identificador de empresa que utiliza una integración privada.
3. Resuelve problemas de acceso y desconecta
reason=not_granted: el usuario no aprobó ese permiso. Vuelve a conectar y solicítalo solo si la función lo necesita.reason=role_reduced: los roles actuales del usuario no permiten la acción. Pide a su administrador que revise el acceso; reconectar repetidamente no lo resolverá.invalid_grant: la autorización fue revocada o el token/código ya no puede usarse. Inicia una conexión nueva aprobada por el usuario.invalid_client: revisa los datos de registro y el estado de la aplicación antes de reintentar.- La lista de aplicaciones no carga: confirma la cuenta y ubicación, recarga una vez y contacta a soporte si continúa. No sustituyas tokens OAuth por credenciales privadas para evitar el problema.
Los usuarios pueden revisar sus autorizaciones en Account activity → Connected apps. El desarrollador debe revocar el token de renovación mediante el punto de revocación documentado cuando el cliente desconecte la integración. Consulta los puntos de acceso, campos y reglas de reintento exactos en la referencia OAuth actual.
Guías relacionadas
Integraciones Privadas · Llamadas e historial del contacto · API de SMS y MMS · API de WhatsApp
¿Necesitas ayuda?
Llama, envía un mensaje de texto o escribe por WhatsApp al (833) 966-4835, o envía un correo a info@zonitel.com. Comparte los ejemplos relevantes en privado; nunca incluyas contraseñas ni códigos de verificación.