Skip to content

Antes de mandar el sign-off y el mail a Sean (interno) ​

Date: 2026-10-06 (actualizado el 2026-10-05 con las decisiones de Carlos de ese día) Uso interno: este archivo no se manda a Soterex. Es lo que tiene que estar hecho, y lo que hay que revisar, antes de enviar 2026-10-06-c2p-sign-off (en inglés, va a Soterex y solo lleva lo que Soterex tiene que ver) y el borrador 2026-10-06-mail-sean-sandbox-alineado. Antes esto vivía como un bloque dentro del propio sign-off; se sacó porque el documento que se manda no puede llevar datos de infraestructura ni del PR.

Qué se manda ​

PiezaArchivoEstado
El mail2026-10-06-mail-sean-sandbox-alineado.md (cuerpo en inglés)Borrador. No está enviado ni guardado en ningún sistema de mail
El sign-off2026-10-06-c2p-sign-off.mdListo, con un solo placeholder: [CONTACTO CIS] (sección 7, dos lugares)
El OpenAPIcis-latam-soterex-c2p-openapi-v2.yamlListo. Es idéntico a doc/site/public/openapi.yaml (se compara con cmp) y pasa redocly lint (su única advertencia es que no declara licencia)
La collection de Postmancis-latam-soterex-c2p-sandbox.postman_collection.jsonLista. Con el backend final (tarifario de 50 USD, replay con el estado real), en un stack local, corrió con newman: 35 requests, 59 aserciones, 0 fallas. client_secret y webhook_secret van con un <PLACEHOLDER …>

Qué tiene que estar hecho antes de mandarlo ​

