Conecta tu aplicación con OAuth de Zonitel

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

  1. 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.
  2. 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.
  3. 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).
Opciones de tipo de aplicación y público en el registro de aplicaciones de Office
  1. 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.
  2. 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.
  3. 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:

  1. Inicia solo cuando el usuario elija conectar. Genera un state y un par PKCE nuevos, de un solo uso, para cada intento. S256 es obligatorio; no se acepta PKCE plain.
  2. Envía al usuario al punto de autorización documentado con el retorno registrado y los permisos necesarios. Al volver, valida state y el emisor exacto iss; procesa una denegación sin volver a abrir el consentimiento repetidamente.
  3. 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.
  4. Consulta GET /api/v3/oauth/context para 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.
  5. Llama a la API con Authorization: Bearer TU_TOKEN_OAUTH. No envíes X-Client-Id ni un client_id de 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.
  6. Renueva según expires_in y 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.

¿Te ha sido útil este artículo?

¿Aún tienes preguntas?

Nuestro equipo de soporte está disponible 24/7 para ayudarte a comenzar

Habla con nosotros en WhatsApp