ADR-017: El contrato C2P es la especificación de Soterex
Date: 2026-10-05 Status: Accepted — decisiones D1 a D15 del plan doc/plans/2026-10-05-alineacion-contrato-c2p-soterex.md (las D1–D15 de ese plan, no las de ADR-012, que tiene su propia numeración). Implementado en el branch docs/plan-alineacion-contrato-c2p (PR #80, pendiente del merge de Carlos): hechas K1 a K5 y K8 (la API y la pantalla «Comisiones» del tarifario, ver ADR-018 §6), más una ronda de correcciones de una revisión independiente que cambió algunos detalles de lo que se decide acá (se marcan abajo); parcial K6 (el código y la documentación están, falta el flag enabled = true del scheduler de Staging en Terraform, que edita y aplica Carlos, y está en pausa por decisión de Carlos del 2026-10-05: todavía no hay URL ni secret de Soterex); K7 es esta documentación. Actualizado el 2026-10-05 con las decisiones de Carlos de ese día: el replay devuelve el estado real (§2), la comisión provisional son 50 USD fijos también en producción (ADR-018), y los riesgos que se dejan como están y el scheduler apagado («Riesgos y decisiones de Carlos»). Supersedes in part: ADR-012 — los contratos de SendRequest, Cancel y Notifications de sus §5 y §6, y la seguridad perimetral de su §7 (el detalle, en Qué reemplaza de ADR-012). La dirección de la integración (Soterex llama a CIS), OAuth, los clientes y el MTCN siguen vigentes. Ver también: ADR-018 (la comisión, decidida aparte el mismo día), ADR-007 (ningún saldo cambia).
Context
ADR-012 (2026-09-30) corrigió la dirección de la integración —Soterex es quien llama a CIS— pero conservó el contrato del spec v1.4: el de Zoom, escrito para el modelo pull original (doc/site/public/openapi.yaml). Es decir que la API se construyó bien en dirección y mal en forma: nunca se comparó contra el documento que Soterex mandó el 2026-08-12 y que CIS aceptó como contrato definitivo el 2026-08-14 (doc/reference/2026-08-12-especificacion-soterex/).
El plan de alineación del 2026-10-05, revisado por tres revisores independientes (especificación, código y huecos), encontró 27 diferencias (§1 del plan). Ocho eran bloqueantes, y juntas tenían una consecuencia concreta:
- Todo
Cancelde Soterex se rechazaba: exigíamossub_status(2109/2110) y la especificación dice que "the current callers do not populate them; build for them to be absent". - Ninguna notificación se daba por entregada: leíamos
codResponse === 'COD_000'y el acuse real de Soterex traemessageCode. Todo terminaba en reintentos yFAILED. - Soterex rechazaba nuestras notificaciones con un 400: el body iba plano y no anidado en
notificationData, con los mismos campos para todo estado, unsub_statusde relleno enPAID(que "must not be sent on PAID") y sintimeenCANCELLED. - El webhook iba con HTTP Basic y sin firma, y la firma HMAC es "not negotiable" para Soterex.
- Un reintento con un dato reformateado se rechazaba con
2001, cuando la especificación y CIS (04/09) piden que todotransaction_idrepetido devuelva el original. - Todo create armado según la especificación rebotaba con
2016: pedíamosfeeen el request y la Operación 2 no lo manda.
Del resto, las más importantes: los rechazos de negocio eran HTTP 400 y no HTTP 200 con status: "REJECTED"; amount y fee iban como número en unas respuestas y como texto en otras; el vencimiento (expiration_date, antes expirate_date) no se aplicaba en ningún lado; no existían los disparos a demanda del sandbox (que Soterex necesita para cerrar su etapa Build); y no estaban entregados los vocabularios cerrados de estados y errores ni el documento de sign-off que CIS prometió el 04/09.
Restricciones que mandan:
- Soterex ya tiene su cliente construido contra su propia especificación. Para ellos, un proveedor que la respeta "drops into our existing architecture as configuration rather than new code". Cada desvío nuestro es código nuevo de su lado.
- El compromiso con Soterex es el martes 2026-10-06: sandbox alineado y documento de sign-off.
- Nadie más consume el contrato viejo. Lo único que pudo haberse probado contra él son las credenciales del 2026-09-30.
- Ningún saldo se materializa (ADR-005, ADR-007): nada de esto toca ledgers.
Decision
El contrato es la especificación de Soterex, sus cuatro desviaciones, y lo que CIS confirmó por escrito el 2026-08-14 y el 2026-09-04. Donde la especificación no dice nada, mandan las confirmaciones de CIS. Todo lo demás se copia exacto: nombres, anidado y literales (ACCEPTED, REJECTED). Los JSON del plan (§4) son la especificación, y el código se prueba contra ellos campo por campo y con el JSON entero. El resto de las decisiones, agrupadas:
1. Forma de las respuestas y de los rechazos (D1, D3, D4)
- Todo rechazo de negocio es HTTP 200, con
status: "REJECTED", el código específico encode, unmessagediagnóstico que nombra el campo yentityResponsecomo texto. Sindtc_estatus, salvoCODE_010("ya cobrada"). Los 4xx y 5xx quedan para lo que no es de negocio: 401, 404, 405, 429 y 500, todos con el mismo envelope (CODE_404,CODE_405,CODE_429,CODE_500; cualquier otro estado HTTP esCODE_<estado>con un texto fijo y sin detalle interno). Todo error de/api/c2p/*y de/api/oauth/*sale en JSON, con o sinAccept(el cliente de Soterex no lo manda por defecto); el endpoint de token usa el formato OAuth (error,error_description:temporarily_unavailableen el 429,server_erroren el 500). entityResponse.transaction_ides la referencia de CIS (el UUID de la transacción): la tabla de la Operación 2 de la especificación la define como la referencia del proveedor y el ejemplo de la Operación 3 trae el mismo campo. ElRS-de Soterex viaja en el request y en todas las notificaciones. La especificación también dice que elRS-"must be echoed back on every response and every notification": se lee como aplicable a las notificaciones, porque el envelope no tiene otro campo donde devolverlo sin pisar la referencia del proveedor. Se pide confirmación a Soterex en el sign-off.amountyfeeson texto de 2 decimales en toda respuesta; en el requestamountacepta número o texto.- Ningún valor del request puede provocar un 500: textos de más de 255 caracteres, bytes nulos, montos enormes, arrays o números donde va un texto son rechazos con su propio código (
2018a2025). Un body que no se pudo leer (JSON roto, unContent-Typeque no es JSON) lo dice (body: not valid JSON or unsupported Content-Type…) en vez de acusar un campo faltante. origin_currencyes siempreUSDysendersiempreUS, como dice la especificación ("Always USD", "Always US"): otro valor bien formado se rechaza con2009y2011(Must be USD,Must be US), porque un envío en otra moneda se registraría y se pagaría como dólares. Los mensajes dicen qué falló (Country not enabledpara un país bien formado que CIS no opera,amount: must be greater than zero, …).- Un
Bearercon formato imposible (el id previo al|no numérico, caracteres de control, más de 256) es un401 CODE_008sin tocar la base; el esquemaBearerno distingue mayúsculas (RFC 7235).
2. Idempotencia sin rechazo (D1, fila 7 del plan)
Todo SendRequest con un transaction_id que el cliente ya usó devuelve la transacción original con COD_009, aunque el payload sea distinto: un reintento nunca se rechaza. Qué campos difieren queda en la auditoría (solo los nombres, nunca los valores). Se resuelve antes de validar el resto, y también cuando la carrera la arbitra el índice único. Desaparece el 2001.
Actualización 2026-10-05 (decisión de Carlos): el replay devuelve el estado real. «La transacción original» ya no es la respuesta del alta tal cual. El replay es la misma respuesta (code: COD_009, status: ACCEPTED, message: Duplicate request: original transaction returned y la misma entityResponse: id de CIS, token, amount, fee, expiration_date) con una sola diferencia: dtc_estatus es el estado actual de la transacción, ACCEPTED, PAID o CANCELLED. Antes era siempre ACCEPTED (el literal del plan): si Soterex repetía el SendRequest de algo que ya se cobró o se canceló, la respuesta no se lo decía y solo la notificación lo hacía. Cómo queda:
| La transacción original está | status | dtc_estatus | Qué entiende Soterex |
|---|---|---|---|
ACCEPTED y vigente | ACCEPTED | ACCEPTED | Existe y se puede cobrar (igual que antes) |
ACCEPTED pero vencida, sin que c2p:expire la haya cancelado todavía | ACCEPTED | ACCEPTED | Se informa el estado guardado, no se deduce: el replay no cancela ni decide |
PAID | ACCEPTED | PAID | Ya se cobró |
CANCELLED (por Soterex, por CIS o por vencimiento) | ACCEPTED | CANCELLED | Ya no se puede cobrar: hace falta una transacción nueva (RS- nuevo, previous_transaction_id) |
status sigue siendo ACCEPTED en los tres casos: es el resultado de la llamada (se aceptó, un replay nunca se rechaza), no el estado de la transacción. Quien decide qué hacer con un COD_009 tiene que mirar dtc_estatus. El alta (COD_000) no cambia (dtc_estatus: ACCEPTED). Los dos caminos del replay —el chequeo previo y la carrera por el índice único— pasan por el mismo método. El sign-off (1.4), el OpenAPI, la collection de Postman y el mail lo dicen así.
3. La comisión la calcula CIS (D2, D2b) — ADR-018
Decidido aparte en ADR-018: fee sale del request (se ignora si llega y se audita si difiere), CIS lo calcula con un tarifario por país y lo guarda al crear. Rige uno provisional de Guatemala de 50 USD fijos por transacción, en todos los ambientes, producción incluida (decisión de Carlos, 2026-10-05; la decisión original era el 1 % solo fuera de producción).
4. Firma del webhook (D5)
El webhook se firma con HMAC-SHA256 y deja de usar HTTP Basic. Se firma el string "{timestamp}.{body}" con el secret tal como se compartió, como texto UTF-8 (no se decodifica de hex ni de base64), en hex minúscula, con los headers X-CIS-Timestamp (epoch en segundos, UTC), X-CIS-Signature y X-CIS-Key-Id.
- El payload se guarda al encolar; en cada intento, justo antes del POST, se serializa, se toma un timestamp nuevo y se firma, y se manda ese mismo string. Timestamp y firma nunca se guardan: la tolerancia de Soterex es de 300 segundos y los reintentos son de minutos.
- El secret lo provee Soterex; el Admin lo carga en Configuración, cifrado, con un
key_idde texto libre (k1si no se indica). Se firma con el secret activo más reciente; el anterior se conserva 24 horas solo para poder volver atrás. - Nunca se manda sin firmar: en modo real sin secret activo, la entrega falla y se reintenta (cinco intentos); si sigue sin secret, queda
FAILEDy se reenvía a mano cuando haya uno. - Revocar un secret programado (que todavía no empezó) le devuelve la vigencia al anterior: sin eso el anterior vencía igual en la fecha del secret revocado y no quedaba ninguno para firmar. Las altas y revocaciones se serializan entre sí.
- El secret mide de 8 a 512 caracteres (el mínimo bajó de 16 en la revisión independiente: lo elige Soterex). No se loguea, no se devuelve por ninguna API, no entra en la auditoría y se guarda cifrado.
5. Notificaciones (D6, D12, D15)
- Se notifica
CANCELLEDen toda cancelación: la de operaciones de CIS, la que pide Soterex porCancely la del vencimiento (D6). Solo en la transición realACCEPTED→CANCELLED: un re-cancel idempotente o el que pierde la carrera no encola nada. - Solo se notifican y vencen las transacciones que entraron por la API (
api_client_idno nulo, D12), en todos los caminos. Los datos de demo de Staging no se tocan: una migración marca comoSKIPPEDlo que la demo había dejado pendiente. - Los
sub_statuspor defecto (CXL_*) se arman solo dentro de la notificación (D15). Las columnassub_status_codeysub_status_messagede la transacción guardan únicamente lo que mandó Soterex, como registro fiel de lo recibido. (Nota del 2026-10-07: la razón original era que el reporte de Cumplimiento las leía para la columna 30. Desde G9.2 esa columna sale siempre vacía y el reporte ya no las lee: D15 se mantiene igual, ahora solo por fidelidad con lo que mandó Soterex.) - El acuse se lee por
messageCode(COD_000,COD_002,COD_003;CODE_004es un duplicado, también entregada). Un 3xx o un 4xx (salvo 429) es falla definitiva; 429, 5xx, timeout o una respuesta sin acuse se reintentan con esperas mínimas de 1, 5, 15 y 60 minutos. Una falla definitiva queda en la auditoría y se reenvía conphp artisan notifications:retry {id}, o todas juntas connotifications:retry --all-failed [--limit=N](100 por defecto, tope 1000; nunca toca lasSKIPPED). - Cada corrida de
notifications:delivertoma las filas de a una, justo antes de enviarlas, de la más vieja a la más nueva (created_at), da un solo intento por fila y se corta a las 50 filas o a los 480 segundos (--limity--max-seconds): por debajo del mutex de 10 minutos, así una corrida viva nunca pierde el mutex y dos corridas nunca envían la misma fila. Lo que no alcanza siguePENDINGpara la corrida siguiente. - La Notifications URL exige
https(salvo en local y testing), sin usuario, contraseña, parámetros ni fragmento: el webhook se autentica con la firma, y cualquier credencial en la dirección terminaría en logs. Cada cambio de la URL queda en la auditoría como servidor y ruta, antes y después. - En producción el modo
mockno existe: la entrega falla (y terminaFAILED) en vez de dar por entregado lo que Soterex nunca recibió, y la pantalla de Configuración lo avisa en rojo.
6. El MTCN vence (D7)
expiration_date es el último día en que se puede cobrar: vencida ⇔ hoy (America/Guatemala) > ese día, y un expires_at nulo no vence. Una vencida no se puede pagar (pay() responde 422 MTCN_EXPIRED) y el comando c2p:expire la cancela y notifica CANCELLED con CXL_EXPIRED. Esto rige solo para las transacciones que entraron por la API (D12, api_client_id no nulo): pay() no rechaza una transacción de demo aunque su fecha esté en el pasado, porque las de demo de Staging llevan un expires_at sembrado para que se vea, no una vigencia real. La misma regla, escrita una sola vez (un método y un scope SQL que un test compara), la usan pay() y el comando. La vigencia de Guatemala pasa a 60 días (lo que dice la carta de Soterex al beneficiario), por migración de datos y en CountrySeeder; las ACCEPTED existentes conservan su expires_at. Vencer no toca ningún saldo.
7. Sandbox (D8, D9)
- En producción no hay
FAILED: un cobro se completa o la transacción sigue pendiente hasta que se paga, se cancela o vence. En el sandbox,FAILEDse dispara a demanda, como CIS se comprometió el 14/08. POST /api/c2p/v1/sandbox/notifysolo manda la notificación, no cambia el estado de la transacción ni toca saldos, queda auditada, y en producción la ruta no existe (404 con el mismo envelope que cualquier URL inexistente, con dos capas independientes). Para probarCODE_010, un operador de CIS paga la transacción desde la pantalla de Staging cuando Sean lo pide.- Qué es un ambiente de pruebas es una sola definición, con lista blanca (
DeploymentEnvironment): sololocal,testingystaging(elAPP_ENVsin espacios en los bordes y en minúscula); todo lo demás es producción, incluidosprod,Production, un valor desconocido y uno vacío. Eso decide a la vez el endpoint del sandbox y el modomock(en producción falla y terminaFAILED). Antes eran tres definiciones que no coincidían (una lista negra en el sandbox y el mock, una comparación exacta en el tarifario provisional). El tarifario provisional ya no depende de esa lista (decisión de Carlos, 2026-10-05: se siembra en todos los ambientes, ver ADR-018).httpen la Notifications URL se admite solo enlocalytesting. - La misma definición es la guarda de «no en producción» de los comandos y seeders. Antes comparaban
app()->environment('production'), una igualdad exacta: conProduction,prodo unAPP_ENVque nadie previó la guarda se salteaba y el comando corría en producción. Ahora pasan porDeploymentEnvironment(fuera delocal/testing/staginges producción):api-client:create(el prefijo delclient_id:cis_prod_en producción,cis_stg_en Staging,cis_local_enlocalytesting: antes un cliente de producción conAPP_ENV=Productionsalía comocis_local_…),demo:reseedydemo:seed-accepted(borran y siembran datos de demo: sololocal/staging, y con--forceen el resto) yStagingTestUsersSeeder(crea cuentas en el Firebase real: se niega en producción). Dos guardas ya eran lista blanca por su cuenta y quedaron como estaban, porque normalizar el valor las abriría aLocalotesting:api-client:generate-secret(sololocal/testing: imprime el secret en claro) yDatabaseSeeder(los usuarios y PDV de desarrollo solo enlocal).
8. Perímetro y contactos (D10, D11, D13, D14)
- No se piden ni se aplican allowlists de IP (D10): CIS no exige allowlist a Soterex y la IP de salida de producción se informa cuando se provisione. La capacidad por cliente (
allowed_ips) sigue en el código, sin usarse. - El contacto técnico de Soterex es Sean Rahimi (D11). Los de CIS y su escalamiento los completa Carlos en el sign-off.
- Liquidación y fondos (D13): la cancelación es inmediata y sincrónica; una transacción no cobrada no consume prefondeo (se debita al cobrar, principal más comisión), así que cancelarla no mueve fondos.
- Secuencia de estados (D14):
ACCEPTEDes intermedio;PAIDyCANCELLEDson terminales. Una cancelada o vencida nunca pasa aPAID, y una corrección es cancel-and-recreate con unRS-nuevo yprevious_transaction_id.
Qué reemplaza de ADR-012
| ADR-012 | Decía | Ahora |
|---|---|---|
| §5 | Envelope y códigos 1xxx/2xxx del spec v1.4; éxito COD_001 / COD_002; rechazos HTTP 400 con CODE_002 y errorDetails | El de la especificación de Soterex: éxito COD_000, rechazos HTTP 200 (D3) |
| §5 | expirate_date, Y-m-d H:i:s; el vencimiento "queda fuera de esta entrega" | expiration_date, yyyy-MM-dd; el MTCN vence (D7) |
| §5 | fee obligatorio en el request (D13) | Lo calcula CIS: ADR-018 |
| §5 | Idempotencia: mismo payload devuelve el original, distinto es el error 2001 | Todo repetido devuelve el original con COD_009; se retira el 2001 |
| §5 | Cancel exige sub_status (2109/2110); una ya cobrada es 2108 | sub_status opcional; ya cobrada CODE_010; inexistente CODE_001. Se retiran 2108 y 2109 |
| §6 | Se notifica PAID y el CANCELLED de CIS, no el que pidió Soterex; payload plano; auth con HTTP Basic de placeholder | CANCELLED en toda cancelación (D6); payload anidado por estado; firma HMAC (D5) |
| §6 | FAILED no figura | FAILED solo a demanda en el sandbox (D8) |
| §7 | La IP allowlist de producción "se pregunta en el mail" | No se piden ni se aplican (D10) |
| §7 (D17) | Throttle de /api/c2p/* por client_id + IP (throttle:c2p) | Por cliente de la API, 60 por minuto, después de autenticar (ThrottleApiClient). El de /api/oauth/token no cambia. Ver la aclaración al final de ADR-012 §7 |
Sigue vigente de ADR-012: la dirección (§1), OAuth 2.0 Client Credentials (§2), los clientes y secrets con rotación (§3), el MTCN aleatorio de 10 dígitos (§4), el outbox como mecanismo de entrega (§6, solo cambia lo que viaja y cómo se firma), la regla de cancelación compartida (TransactionCancellationService) y TLS y el throttle propio de /api/oauth/token (§7).
Alternatives Considered
- Seguir con el spec v1.4 de Zoom (el statu quo). Pros: ya estaba construido y probado por nosotros. Contras: nunca fue el contrato de Soterex, tiene ocho diferencias bloqueantes (el
Cancelde Soterex fallaría siempre y ninguna notificación se daría por entregada) y Soterex aceptó el suyo, no el nuestro. Descartada. - Negociar con Soterex que adapte su cliente a lo que ya construimos. Pros: no tocamos código. Contras: su especificación dice explícitamente que cada desvío que no está en sus cuatro desviaciones es código nuevo de su lado, la firma del webhook es "not negotiable", y los parsers ya existen. Costaría el compromiso del martes y le pediríamos a Soterex trabajo que nos corresponde a nosotros. Descartada.
- Adaptar solo lo bloqueante y dejar el resto para después. Pros: menos código esta semana. Contras: Soterex vería el contrato cambiar en dos tandas, el sign-off no podría afirmar vocabularios cerrados (
CODE_010, los tipos por campo y los códigos de error están en su checklist), y quedarían mezclados dos contratos. Descartada: lo no bloqueante es chico y no tiene sentido pagar dos veces el costo de coordinar. - Un adaptador entre el v1.4 y la forma de Soterex, o versionar la API (
/v1viejo y/v2nuevo) para no cambiar lo que Sean ya pudo probar. Pros: no se rompe nada de lo viejo. Contras: dos contratos que mantener para un único cliente, que además no tiene nada productivo contra el viejo. Descartada: la mitigación es mandar el mail recién con todo desplegado (ver Consecuencias). - Vencimiento solo informativo (como estaba). Contras: la especificación dice "After this date the funds are no longer collectable", y una transacción pendiente para siempre deja a Soterex esperando un desenlace que nunca llega. Descartada.
- Que el disparo a demanda del sandbox cambie el estado de la transacción (D9), para poder probar
CODE_010solo. Pros: una prueba menos manual. Contras: una ruta que muta estados y manda notificaciones firmadas es una forma de mentirle a Soterex sobre un pago si llega a existir en producción. Descartada: solo manda la notificación y un operador paga desde la pantalla. - Notificar también las transacciones de demo (sin
api_client_id). Contras: Soterex no las conoce y le llegarían pagos de transacciones que no existen del otro lado. Descartada (D12).
Consecuencias
- Positivo: se cierran las ocho diferencias bloqueantes: el
Cancelde Soterex funciona, las notificaciones se dan por entregadas, el webhook va firmado y un reintento nunca se rechaza. El sign-off puede responder punto por punto el checklist de la página 13 de la especificación. - Positivo: el contrato queda definido por un documento que ambos lados comparten, no por una interpretación nuestra. Las próximas diferencias se resuelven mirando la especificación, no discutiéndola.
- Negativo: cambia lo que Sean ya pudo haber probado con las credenciales del 30/09 (respuestas, rechazos,
fee, notificaciones, firma). Por eso el mail con el sign-off, el OpenAPI y la collection se manda recién con todo desplegado en Staging: así ve un solo contrato. El mail anterior le dijo cosas que ahora son falsas (quefeees obligatorio, que se usa HTTP Basic, que no se notifica unCANCELLEDpedido por él, que el vencimiento no se aplica) y el nuevo lo dice expresamente. - Negativo: el secret del HMAC es texto UTF-8, no hex ni base64. Si Soterex lo decodifica antes de verificar, todas las firmas fallan. Está escrito así en el sign-off, con un vector de prueba que reproduce cualquiera, y se le pide confirmación.
- Negativo: sin scheduler no sale ninguna notificación, ni el primer intento, y no vence nada: el outbox solo se vacía con
notifications:delivery el vencimiento corre conc2p:expire. K6 deja el código y la documentación; el flag de Terraform (enabled = true) y suapplylos hace Carlos, y por decisión suya del 2026-10-05 no se hacen por ahora (ver «El scheduler no se prende por ahora», abajo). - Negativo: el vencimiento cancela transacciones reales de la API. Mitigado: solo las
ACCEPTEDconapi_client_id, de a una, con lock, idempotente, con un--dry-runque se corre en Staging antes de prender el scheduler, y sin tocar saldos. - Negativo: los códigos
2001,2016,2017,2108,2109yCODE_002conerrorDetailsdejan de devolverse. Cualquier cliente que dependiera de ellos se rompe; se listan como retirados en el sign-off. Negativo: sin tarifario real, producción rechaza todoReemplazado el 2026-10-05: producción arranca con el provisional de 50 USD fijos y ya no rechaza por falta de tarifario (ADR-018, Actualización). El costo que queda: con montos menores a 50 USD la comisión supera al principal, y producción cobra 50 USD por transacción hasta que Tesorería cargue la tabla real.SendRequestcon2026(ADR-018): hay que cargar el de Tesorería antes de abrir.- Negativo: el sandbox topa a los 50 disparos a demanda pendientes por cliente; con el scheduler apagado (el estado actual) las pendientes no se vacían y Sean toparía.
- Negativo: cada corrida de
notifications:deliverentrega a lo sumo 50 notificaciones y da un solo intento por fila: con el tick de 5 minutos de AWS son 600 por hora como máximo, y un backlog mayor sale en varias corridas. Para vaciar una cola grande a mano hay que correr el comando varias veces o subir--limit. - Positivo (revisión independiente): el límite de pedidos de la API C2P es por cliente de la API (60 por minuto, un solo cupo para
SendRequest,Cancely el sandbox) y se cuenta después de autenticar: un request sin token válido responde 401 y no consume nada. El limiter anterior corría antes de la auth y, detrás del ALB, firmaba por la IP del balanceador: cualquiera con unBearer xpodía dejar a Soterex con 429 (ver la aclaración de ADR-012 D17). - Positivo: el replay en carrera ya no reintenta 10 veces ni loguea un agotamiento falso, un
client_idcon bytes nulos o caracteres de control da el 401 genérico sin tocar la base, el esquemaBearerse compara sin distinguir mayúsculas (RFC 7235) y los logs de la integración no llevan el mensaje de una excepción de base de datos. - Positivo: K8 existe: el tarifario real lo carga el Admin desde Parámetros → Comisiones, con avisos de provisional, de huecos y de tramos sin comisión, sin solapamientos y con auditoría (ADR-018 §6). Lo que sigue pendiente es el contenido, que define Tesorería.
- Neutral: quedan abiertos con Soterex, sin bloquear: la URL de Notifications y su secret con el
key_id, las plantillas del reporte de pagos del día siguiente y del estado de cuenta (que CIS mantiene durante el paralelo y después), la vigencia del MTCN (60 días salvo que digan otra) y que elRS-no se repita enentityResponse(D4). - Neutral: la infraestructura de usuario y contraseña de Soterex (los secrets
soterex_usernameysoterex_passwordde Secrets Manager y su inyección en la task de ECS) quedó sin consumidor: ningún código la lee. Limpiarla es un cambio de Terraform aparte, de Carlos. - Neutral: ningún saldo ni ledger cambia (ADR-005, ADR-007).
outbound_notifications.payloadpasó dejsonbajson, porquejsonbreordena las claves y el body que se firma tiene que ser el que se arma.
Riesgos y decisiones de Carlos (2026-10-05)
Lo que el plan dejó explícitamente fuera, o lo que la revisión independiente encontró y no se resolvió en este PR, con lo que Carlos decidió el 2026-10-05, en el chat de la ejecución del plan. Son internos: no figuran en el sign-off ni en el mail a Sean, salvo donde se indica. Ninguno bloquea el sandbox; los de infraestructura son de Carlos.
| # | Riesgo | Decisión de Carlos (2026-10-05) | Qué implica |
|---|---|---|---|
| 1 | trustProxies sin configurar. Detrás del ALB la app ve la IP del balanceador, no la del cliente | Se deja como riesgo conocido | El limiter de /api/oauth/token (por client_id más IP) comparte el cupo de la IP del ALB: un tercero que conozca el client_id (dato público) puede agotar los 30 intentos por minuto de ese cliente y hacer que el pedido de token de Soterex dé 429 un rato (no permite autenticarse, y los tokens emitidos duran una hora). Y ApiClient::allowed_ips, si se llegara a cargar, compararía contra la IP del ALB, no la de Soterex. El control por IP real lo da la regla rate-based del WAF |
| 2 | APP_DEBUG=true en Staging (en todo ambiente que no sea production, infra/terraform/modules/ecs): el sandbox de un tercero | Se deja por ahora | Un 405, o un error fuera del envelope de C2P, puede filtrar detalle de depuración. El 500 de /api/c2p/* ya no lo hace (devuelve el envelope), pero lo demás sí. En producción APP_DEBUG no es true |
| 3 | Notificaciones perdidas si el proceso muere entre el commit del pago o la cancelación y el encolado. No hay conciliación que detecte una transacción PAID o CANCELLED sin su notificación | Para el go-live real | El encolado va después del commit y atrapando cualquier excepción, para que un fallo de notificar no deshaga un pago. Hoy no hay entrega real que conciliar (mock, scheduler apagado): se resuelve antes de producción |
| 4 | Replay de una transacción ya PAID, CANCELLED o vencida devolvía dtc_estatus: ACCEPTED | Resuelto: se devuelve el estado real (dtc_estatus) | Ver §2. status sigue ACCEPTED; una vencida que c2p:expire todavía no canceló sigue ACCEPTED |
| 5 | Una notifications_url guardada antes de la validación nueva no se revalida al enviar | «No hace falta» | La regla (https, sin credenciales) se aplica al guardar; un valor que ya estaba en la base se usa tal cual hasta que un Admin lo vuelva a guardar. La auditoría solo vuelca servidor y ruta, nunca el texto crudo |
| 6 | El mismo client_secret en sandbox y producción (decisión previa de Carlos, 2026-10-04) | Se mantiene el mismo: riesgo aceptado, aunque la especificación de Soterex pide credenciales separadas por ambiente | Lo que cambia entre ambientes es el client_id (cis_stg_… / cis_prod_…) y el host. Un secret filtrado vale para los dos y hay que rotarlo en los dos. El sign-off (3.1) lo dice tal cual |
| 7 | Infraestructura pendiente: Terraform todavía crea e inyecta soterex_username y soterex_password sin que ningún código los lea, y el flag enabled = true del scheduler de Staging no está aplicado | Pendiente de infra (es de Carlos: lo de infra/terraform/ no lo toca una sesión autónoma). El segundo punto, además, está en pausa (ver abajo) | Limpiar los secrets es un cambio de Terraform aparte. Sin el flag no sale ninguna notificación ni vence ninguna transacción |
El scheduler no se prende por ahora
Decisión de Carlos, 2026-10-05. Todavía no tiene la URL de Notifications ni el secret de Soterex, así que la integración sigue en modo mock y el scheduler no se prende por ahora. Quedan en pausa hasta que Soterex mande esos datos (no son pasos de ahora): prender el scheduler (el flag enabled = true de module "scheduler" y su terraform apply), el php artisan c2p:expire --dry-run en Staging, y cargar la URL y el secret en Configuración y pasar a Real. Los pasos están en staging.md marcados como tales.
Qué implica tenerlo apagado:
- Las notificaciones quedan
PENDINGen el outbox. Se encolan al pagar o cancelar, pero nadie correnotifications:deliver: ni siquiera el modomocklas da por entregadas (el mock acusa recibo cuando el comando corre). UnaPENDINGno se pierde. - El sandbox topa a los 50 disparos (
2208):sandbox/notifyrechaza el disparo 51 mientras haya 50 pendientes del cliente, y nada las vacía. Sean no puede seguir probando disparos hasta que se entreguen. - Las transacciones vencidas no se cancelan solas.
c2p:expireno corre: unaACCEPTEDde la API pasado su último día de cobro sigueACCEPTEDy no genera suCANCELLEDconCXL_EXPIRED.pay()ya impide pagarla (422MTCN_EXPIRED), así que no se cobra nada vencido; lo que falta es la cancelación y el aviso a Soterex. - Al prenderlo se envía lo acumulado, incluidas las pruebas viejas. La primera corrida arranca por las más antiguas, de a 50. Si el modo todavía es
mock, el mock las da por entregadas sin mandar nada; si ya esreal, salen a la URL de Soterex, también las de prueba que ya no importan. Antes de pasar a real hay que revisar la cola (la tarjeta «Notificación a Soterex» del detalle, o una consulta de solo lectura sobreoutbound_notificationsconstatus = 'PENDING'). No hay un comando para descartar una fila a mano. - El mail a Sean no puede prometer notificaciones reales hasta que esos datos estén. El borrador y el sign-off lo dicen: nada se entrega hasta tener su URL y su secret, y se les avisa cuando se prenda.
Apéndice: la revisión independiente y sus rondas de correcciones
Varios commits y comentarios del código dicen "revisión independiente, G", "ronda de correcciones, ítem C" o "revisión final #4". Esta es la clave. Después de K1 a K5 y K8, dos revisiones independientes (la primera con tres revisores, la segunda con un panel de ocho lentes: contrato, seguridad, camino de actualización, aceptación de Soterex, frontend, exactitud de la documentación, completitud del plan e higiene) encontraron cosas que se corrigieron en el mismo PR. Las letras A a H son los hallazgos de la primera ronda; los números #N y los códigos FE-N / SEC-N, los de la segunda.
Primera ronda: letras A a H
| Letra | Qué fue | Commits |
|---|---|---|
| A | Un falso positivo de colisión de MTCN: cualquier error de base que nombrara la columna se tomaba por colisión, y el replay en carrera reintentaba 10 veces y logueaba un agotamiento falso. Ahora solo cuenta el índice del propio MTCN | 86ba104 |
| B | El mutex del scheduler de notifications:deliver y c2p:expire duraba 24 horas por defecto: una corrida muerta frenaba todo un día. Pasó a 10 minutos | 4d1c385 |
| C | El limiter de la API C2P no hacía lo que decía: corría antes de la autenticación y firmaba por la IP del balanceador, así que un Bearer x agotaba el cupo de Soterex. Ahora es por cliente de la API, 60 por minuto, después de autenticar (ThrottleApiClient) | ec73f77, 823996e |
| D | La Notifications URL: https obligatorio, sin usuario, contraseña, parámetros ni fragmento, y cada cambio auditado como servidor y ruta | 4ee358d, 5926ba2 |
| E | El modo mock en producción daba por entregado lo que Soterex nunca recibió. Ahora falla (queda FAILED) y la pantalla avisa en rojo | 4ee358d, 5926ba2 |
| F | Un client_id mal formado (bytes nulos, caracteres de control, más de 255) daba un 500 sin autenticar y llegaba entero a la auditoría. Ahora es el 401 genérico sin tocar la base, y la auditoría guarda hasta 64 caracteres | f9b42ea |
| G | Los logs de la integración volcaban el mensaje de una QueryException, que trae el SQL con el nombre, el email, el teléfono y el MTCN del beneficiario. Ahora se reporta sin mensaje (SafeReport) | 270a929, 213d012, ab2a3a0 |
| H | Varios menores, numerados: H1 una transacción cuyo previous_transaction_id es el propio no figura como reemplazada por sí misma (55d948e); H2 el esquema Bearer no distingue mayúsculas (eec0499); H3 notifications:retry --all-failed (en 4ee358d); H4 el secret del webhook admite desde 8 caracteres, antes 16 (bb39818); H5 al revisar un tramo provisional sin mandar descripción, el servidor borra el «PROVISIONAL — reemplazar…» y lo audita (5fdc1fa) | los de cada uno |
Segunda ronda: la revisión final del panel
| Ítem | Qué se corrigió | Commit |
|---|---|---|
| #1 (SEC-01, FE-3) | Revocar un secret programado le devuelve la vigencia al anterior (restored_key_ids en la auditoría) | 2e3fe6a |
| #2 (SEC-02) | Un Bearer con formato imposible da 401 CODE_008 sin tocar la base (antes podía dar un 500) | e2d8e8e |
| #3 (FE-1) | CORS expone Retry-After y X-RateLimit-* al navegador | 76458a2 |
| #4 | Una sola definición de ambiente de pruebas, con lista blanca (local, testing, staging) | eff42da |
| #5 | notifications:deliver reserva fila por fila, con tope de 50 filas y 480 s, y entrega por created_at | 080b2da |
| #6 | Los secrets del webhook: altas y revocaciones serializadas, expresiones con /D, mensajes 422 en español | 12ce183 |
| #7, #48 | Todo error de /api/oauth/* y /api/c2p/* sale en JSON con su envelope, con o sin Accept | 75958b2 |
| #8, #9 | origin_currency solo USD y sender solo US, y mensajes de rechazo que dicen qué falló | 4fe7555 |
| #40 | El segundo nivel de paying_office (el PDV de la caja) se prueba a través de pay() real | eaa4a5b |
| FE-2, FE-5, FE-7, FE-8 | Frontend: el detalle no deja los datos de la transacción anterior si falla la carga de otra; sin escritura no hay alta ni «Revocar» de secrets y un 403 se dice; el modal del tramo se anuncia como diálogo; un estado de entrega desconocido no rompe la tarjeta | a99ec03, c6debb1, 7dabd2d, 38f2984, 25b6927 |
| DOC-01, DOC-02, #16, #27, #29 a #36, #41, #46 | La documentación: el sign-off ya no promete que la entrega espera un secret, el mail no pega el secret, el OpenAPI refleja el orden real de validación, la nota interna salió del sign-off, y esta clave | los docs(c2p): K7 |
Los comentarios del código con una letra o un #N se refieren a esta tabla.
Tercera ronda: las decisiones de Carlos y las correcciones del 2026-10-05
Los commits fix(c2p): decisión — y docs(c2p): decisión — son lo que Carlos decidió ese día en el chat; los fix(c2p): rotas — son cosas que se encontraron rotas o inconsistentes después de la segunda ronda y se corrigieron en el mismo PR.
| Qué | Dónde está documentado | Commit |
|---|---|---|
| El tarifario provisional de Guatemala son 50.00 USD fijos, sembrados en todos los ambientes | ADR-018 (Actualización) | e0c8a38 |
El replay devuelve el estado real en dtc_estatus | §2 de este ADR | 53219f7 |
El tipo de cambio vigente desempata por id cuando dos altas caen en el mismo segundo (effective_from es timestamp(0); con un empate el vigente quedaba a merced del plan de Postgres) | doc/manual/70-tipo-cambio.md | 2d3fd86, 60a225b |
Una comisión mayor que el principal se da de alta, se paga y descuenta bien (ComisionMayorQuePrincipalTest) | ADR-018 (Actualización, efecto 1) | c66c047 |
Las guardas de producción de comandos y seeders pasan por DeploymentEnvironment | §7 de este ADR | 99791e6 |
El historial del detalle atribuye a la API de Soterex el cambio de estado que hizo ella (by_api_client en cada asiento; antes salía como «Sistema») | doc/manual/20-transacciones.md | 4d21629, 796d432 |
| Configuración: sin permiso de escritura no hay «Guardar» y un 403 dice qué no se pudo hacer | doc/manual/84-admin-configuracion.md | 95b2f9d |
| Pagar y guardar datos del pago mandan solo los 13 campos del pago (interno: no cambia nada visible) | — | cc09a9d |
c2p:expire se registra antes que notifications:deliver | doc/environments/staging.md (sección del scheduler) | 4cb0dbb |
| El job de frontend del CI corre vitest, y un job nuevo comprueba que los dos OpenAPI sean idénticos | doc/environments/dev.md | 740b10e |

