ADR-012: Dirección de la integración (Soterex llama a CIS) y OAuth 2.0 Client Credentials
Date: 2026-09-30 Status: Accepted — en implementación 2026-09-30 (feature/api-c2p-entrante) Superseded in part by: ADR-017 (2026-10-05) — el contrato de SendRequest, Cancel y Notifications (§5 y §6: envelope y códigos, expirate_date, idempotencia con 2001, sub_status obligatorio, notificación plana con auth HTTP Basic, sin notificar el CANCELLED pedido por Soterex) y la IP allowlist (§7): ahora manda la especificación de Soterex; la dirección, OAuth, los clientes y el MTCN siguen vigentes Superseded in part by: ADR-018 (2026-10-05) — la D13 (fee obligatorio en el request de SendRequest): ahora lo calcula CIS Ver también: ADR-005 (comisión fuera de la caja, sigue vigente), ADR-007 (la comisión descuenta solo la Holding)
Context
El Análisis Funcional de julio (doc/functional/2026-07-24-soterex-integracion/) documentó la integración con Soterex como pull: la WebApp (esta app) llama a tokenC2P y SendRequest de Soterex por un cron cada 30 minutos, y a Cancel cuando un Backoffice cancela desde la app. Esa lectura dejó una pregunta bloqueante desde julio, la #2b: si es la WebApp quien llama a Soterex, ¿cómo le llega una cancelación que decide Soterex? Ninguna de las tres opciones que planteaba el propio documento (traerla en la respuesta del cron, un endpoint no documentado, o que en la práctica nunca pase) se pudo cerrar, y quedó como el único punto realmente bloqueante para avanzar M5.
El 2026-09-18, Sean Rahimi (Prutech, del lado de Soterex) escribió pidiendo credenciales OAuth 2.0 Client Credentials para que Salesforce (donde vive la integración del lado de Soterex) llame a "las APIs de CIS". Eso es exactamente lo opuesto al modelo documentado: es Soterex quien llama a CIS, no al revés.
El propio material de julio ya lo delataba, releído con este dato nuevo:
openapi.yamlse titula "CIS Latam × Soterex — C2P Transactional APIs", con servers enapi.cislatam.net(no en un dominio de Soterex) — son APIs de CIS, aunque el título nombre a los dos.SendRequest"registra la solicitud y devuelve el MTCN y elfee". Quien genera un código y lo devuelve es quien responde a la llamada, no quien la hace.- El job
RunSoterexSendRequest(app/Jobs/, disparado cada 30 min desderoutes/console.php) nunca se pudo implementar — su propio TODO dice que Soterex no expone un endpoint para "listar pendientes". No existe ese endpoint porque no hace falta: no es Soterex quien tiene que listar nada, es CIS quien recibe la solicitud directamente.
La pregunta #2b se disuelve, no se resuelve con una opción de las tres que planteaba: no hace falta que la WebApp se entere de una cancelación de Soterex por un canal indirecto, porque la cancelación entra directo por nuestro propio endpoint Cancel, igual que la creación entra por SendRequest.
Decision
1. CIS expone la API; Soterex es el cliente (D1)
Se invierte el modelo: CIS expone POST /api/c2p/v1/SendRequest y POST /api/c2p/v1/Cancel; Soterex (desde Salesforce) los llama. Esto reemplaza el modelo pull del Análisis Funcional y cierra la pregunta #2b — una cancelación de Soterex ya no necesita un canal aparte, es una llamada más a Cancel.
Lo que no cambia: el pago en ventanilla, las tres capas de prefondeo (ADR-007), Caja, documentos, papeleta. Todo eso sigue operando sobre la transacción una vez que existe — lo único que cambia es cómo nace (por API en vez de por seeder/demo, cuando M5 esté activo).
2. Auth: OAuth 2.0 Client Credentials estándar, no el tokenC2P del spec v1.4 (D2–D5)
POST /api/oauth/token implementa RFC 6749 §4.4 puro — no el tokenC2P documentado (usuario y contraseña propios, respuesta envuelta en entityResponse). Salesforce Named Credentials consume Client Credentials estándar sin código custom; envolver la respuesta en un formato propietario obligaría a Sean a escribir un adapter en Salesforce, que es justo lo que Client Credentials evita.
Se acepta el pedido de token de las dos formas que trae Salesforce: client_secret_basic (header Authorization: Basic) y client_secret_post (body). Sin scope obligatorio (se acepta y se ignora scope=c2p si lo mandan) y sin audience. Respuesta JSON plano, Cache-Control: no-store, errores RFC 6749 §5.2 (invalid_client 401, sin distinguir si falló el client_id o el secret).
La implementación reusa Laravel Sanctum (ya en composer.json, sin uso todavía en el código): tokens opacos, hasheados con SHA-256 por el propio Sanctum, tokenable = un modelo nuevo ApiClient (no User — la auth de máquina queda separada de la de humanos, que sigue siendo 100% Firebase). Se agrega una ability c2p y un guard/middleware propio (auth.c2p), para que un token de máquina nunca abra un endpoint humano ni viceversa.
3. Clientes y secrets con rotación (D6–D8)
Dos tablas nuevas: api_clients (uno por ambiente — el de staging no sirve en producción) y api_client_secrets, con más de un secret vigente por cliente a la vez. Eso es lo que permite rotar con solapamiento: api-client:rotate-secret {client} --overlap=24h agrega un secret nuevo y vence el anterior a las 24 h en vez de invalidarlo al instante; revocación inmediata aparte con api-client:revoke-secret.
El secret en claro nunca pasa por un log remoto. El workflow run-artisan-command.yml vuelca la salida del comando en los logs de GitHub Actions — un api-client:create que generara e imprimiera el secret ahí lo filtraría. Por eso el flujo es: el secret se genera en la máquina de Carlos (php artisan api-client:generate-secret, corre local, nunca en CI), que devuelve el secret en claro y su hash Argon2id en base64; en staging solo corre api-client:create --secret-hash-b64=<hash>, que nunca ve ni imprime el secret real. api-client:list no imprime secrets ni hashes bajo ninguna circunstancia.
4. MTCN aleatorio y único, nunca reutilizado (D11)
El Análisis Funcional decía "secuencial", heredado de la macro del Excel original, y el único generador que existe hoy (DemoTransactionSeeder) es en efecto un contador secuencial con zero-padding — no hay ninguna lógica de producción todavía. Un MTCN secuencial es enumerable: es exactamente lo contrario del anti-enumeración que ya se construyó en Pago (E2, búsqueda solo por MTCN exacto, 404 ambiguo). El MTCN es lo que el beneficiario presenta en el mostrador para cobrar — que sea adivinable es un riesgo real, no teórico.
El MTCN pasa a ser 10 dígitos de un CSPRNG (random_int), único en toda la tabla transactions (incluidas las de demo, las históricas y las canceladas), nunca reutilizado. La unicidad la garantiza un índice único en la base sobre mtcn (ya existe desde la migración original) — no un chequeo previo en PHP, que tendría una carrera de por medio. Se inserta y, si choca con el índice, se regenera y se reintenta, con un tope de intentos y error 500 logueado si se agota (con 10 dígitos aleatorios y un volumen de transacciones bajo, la probabilidad de colisión es mínima, pero el reintento cubre el caso igual). Los MTCN de demo (0000000001…) no se tocan — el generador nuevo solo corre para transacciones creadas por API.
5. SendRequest, Cancel, fee obligatorio y expirate_date (D9–D13)
Reemplazado en parte el 2026-10-05 por ADR-017 y ADR-018. Lo que sigue es el contrato del 2026-09-30 y ya no rige en esto: el envelope y los códigos del spec v1.4, el éxito
COD_001yCOD_002, los rechazos HTTP 400 conCODE_002yerrorDetails,expirate_date, elfeeobligatorio en el request, la idempotencia con el error2001y elCancelconsub_statusobligatorio (2108,2109). Hoy manda la especificación de Soterex: ver la tabla «Qué reemplaza de ADR-012» de ADR-017. Sigue vigente queSendRequestcrea la transacciónACCEPTEDsin PDV, el MTCN y queCancelbusca por cliente,transaction_idytoken.
Se mantienen los paths, envelopes (code/status/dtc_estatus/message/entityResponse) y códigos de error (1xxx/2xxx) del spec v1.4 — es el contrato que Soterex ya conoce, no hay razón para romperlo. Solo se adapta destination_country a los países habilitados en ABM Países (GT hoy, no el ^VE$ original).
SendRequest crea la transacción ACCEPTED, sin PDV (misma bolsa compartida por país que ya existe hoy para las transacciones de demo), guarda qué ApiClient la creó y responde COD_001 sin validar prefondeo — el pago sigue validando la caja, no el prefondeo del país (ADR-007 §2), y eso no cambia para las transacciones que entran por API.
La comisión (fee) la manda Soterex (confirmado por Carlos, 2026-09-30) — ADR-005 sigue vigente, no se construye ningún motor de comisiones. La diferencia es de dónde viaja: el spec v1.4 solo tenía fee en la respuesta, porque se escribió para el modelo pull (invertido). Con el modelo correcto, fee viaja en el body de SendRequest como campo obligatorio (mismo formato que amount), CIS lo guarda tal cual en transactions.fee (columna que ya existe) y lo devuelve sin modificar en la respuesta. Sigue siendo información restringida — no se muestra en pantallas operativas de Pago — y descuenta solo de la Holding, no de Caja ni del prefondeo del país (ADR-007). Se le avisa a Sean en el mail de C5 que el request ahora lleva fee.
Cancel valida que transaction_id y token (MTCN) coincidan y sean del mismo cliente que hizo el SendRequest original, y que la transacción siga ACCEPTED — si ya está PAID, rechazo con código de negocio; si ya está CANCELLED, responde idempotente con el estado actual en vez de error. La regla de "solo se puede cancelar si sigue ACCEPTED, con lock pesimista dentro de una transacción de DB" ya existe en TransactionController::cancel (el cancel humano, desde Backoffice) — se extrae a un servicio compartido para no duplicar esa regla entre el cancel humano y el de API. Esto es, en los hechos, el cierre operativo de la pregunta #2b: la cancelación de Soterex entra por acá.
expirate_date = fecha de alta + N días, con N configurable por país (default 30, provisional — se confirma con Soterex en el mail de C5). Se guarda en transactions.expires_at, columna que ya existe. El vencimiento automático (pasar a EXPIRED o similar al cumplirse el plazo) queda fuera de esta entrega.
Idempotencia de SendRequest (cierra la pregunta abierta #12 del Análisis Funcional, que había quedado resuelta bajo el modelo pull): un reintento con el mismo transaction_id (para el mismo ApiClient) se resuelve comparando el payload nuevo contra los datos ya guardados de la transacción existente, campo por campo (first_name, last_name, amount, fee, destination_country, sender, origin_currency, traveling_with_minors, minor_full_name, alien_registration_number, email, phone) — no hace falta una columna de hash aparte, esos campos ya están en transactions. Si todos coinciden, es un reintento genuino (típicamente por timeout del lado de Salesforce): se devuelve la misma respuesta original (mismo MTCN, mismo fee, misma expirate_date), sin crear una segunda transacción. Si alguno difiere, es un conflicto real (el transaction_id se reutilizó con datos distintos): error 2001 (duplicado). No hace falta el endpoint de consulta alternativo que el plan dejaba como respaldo (b) — comparar contra la fila existente alcanza y es más simple.
6. Notifications sale por outbox, nunca dentro del request de pago (D15)
Reemplazado en parte el 2026-10-05 por ADR-017. El outbox sigue siendo el mecanismo. Ya no rige: que no se notifique el
CANCELLEDque pidió Soterex (hoy se notifica toda cancelación), el payload plano, la auth con HTTP Basic de placeholder (hoy el webhook se firma con HMAC-SHA256) ni el modo mock mientras no haya URL (en producción el mock no existe).
CIS notifica a Soterex en PAID y en CANCELLED iniciado por CIS (no se notifica un CANCELLED que pidió el propio Soterex, salvo que ellos lo pidan explícitamente — se pregunta en el mail). El envío usa un outbox (tabla outbound_notifications + comando notifications:deliver con backoff) en vez de un POST síncrono dentro del flujo de pago: en staging la cola es sync y el scheduler está apagado, así que un POST externo colgado adentro del pago colgaría la ventanilla. Mientras no haya notifications_url ni el método de auth de Soterex confirmados, el Notification queda en modo mock (se encola igual, visible en la base, pero no sale a ningún lado real) — ambos datos se piden en el mail de C5.
7. Seguridad perimetral en sandbox: solo TLS (D17)
Reemplazado en parte el 2026-10-05 por ADR-017 (D10). Ya no se pregunta ni se aplica una IP allowlist: CIS no la exige y la IP de salida de producción se informa cuando se provisione. El límite de pedidos de
/api/c2p/*pasó a ser por cliente de la API (ver la aclaración al final de esta sección).
Sin mTLS y sin IP allowlist para esta entrega — el ALB ya exige TLS 1.2+, y alcanza para sandbox. allowed_ips en api_clients queda implementado y vacío; en producción se puede cargar el rango de egress de la org de Salesforce de Soterex si lo piden (se pregunta en el mail). Throttle propio en /api/oauth/token y en /api/c2p/*, independiente del WAF — la regla rate-based del WAF (2000 req/5 min por IP) puede ser compartida entre orgs de Salesforce distintas del lado de ellos; para sandbox alcanza, se documenta como riesgo a revisar antes de producción.
Aclaración 2026-10-05 (revisión independiente de la alineación al contrato). El throttle de
/api/c2p/*de arriba (throttle:c2p, porclient_id+ IP) no hacía lo que decía, y se reemplazó.ThrottleRequestscorre por prioridad antes de la autenticación, así que nunca veía al cliente (la clave erasin-client-id|<IP>para todos) y, detrás del ALB sintrustProxies, esa IP es la del balanceador: todo el tráfico, incluido el de un tercero conBearer x, compartía un único cupo de 60/min y cualquiera podía dejar a Soterex con429. Ahora un middleware propio (ThrottleApiClient, aliasthrottle.client:60,1) corre después deauth.c2py limita porApiClient, 60/min, un solo cupo para SendRequest, Cancel y el endpoint a demanda del sandbox (orden:c2p.sandbox→auth.c2p→throttle.client). Un request sin token válido responde401y no consume ningún cupo compartido. El429sigue siendo el envelopeCODE_429conRetry-After. Dos notas honestas que quedan: (1) el limiter de/api/oauth/tokensigue porclient_id+ IP y, mientras no se configuretrustProxies(decisión de infra), comparte el cupo de la IP del ALB: un tercero que conozca elclient_id(dato público) puede agotar los 30 intentos/min de ese cliente —o, con cualquierclient_id, los 60/min de la IP— y que el pedido de token de Soterex dé429un rato (los tokens ya emitidos duran una hora y Soterex reintenta). No permite autenticarse, pero es una molestia real. (2) El control por IP real lo da la regla rate-based del WAF, no esta capa.
Alternatives Considered
- Implementar el
tokenC2Pdel spec v1.4 tal cual (usuario/contraseña propios, envelopeentityResponse) — descartado: Salesforce Named Credentials no sabe leer un token adentro de un formato propietario sin código custom de su lado: obligaría a Sean a escribir un adapter para algo que Client Credentials estándar resuelve gratis. - JWT firmado en vez de tokens opacos de Sanctum — descartado: Sanctum ya está en el proyecto sin usarse, cubre exactamente este caso (tokens de máquina con abilities y expiración), y no agrega la complejidad operativa de gestionar claves de firma.
- Un solo secret por cliente, sin rotación con solapamiento — descartado: Sean preguntó explícitamente por rotación con 24 h de solapamiento (pregunta 7 de su mail); un solo secret activo obliga a coordinar un corte exacto entre Carlos y Sean, que es justo lo que el solapamiento evita.
- Chequear unicidad del MTCN en PHP antes de insertar — descartado: dos requests concurrentes podrían generar el mismo MTCN y pasar el chequeo antes de que ninguno de los dos hubiera insertado todavía (TOCTOU). El índice único en la base más reintento ante colisión no tiene esa ventana.
- POST síncrono a Soterex dentro del handler de
pay()para Notifications — descartado: sin scheduler activo en staging y con la cola en modosync, un POST externo lento o caído colgaría el pago en ventanilla. El outbox lo desacopla.
Consequences
- Positivo: cierra la pregunta #2b, que era la única bloqueante del Análisis Funcional desde julio. El modelo queda alineado con lo que Soterex realmente necesita, sin esperar que ellos cambien nada de su lado.
- Positivo: Sanctum, ya presente como dependencia sin usar, cubre el caso completo (tokens de máquina, expiración, abilities) sin necesidad de una librería nueva.
- Negativo: hay que borrar código que se había escrito para el modelo pull (
RunSoterexSendRequest, los métodostoken/sendRequest/canceldeSoterexClient) — trabajo que no se pierde en el sentido de aprendizaje (confirmó que el modelo estaba invertido), pero sí en horas de implementación previas. - Negativo: el MTCN aleatorio con reintento agrega una dependencia de timing (aunque mínima) al insert de
SendRequest, comparado con un contador secuencial directo — aceptable dado el volumen esperado y que la alternativa (secuencial) es un riesgo de seguridad real, no cosmético. - Neutral:
expirate_datecon N configurable por país queda con un default provisional (30 días) hasta que Soterex lo confirme — no bloquea la implementación, pero el valor real puede cambiar sin tocar código (es de configuración, no está hardcodeado en la lógica). - Neutral: la seguridad perimetral de sandbox (solo TLS, sin mTLS/IP allowlist) es deliberadamente mínima — producción necesita revisar esto de nuevo antes de ir con datos reales, ya documentado como pendiente explícito.

