From cbb29086cc2c1404b1caa3c8d4074077d934caeb Mon Sep 17 00:00:00 2001 From: JohannVelazquez Date: Tue, 11 Aug 2026 20:23:55 -0600 Subject: [PATCH] =?UTF-8?q?Documenta=20las=20definiciones=20Jira=E2=86=92B?= =?UTF-8?q?IND=20y=20su=20validaci=C3=B3n=20por=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consolida el disparador, los huecos de datos y el protocolo de prueba para continuar el desarrollo con decisiones trazables. --- bitacora/PENDIENTES.md | 22 +- bitacora/REGISTRO.md | 81 +++++++ planeacion/Correo-respuesta-Noe-2026-08-10.md | 56 +++++ planeacion/Investigacion-API-Jira.md | 211 ++++++++++++++---- 4 files changed, 323 insertions(+), 47 deletions(-) create mode 100644 planeacion/Correo-respuesta-Noe-2026-08-10.md diff --git a/bitacora/PENDIENTES.md b/bitacora/PENDIENTES.md index 824868b..f458e23 100644 --- a/bitacora/PENDIENTES.md +++ b/bitacora/PENDIENTES.md @@ -2,7 +2,27 @@ Acciones vivas del proyecto. Formato: `[ ]` abierta · `[x]` cerrada (no se borran, dejan rastro). Cada una con responsable y, si aplica, fecha. Ver contexto en [REGISTRO.md](REGISTRO.md). -_Última actualización: 2026-07-23 (sesión de reglas del 22-jul REALIZADA: alta de clientes mapeada, fee = despacho, Jira confirmado en el proceso con estatus "resuelto" como disparador; no se tocaron PUE/PPD ni particularidades de envío; hoy 23-jul validación del prototipo a las 7:00 pm)._ +_Última actualización: 2026-08-10 (Balam definió el flujo Jira→BIND en el correo del 7-ago: disparador = `En proceso de facturación`, todos los request types, monto/conceptos como campos de Jira, prueba acompañada sin `FACTEST`. Verificado por API el 10-ago: el campo `Monto sin IVA` ya existe, pero **los conceptos no tienen campo** y **10 de 69 tickets no traen datos estructurados**. Ver [REGISTRO #59](REGISTRO.md))._ + +## 🔥 Flujo Jira→BIND — abierto tras la definición del 7-ago + +- [x] ~~🔥 **Johann — responder el correo del hilo de Jira**~~ → **Enviado el 10-ago.** Pide ticket de ejemplo, propone mié 12 / jue 13 a las 7:00 am, fija el alcance en la cotización y recuerda Azure. Texto en [REGISTRO #59](REGISTRO.md). +- [ ] 🔥 **Balam — levantar el TICKET DE EJEMPLO capturado "como debería ser"** (pedido para hoy/mañana en el correo del 10-ago). Tarea **dejada sin asignar a propósito** para que Balam la ruteé; en la práctica es de Arturo. Es el mecanismo elegido para resolver por evidencia, y no por correo, los huecos de abajo. ⚠️ **Riesgo: el precedente de latencia es de 8 días** (pregunta del 30-jul contestada el 7-ago). Si no hay respuesta para mañana al mediodía, empujar por WhatsApp con Erika, que es el canal que responde el mismo día. +- [ ] 🔥 **Balam/Noé — confirmar la sesión** (mié 12 o jue 13, 7:00 am). Sin fecha confirmada no hay prueba acompañada. +- [ ] 🔴 **Conceptos/partidas — se resuelve con el ticket de ejemplo.** El acuerdo del 4-ago resolvió el monto (`customfield_11556`) pero **no existe campo de conceptos en todo el sitio de Jira**. Si en el molde el desglose no cabe en ningún campo, hay que agregar uno; si no, la cotización va de una sola línea. **Sigue siendo el único bloqueo real para cerrar B7.** +- [ ] 🔴 **ACUNTIA — se resuelve con el segundo ticket de ejemplo.** `FAC-100` trae **un solo** `Monto sin IVA` (7,594.00 USD) para el ticket que históricamente representa 40–48 facturas. ¿Un ticket → una cotización? Ver [REGISTRO #55](REGISTRO.md) punto 6. +- [ ] ⚠️ **Tickets de `Automation for Jira` — convertido en SUPUESTO, ya no bloquea.** 10 de 69 no tienen request type ni un solo campo (incluido `FAC-91`, vivo en validación nacional). En el correo del 10-ago se asienta que **siguen tramitándose a mano** y que la automatización cubre solo los que entran por el portal. Si Balam objeta, la regla de Automation tendría que propagar los campos (trabajo de ellos). El molde capturado a mano no puede resolver esto. +- [ ] ⚠️ **Johann — decidir el destino de la cotización de la prueba en BIND.** El ejercicio escribe una **cotización real en BIND producción**. Anunciado en el correo, con dos salidas ofrecidas: cancelarla al terminar o apuntarla a un cliente de prueba. Definir cuál antes de la sesión. +- [ ] 🔴 **¿El comercial ya genera la cotización en BIND, o la genera la plataforma?** Contradicción abierta: el 6-jul Ara dijo que **el comercial la genera y la plataforma la convierte** a prefactura ([REGISTRO #27](REGISTRO.md)); el 4-ago Arturo dijo que **la plataforma la genera**; y el formulario de Jira sigue exigiendo **adjuntar la cotización**. Si ambas cosas ocurren, **quedan dos cotizaciones por ticket**. Se resuelve viendo qué adjunto pone Arturo en el ticket de ejemplo: cotización de BIND ya existente (→ convertir) o documento comercial (→ crear). +- [x] ~~**Alcance del ejercicio en vivo: ¿cotización o prefactura?**~~ → **Decidido (10-ago): termina en la COTIZACIÓN.** Es lo que contestó Arturo el 4-ago; la aprobación de Araceli va entre `En proceso de facturación` y `Facturado`, así que la prefactura pertenece después; Arturo pidió gradualismo explícito; y la cotización se cancela sin efecto fiscal mientras la prefactura es un registro en `Invoices` con `UUID = null`. La prefactura queda para la segunda sesión. Candados acordados: **cotización → prefactura → aprobación humana → timbrado** ([REGISTRO #55](REGISTRO.md)). +- [ ] ⚠️ **La transición automática depende de Azure.** En la prueba del miércoles el disparo es **manual** (pipeline `Draft→DryRun→Confirmed` de ADR-001 con flags apagados). Para que corra automática hace falta el ambiente publicado y corriendo continuo — otro argumento para insistir en el acceso a Azure. +- [ ] 🔥 **Johann — preparar el script contra el ticket de ejemplo** en cuanto Arturo lo levante, para llegar a la sesión con el flujo funcionando. Compartirlo con Balam **antes** de la sesión (protocolo del Bloque 6 de `../planeacion/Investigacion-API-Jira.md`). +- [ ] **Balam/Noé — fecha para la prueba acompañada de escritura.** Aceptado el formato el 7-ago, sin día propuesto por ellos. En el correo del 10-ago se proponen **mié 12 o jue 13-ago, 7:00 am o después de 6:00 pm** (30 min), sobre un ticket que cree Arturo, con el script compartido de antemano. **No habrá `FACTEST`.** +- [ ] **Balam — ¿nacional vs extranjero cambia la cotización** o solo el paquete de salida (PDF+XML vs PDF)? Hay dos estatus de validación y una aprobación por rama. +- [ ] **Balam/Pedro — migrar a cuenta de servicio** en vez de la cuenta personal de Pedro. Planteado el 29-jul, sin respuesta: hoy todo lo que escriba la plataforma queda firmado como Pedro y una rotación suya mata la integración. +- [ ] **Johann — levantar el sandbox Jira Cloud propio** (plan Free, proyecto JSM que replique el workflow de FAC). Con `FACTEST` descartado, es el único lugar donde se puede equivocar sin costo. +- [ ] ⚠️ **Johann — implementar la detección por changelog, no por estatus actual.** `FAC-100` estuvo **2m44s** en el estatus disparador; un poller de 15 min que consulte el estado actual se pierde la mayoría de los disparos. Refuerza el caso de pedir un webhook / regla de Automation a Pedro. +- [ ] **Johann — mover el token de Jira a user-secrets/Key Vault** y borrarlo de disco (ya está en `.gitignore:9`). Mismo pendiente que arrastra `bind_token_api.txt`. ## 🔴 Johann (proveedor) — inmediato diff --git a/bitacora/REGISTRO.md b/bitacora/REGISTRO.md index 98f8955..b5c49cd 100644 --- a/bitacora/REGISTRO.md +++ b/bitacora/REGISTRO.md @@ -1103,6 +1103,87 @@ Johann envió el **avance por actividad en texto** (8:12 am), con 👍 de Erika --- +## 59 · Jul 30 – Ago 10, 2026 · Correo · Balam define el flujo Jira→BIND: disparador, campos y prueba acompañada ⭐🔥 + +> Hilo `RV: Seguimiento: medición de consumo API de Jira y accesos` (fuente original conservada localmente; no versionada porque contiene cabeceras y adjuntos completos del correo). Continúa [#56](REGISTRO.md). Es **la definición del flujo de facturación que estaba bloqueando B7 desde el 24-jul** ([#55](REGISTRO.md), [#58](REGISTRO.md)). + +**Cronología (8 días de latencia):** + +| Fecha | Movimiento | +|---|---| +| 30-jul 10:28–11:44 am | Pedro confirma su correo, **regenera el token** y comparte la URL `https://balam-jsm-temp.atlassian.net`. Cierra el 401 del 29-jul. | +| 30-jul 1:07 pm | **Johann pregunta las 4 definiciones** (disparador, alcance de request types, fuente de monto/conceptos, y FACTEST vs prueba acompañada) + reporta el hallazgo de que el monto no está en campos estructurados. | +| 3-ago 4:58 pm | Noé **escala internamente** a Araceli y Arturo (CC Pedro), reconociendo el cambio de propósito: *"el flujo de JIRA tenía un propósito claro, validar la actividad y la evidencia, ahora cambiar a ejecutar y automatizar actividades con el desarrollo"*. Entra **Araceli Sánchez** al hilo. | +| 3-ago 4:59 pm | Noé a Johann: *"Estamos definiendo para darte respuesta mañana mismo"*. | +| 4-ago 12:15 pm | **Arturo responde en verde** sobre los tres puntos + adjunta captura del formulario y del filtro de request types. | +| 7-ago 5:34 pm | Noé reenvía a Johann y **contesta la cuarta**: prueba acompañada. | + +**Las 4 definiciones, cerradas:** + +1. ⭐ **La cotización BIND se genera al entrar a `En proceso de facturación`.** Y: *"por el momento todo se tramitará como facturación normal, hasta el explorar el módulo de proyectos en BIND"* → **el caso de facturación recurrente queda fuera de alcance por ahora.** +2. ⭐ **Se observan TODOS los request types** de la bandeja de facturación, no solo `Facturación adicional`. +3. ⭐ **Monto y conceptos van como campos de Jira**, no del adjunto. Noé: *"resta rapidez, pero garantiza consistencia de datos"*. Arturo: *"de acuerdo, deben ser los campos de JIRA (omitir el campo recurrencia)"*. +4. ⭐ **No habrá proyecto `FACTEST`:** *"Preferimos una prueba acompañada sobre un ticket"* (Noé). + +**Verificación por API el 10-ago (solo lectura; detalle en `../planeacion/Investigacion-API-Jira.md`):** + +- ✅ **El acuerdo ya está implementado en Jira:** `Monto sin IVA` existe como `customfield_11556` (number/float, obligatorio) en el request type 83. Desapareció `Periodo de Incidencias`. +- 🔴 **Pero solo 2 de 69 tickets lo tienen poblado** — `FAC-100` y `FAC-101`, ambos creados el **4-ago**, el mismo día de la respuesta de Arturo. Sin histórico contra el cual validar el mapeo. +- 🔴 **`conceptos`/partidas NO existe como campo en todo el sitio.** El catálogo completo solo tiene `Monto sin IVA` (11556), `Monto con IVA` (11522, sin usar en el formulario) y `Total forms` (de JSM). **El acuerdo resolvió el monto pero no los conceptos.** +- 🔴 **"Todos los request types" incluye tickets sin request type:** el filtro de la bandeja muestra 6 opciones (las 4 del portal + `Empty` + `Emailed request`). **10 de 69 tickets no tienen request type ni un solo campo estructurado**; nacen de `Automation for Jira` desde HH/SA/IN/RH, con los datos codificados en el `summary`. **No son ruido:** `FAC-91` es uno de ellos y está vivo en `En validación nacional` (`[FACTURA COMPLETA - Staff Augmentation] Axians — RH-36`). +- 🔴 **El estatus disparador dura minutos.** `FAC-100` estuvo **2m44s** en `En proceso de facturación` (11:51:25 → 11:54:09 del 5-ago) y 25 min de punta a punta. Solo 1 de 69 tickets está parado ahí hoy. **Un poller que consulte el estatus actual se pierde la mayoría de los disparos → la detección por changelog pasa de preferencia a requisito.** +- ⭐ **Hallazgo nuevo: el workflow tiene aprobaciones de JSM**, con **Araceli Sánchez** como aprobadora en las ramas de validación nacional/extranjera (`customfield_10003`/`10025`). El paso a `Facturado` es una aprobación formal, no una transición simple. La plataforma no debe aprobar nunca. +- ✅ `FAC-100` cierra con `status = Facturado` **y** `resolution = Done` consistentes (resuelve la trampa documentada el 30-jul). +- ✅ Headers de rate limit confirmados: `X-RateLimit-Limit: 350`, `X-RateLimit-Remaining: 348`, más los estándar `RateLimit-Policy`/`RateLimit`. **El límite observado es 350, no los 100/s que mencionó Pedro** → leer el header, no hardcodear. +- ✅ El origen es **creación por Automation, no move entre proyectos**: sin cambios de `project`/`key` en los changelogs, con `issuelinks` al ticket origen. **Escuchar FAC basta.** +- ⚠️ `Facturación recurrente` sigue siendo obligatorio y se está llenando (`FAC-100`: `Si`, periodo `12`) pese al acuerdo de omitirlo. +- ⚠️ `Nombre del Cliente` es **ADF**, no string, y **no trae RFC** — la llave de match contra BIND queda en el nombre escrito a mano. +- ⚠️ **ACUNTIA ya tiene caso real:** `FAC-100` es `Julio/CONSULTORIA Y SERVICIOS (Eduardo Fiallo CEMEXUSA)/ACUNTIA`, `Helmstone`, USD, 45 días, **un solo `Monto sin IVA` de 7,594.00** — para el ticket que históricamente representa 40–48 facturas ([#55](REGISTRO.md) punto 6). + +> **Lectura estratégica:** +> - **B7 queda desbloqueado en su mayor parte.** El disparador está definido y el campo de monto ya existe: se puede implementar lectura, detección por changelog, parser de ADF y mapeo. **Lo único que sigue bloqueado es el armado final de la cotización**, por la definición de conceptos. +> - **El acuerdo del 4-ago resolvió el monto y olvidó los conceptos.** Es el hueco más caro del hilo: sin partidas, la cotización BIND sale de una sola línea. Puede ser aceptable, pero tiene que ser una decisión explícita de Balam, no un default silencioso. +> - **"Todos los request types" no es implementable literalmente.** ~14% de los tickets no tiene datos con los que armar nada. Hay que acotar el alcance por escrito o pedir que la regla de Automation propague los campos — y eso es trabajo de Balam. +> - **Sin `FACTEST`, el sandbox propio deja de ser opcional.** Se escribirá en producción una sola vez, acompañado; todo el desarrollo previo tiene que ocurrir en un sitio Jira Cloud gratuito propio. +> - **8 días de latencia en la definición**, con el agravante de que la pregunta se hizo el 30-jul y el escalamiento interno no arrancó hasta el 3-ago. Suma al patrón ya documentado: la definición del flujo lleva bloqueando desde el 24-jul. +> - **Araceli entra al hilo como aprobadora**, tanto en el correo como en el workflow de Jira. Es un interlocutor nuevo para las definiciones que faltan. +> - **PUE/PPD gana evidencia:** hay tickets `Seguimiento del Ticket con pago anticipado:`, lo que sugiere casos PUE reales y refuerza la pregunta que lleva cuatro sesiones sin hacerse ([#52](REGISTRO.md)). + +**Respuesta de Johann — ENVIADA el 10-ago, tarde.** Texto completo y borradores previos en `../planeacion/Correo-respuesta-Noe-2026-08-10.md`: + +> Buenas tardes, espero se encuentren bien. +> Gracias por las definiciones, quedan claras y ya retomé el desarrollo, ya validé que el campo "Monto sin IVA" está creado y funcionando. +> Para aterrizar los detalles que faltan sería de ayuda que hoy o mañana se cree un ticket de ejemplo capturado "como debería ser", con todos los campos llenos tal como quieren que se capture de aquí en adelante. Contra ese molde llego a la sesión con el flujo ya funcionando. +> Para la sesión, ¿les funciona el miércoles 12 o el jueves 13, a las 7:00 am? +> El ejercicio termina en la cotización en BIND. +> Sigo pendiente del acceso a Azure para publicar el ambiente. +> Quedo atento. Saludos. + +**Decisión de enfoque:** en lugar de resolver los tres huecos con otra ronda de correos, se pide **un ticket de ejemplo capturado "como debería ser"**. Balam ya está adoptando el llenado completo de campos, así que el molde resuelve por evidencia lo que la prosa tardaría dos semanas en definir, y permite preparar el script contra datos reales para llegar a la sesión con el flujo funcionando. + +**La tarea se dejó deliberadamente sin asignar** ("sería de ayuda que se cree"), para que Balam la ruteé internamente: Arturo no estaba en el CC del correo de Noé, y Noé ya venía haciendo ese papel de router desde el escalamiento del 3-ago. Nombrar a un ausente habría sido peor que dejarlo abierto. + +**Alcance del ejercicio fijado: termina en la COTIZACIÓN, no en la prefactura.** Razones: es lo que contestó Arturo el 4-ago; la aprobación de Araceli va entre `En proceso de facturación` y `Facturado`, así que la prefactura pertenece después; Arturo pidió gradualismo explícito el 24-jul; y una cotización se cancela sin efecto fiscal, mientras que en BIND la prefactura es un registro en `Invoices` con `UUID = null` y los shapes de los POST nunca se han probado. Respeta los tres candados de Noé: **cotización → prefactura → aprobación humana → timbrado** ([#55](REGISTRO.md)). + +**Lo que el correo final dejó fuera y ahora se resuelve verbalmente en la sesión** (sin constancia escrita previa): +- Que el ejercicio **genera una cotización real en BIND producción** y que se cancela al terminar. **Anunciarlo al abrir la sesión, antes de ejecutar.** +- El compromiso de **compartir el script antes** (condición de Noé del 24-jul). Mandarlo por separado cuando esté listo. +- Que el **disparo es manual** en esta prueba (pipeline `Draft→DryRun→Confirmed` de ADR-001 con flags apagados) y que la versión automática **depende de Azure**. +- **ACUNTIA** y el **supuesto de los tickets de `Automation for Jira`**. + +**Pendientes que deja el hilo:** +- [x] ~~🔥 Johann — **responder el correo**~~ → **Enviado el 10-ago** (texto arriba). +- [ ] 🔴 Balam/Arturo — **definir de dónde salen los conceptos/partidas** de la cotización. +- [ ] 🔴 Balam/Arturo — **decidir qué pasa con los tickets creados por Automation** (10 de 69, sin campos). +- [ ] 🔴 Balam/Arturo — **confirmar si ACUNTIA es un ticket → una cotización** o sigue siendo 40–48 facturas. +- [ ] Balam/Noé — **fecha para la prueba acompañada** de escritura. +- [ ] Balam — **¿nacional vs extranjero cambia la cotización** o solo el paquete de salida? +- [ ] Balam/Pedro — **cuenta de servicio** en vez de la cuenta personal de Pedro (planteado el 29-jul, sin respuesta). +- [ ] Johann — **levantar el sandbox Jira Cloud propio** (plan Free) para desarrollar sin tocar producción. +- [ ] Johann — mover el token de Jira a **user-secrets/Key Vault** y borrarlo de disco (ya está gitignoreado). + +--- + ## Resumen ejecutivo del hilo (para contexto rápido) ### Datos duros confirmados por Balam diff --git a/planeacion/Correo-respuesta-Noe-2026-08-10.md b/planeacion/Correo-respuesta-Noe-2026-08-10.md new file mode 100644 index 0000000..c51a85e --- /dev/null +++ b/planeacion/Correo-respuesta-Noe-2026-08-10.md @@ -0,0 +1,56 @@ +# Correo — Respuesta a Noé/Arturo: ticket de ejemplo "como debería ser" + fecha de la prueba acompañada + +Enviado · 10-ago-2026 + +Responder a todos sobre el hilo `RV: Seguimiento: medición de consumo API de Jira y accesos` +**Para:** Noé Rocha · **CC:** Arturo Rosas; Araceli Sánchez; Pedro Ayala; Erika Chávez +**Asunto:** (el del hilo, con `RE:`) + +> ⚠️ **Agregar a Arturo y a Erika al CC:** Noé mandó su correo del 7-ago solo con Araceli y Pedro en copia, pero Arturo es quien captura y define. Erika coordina agendas. + +**Contexto:** Noé reenvió el 7-ago las respuestas de Arturo del 4-ago, más la definición de que las pruebas serán acompañadas. Las cuatro preguntas del 30-jul quedan cerradas. + +**Estrategia — versión mínima.** Solo cinco cosas: agradecer, pedir el ticket de ejemplo, proponer fecha, decir dónde termina el ejercicio y recordar Azure. Todo lo demás se resuelve en la sesión o con el molde. El ticket capturado "como debería ser" hace el trabajo que antes hacían tres párrafos de preguntas: si los conceptos no caben en ningún campo, se ve en el ejemplo. + +**Lo que se sacó del correo y ahora hay que llevar A LA SESIÓN** (ninguno se pierde, pero ya no tienen registro escrito previo): + +1. 🔴 **ACUNTIA** — que el molde no cubre si Arturo captura un caso normal. `FAC-100` trae un solo monto de 7,594.00 USD para el ticket que históricamente son 40–48 facturas. **Es el riesgo más grande de alcance y ya no está pidiéndose por escrito** → preguntarlo en la sesión, o mandar un correo aparte si quieres constancia. +2. ⚠️ **El supuesto de los tickets de `Automation for Jira`** (10 de 69, sin campos, `FAC-91` activo). Ya no queda asentado por escrito que siguen manuales, así que la carga de objetar no está de su lado. Plantearlo en la sesión. +3. **Conceptos/partidas** — se resuelve solo con el molde, pero conviene mirar el ejemplo con esto en mente antes de la sesión. +4. **PUE vs PPD** y **cuenta de servicio** — ya estaban diferidos a la sesión desde la versión anterior. + +**Alcance del ejercicio — cotización, NO prefactura.** Razones: (1) es literalmente lo que Arturo contestó el 4-ago; (2) la aprobación de Araceli está entre `En proceso de facturación` y `Facturado`, así que la prefactura pertenece *después* — Noé lo cerró como tres candados: **cotización → prefactura → aprobación humana → timbrado** ([REGISTRO #55](../bitacora/REGISTRO.md)); (3) Arturo pidió gradualismo explícito (*"para ir monitoreando la eficiencia de la IA"*); (4) una cotización se cancela sin efecto fiscal, mientras que en BIND la prefactura **no es un recurso aparte** sino un registro en `Invoices` con `UUID = null`, y los *shapes* de los POST nunca se han probado. + +**El disparo es manual en esta prueba.** No es un modo inventado para la ocasión: son las etapas del pipeline ya modelado `Draft → DryRun → Confirmed` (ADR-001) con los feature flags apagados. La versión automática es el mismo código con el flag encendido, y **depende de Azure** para correr continuo. + +> ⚠️ **Contradicción pendiente que el ticket de ejemplo resolverá solo:** el 6-jul Ara describió que **el comercial genera la cotización en BIND** y la plataforma la *convierte* a prefactura ([REGISTRO #27](../bitacora/REGISTRO.md)); el 4-ago Arturo dijo que la plataforma la *genera*; y el formulario sigue exigiendo **adjuntar la cotización**. Si ambas cosas ocurren, **quedan dos cotizaciones por ticket**. El adjunto que Arturo ponga en el ejemplo lo dirá. + +====================================================================== + +## VERSIÓN FINAL (la que Johann envía) + +Buenas tardes, espero se encuentren bien. + +Gracias por las definiciones, quedan claras y ya retomé el desarrollo, ya validé que el campo "Monto sin IVA" está creado y funcionando. + +Para aterrizar los detalles que faltan sería de ayuda que Arturo cree hoy o mañana un ticket de ejemplo capturado "como debería ser", con todos los campos llenos tal como quieren que se capture de aquí en adelante. Contra ese molde llego a la sesión con el flujo ya funcionando. + +Para la sesión, ¿les funciona el miércoles 12 o el jueves 13, a las 7:00 am? + +El ejercicio termina en la cotización en BIND. + +Sigo pendiente del acceso a Azure para publicar el ambiente. + +Quedo atento. + +Saludos. + +====================================================================== + +**Lo que la versión final deja fuera y por tanto pasa a la sesión (verbal, sin constancia escrita previa):** + +- **El destino de la cotización de prueba.** El correo ya no dice que el ejercicio genera una cotización real en BIND producción ni que se cancela al terminar. Anunciarlo al abrir la sesión, antes de ejecutar. +- **El compromiso de compartir el script antes.** Era la condición de Noé del 24-jul. Mandarlo igual por separado cuando esté listo. +- **La prefactura como paso siguiente** y los tres candados. Explicarlo en la sesión para que no esperen ver el flujo completo. +- **ACUNTIA** y **el supuesto de los tickets de `Automation for Jira`** (ver arriba). +- ✅ **El ticket de ejemplo ya tiene dueño nombrado** (Arturo). Solo falta **agregarlo al CC**: no venía en el correo de Noé del 7-ago. diff --git a/planeacion/Investigacion-API-Jira.md b/planeacion/Investigacion-API-Jira.md index 7a8e974..3b5b2fc 100644 --- a/planeacion/Investigacion-API-Jira.md +++ b/planeacion/Investigacion-API-Jira.md @@ -1,6 +1,6 @@ # Investigación de la API de Jira — qué probar exactamente -**Fecha:** 30-jul-2026 +**Fecha:** 30-jul-2026 · **Actualizado:** 10-ago-2026 **Propósito:** lista cerrada de pruebas y preguntas para habilitar la integración **Jira → cotización BIND** (estimada en ~10 h, [REGISTRO #51](../bitacora/REGISTRO.md)). Documento de trabajo interno; sirve también como briefing para el agente/chat especializado en la API de Jira. **Estado validado (30-jul):** @@ -9,7 +9,22 @@ - La búsqueda de FAC devolvió **66 tickets**. La API vigente es `GET /rest/api/3/search/jql`, con paginación por `nextPageToken`; el endpoint clásico `/rest/api/3/search` responde **410 Gone**. - Estatus confirmados: `Open`, `En proceso de facturación`, `En espera por colaborador`, `En validación nacional`, `En validación extranjera`, `Facturado` y `Cancelado`. No se observó un estatus llamado “Resuelto”. - Límites de consumo ya aclarados por Pedro (sin tope mensual; 3 límites de velocidad; telemetría solo en headers `X-RateLimit-*`). -- **Pendiente antes de escribir código productivo:** decisión de negocio sobre el estatus disparador, definición de qué request type debe observarse, fuente de monto y conceptos para la cotización, y aprobación explícita de cada prueba de escritura. + +--- + +## ⭐ Decisiones de negocio recibidas (correo del 7-ago) y su verificación por API (10-ago) + +Balam contestó las tres preguntas del 30-jul. Arturo respondió el **4-ago** (en verde sobre el correo de Noé), Noé lo reenvió el **7-ago**. Fuente: `RV_ Seguimiento_ medición de consumo API de Jira y accesos.eml`. + +| Decisión de Balam | Quién / cuándo | Verificación por API (10-ago) | +|---|---|---| +| La cotización BIND **se genera al entrar a `En proceso de facturación`** | Arturo, 4-ago | ✅ Estatus y transición `Iniciar facturación` ya inventariados (Bloque 3) | +| **Todo se tramita como facturación normal**; el caso recurrente espera a que se explore el módulo de Proyectos de BIND | Arturo, 4-ago | ⚠️ El campo `Facturación recurrente` sigue siendo **obligatorio** y se está llenando (FAC-100: `Si`, periodo `12`) | +| Se observan **todos los request types** de la bandeja de facturación, no solo `Facturación adicional` | Arturo, 4-ago | 🔴 **10 de 69 tickets no tienen request type alguno** y ninguno trae campos de facturación (ver Bloque 1) | +| Monto y conceptos van **como campos de Jira**, no del adjunto; **omitir el campo de recurrencia** | Arturo, 4-ago | ⚠️ `Monto sin IVA` ya existe y funciona; **`conceptos` no existe como campo en todo el sitio** (ver Bloque 2) | +| Las pruebas de escritura son **prueba acompañada sobre un ticket**, no proyecto `FACTEST` | Noé, 7-ago | Se descarta el sandbox en la instancia de Balam → aplica el protocolo del Bloque 6 sin excepción | + +**Lo que sigue abierto tras estas respuestas:** de dónde salen los **conceptos/partidas** de la cotización, qué hacer con los tickets sin campos estructurados, si nacional/extranjero cambia la cotización o solo el paquete de salida, **PUE vs PPD**, la fecha de la prueba acompañada y la migración a cuenta de servicio. --- @@ -59,25 +74,41 @@ GET /rest/servicedeskapi/servicedesk ``` → FAC corresponde a `serviceDeskId: 35`. -Request types disponibles: +Request types **publicados en el portal** (`GET /rest/servicedeskapi/servicedesk/35/requesttype`, `isLastPage: true`): -| requestTypeId | Nombre | -|---:|---| -| 84 | Bajas | -| 83 | Facturación adicional | -| 389 | Automatización | -| 12 | Facturación | +| requestTypeId | Nombre | Campos obligatorios | +|---:|---|---:| +| 84 | Bajas | 7 | +| 83 | Facturación adicional | 10 | +| 389 | Automatización | 1 (solo `summary`) | +| 12 | Facturación | 1 (solo `summary`) | -Contratos ya consultados: +Contratos verificados el 10-ago con `/requesttype/{id}/field`: | Request type | Hallazgo | |---|---| -| **Bajas** (`84`) | Exige Empresa origen, Summary, Cálculo de Finiquito // VoBo de Finiquito (adjunto), Nombre del Cliente, Nombre del Colaborador, Fecha de la Baja y Motivo de la Baja. | -| **Facturación adicional** (`83`) | Exige Empresa origen, Summary, Cliente Nuevo, Nombre del Cliente, cotización/CSF adjuntos, Tipo de Moneda, Días de Crédito, Periodo de Incidencias, Facturación recurrente y Periodo de recurrencia. Es el contrato más completo, pero no expone monto ni conceptos como campos estructurados. | +| **Bajas** (`84`) | Empresa origen, Summary, adjunto de Cálculo/VoBo de Finiquito, Nombre del Cliente, Nombre del Colaborador, Fecha de la Baja y Motivo de la Baja. | +| **Facturación adicional** (`83`) | Empresa origen, `MES / DESCRIPCIÓN / CLIENTE` (es el `summary`), Cliente Nuevo, Nombre del Cliente, adjunto de cotización/CSF, Tipo de Moneda, Días de Crédito, Facturación recurrente, Periodo de recurrencia y **`Monto sin IVA`**. Es el contrato más completo. ⚠️ **Cambió desde el 30-jul:** se agregó `Monto sin IVA` y desapareció `Periodo de Incidencias`. | | **Automatización** (`389`) | Solo exige Summary. | | **Facturación** (`12`) | Solo exige Summary. | -**Implicación:** la integración no debe asumir que “Facturación” (`12`) es el formulario origen de datos; `Facturación adicional` (`83`) es el candidato más completo, pero todavía no basta para crear una cotización en BIND. Falta confirmar con Balam qué request type entra en la automatización y si monto/conceptos se leerán de la cotización adjunta o se incorporarán como campos de Jira. Mantener una cotización adjunta como entrada mientras la integración genera otra en BIND puede duplicar el proceso. +### 🔴 “Todos los request types” incluye tickets sin request type + +La bandeja de FAC muestra en el filtro de la UI **6 de 6** opciones: las 4 de arriba más **`Empty`** y **`Emailed request`**. Ninguna de esas dos aparece en `servicedeskapi` porque no están publicadas en el portal. El conteo real sobre los **69 tickets** de FAC (10-ago): + +| Request type | Tickets | c/Monto | c/Moneda | c/Cliente | c/Adjunto | +|---|---:|---:|---:|---:|---:| +| 83 — Facturación adicional | 48 | **2** | 48 | 48 | 48 | +| **(sin request type)** | **10** | 0 | 0 | 0 | 3 | +| 84 — Bajas | 6 | 0 | 0 | 6 | 6 | +| 389 — Automatización | 4 | 0 | 0 | 0 | 4 | +| 12 — Facturación | 1 | 0 | 0 | 0 | 1 | + +Los **10 tickets sin request type** tienen `creator` y `reporter` = **`Automation for Jira`**: nacen de una regla de Automation desde otras bandejas (HH, SA, IN, RH), no del portal. Y **no son ruido**: `FAC-91` es uno de ellos, está vivo en `En validación nacional` y su summary es `[FACTURA COMPLETA - Staff Augmentation] Axians - Incident Manager — RH-36`. Es decir, **hay facturación real entrando por una vía que no tiene ni un solo campo estructurado** — los datos viajan codificados en el `summary` y en la `description` (ADF), más 2 adjuntos. + +`Emailed request` hoy tiene 0 tickets, pero existe en la configuración: cualquier correo a la bandeja aterriza ahí, también sin campos. + +**Implicación:** el acuerdo literal “todos los request types” significa que **~14% de los tickets no puede generar una cotización automática** con el diseño de campos estructurados. Hay dos salidas y conviene que Balam elija explícitamente: (a) acotar la automatización a los request types que sí traen campos y dejar los demás en tratamiento manual, o (b) que Automation for Jira propague los campos al crear el ticket en FAC. La opción (b) es trabajo del lado de Balam, no de la plataforma. --- @@ -104,7 +135,35 @@ GET /rest/api/3/issue/FAC-98?expand=names,renderedFields ``` → caso real de tipo Bajas: cliente Axians, colaborador, fecha y motivo de baja en campos estructurados; una evidencia adjunta; sin descripción. Los valores de texto enriquecido regresan como ADF. -Sigue pendiente una muestra deliberada de facturación nacional, extranjera, recurrente y el caso ACUNTIA (un ticket con Excel de 40–48 facturas, [REGISTRO #55](../bitacora/REGISTRO.md) punto 6). Esto debe confirmar dónde viven monto y conceptos, cómo se usa la cotización adjunta y si el supuesto contractual de un ticket → una cotización se cumple en los casos reales. +### Mapeo de campos confirmado (10-ago) + +| Campo de Jira | `fieldId` | Tipo | Valores | → BIND | +|---|---|---|---|---| +| Empresa origen | `customfield_11423` | option | `Balam`, `RegioTurk`, `Helmstone` | Emisor (multi-empresa) | +| MES / DESCRIPCIÓN / CLIENTE | `summary` | string | texto libre | Referencia / parseo de respaldo | +| Cliente Nuevo | `customfield_10052` | option | `Si`, `No` | Decide si hay que dar de alta el cliente | +| Nombre del Cliente | `customfield_10202` | **ADF** (textarea) | texto enriquecido | Match contra `Clients` de BIND | +| Tipo de Moneda | `customfield_10053` | option | `MXN`, `USD`, `OTRO` | Moneda de la cotización | +| Días de Crédito | `customfield_10054` | option | `30`, `45`, `NA` | Condiciones de pago | +| Facturación recurrente | `customfield_10552` | option | `Si`, `No` | Fuera de alcance por ahora (Arturo, 4-ago) | +| Periodo de recurrencia | `customfield_10553` | string | texto | Fuera de alcance por ahora | +| **Monto sin IVA** | **`customfield_11556`** | **number/float** | — | **Total de la cotización** | +| Approvers | `customfield_10003` | array/user | — | Gobierno (ver Bloque 3) | + +⚠️ **`Nombre del Cliente` es ADF, no string.** El match contra BIND tiene que extraer texto plano de un documento estructurado, no leer un campo de texto. Nada garantiza que el nombre escrito a mano coincida con la razón social en BIND; **el campo no trae RFC**, que sería la llave confiable. + +### 🔴 Dos huecos que el acuerdo del 4-ago no cierra + +1. **`Monto sin IVA` existe pero está prácticamente vacío.** Solo **2 de 69** tickets lo tienen: `FAC-100` y `FAC-101`, ambos creados el **4-ago** — el mismo día en que Arturo contestó el correo. El campo se agregó en ese momento; los 67 tickets anteriores lo tienen en `null`. Es buena noticia (el acuerdo ya se implementó) con dos consecuencias: no hay histórico para validar el mapeo contra facturas reales, y la obligatoriedad solo aplica al crear por portal — un ticket nacido de Automation entra con `null` igual. + +2. **`conceptos` / partidas no existe como campo en NINGUNA parte del sitio.** `GET /rest/api/3/field` filtrado por monto/concepto/partida/importe/precio/cantidad/RFC devuelve únicamente: + - `customfield_11556` — `Monto sin IVA` (en uso) + - `customfield_11522` — `Monto con IVA` (existe, **no está en el formulario 83**) + - `customfield_10031` — `Total forms` (de JSM, no es de facturación) + + Con un solo monto agregado **no se pueden armar partidas**: la cotización BIND queda de una sola línea con la descripción del `summary`. Eso puede ser aceptable como decisión, pero **hay que tomarla explícitamente**, y no cubre el caso ACUNTIA. Que exista `Monto con IVA` sin usar además abre la pregunta de si el IVA lo calcula BIND o viene dado. + +**El caso ACUNTIA ya tiene evidencia:** `FAC-100` es exactamente eso — summary `Julio/CONSULTORIA Y SERVICIOS (Eduardo Fiallo CEMEXUSA)/ACUNTIA`, `Helmstone`, `USD`, 45 días, `Monto sin IVA = 7594.00`, con 2 adjuntos. **Un solo monto para un ticket que históricamente representa 40–48 facturas** ([REGISTRO #55](../bitacora/REGISTRO.md) punto 6). El supuesto “un ticket → una cotización” necesita confirmarse contra este caso antes de codificar. > ⚠️ **ADF (Atlassian Document Format).** En Jira Cloud v3, `description` y los comentarios **no son texto plano ni wiki markup: son JSON estructurado**. Hay que decidir ya si se parsea ADF o se pide `expand=renderedFields` (HTML). Y al **escribir** comentarios/descripciones hay que **construir ADF válido**, no mandar un string. Es la trampa que más tiempo cuesta si se descubre tarde. @@ -112,9 +171,9 @@ Sigue pendiente una muestra deliberada de facturación nacional, extranjera, rec --- -## Bloque 3 — Workflow, estatus y transiciones (el disparador) 🟡 +## Bloque 3 — Workflow, estatus y transiciones (el disparador) ✅🟡 -La **regla de negocio** (qué estatus dispara qué) sigue bloqueada por la definición interna de Balam. Pero el **inventario técnico se puede levantar hoy** y es justo lo que hace que esa sesión dure 20 minutos en vez de una hora: llegar con la lista real de estatus en pantalla. +**Disparador confirmado por Arturo el 4-ago: la cotización BIND se crea al entrar a `En proceso de facturación`.** El inventario técnico ya estaba levantado, así que la regla de negocio queda cerrada. **Inventario confirmado:** ``` @@ -156,13 +215,36 @@ En validación nacional o extranjera --[Facturación completa]--> Facturado En validación nacional o extranjera --[Rechazar actividad]--> En proceso de facturación ``` -El diagrama también contempla cancelación desde los estados de trabajo y reapertura; la API confirmó al menos `Cancelado --[Reabrir Ticket]--> Open` en FAC-89. **No existe un estado “Resuelto” en el workflow.** El diagrama describe el movimiento del ticket, pero no establece en qué transición se debe crear la cotización BIND. Esa regla debe ser confirmada por Balam: la candidata natural es la entrada a `En proceso de facturación` mediante `Iniciar facturación`; `Facturado` es la confirmación final de que la factura se emitió. +El diagrama también contempla cancelación desde los estados de trabajo y reapertura; la API confirmó al menos `Cancelado --[Reabrir Ticket]--> Open` en FAC-89. **No existe un estado “Resuelto” en el workflow.** Con la respuesta del 4-ago, la regla queda: **`Iniciar facturación` (Open → En proceso de facturación) dispara la cotización**; `Facturado` confirma que la factura se emitió. -⚠️ **Dos trampas conocidas:** -1. **`Facturado` como estatus ≠ campo `resolution`.** En Jira son cosas distintas: un ticket puede estar en Facturado con `resolution: null`, o cerrarse con `resolution: Done`. Hay que confirmar cuál de los dos es la señal confiable de “esta factura sí se emitió”, aunque el workflow muestra que `Facturado` es la salida de `Facturación completa`. +### 🔴 Hallazgo crítico: el estatus disparador dura minutos, no horas + +Recorrido real de `FAC-100` (4–5 ago), desde su changelog: + +| Hora | Transición | Autor | +|---|---|---| +| 05-ago 11:51:25 | `Open` → **`En proceso de facturación`** | Arturo Rosas | +| 05-ago 11:54:09 | → `En validación extranjera` | Arturo Rosas | +| 05-ago 12:16:37 | → `Facturado` | **Araceli Sánchez** | + +**El ticket estuvo 2 minutos 44 segundos en el estatus disparador**, y 25 minutos de punta a punta. Hoy solo **1 de los 69 tickets** está parado en `En proceso de facturación` (65 ya están `Facturado`). + +**Consecuencia de diseño, no negociable:** un poller de 15 min que pregunte *“¿qué tickets están hoy en `En proceso de facturación`?”* **se pierde la mayoría de los disparos**. La detección **tiene que leer el changelog** y buscar el *cruce* de estado dentro de la ventana, exactamente como se resolvió la detección de pagos en BIND (ADR-004). Esto confirma y vuelve obligatorio lo que antes era una preferencia de arquitectura, y refuerza el caso de los webhooks (Bloque 4) para reducir la latencia. + +### ⭐ Hallazgo nuevo: el workflow tiene aprobaciones de JSM + +Ni FAC-98 ni el diagrama lo mostraban. Tanto `FAC-100` como `FAC-91` traen: +- `customfield_10003` **Approvers** = `Araceli Sánchez` +- `customfield_10025` **Approvals** = el estatus donde vive la aprobación (`En validación extranjera` / `En validación nacional`) + +Es decir, **el paso a `Facturado` pasa por una aprobación formal de Araceli**, no por una transición simple. Implicaciones: (1) la plataforma **no debe intentar aprobar** — eso es decisión humana; (2) si algún día tuviera que transicionar a `Facturado`, la vía correcta es `/rest/servicedeskapi/request/{id}/approval`, no `/transitions`; (3) la aprobación es un buen punto de trazabilidad para saber quién autorizó cada factura. + +⚠️ **Trampas:** +1. ~~**`Facturado` como estatus ≠ campo `resolution`.**~~ **Resuelto (10-ago):** en `FAC-100`, `status = Facturado` **y** `resolution = Done` **y** `resolutiondate` poblada, todo consistente. Ambas señales sirven; se usará el cruce de estatus en el changelog por coherencia con el resto del diseño. 2. **Las transiciones son contextuales**: `/transitions` solo devuelve las salidas del estado actual, y pueden tener **pantallas con campos obligatorios**. Probar con `expand=transitions.fields` para saber si transicionar por API exige llenar algo. +3. **`issuetype` de FAC es `admon`**, no “Service Request”. Cualquier JQL o creación por API debe usar ese nombre. -**Changelog = la fuente de la detección.** `expand=changelog` da cada cambio de estatus con timestamp y autor. Es el equivalente en Jira del enfoque ya usado con BIND para detectar pagos por transición (ADR-004): la plataforma detecta el cruce de estado, no lo infiere del estado actual. Verificar que el changelog venga completo o si pagina (`/rest/api/3/issue/{key}/changelog`). +**Changelog = la fuente de la detección.** `expand=changelog` da cada cambio de estatus con timestamp y autor. Verificado en FAC-100 (`total: 6`) y FAC-91 (`total: 8`): vienen completos y sin paginar en tickets de este tamaño. Para tickets con mucho historial hay que usar `/rest/api/3/issue/{key}/changelog`, que sí pagina. --- @@ -191,7 +273,16 @@ Validar también: `fields=` para pedir solo lo necesario (menos payload, menos p **Recomendación:** **arrancar con polling** y dejar el webhook para después. Ningún webhook sirve hasta que exista un endpoint público, y Azure sigue pendiente del lado de Balam. El polling además es reversible y no depende de que Pedro toque su instancia. -**c) Rate limits.** Ya documentados por Pedro. Lo que falta es **verificar en la práctica** que los headers `X-RateLimit-Limit` / `Remaining` / `NearLimit` efectivamente vienen en las respuestas (no todos los endpoints los emiten) y capturar un 429 real si se puede, para confirmar `Retry-After` y `RateLimit-Reason`. +**c) Rate limits — headers verificados ✅ (10-ago).** La respuesta de `/rest/api/3/search/jql` sí los emite: + +```text +X-RateLimit-Limit: 350 +X-RateLimit-Remaining: 348 +RateLimit-Policy: "jira-burst-based";q=100;w=1 +RateLimit: "jira-burst-based";r=348;t=1 +``` + +Tres notas: (1) la telemetría existe y el autorregulado por headers es viable, como se le dijo a Erika el 29-jul; (2) el límite observado es **350**, no los 100/s que mencionó Pedro — hay que leer el header y no hardcodear el número; (3) aparecen también los headers estándar `RateLimit-*` (RFC) además de los `X-RateLimit-*`, así que el cliente debe tolerar ambos. `X-RateLimit-NearLimit` no apareció porque no se llegó al 20% del umbral. No se provocó un 429 deliberadamente contra producción. --- @@ -206,15 +297,28 @@ Pedro dijo que procesos que **se cierran en RH o Administración General caen en | **Subtarea / hijo** | `parent` / `subtasks` | Relevante para ACUNTIA (1 ticket ↔ 40 facturas) | | **Move entre proyectos** | `changelog` con cambio del campo `project` | 🔴 **La llave del ticket CAMBIA** (RH-45 → FAC-89). Cualquier folio persistido se rompe | -**Prueba:** tomar 5–10 tickets FAC recientes con `expand=changelog` y clasificar cómo llegaron ahí. Si aparecen moves, **hay que persistir el `id` numérico del issue (inmutable), no solo la llave `FAC-nnn`** — decisión de modelo de datos que conviene tomar antes de escribir la entidad. +**Resultado de la prueba (10-ago): es creación por Automation, no move. ✅** -**Pregunta ligada, ya identificada el 27-jul:** ¿basta escuchar FAC o hay que rastrear también el origen en RH/AG? +Los 10 tickets sin request type tienen `creator` = `reporter` = **`Automation for Jira`**, y sus changelogs (revisados en FAC-91) **no muestran cambios de `project` ni de `key`**. El patrón es: la regla de Automation **crea** un ticket nuevo en FAC y lo **liga** al original con `issuelinks`. Ejemplos de summary, que llevan el origen embebido: + +```text +FAC-91 [FACTURA COMPLETA - Staff Augmentation] Axians - Incident Manager — RH-36 +FAC-1 Seguimiento del Ticket Cerrado: HH-1 - Prueba #1 +FAC-28 Seguimiento del Ticket con pago anticipado: HH-8 - TLE +``` + +Se ven tres bandejas de origen: **HH** (headhunting), **SA** (staff augmentation), **IN**, y **RH**. Dos patrones de regla: `Seguimiento del Ticket Cerrado:` y `Seguimiento del Ticket con pago anticipado:` — el segundo probablemente implique PUE y toca la pregunta pendiente de PUE/PPD. + +**Conclusiones para el modelo de datos:** +- **Escuchar FAC basta** para detectar el disparo; el origen se obtiene de `issuelinks` sin salir del proyecto. +- No hay evidencia de moves, así que la llave `FAC-nnn` **parece** estable. Aun así conviene **persistir el `issue.id` numérico** (FAC-100 = `17308`, FAC-91 = `14348`): es inmutable por diseño y el costo de guardarlo es cero. +- ⚠️ Estos tickets son la vía sin campos estructurados del Bloque 1. Si la automatización debe cubrirlos, **la regla de Automation de Balam tendría que propagar los campos** al crear el ticket en FAC. --- ## Bloque 6 — Escritura (CRUD): qué probar, cómo aprobarlo y dónde 🔴 -Noe autorizó una prueba de creación **en vivo y acompañada**. La recomendación es conservar esa condición: el sitio es producción y el token efectivo tiene permisos para crear, editar, transicionar, comentar, adjuntar e incluso borrar tickets en FAC. +**Confirmado por Noé el 7-ago: prueba acompañada sobre un ticket acordado. No habrá proyecto `FACTEST`.** Eso cierra la pregunta pero **deja el riesgo intacto**: se escribirá en producción, y el token tiene permisos para crear, editar, transicionar, comentar, adjuntar e incluso borrar tickets en FAC. El protocolo de abajo pasa de recomendación a requisito, y el sandbox propio (ver recuadro al final del bloque) pasa de opcional a necesario para desarrollar sin tocar Balam. **Protocolo obligatorio para cualquier prueba de escritura:** 1. Preparar un script idempotente y de una sola operación; sin bucles, sin búsquedas masivas y sin credenciales embebidas. @@ -234,19 +338,19 @@ Noe autorizó una prueba de creación **en vivo y acompañada**. La recomendaci 5. **Editar** — `PUT /rest/api/3/issue/{key}`. 6. **Borrar** — `DELETE /rest/api/3/issue/{key}`. Requiere permiso de admin de proyecto. **Probablemente ni se tenga ni convenga tenerlo**; en producción el borrado no debe ser una capacidad de la plataforma. -> 🔴 **Dónde probar — la recomendación más importante de este documento.** -> La instancia de Pedro es **producción**, igual que BIND, y ya se pagó el costo de esa restricción una vez. Dos salidas, no excluyentes: -> 1. **Pedir a Pedro un proyecto de pruebas** (p. ej. `FACTEST`) que replique el workflow de FAC. Barato para él, elimina el riesgo. -> 2. **Crear un sitio propio y gratuito de Jira Cloud** (plan Free, hasta 10 usuarios) con un proyecto JSM. Sirve para desarrollar el cliente, el parser de ADF, la paginación y las transiciones **sin tocar nada de Balam** ni depender de que respondan. Es el sandbox que BIND nunca tuvo. Contra producción solo se corre lectura y, al final, la prueba acompañada. +> 🔴 **Dónde probar.** +> ~~Pedir a Pedro un proyecto de pruebas `FACTEST`~~ → **descartado por Noé el 7-ago:** será prueba acompañada sobre un ticket. Queda entonces una sola vía de mitigación: > -> Esta segunda opción sigue siendo útil para desarrollar el cliente y probar ADF sin tocar datos de Balam. El 401 ya está resuelto, pero el riesgo de escribir en producción permanece. +> **Crear un sitio propio y gratuito de Jira Cloud** (plan Free, hasta 10 usuarios) con un proyecto JSM que replique el workflow de FAC. Sirve para desarrollar el cliente, el parser de ADF, la paginación, las aprobaciones y las transiciones **sin tocar nada de Balam** ni depender de que respondan. Es el sandbox que BIND nunca tuvo. Contra producción solo se corre lectura y, al final, la única prueba acompañada. +> +> Con el `FACTEST` descartado, esto ya no es una alternativa: es el único lugar donde se puede equivocar sin costo. --- ## Bloque 7 — Gobierno y seguridad 🟡 -- 🔴 **`propuesta/token-jira.txt` NO está en `.gitignore`** (aparece como no rastreado, no como ignorado): un `git add .` lo commitea al historial. Agregarlo al `.gitignore` y mover el token a user-secrets / Key Vault. Mismo pendiente que arrastra `bind_token_api.txt`. -- **Cuenta de servicio vs cuenta personal de Pedro** (ya planteado en el borrador de correo del 29-jul): hoy todo lo que la plataforma escriba en Jira queda firmado con el nombre de Pedro, y una rotación suya deja la integración muerta. Verificar con `GET /rest/api/3/myself` con qué identidad se está actuando. +- ✅ ~~**`propuesta/token-jira.txt` NO está en `.gitignore`**~~ → **Resuelto:** ignorado en [`.gitignore:9`](../.gitignore). Sigue pendiente mover el token a user-secrets / Key Vault y borrarlo de disco. Mismo pendiente que arrastra `bind_token_api.txt`. +- **Cuenta de servicio vs cuenta personal de Pedro** (ya planteado en el borrador de correo del 29-jul): hoy todo lo que la plataforma escriba en Jira queda firmado con el nombre de Pedro, y una rotación suya deja la integración muerta. Verificar con `GET /rest/api/3/myself` con qué identidad se está actuando. **Sin respuesta al 10-ago.** - 🔴 **Alcance de permisos:** validado con `GET /rest/api/3/mypermissions` para FAC. El token puede navegar, crear, editar, transicionar, comentar, adjuntar y borrar tickets. Es un alcance excesivo para producción; la integración no debe implementar borrado y conviene migrar a una cuenta de servicio con permisos mínimos. - **Vigencia 27-jul-2027** → dejar registrado el vencimiento y el plan de rotación desde ahora. - **Datos de clientes en adjuntos y descripciones** — misma regla que BIND: nunca a disco del repo ni a documentos compartidos. @@ -255,14 +359,22 @@ Noe autorizó una prueba de creación **en vivo y acompañada**. La recomendaci ## Bloque 8 — Preguntas para Pedro / Balam (no se resuelven con la API) -Estas van por correo o en la siguiente sesión; ninguna se contesta probando: +**Cerradas con el correo del 7-ago:** -1. **¿Puede crear un proyecto de pruebas `FACTEST`** con el mismo workflow de FAC? -2. **¿Quién puede crear webhooks o reglas de Automation** apuntando a una URL nuestra, y bajo qué proceso? -3. **¿Debe observarse/automatizarse `Facturación adicional` (83), `Facturación` (12) u otro request type?** El 83 contiene campos estructurados útiles; el 12 solo exige Summary. -4. **¿Cuál estatus dispara la cotización y cuál confirma la factura?** Los nombres reales y las transiciones de salida ya se conocen, pero la regla de negocio no. -5. **¿De dónde deben obtenerse monto y conceptos?** No existen como campos estructurados en el request type 83; definir si se extraen del adjunto o se agregan a Jira. -6. **PUE vs PPD** — la pregunta que no se ha alcanzado a hacer en tres sesiones ([REGISTRO #52](../bitacora/REGISTRO.md)). +1. ~~**¿Puede crear un proyecto de pruebas `FACTEST`?**~~ → **No.** Prueba acompañada sobre un ticket (Noé, 7-ago). +2. ~~**¿Debe observarse `Facturación adicional` (83), `Facturación` (12) u otro?**~~ → **Todos los request types** de la bandeja (Arturo, 4-ago). ⚠️ Con la salvedad del Bloque 1: 10 tickets no tienen request type ni campos. +3. ~~**¿Cuál estatus dispara la cotización?**~~ → **`En proceso de facturación`** (Arturo, 4-ago). +4. ~~**¿Monto del adjunto o como campo?**~~ → **Campo de Jira.** Ya implementado (`customfield_11556`), omitiendo recurrencia (Arturo, 4-ago). + +**Abiertas:** + +5. 🔴 **¿De dónde salen los CONCEPTOS/partidas?** El acuerdo resolvió el monto pero no los conceptos, y **no existe campo para ellos en el sitio**. ¿Cotización de una sola línea con el `summary` como descripción, o se agrega un campo? +6. 🔴 **¿Qué pasa con los tickets creados por Automation for Jira** (10 de 69, sin ningún campo estructurado, incluido `FAC-91` que está vivo)? ¿Se acota la automatización o la regla de Automation propaga los campos? +7. 🔴 **ACUNTIA / `FAC-100`:** ¿un ticket con `Monto sin IVA` único debe generar **una** cotización, o sigue siendo el caso de 40–48 facturas? +8. **¿Nacional vs extranjero cambia la cotización** o solo el paquete de salida (PDF+XML vs PDF)? Hay dos estatus de validación distintos y una aprobación por cada rama. +9. **¿Quién puede crear webhooks o reglas de Automation** apuntando a una URL nuestra, y bajo qué proceso? Gana urgencia: el estatus disparador dura minutos (Bloque 3). +10. **PUE vs PPD** — la pregunta que no se ha alcanzado a hacer en cuatro sesiones ([REGISTRO #52](../bitacora/REGISTRO.md)). Los tickets `Seguimiento del Ticket con pago anticipado:` sugieren que sí hay casos PUE reales. +11. **Cuenta de servicio** en lugar de la cuenta personal de Pedro, y fecha para la prueba acompañada. --- @@ -270,14 +382,17 @@ Estas van por correo o en la siguiente sesión; ninguna se contesta probando: | # | Acción | Bloqueado por | |---|---|---| -| 1 | Blindar el token (`.gitignore` + secrets) | — | -| 2 | Completar la muestra de tickets y el mapeo a BIND | Definición del caso de negocio | +| 1 | ✅ Blindar el token (`.gitignore`) — falta secrets/Key Vault | — | +| 2 | ✅ Mapeo de campos y contratos de request type verificados (10-ago) | — | | 3 | Implementar lectura con `/search/jql`, cursor y ventana de solape | — | -| 4 | Preparar y compartir el script de escritura mínimo para revisión | Definición de flujo de Balam | -| 5 | Levantar un sandbox Jira propio o `FACTEST` | Apoyo de Pedro si se usa FACTEST | -| 6 | Ejecutar una única prueba de escritura acompañada | Aprobación, script revisado y ticket de prueba | +| 4 | **Detección por changelog del cruce a `En proceso de facturación`** | — (ya desbloqueado por el acuerdo del 4-ago) | +| 5 | Parser de ADF para `Nombre del Cliente` + match contra `Clients` de BIND | ⚠️ Sin RFC; definir tolerancia del match | +| 6 | Armado de la cotización BIND | 🔴 Definición de conceptos/partidas (pregunta 5) | +| 7 | Levantar un sandbox Jira propio (plan Free) | — (ya no depende de Balam) | +| 8 | Preparar y compartir el script de escritura mínimo para revisión | — | +| 9 | Ejecutar una única prueba de escritura acompañada | Fecha de Balam + script revisado + ticket acordado | -**Lo que puede avanzar ya:** el cliente de lectura, manejo de ADF, paginación por cursor, mapeo de campos y detección incremental. La escritura queda deliberadamente fuera del flujo automático hasta que haya sandbox o una sesión de validación acompañada. +**Lo que puede avanzar ya:** el cliente de lectura, manejo de ADF, paginación por cursor, mapeo de campos, detección incremental por changelog y el sandbox propio. **Lo único que sigue bloqueado es el armado final de la cotización**, por la definición de conceptos. La escritura queda fuera del flujo automático hasta la sesión acompañada. --- @@ -287,6 +402,10 @@ Estas van por correo o en la siguiente sesión; ninguna se contesta probando: > > Para la capa de lectura, usar `GET /rest/api/3/search/jql`, paginar por `nextPageToken` y aplicar una ventana de solape al checkpoint de `updated`. No usar `/rest/api/3/search`: responde 410. > -> Para JSM, usar `/rest/servicedeskapi` al consultar request types y su contrato de campos. FAC tiene los request types Bajas (84), Facturación adicional (83), Automatización (389) y Facturación (12). Bajas y Facturación adicional ya tienen su contrato verificado; el segundo incluye cliente, moneda, crédito, periodo y recurrencia, pero no monto ni conceptos estructurados. +> Para JSM, usar `/rest/servicedeskapi` al consultar request types y su contrato de campos. FAC publica 4 request types: Bajas (84), Facturación adicional (83), Automatización (389) y Facturación (12); los cuatro contratos están verificados. **Facturación adicional (83) es el único con datos de facturación** e incluye `Monto sin IVA` (`customfield_11556`, number). **No existe campo de conceptos/partidas en el sitio.** > -> Pendientes técnicos: revisar changelog y origen de tickets; muestrear tickets nacionales, extranjeros y recurrentes; y diseñar un script de escritura de una sola operación para revisión previa. El script debe ser idempotente, no incluir credenciales y ejecutarse únicamente en sandbox o acompañado en un ticket de prueba acordado. +> **El disparador acordado es el cruce a `En proceso de facturación`, y dura minutos** (FAC-100: 2m44s). La detección debe leer el changelog y buscar el cruce dentro de la ventana; consultar el estatus actual no sirve. El `issuetype` es `admon`. El workflow tiene **aprobaciones de JSM** con Araceli como aprobadora en las ramas de validación nacional/extranjera: la plataforma nunca aprueba. +> +> **10 de 69 tickets nacen de `Automation for Jira`** desde HH/SA/IN/RH, sin request type y sin ningún campo estructurado; los datos van en el `summary` y la `description` (ADF), con el origen en `issuelinks`. Persistir el `issue.id` numérico además de la llave. +> +> Pendientes técnicos: parser de ADF para `Nombre del Cliente` (no trae RFC), armado de la cotización cuando se defina el tema de conceptos, y diseñar un script de escritura de una sola operación para revisión previa. El script debe ser idempotente, no incluir credenciales y ejecutarse únicamente en el sandbox propio o acompañado en el ticket de prueba acordado. **No habrá `FACTEST`.**