Prompt de ejecución — API C2P entrante para Soterex
Date: 2026-09-30 Uso: copiar el bloque de abajo como primer mensaje de una sesión nueva de Claude Code en este repo. Ejecuta doc/plans/2026-09-30-api-c2p-entrante-soterex.md.
Sos el product owner de este proyecto (Soterex / CIS Latam) y ejecutás de punta a punta un plan ya
decidido. Activá el skill `product-owner` y coordiná con los agentes y skills que necesites:
`architect` (ADR-012), `backend-dev` (casi todo), `security` (OAuth, secrets, tokens:
es obligatorio que revise C2 y C3), `frontend-dev`/`ui-engineer` (pantalla de Configuración), `tech-writer` (análisis funcional, openapi y el documento para Soterex) y
`code-reviewer` antes de cada push.
## Paso 0 — Branch (antes que nada)
git fetch origin feature/api-c2p-entrante
git checkout feature/api-c2p-entrante
git pull origin feature/api-c2p-entrante
TODO el trabajo va en ese branch. No crees otros. Si `main` avanza, traelo con
`git merge origin/main`; nada de rebase ni force-push.
## Contexto
Leé `CLAUDE.md` y respetalo: el stack está cerrado, las decisiones de arquitectura van en ADR, y el
estilo es español rioplatense con comentarios que explican el porqué.
Después leé el plan entero: `doc/plans/2026-09-30-api-c2p-entrante-soterex.md`. Es tu fuente de
verdad. Lo esencial: Soterex (desde Salesforce) nos pidió credenciales OAuth 2.0 Client
Credentials para llamar a NUESTRAS APIs SendRequest y Cancel. La documentación funcional tenía la
integración al revés (la WebApp llamando a Soterex por cron). El plan corrige el modelo, fija las
decisiones D1–D18 y define las entregas C1 a C5.
## Vas a trabajar solo: Carlos está durmiendo
- **No esperes respuestas ni hagas preguntas bloqueantes.** Las decisiones de D1–D18 ya están
tomadas; no las reabras.
- Si aparece algo que el plan no cubre, **elegí la opción más conservadora y reversible**
(priorizando seguridad y no romper lo que ya funciona), aplicala, y anotala en una sección
**"Decisiones que tomé sin Carlos"** del PR y del documento final, con el porqué. Solo frená un
tema si seguir implicaría una operación prohibida (abajo); en ese caso dejalo documentado y
seguí con lo demás.
- Trabajá hasta terminar C1–C5, en orden.
**Autorizado sin preguntar:** implementar, correr tests, commitear, pushear a
`feature/api-c2p-entrante` y abrir o actualizar UN PR contra `main` con `gh pr create` / `gh pr
edit`. Si `gh` no está, usá las herramientas de GitHub disponibles.
**Prohibido (lo hace Carlos a la mañana):**
- mergear a `main`;
- cualquier push, merge o deploy a `staging` o `production`;
- correr workflows contra AWS (`run-artisan-command`, `terraform-*`) o crear el cliente OAuth real;
- tocar Terraform aplicado;
- operaciones destructivas (force-push, reset --hard, `migrate:fresh` fuera de tu entorno local);
- escribir un secret real, un token o una credencial en el repo, en un log, en el PR o en el chat.
## Cómo trabajar cada entrega (C1 a C5)
1. Releé la sección de la entrega y armá la lista de tareas.
2. Implementá. Los tests van en el mismo commit que el código, con prefijo en el mensaje (por
ejemplo, `feat(api): C2 — endpoint OAuth client credentials`).
3. Corré y **pegá la salida real** en el resumen:
- Backend: `docker exec soterex-backend-1 php artisan test` y `vendor/bin/pint --test`. Si
Docker no está, levantá el stack con `./start-dev.sh` o corré los tests con Postgres local,
según `doc/environments/dev.md`.
- Frontend: `npm run test` y `npm run build`.
4. `code-reviewer` sobre el diff; en C2 y C3, además, `security`. Corregí lo que marquen o
explicá por qué no.
5. Push. Después de C1, abrí el PR y actualizá la descripción con cada entrega.
## Reglas que no se negocian
- **El secret nunca se imprime en un entorno remoto ni queda en logs** (D8). En staging solo viaja
el hash, en base64. `api-client:list` no muestra secrets ni hashes.
- **Auth de máquina separada de la de humanos.** Firebase sigue siendo el auth de la app; el
middleware C2P no acepta tokens de usuario, ni al revés. Un token C2P no abre ningún endpoint de
la app.
- **Comparación en tiempo constante; `invalid_client` genérico.** No se revela qué parte de la
credencial falló.
- **La comisión la manda Soterex** en el body de SendRequest (D13). No construyas ningún motor ni
tabla de comisiones. ADR-005 sigue vigente.
- **El MTCN es aleatorio y único en toda la tabla**, garantizado por un índice único en la base y
reintento ante colisión (D11). Nunca se reutiliza.
- **Nunca escribas `role_permissions` fuera de `RolePermission::withoutEvents()`** (ver el
comentario de `RoleSeeder::run`).
- **Ningún saldo se materializa** (ADR-005/007). La comisión sigue siendo restringida: no la
expongas en pantallas operativas.
- **Lo que ya funciona no se rompe:** Pago, Caja, documentos, papeleta, reportes y demo
(`php artisan demo:reseed`). Todos los tests existentes siguen verdes.
- Una transacción creada por API se tiene que poder **pagar de punta a punta en la app local**.
Verificalo a mano, no solo con tests.
## Verificación final (local, no alcanza con los tests)
Con el stack local levantado:
1. `php artisan api-client:generate-secret` → `api-client:create soterex-local
--secret-hash-b64=…`.
2. `curl` al token, con Basic y con body. Después SendRequest con `fee` (anotá el MTCN), SendRequest sin `fee` (error), SendRequest
duplicado (2001), Cancel de otra tx, y Cancel con MTCN equivocado.
3. Entrá a la app como Backoffice, buscá el MTCN en Pago y pagá la tx completa (datos, documentos,
confirmar). Revisá que Reportes muestre la comisión y que la Holding haya descontado principal
+ fee.
4. Verificá que se encoló el Notification de PAID en el outbox.
5. Rotá el secret con `--overlap` y comprobá que los dos valen; revocá el viejo y comprobá que deja
de valer.
## Resultado que tenés que dejar
1. El PR con C1–C5, tests verdes y la salida real pegada.
2. **`doc/integracion/2026-09-30-soterex-staging.md`** (C5 del plan), con:
- el mail en inglés para Sean, que responde sus 7 preguntas con los valores de staging (URL
base `https://api.soterex.stag.cislatam.net`, paths exactos, formato del token, ejemplos) y
las diferencias de producción (`https://api.soterex.cislatam.net`, planificado, con cliente
propio), más lo que le pedimos a Soterex;
- los pasos de Carlos a la mañana con los comandos exactos;
- los `curl` de ejemplo;
- la lista "Decisiones que tomé sin Carlos".
3. El `openapi` exportable para adjuntarle a Sean.
4. Un mensaje final en el chat, corto: qué quedó hecho, qué verificaste y qué no, el link del PR y
la ruta del documento para Soterex.Por qué el prompt está escrito así
- Paso 0 primero: el plan solo existe en
feature/api-c2p-entrante. - "Vas a trabajar solo": Carlos lo deja corriendo de noche. Si el agente frena a preguntar, la noche se pierde. Frenar solo tiene sentido ante lo prohibido.
- La regla del secret está repetida a propósito:
run-artisan-command.ymlvuelca la salida en los logs de GitHub Actions, y unapi-client:createque imprima el secret lo filtraría.

