Diferencias

Muestra las diferencias entre dos versiones de la página.

--- a:users:users:api_users [2025/06/27 15:18]
vcortes
+++ a:users:users:api_users [2026/09/15 09:10] (actual)
wiki: technical_support:configuration:api_users gana la sección "Configurar Webhooks" (los 5 tipos de notificación, URL, cabeceras y autenticación por HTTP), y a:users:users:api_users corrige su sección "Webhooks" pública, que describía como accesible al colegio una pantalla exclusiva del administrador principal de la plataforma. (+2 mejoras más de la corrida), algebraix
@@ Línea 1: / Línea 1: @@
 ====== Usuarios API ======
 Este tipo de usuario está diseñado para hacer que sistemas externos se conecten de forma segura y automática a una plataforma o aplicación, con permisos específicos para consultar, enviar o modificar información mediante solicitudes programadas.
+**IMPORTANTE:** El alta, la modificación y la desactivación de un usuario API las realiza Algebraix; ningún administrador ni operador de tu colegio ve las pestañas **Agregar usuario API**, **Modificar**, **Desactivar** o **Reactivar**, y no hay permiso que las habilite. Lo que sí puedes hacer desde tu colegio es consultar los usuarios API dados de alta y el detalle de cada uno. Si necesitas un usuario API nuevo, un cambio de contraseña o de endpoints, o dar de baja una integración, solicítalo a Algebraix.
   - En tu "Panel de control" selecciona **Usuarios API.**
   - Da clic en **Agregar usuario API.**
@@ Línea 20: / Línea 22: @@
     * **Acceso a todos los grupos (actuales y futuros):** Esto le dará acceso a todos los grupos del colegio incluidos aquellos que lleguen a darse de alta después de la creación de este usuario.
     * **Grupos:** Despliega el "Campus", la "Sección", el "Grado" y selecciona el o los grupos a los que darás acceso a esta usuario.
-    * Puedes darle acceso también para los perfiles de estudiantes "Solicitantes", "Graduados" y "Desactivados".
   - Para guardar da clic en **Aceptar.**
 ===== Modificar usuario API =====
@@ Línea 31: / Línea 32: @@
   - Para guardar los cambios da clic en **Aceptar.**
 ===== Webhooks =====
-  - Desde tu "Panel de control" selecciona **Usuarios API.**
+**IMPORTANTE:** Configurar los webhooks —las URLs a las que la plataforma envía en automático un aviso por cada cambio en cargos, pagos, descuentos, becas o usuarios— es exclusivo del administrador principal de la plataforma; ningún administrador ni operador de tu colegio ve esta pantalla, y no hay permiso que la habilite. Si necesitas configurar o modificar un webhook, solicítalo a Algebraix.
-  - Despliega "Webhooks" y selecciona **Webhooks.**
-  - En **Pagos** agrega la URL o IP desde donde se reciben las peticiones.
-    * Da clic en **Ver detalles** para que observes como está construida la petición.
-    * {{ :a:users:users:ver_detalles_webhook.png?direct&400 |}}
-    * Haz clic en **Pagos** para que se te envíe a la documentación de la API.
-    * {{ :a:users:users:pagos_peticion_api.png?direct&400 |}}
-  - Para agregar **Cabeceras** marca la casilla.
-    * Se muestra el campo de "Llave" y "Valor" para que agregues la información.
-    * Si deseas agregar más de una cabecera, da clic en **Agregar fila.**
-    * Para borrar alguna cabecera, da clic en el ícono de **Eliminar** {{icon>ffar fa-trash-alt text-red}}
-  - Marca la casilla de **Autenticación por HTTP** para poder agregar:
-    * **Username:** El nombre de usuario que se utilizará para la autenticación.
-    * **Password:** La contraseña que se utilizará para la autenticación.
-  - En **Usuarios** agrega la URL o IP desde donde se reciben las peticiones.
-    * Da clic en **Ver detalles** para que observes como está construida la petición.
-    * {{ :a:users:users:ver_detalles_webhook_usuarios.png?direct&400 |}}
-    * Al dar clic en cada uno de los perfiles de usuario, se te enviará a la documentación de la API.
-    * {{ :a:users:users:api_usuarios.png?direct&400 |}}
-  - Para agregar **Cabeceras** marca la casilla.
-    * Se muestra el campo de "Llave" y "Valor" para que agregues la información.
-    * Si deseas agregar más de una cabecera, da clic en **Agregar fila.**
-    * Para borrar alguna cabecera, da clic en el ícono de **Eliminar** {{icon>ffar fa-trash-alt text-red}}
-  - Marca la casilla de **Autenticación por HTTP** para poder agregar:
-    * **Username:** El nombre de usuario que se utilizará para la autenticación.
-    * **Password:** La contraseña que se utilizará para la autenticación.
-  - Para guardar da clic en **Aceptar.**
 ===== Colas pendientes =====