Lo que dicen el mail y el sign-off es verdad solo si esto está hecho. Si algo falta, prometen de más.

  1. Completar [CONTACTO CIS] en el sign-off (sección 7: el contacto técnico de CIS y el de soporte y escalamiento de producción, en dos lugares cada uno). Es el único dato que el sign-off no puede completar solo.
  2. El PR #80 mergeado y desplegado en Staging, con las migraciones corridas. El PR trae K1 a K8 (la API alineada, las notificaciones, la firma, el vencimiento, los disparos del sandbox, el tarifario y su pantalla), una ronda de correcciones de una revisión independiente y una última ronda del panel de revisión (ver ADR-017, apéndice). Si Sean prueba contra Staging sin el deploy, ve dos contratos.
  3. El scheduler de Staging NO se prende por ahora (decisión tuya del 2026-10-05) y no hace falta para mandar el mail. Todavía no tenés la URL ni el secret de Soterex y la integración sigue en mock. En pausa hasta que Soterex mande esos datos: el php artisan c2p:expire --dry-run, el enabled = true de module "scheduler" (infra/terraform/environments/staging/main.tf, con terraform plan y apply tuyos) y la carga de la URL y el secret (pasos y qué mirar en staging.md). El mail y el sign-off ya dicen la verdad de ese estado: que el job de entrega y el de vencimiento del sandbox no están corriendo, que las notificaciones esperan en una cola y no se manda nada hasta tener su URL y su secret, que sandbox/notify encola pero no entrega y puede topar a los 50 pendientes (2208), y que una transacción vencida no se puede pagar pero no se cancela sola. El mail no promete notificaciones reales. Si antes de mandar prendés el scheduler o pasás a Real, esos textos (mail punto 4 y «Expiry»; sign-off «Honest scope», 1.9, 2.5, 2.6, 5 y 8) quedan desactualizados: reescribilos. Detalle de qué implica tenerlo apagado en staging.md.
  4. Correr contra Staging, con el client_id real, un token, un SendRequest y un Cancel con curl, y comparar las respuestas con las secciones 1.4, 1.5 y 2.2 del sign-off (incluido el replay de una transacción cancelada: COD_009 con dtc_estatusCANCELLED, y el fee de 50.00). Todo lo que dice el sign-off sale de leer el código y de las verificaciones del PR contra un stack local descartable, no de una corrida contra Staging. También conviene probar un POST /api/c2p/v1/sandbox/notify (en Staging existe; en producción no).
  5. El secret del cliente OAuth no viaja en el mail. El sign-off (2.1), el OpenAPI y la collection dicen que va por un canal seguro aparte. Por defecto el mail dice "client_secret: unchanged, as sent to you through the secure channel on 2026-10-04" (según doc/environments/production.md, Sean ya lo tiene). Solo si hubo rotación se usa el placeholder [CLIENT_SECRET], y el valor se manda por el canal acordado, nunca en el cuerpo.
  6. Staging queda en modo mock y con el scheduler apagado hasta que Sean mande la URL de Notifications y el secret del HMAC (el mail lo dice). Cuando los manden (paso en pausa, no de ahora): revisar la cola de notificaciones PENDING (se entrega lo acumulado, también las pruebas viejas: con el modo en mock se dan por entregadas sin mandarse, con el modo Real salen a su URL), cargar el secret, después la URL (https://, sin usuario, parámetros ni fragmento), pasar a Real, prender el scheduler y avisarle a Sean (el mail le prometió avisarle). Ver staging.md y el manual de Configuración. En producción el mock no existe.
  7. No se piden IPs (D10). El sign-off dice que CIS no exige allowlist y que la IP de salida de producción se informa cuando se provisione (un NAT Gateway por zona de disponibilidad, un conjunto chico de IPs fijas). Producción todavía no está provisionada.
  8. Adjuntos: el sign-off (como .md o exportado a PDF), el OpenAPI y la collection. Comprobar con cmp que los dos OpenAPI siguen idénticos si se tocó alguno.

Lo que el sign-off no puede afirmar ​

El sign-off marca cada ítem como Confirmed, Ready in sandbox, Needs Soterex o Pending CIS. Nada se probó contra un Soterex real (no hay endpoint de ellos todavía): las notificaciones entregadas y acusadas, la verificación de la firma de su lado, la firma mala rechazada y el duplicado aceptado dependen de su URL y de su secret, y figuran como Needs Soterex. Lo marcado Ready in sandbox se verificó contra un receptor local que se comporta como describe su especificación (verifica la firma, la tolerancia de 300 s y el cuerpo por estado).

Además, dos jobs programados del sandbox no están corriendo (la entrega de notificaciones y el vencimiento): el sign-off lo dice en el «Honest scope» y en las secciones 1.9, 2.5, 2.6 y 5, y por eso el estado Needs Soterex de «Timeout and retry» y la nota en «On-demand triggers».

Quedan abiertos con Soterex, sin bloquear: la URL y el secret del HMAC con su key_id, las plantillas del reporte de pagos del día siguiente y del estado de cuenta, la vigencia del MTCN (60 días en Guatemala, tomados de la carta de Soterex), que el RS- no se repita en entityResponse.transaction_id (D4), y un contacto de soporte y escalamiento del lado de ellos.

Decisiones de Carlos (2026-10-05) y lo que sigue sin decidir ​

Decidido, y ya reflejado en el sign-off, el mail, el OpenAPI y la collection:

  • El mismo client_secret en sandbox y producción: se mantiene el mismo (decisión del 2026-10-04, reafirmada el 2026-10-05; riesgo aceptado). La especificación de Soterex pide credenciales separadas por ambiente. El sign-off (3.1) dice lo que es: distinto client_id y host, el mismo secret; el OpenAPI y la collection ya no dicen «credenciales separadas», dicen «client_id distinto».
  • El replay de una transacción ya pagada o cancelada devuelve el estado real (dtc_estatus PAID o CANCELLED; status sigue ACCEPTED). Sign-off 1.4 y 2.3, OpenAPI (idempotencia, tabla y ejemplos) y collection (un request nuevo: el replay de la cancelada). Antes devolvía el alta original con ACCEPTED.
  • El tarifario: 50 USD fijos por transacción, para cualquier monto, también en producción, y editable por país en Parámetros → Comisiones. Teresa carga la tabla real cuando la defina; ya no es un requisito para abrir producción. El sign-off lo dice (1.1, 3.3, 5): producción abre con el provisional, no es el tarifario definitivo, y con montos menores a 50 USD la comisión supera al principal (no se rechaza). El ejemplo 500.00 → 5.00 de la especificación ya no sale del tarifario: ahora da 50.00, y todos los ejemplos de montos y de payloads (incluido el vector de prueba de la firma, recalculado con las cuatro herramientas) lo reflejan.
  • El scheduler no se prende por ahora, ni se carga la URL y el secret, ni se pasa a Real: todo en pausa hasta que Soterex mande los datos (punto 3 de arriba).
  • Los riesgos que se dejan como están (trustProxies, APP_DEBUG en Staging, la URL guardada sin revalidar, la conciliación de notificaciones perdidas para el go-live): ver «Riesgos y decisiones de Carlos» en ADR-017.

Sin decidir (el sign-off no lo promete, para no comprometerte):

  • Avisar a Soterex antes de reemplazar el provisional por la tabla de Tesorería. El fee que ven en cada respuesta cambia, y entra en el total que ellos guardan («principal más comisión»). El sign-off solo dice que «CIS Treasury's definitive schedule replaces it when it is defined». Si querés comprometer un aviso previo (como el de 30 días para certificados o endpoints), agregalo en 1.1 y en 4.

Las cinco consultas de los ajustes v3 (aparte) ​

No son parte de este paquete. Salen del plan de ajustes v3 del cliente GT (D3-22, §6.2): prefondeo por API, el prefijo «C-» del MTCN, el RS-, cómo modifica Soterex una transacción ya enviada y la lista de países. Son solo consulta y no bloquean nada de lo de arriba. El borrador está en 2026-10-07-borrador-preguntas-a-soterex-ajustes-v3, con lo que hay que decidir antes de mandarlo. Por defecto van en un mail aparte, después de este, porque citan secciones del sign-off (1.2, 1.3, 1.4 y 8); el borrador explica cómo pegarlas en el mail del 6/10 si preferís mandar todo junto.

Lo que no va en el sign-off ni en el mail ​

Los riesgos que dejó el plan, que son internos (trustProxies sin configurar, APP_DEBUG fuera de producción, notificaciones perdidas si el proceso muere entre el commit y el encolado, la URL guardada antes de la validación, el mismo client_secret en los dos ambientes, la infraestructura de usuario y contraseña sin consumidor y el scheduler sin aplicar), están en la sección «Riesgos y decisiones de Carlos (2026-10-05)» de ADR-017, con lo que decidiste de cada uno y qué implica tener el scheduler apagado.

Documentación viva — se actualiza junto con el código, no es un anexo aparte.