Skip to content

Prompt de ejecución — Alinear la API C2P al contrato con Soterex ​

Date: 2026-10-05 Uso: copiar el bloque como primer mensaje de una sesión nueva de Claude Code en /Users/peluca/projects/soterex. Ejecuta doc/plans/2026-10-05-alineacion-contrato-c2p-soterex.md.


Sos el product owner de este proyecto (Soterex / CIS Latam) y coordinás la ejecución de un plan ya
aprobado. Arrancás de cero, Carlos está durmiendo y nadie va a contestar preguntas: trabajá de
corrido y dejá todo por escrito. Para mañana a la mañana tiene que estar terminado; el compromiso
con Soterex es el martes 2026-10-06.

## 1. Contexto, antes de tocar código

Leé en este orden:
1. `CLAUDE.md`.
2. **Trabajá en un worktree propio, nunca en `/Users/peluca/projects/soterex`**: ahí hay otra
   sesión trabajando en otro branch (`feature/ajustes-v3-cliente-gt`) con archivos sin commitear.
   No hagas `checkout` en ese directorio ni toques sus archivos.
       cd /Users/peluca/projects/soterex
       git fetch origin
       git worktree add .claude/worktrees/c2p-contrato docs/plan-alineacion-contrato-c2p
       cd .claude/worktrees/c2p-contrato
       git pull origin docs/plan-alineacion-contrato-c2p
   Todo lo que sigue (código, tests, commits, push) se hace desde ese worktree.
3. `doc/plans/2026-10-05-alineacion-contrato-c2p-soterex.md` — el plan. Entero. §4 es el
   contrato objetivo: los JSON de ahí son la especificación que tenés que cumplir al pie de la letra.
4. `doc/reference/2026-08-12-especificacion-soterex/` — la especificación de Soterex (el PDF y su
   texto en `stipend-spec.txt`). Es el contrato que CIS aceptó como definitivo.
5. `doc/architecture/ADR-012-direccion-integracion-c2p-entrante-oauth.md` y
   `doc/integracion/2026-09-30-soterex-staging.md`.
6. El código de la integración: `C2PController`, `OAuthTokenController`, `VerifyApiClientToken`,
   `NotificationOutboxService`, `NotificationsDeliver`, `SoterexClient`, `SoterexSetting`,
   `TransactionCancellationService`, y dónde `TransactionController` encola notificaciones al pagar
   y al cancelar. Sus tests en `backend/tests/Feature/`.

**El stack de Docker que está corriendo (`soterex-backend-1` y compañía) monta el directorio
principal, no tu worktree**, y lo está usando la otra sesión. No lo uses para tus tests ni lo
reinicies. Levantá tu propio stack descartable que monte el `backend/` de tu worktree, con su
propia base y su propio Firebase Auth Emulator, en puertos y nombres de proyecto distintos (por
ejemplo `docker compose -p c2p-contrato` con un override de puertos). Es lo mismo que se hizo para
verificar el PR #55: ver `doc/integracion/2026-09-30-soterex-staging.md` §5 y
`doc/environments/dev.md`. Al terminar, bajalo.

## 2. Qué hacés

Las entregas del plan (§5) **en este orden: K1, K2, K3, K6, K4, K5, K8, K7**, en el branch
`docs/plan-alineacion-contrato-c2p` y con un solo PR contra `main`. Commits con prefijo
(`feat(c2p): K1 — …`). Si el tiempo no alcanza, ese mismo orden es la prioridad: los bloqueantes
primero. K7 se escribe al final y documenta solo lo que quedó hecho. §5 del plan también lista los
tests existentes que hay que reescribir (no borrar).

Usá los agentes que necesites: `backend-dev`, `frontend-dev` para la pantalla de K8, `architect` para los ADR-017 y 018, `tech-writer` para el
sign-off y el OpenAPI, `code-reviewer` antes de abrir el PR, y `security` sobre K3 (firma HMAC y
manejo del secret) y K5 (endpoint de sandbox).

## 3. Cómo trabajás cada entrega

1. Tests en el mismo commit que el código. Cada fila de §1 del plan que toca la entrega tiene que
   quedar cubierta por un test que falle si se reintroduce la diferencia.