-  - Desde tu "Panel de control" selecciona **Usuarios API.**
+**IMPORTANTE:** Consultar y reintentar las colas de webhooks pendientes es exclusivo del administrador principal de la plataforma; ningún administrador ni operador de tu colegio ve esta pantalla, y no hay permiso que la habilite. Si un envío a tu sistema externo sigue fallando después de varios intentos, repórtalo a Algebraix.
-  - Despliega "Webhooks" y selecciona **Colas pendientes.**
-    * **NOTA:** Se mostrarán colas pendientes cuando los intentos de envío sean a partir de 6.
+===== Prechecks =====
-      * En 5 minutos envía 3 intentos.
+La pestaña **Prechecks** muestra las validaciones que la plataforma corre sobre los datos del colegio antes de que se sincronicen con Mattilda, la plataforma de pagos: agrupa en ocho tablas los registros con datos duplicados, incompletos, inválidos o mal capturados, para que los corrijas antes de que lleguen a Mattilda.
-      * En 10 minutos envía 4 intentos.
+  - Desde tu **Panel de control** selecciona **Usuarios API.**
-      * En 30 minutos envía 5 intentos.
+  - Da clic en la pestaña **Prechecks.**
+  - Cada una de las ocho pestañas de arriba trae, junto a su nombre, un contador con el total de registros que encontró; mientras carga se muestra un ícono de carga en su lugar.
+  - Arriba a la derecha, el botón de exportar a Excel descarga un archivo con una hoja por cada una de las ocho pestañas, con todos los registros sin filtrar.
+  - Cada tabla trae su propio campo **Filtrar**, que acota los renglones visibles conforme escribes, y se pagina de 50 en 50 registros.
+  - En las columnas de estatus (CURP, correo electrónico, celular, datos fiscales) el color de la etiqueta indica el problema encontrado: verde es que el dato está completo, rojo que falta, amarillo que está duplicado con otro registro, morado que faltan datos fiscales completos y naranja que el dato es genérico, por ejemplo un correo o un RFC de plantilla.
+  - Cuando un alumno o un padre de familia tiene un dato marcado como duplicado, aparece el icono de **Buscar** junto a su renglón; da clic para ver con quién se duplica cada dato, en una ventana emergente.
+==== Dobles titulares ====
+Lista a los estudiantes que tienen más de un padre o más de una madre registrados como titulares, con **Nombre del estudiante**, **Sección**, **Grado** y **Grupo**; en **# Padres** y **# Madres** ves cuántos tiene cada quien, y en **Padres** y **Madres** la lista de nombres, cada uno con un enlace a su ficha.
+==== Detalle alumnos ====
+Lista a los estudiantes con algún dato faltante, inválido o duplicado para la sincronización.
+  - **Nombre del estudiante**, **Sección**, **Grado** y **Grupo**.
+  - **Sup. propia:** un icono de palomita indica que el estudiante tiene su propia supervisión de facturación asignada; una tacha, que no la tiene.
+  - **CURP**, **Correo electrónico** y **Celular**, cada uno con su estatus.
+  - **RFC**, **Régimen fiscal**, **Uso CFDI** y **Datos fiscales**, con el estatus de este último.
+  - Da clic en el **Nombre del estudiante** para abrir su ficha.
+==== Detalle padres ====
+Lista a los padres de familia —y a los profesores marcados como tutores— con algún dato faltante, inválido o duplicado.
+  - **Activo**, con un icono de palomita o de tacha.
+  - **Nombre del padre**, con un icono de persona junto al nombre si en realidad es un profesor tutor.
+  - **Hijos**, la lista de sus hijos asociados, con el grupo de cada uno.
+  - **Correo electrónico** y **Celular**, cada uno con su estatus, y **RFC**, **Régimen fiscal**, **Uso CFDI** y **Datos fiscales**.
+  - Da clic en el nombre para abrir la ficha del padre de familia o del profesor, según corresponda.
+==== Espacios alumnos y Espacios padres ====
+Estas dos pestañas muestran a estudiantes y a padres de familia —o profesores tutores— cuyos datos traen espacios de más, al principio, al final o en medio del texto, en alguno de sus campos; eso puede provocar que el dato no se reconozca como igual al llegar a Mattilda.
+  - **Espacios alumnos** muestra **Matrícula**, **Nombre del estudiante**, **Sección**, **Grado**, **Grupo**, **Nombre**, **Apellido paterno**, **Apellido materno**, **Correo electrónico** y **Nombre o razón social**.
+  - **Espacios padres** muestra **Nombre del padre**, **Nombre**, **Apellido 1**, **Apellido 2**, **Correo electrónico** y **Nombre o razón social**.
+  - En ambas, la columna **Campo con espacios** enlista cuál o cuáles de esos campos traen el espacio de más.
+==== Correos inválidos ====
+Lista, mezclados en una sola tabla, a los estudiantes, padres de familia y profesores cuyo correo electrónico no tiene una forma válida, con **Tipo** —**Estudiante**, **Padre de familia** o **Profesor**—, **Nombre**, **Sección**, **Grado**, **Grupo** y **Correo electrónico**. Da clic en el nombre para abrir la ficha correspondiente.
+==== Sin supervisión c/ facturación ====
+Lista a los estudiantes que tienen sus propios datos de facturación —**RFC**, **Régimen fiscal**, **Uso CFDI** y **Nombre o razón social**— pero no tienen ningún padre de familia asignado como responsable de esa facturación. Muestra también **Matrícula**, **Nombre del estudiante**, **Sección**, **Grado** y **Grupo**.
+==== Sin padre principal ====
+Lista a los estudiantes que no tienen ningún padre de familia marcado como el titular principal, con **Nombre del estudiante**, **Sección**, **Grado**, **Grupo** y **Padres de familia**, la lista de los padres asociados con un enlace a la ficha de cada uno.
+<notes>FALTA_CAPTURA — pantalla: Panel de control → Usuarios API → Prechecks; mostrar: la pestaña Prechecks con la barra de las ocho tablas y una de ellas abierta con sus columnas y el filtro; archivo sugerido: :a:users:users:prechecks_mattilda.png</notes>
+===== Permisos para el operador =====
+Para que el operador pueda consultar esta pantalla, es necesario asignarle el siguiente permiso al momento de agregarlo o modificar su perfil:
+    * Desde "Permisos globales" > **Webhooks.**
+      * **Prechecks:** Permite consultar la pestaña Prechecks y sus ocho tablas de validación.
+El administrador de la escuela consulta esta pantalla sin necesidad de asignarle ningún permiso.
+===== Consultar los usuarios API =====
+  - Desde tu **Panel de control** selecciona **Usuarios API**.
+  - El panel **Usuarios API** lista las cuentas activas, una por renglón, con las columnas:
+    * La primera columna, sin título, muestra un indicador de color con la leyenda "Activo".
+    * **Nombre de usuario:** El identificador con el que la integración se conecta. Da clic en él para abrir el detalle del usuario.
+    * **Nombre** y **Apellido:** A quién o a qué sistema corresponde la cuenta.
+    * **Correo electrónico:** El correo registrado en la cuenta.
+    * **Creado por:** El usuario que dio de alta la cuenta.
+    * **Fecha y hora de creación:** Cuándo se creó.
+  - Puedes ordenar la tabla dando clic en el título de cualquiera de esas columnas.
+  - Más abajo, el panel **Usuarios API desactivados** lista las cuentas que ya no están en uso, con su indicador, **Nombre**, **Apellido**, **Correo electrónico** y la columna **Acciones**. Estas cuentas ya no tienen nombre de usuario ni permisos.
+  - Ambos paneles se pueden plegar y desplegar desde su encabezado.
+  - Si el colegio todavía no tiene ninguna cuenta de este tipo, se muestra el aviso "No se han encontrado usuarios API".
+<notes>FALTA_CAPTURA — pantalla: Panel de control → Usuarios API; mostrar: el panel Usuarios API con sus columnas y, debajo, el panel Usuarios API desactivados; archivo sugerido: :a:users:users:usuarios_api_listado.png</notes>
+===== Consultar el detalle de un usuario API =====
+  - Desde tu **Panel de control** selecciona **Usuarios API**.
+  - Da clic en el **Nombre de usuario** de la cuenta que quieres revisar.
+  - A la izquierda se muestra la ficha del usuario, encabezada con su apellido y nombre y la leyenda **Usuario API**, con los datos registrados: **Nombre de usuario** (solo si la cuenta está activa), **Nombre**, **Apellido**, **Correo electrónico**, **Direcciones IPv4 y CIDR** y **Direcciones IPv6 y CIDR** desde las que se le permite conectarse. Si la cuenta tiene acceso a todos los grupos, aparece además **Todos los grupos** bajo **Permisos de grupo**.
+  - A la derecha se muestra el panel **Endpoints**, plegado. Al desplegarlo verás, agrupados, **todos** los endpoints de la API con el método de cada uno —el catálogo completo, no solo los de esta cuenta—. Lo que distingue a los que tiene concedidos es el icono: palomita verde si lo tiene, tacha roja si no. Al auditar hasta dónde llega una integración, fíjate en el icono y no en la longitud de la lista.
+  - Debajo, el panel **Permisos de grupo** enlista los grupos a los que alcanza la cuenta, organizados por campus, sección y grado. Este panel no se muestra cuando la cuenta tiene acceso a todos los grupos.
+  - El campo **Filtrar permisos**, arriba de los paneles, acota lo que se muestra conforme escribes.
+  - **Nota:** Si la cuenta está desactivada se muestra el aviso "Usuario desactivado" y no se despliegan los paneles de endpoints ni de grupos, porque al desactivarla se le retiraron todos.
+<notes>FALTA_CAPTURA — pantalla: Panel de control → Usuarios API → clic en un nombre de usuario; mostrar: la ficha del usuario a la izquierda y el panel Endpoints desplegado a la derecha, con el campo Filtrar permisos arriba; archivo sugerido: :a:users:users:usuario_api_detalle.png</notes>
+<notes>REVISION_PENDIENTE — redactado por el canal automático y publicado sin revisión de un segundo lector. Para revisarlo: ARTICULOS="a:users:users:api_users" make -C pipeline revisar</notes>