Aplicaciones OAuth para socios

Una aplicación OAuth propiedad del socio está pensada para una integración que se conecta a varias cuentas de Planfix. Las mismas credenciales de la aplicación se usan para todas las cuentas de los clientes, mientras que cada cuenta controla la admisión por separado y cada usuario otorga su consentimiento para su propia conexión.

Si una integración está destinada a una sola cuenta, es más sencillo crear una account-owned application.

Creación de una aplicación

Abra su cuenta de socio.
Vaya a OAuth applications.
Seleccione Create application.
Introduzca el nombre y la descripción que verán los usuarios y los administradores.
Seleccione el tipo de cliente OAuth.
Añada los redirect URIs.
Seleccione los scopes mínimos requeridos del REST API.
Guarde la aplicación y copie sus credenciales.

Una aplicación nueva es privada y requiere aprobación explícita en cada cuenta a la que se conecta.

Tipo de cliente OAuth

Tipo	Aplicaciones previstas	Credenciales
Public	Aplicaciones móviles, de escritorio y basadas en navegador, y clientes MCP locales.	Un `client_id` solamente. No hay client secret; PKCE S256 es obligatorio.
Confidential	Aplicaciones del lado del servidor donde el secreto puede almacenarse fuera del dispositivo del usuario y del código del cliente.	Un `client_id` y `client_secret`.

El tipo de cliente OAuth es independiente de si una aplicación está publicada. Por ejemplo, una aplicación móvil privada es un cliente OAuth público sin secreto.

Redirect URIs

Especifique cada URL a la que Planfix puede devolver a un usuario tras el inicio de sesión.

Use https para un servicio web.
http está permitido solo para direcciones loopback como localhost y 127.0.0.1.
Un cliente puede usar un puerto dinámico para una dirección loopback, pero el esquema, host, ruta y query deben coincidir.
No use comodines, fragmentos de URL ni redirect URIs que no controle.

Scopes

Los scopes definen los permisos máximos de la aplicación. Solicite únicamente los niveles de acceso necesarios de la REST API scope list.

Los scopes de la aplicación no sustituyen los permisos normales del usuario. Incluso cuando se concede un scope, la aplicación solo puede trabajar con los datos disponibles para ese usuario.

Cambiar los redirect URIs o los scopes crea una nueva versión para aprobación. Las cuentas previamente conectadas deben revisar y aprobar la nueva versión, y los usuarios deben conectarse de nuevo.

Conectar una cuenta de cliente

Una aplicación privada propiedad del socio debe ser aprobada explícitamente por un administrador en cada cuenta.

Abra la aplicación en su cuenta de socio.
En el área del enlace de aprobación, introduzca el nombre de la cuenta del cliente.
Copie el enlace generado y envíelo a un administrador de esa cuenta.
Pida al administrador que verifique el propietario, los redirect URIs y los scopes, y luego apruebe la aplicación.
Tras la aprobación, los usuarios de la cuenta pueden completar la autorización OAuth. Cada usuario consiente por separado en su propio nombre.

El enlace abre Account management → API → OAuth and MCP applications y muestra la aplicación solicitada.

Un administrador que también esté conectando la aplicación puede seleccionar Approve and connect.

Aplicaciones privadas y publicadas

Estado	Cómo se admite en una cuenta
Private	Siempre requiere aprobación explícita por parte de un administrador de cada cuenta.
Published	Disponible sin aprobación separada cuando la política de la cuenta es Allow published applications. Aun así requiere aprobación cuando la política es Approved applications only.

La publicación es una revisión separada de Planfix. Antes de enviar una aplicación, prepare un nombre y descripción claros, un conjunto mínimo de scopes, redirect URIs en funcionamiento y documentación para los usuarios sobre cómo conectar y eliminar la integración. Contacte con el Soporte de Planfix para el procedimiento de publicación.

Direcciones de conexión

Use los endpoints OAuth globales:

Propósito	Dirección
Authorization	`https://auth.planfix.com/oauth/authorize`
Token	`https://auth.planfix.com/oauth/token`
Userinfo	`https://auth.planfix.com/oauth/userinfo`
MCP	`https://mcp.planfix.com/mcp`

No añada el nombre de la cuenta a una URL global. El usuario selecciona la cuenta en una página de Planfix. El protocolo completo, incluyendo resource, PKCE, refresh de token y revocación, se describe en OAuth 2.0 para aplicaciones.

Gestión de una aplicación

Un socio puede:

editar el nombre y la descripción;
cambiar los redirect URIs y los scopes;
deshabilitar y volver a habilitar la aplicación;
rotar el client secret de una aplicación confidential;
generar un enlace de aprobación de la aplicación para una cuenta específica.

Tras la rotación del secreto, el client secret antiguo deja de funcionar inmediatamente. Actualice el secreto en el servidor de la integración y nunca lo envíe a los usuarios.

Deshabilitar una aplicación bloquea la autorización OAuth y los tokens emitidos en todas las cuentas. Esta acción afecta a todos los clientes que usan la aplicación.

Recomendaciones antes del lanzamiento

Use Authorization Code con PKCE S256 y valide state.
Solicite solo los scopes que necesite.
Muestre la cuenta seleccionada al usuario después del inicio de sesión.
Gestione la rotación del refresh token: después de un refresh exitoso, el refresh token anterior deja de ser válido.
No escriba tokens, authorization codes, code_verifier ni client secrets en los logs.
Documente cómo los usuarios pueden desconectar la integración y solicitar la eliminación de sus datos.
Pruebe la revocación de aprobación, la deshabilitación de la aplicación y los escenarios de reconexión.