2. Corré y pegá la salida real, **siempre contra el código de tu worktree**: `php artisan test` y
   `vendor/bin/pint --test` dentro de tu contenedor descartable; si tocás el frontend, `npm ci`,
   `npm run test` y `npm run build` en `frontend/` del worktree; si tocás Markdown de `doc/`,
   `npm ci` y `npm run docs:build` en `doc/` del worktree.
3. Verificá a mano contra el stack local, no alcanza con los tests:
   - Creá un cliente C2P en tu stack descartable (`php artisan api-client:generate-secret` y
     `api-client:create` dentro de tu contenedor) y corré la collection del repo con su secret.
   - Para el webhook, levantá un receptor local que verifique la firma y conteste como Soterex
     (`messageCode`), y comprobá cada fila de la tabla de entrega de §4.4.
4. Push al branch. Abrí el PR al terminar K1 (`gh pr create --base main`) y actualizá la
   descripción con cada entrega.

## 4. Autorización y límites

Te autorizo a implementar, testear, commitear, pushear a `docs/plan-alineacion-contrato-c2p` y
abrir o actualizar su PR sin pedirme confirmación.

No hagas nada de esto: mergear; push, merge o deploy a `staging` o `production`; `terraform
apply`; disparar workflows de GitHub Actions; correr comandos contra staging o producción; mandar
mails o mensajes; force-push, `reset --hard` o rebase de un branch pusheado.

Si aparece algo que el plan no decide, tomá la opción que más se parezca a la especificación de
Soterex, anotala en "Decisiones que tomé sin Carlos" del PR y seguí. Si toca plata o datos de
transacciones reales y no hay una opción conservadora clara, dejá esa parte sin hacer y explicá qué
falta.

## 5. Reglas que no se negocian

- **El contrato de §4 se copia exacto**: nombres de campo, anidado, literales (`ACCEPTED`,
  `REJECTED`, `CANCELLED`), códigos y mensajes. Un test por forma de respuesta que compare el JSON
  entero, no campo por campo.
- **La firma va sobre los bytes que se mandan y se calcula en cada intento.** En cada envío:
  serializá el payload, timestamp nuevo, HMAC sobre `"{timestamp}.{body}"`, y mandá ese mismo
  string. El timestamp y la firma nunca se guardan (la tolerancia de Soterex es 300 s y los
  reintentos son de minutos).
- **El secret del webhook nunca se loguea, nunca se devuelve por API y se guarda cifrado.**
- **La comisión la calcula CIS** con el tarifario por país (D2 y D2b del plan): `fee` no va en el
  request y si llega se ignora. [Reemplazado el 2026-10-05, ver ADR-018: el provisional pasó a 50 USD fijos y se siembra en todos los ambientes.] El tarifario provisional del 1 % se siembra **solo fuera de
  producción**.
- **El replay nunca rechaza**: todo `transaction_id` repetido devuelve la original con `COD_009`.
- **Solo se notifican y vencen transacciones que entraron por la API** (`api_client_id` no nulo,
  D12). Los datos de demo de staging no se tocan.
- **CANCELLED se encola solo en la transición real ACCEPTED→CANCELLED** (D6).
- **Ningún saldo se materializa** (ADR-005, ADR-007). El vencimiento cancela, no toca saldos.
- **El comando de vencimiento solo toca transacciones ACCEPTED con el vencimiento pasado**, de a una,
  con lock, y es idempotente.
- **El endpoint de sandbox no existe en producción** y no cambia el estado de ninguna transacción.
- **Nada de PII ni secrets en logs ni en la auditoría.**
- Los ADRs nuevos son **ADR-017** (contrato) y **ADR-018** (comisión). Agregalos a
  `doc/architecture/index.md`.
- **El borrador del mail a Sean** (K7) dice solo lo que quedó hecho y verificado, y lleva el
  secret como placeholder.

## 6. Al terminar

Dejá en el chat y en la descripción del PR:
1. El link del PR y el estado del CI.
2. Por entrega: hecha, parcial o sin hacer; qué verificaste a mano y qué no.
3. Las decisiones que tomaste sin Carlos.
4. Lo que le toca a Carlos el lunes (§7 del plan), en orden.
5. Lo que encontraste roto o raro y no era de este plan.

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