Skip to content

Plan — API C2P entrante para Soterex (Salesforce) ​

Date: 2026-09-30 Branch: feature/api-c2p-entrante

Fuente: mail de Sean Rahimi (Prutech, del lado de Soterex), 2026-09-18, "Re: Technical Kick Off CIS APIs". Sean está configurando en Salesforce las llamadas a "las APIs de CIS" con OAuth 2.0 Client Credentials (External Credentials + Named Credentials). Para eso pide siete datos del sandbox, con las diferencias de producción:

  1. URL del token.
  2. URL base y paths de Send y Cancel.
  3. client_id y client_secret del sandbox, por un canal seguro.
  4. Formato del pedido de token: Basic o body, content type, scopes, audience.
  5. Formato de la respuesta del token, su vida útil (expires_in) y el header Authorization.
  6. Requisitos de seguridad adicionales: IP allowlisting, mTLS, clientes separados por ambiente.
  7. Rotación del secret, y si se admite un solapamiento de 24 h.

Lo que lo bloquea hoy es la URL del token y las credenciales de sandbox.

Actualizado 2026-09-30: Carlos confirmó que la comisión la manda Soterex (D13) y que el MTCN es aleatorio y único (D11).

Qué es esto: el análisis de ese pedido contra el sistema y la documentación funcional, las decisiones tomadas y el plan de implementación. El resultado final es la información lista para mandarle a Soterex sobre staging.


0. Hallazgo principal: la documentación tiene la integración al revés ​

Lo que dice la documentación (Análisis Funcional 2026-07-24, 00-resumen.md, 06-preguntas-abiertas.md #2; openapi.yaml; SoterexClient):

  • La WebApp llama a Soterex: tokenC2P y SendRequest desde un cron cada 30 min, y Cancel cuando Backoffice cancela.
  • Notifications va de la WebApp hacia Soterex.

Lo que dice Sean: Soterex llama a CIS. Ellos piden un token a CIS y llaman a los endpoints Send y Cancel de CIS.

El pedido de Sean es el correcto. La documentación interpretó mal el kick-off, y el propio material lo delata:

  • El openapi.yaml se titula "CIS Latam — C2P Transactional APIs", con servers en api.cislatam.net. Son APIs de CIS.
  • SendRequest "registra la solicitud y devuelve el MTCN y el fee". Quien genera el MTCN y la comisión es el que responde, o sea CIS. Nadie le pide a otro que le devuelva un código que genera uno mismo.
  • El job RunSoterexSendRequest nunca se pudo implementar. Su TODO lo dice: "Soterex no expone en el spec un endpoint de listar pendientes". No existe porque no es Soterex quien las lista.
  • La pregunta abierta #2b (cómo llega una cancelación iniciada por Soterex), bloqueante desde julio, se disuelve: llega por nuestro Cancel.
  • La comisión la manda Soterex (confirmado por Carlos, 2026-09-30): ADR-005 sigue vigente. Como ahora Soterex es quien llama, el fee viaja en el body de SendRequest (Soterex → CIS) y CIS lo devuelve tal cual en la respuesta. El spec v1.4 no lo tiene en el request: se agrega y se le avisa a Sean en el mail.

Modelo correcto (push):

Soterex (Salesforce)                         CIS (esta app, api.soterex.*.cislatam.net)
  │  POST /api/oauth/token  (client credentials)  ──▶  emite access_token (1 h)
  │  POST /api/c2p/v1/SendRequest  (Bearer, +fee)  ──▶  crea tx ACCEPTED con su fee, genera MTCN
  │                                              ◀──  { token: MTCN, expirate_date, amount, fee }
  │  POST /api/c2p/v1/Cancel  (Bearer)            ──▶  cancela si sigue ACCEPTED
  │
  ◀──  POST <notifications_url de Soterex>             CIS avisa PAID / CANCELLED (por CIS)

Lo que no cambia: el pago en ventanilla, las tres capas de prefondeo (ADR-007), Caja, documentos, papeleta. Todo eso opera sobre la transacción una vez que existe; lo único que cambia es cómo nace.


1. Decisiones (tomadas por PO el 2026-09-30; Carlos puede vetarlas) ​

#DecisiónPor qué
D1CIS expone la API y Soterex es el cliente. Se registra en ADR-012, que reemplaza el modelo pull del Análisis Funcional y cierra #2b.§0
D2Auth = OAuth 2.0 Client Credentials estándar (RFC 6749 §4.4) en POST /api/oauth/token. No se implementa el tokenC2P del spec v1.4 (usuario y clave, respuesta envuelta en entityResponse), porque Salesforce Named Credentials no sabe leer un token dentro de un envelope propietario.Es lo que pide Sean, y es lo único que Salesforce consume sin código custom
D3El pedido de token acepta las dos formas: client_secret_basic (header Authorization: Basic base64(id:secret)) y client_secret_post (client_id/client_secret en el body). Content type application/x-www-form-urlencoded, grant_type=client_credentials. Sin scope obligatorio (se acepta y se ignora scope=c2p) y sin audience.Salesforce trae un toggle entre body y header; que funcionen los dos evita un ida y vuelta
D4Respuesta RFC 6749 §5.1, JSON plano: {"access_token","token_type":"Bearer","expires_in":3600,"scope":"c2p"}, con Cache-Control: no-store. Errores RFC 6749 §5.2 (invalid_client 401 con WWW-Authenticate, unsupported_grant_type 400, invalid_request 400). Header de las APIs: Authorization: Bearer <access_token>.Estándar. 1 h es el valor habitual, y Salesforce renueva solo ante un 401
D5Tokens opacos con Sanctum (ya está en composer.json), con tokenable = el modelo nuevo ApiClient, expires_at a 1 h y ability c2p. El token se guarda hasheado (SHA-256, lo hace Sanctum). Se crea un guard y un middleware propios para /api/c2p/*, separados del auth de Firebase de los usuarios humanos.Reusa una dependencia existente; no hace falta firmar JWT ni gestionar claves
D6Clientes y secrets: tabla api_clients (nombre, client_id público con prefijo por ambiente, p. ej. cis_stg_…, activo, allowed_ips nullable) y tabla api_client_secrets (hash Argon2id, expires_at nullable, revoked_at, last_used_at). Un cliente puede tener más de un secret vigente: así se hace la rotación con solapamiento. Un cliente por ambiente: el de staging no sirve en producción.Pregunta 6 y 7 de Sean
D7Rotación: api-client:rotate-secret {client} --overlap=24h agrega un secret nuevo y le pone vencimiento al anterior. El solapamiento de 24 h está soportado (configurable). Los tokens ya emitidos con el secret viejo siguen valiendo hasta que expiran (≤1 h). Revocación inmediata con api-client:revoke-secret.Pregunta 7
D8El secret nunca pasa por logs de CI. run-artisan-command.yml muestra la salida del comando en los logs de GitHub Actions, así que un comando que imprima el secret en staging lo filtra. Flujo: Carlos genera el secret en su máquina (php artisan api-client:generate-secret local, o cualquier CSPRNG), que le devuelve el secret y su hash Argon2id en base64 (el workflow parte el comando por espacios y el hash tiene $). En staging solo corre api-client:create soterex --secret-hash-b64=<…>. El secret en claro solo lo tienen Carlos y Sean.Seguridad; el workflow hace split(" ") del input
D9Paths de negocio: se mantienen los del spec v1.4, POST /api/c2p/v1/SendRequest y POST /api/c2p/v1/Cancel, con los mismos envelopes (code/status/dtc_estatus/message/entityResponse) y los mismos códigos de error (1xxx, 2xxx). Solo se adaptan los valores a Guatemala: destination_country = un país habilitado en ABM Países (hoy GT), no ^VE$.Es el contrato que Soterex ya conoce
D10SendRequest: valida según el spec; transaction_id duplicado para ese cliente → error 2001 (el spec lo declara suficiente, #12). Crea la tx ACCEPTED, sin PDV (bolsa del país, como hoy), guarda qué ApiClient la creó y el fee recibido, genera el MTCN y responde COD_001. No valida prefondeo: el pago valida la caja (ADR-007 §2). Idempotencia ante reintentos por timeout: un reintento con el mismo transaction_id y el mismo payload devuelve la respuesta original, en vez de 2001, si el spec lo permite; si no, 2001 más una forma de consultar. Decidirlo y documentarlo en ADR-012.—
D11El MTCN es aleatorio, no secuencial, y ÚNICO (confirmado por Carlos, 2026-09-30): 10 dígitos de un CSPRNG (random_int), único en toda la tabla transactions (incluidas las de demo, las históricas y las canceladas; un MTCN nunca se reutiliza). La unicidad la garantiza la base con un índice único sobre mtcn (verificar si ya existe; si no, crearlo), no un chequeo previo en PHP: se inserta y, si choca con el índice, se genera otro y se reintenta (tope de intentos, error 500 logueado si se agota). Test que fuerce una colisión. El Análisis Funcional decía "secuencial", heredado de la macro del Excel. Pero el MTCN es lo que presenta el beneficiario para cobrar, y uno secuencial es enumerable, lo contrario del anti-enumeración que se construyó en Pago (E2). Los MTCN de demo (0000000001…) no se tocan.Seguridad
D12expirate_date = alta + N días, con N configurable por país (default 30, provisional; se confirma con Soterex/CIS). Se guarda en transactions.expires_at, que ya existe. Esta entrega no agrega el vencimiento automático.El spec lo exige en la respuesta
D13La comisión (fee) la manda Soterex (Carlos, 2026-09-30; ADR-005 sigue vigente, no hay motor de comisiones). Se agrega fee como campo obligatorio del body de SendRequest, con el mismo formato que amount (^\d+(\.\d{1,2})?$, ≥ 0), y con código de error nuevo en la serie 2xxx (falta / inválido; elegir los siguientes libres y documentarlos). Se guarda en transactions.fee y se devuelve tal cual en la respuesta. Sigue siendo información restringida (§2.5 de roles) y descuenta solo de la Holding (ADR-007). Hay que avisarle a Sean que el request lleva fee.El spec v1.4 lo tenía solo en la respuesta, porque se escribió pensando en el modelo invertido
D14Cancel (iniciado por Soterex): valida que transaction_id y token (MTCN) coincidan y sean de ese cliente, y que la tx esté ACCEPTED (PAID → rechazo con código de negocio; ya CANCELLED → idempotente, devuelve el estado). Guarda sub_status y audita con actor = el ApiClient. Reusa el mismo lock que TransactionController::cancel: extraer un servicio para no duplicar la regla.Cierra #2b
D15Notifications (CIS → Soterex) en PAID y en CANCELLED iniciado por CIS. No se notifica un CANCELLED que pidió el propio Soterex, salvo que lo pidan. Se hace con outbox: tabla outbound_notifications y un comando notifications:deliver que reintenta con backoff. El envío nunca va dentro del request de pago. Mientras no haya notifications_url y auth de Soterex, queda en modo mock y se encola igual (se ve en la base). Faltan del lado de Soterex la URL y su método de auth: se piden en el mail.En staging la cola es sync y el scheduler está apagado; un POST externo dentro del pago lo colgaría
D16Limpieza del modelo pull: se borran RunSoterexSendRequest, su entrada en routes/console.php y los métodos token/sendRequest/cancel de SoterexClient. SoterexClient pasa a ser solo el cliente de Notifications. SoterexSetting y la pantalla Configuración se reducen a lo que sigue teniendo sentido: modo mock/real, notifications_url y la auth hacia Soterex. Revisar la migración de datos de soterex_settings (hay credenciales viejas en staging, en modo mock).Código muerto que además documenta lo contrario de la realidad
D17Seguridad perimetral en sandbox: solo TLS (el ALB ya exige TLS 1.2+), sin mTLS y sin IP allowlist. allowed_ips queda implementado y vacío; en producción se puede cargar el rango de egress de Salesforce de su org si ellos lo quieren. Revisar la regla rate-based del WAF (2000 req/5 min por IP): Salesforce comparte IPs de salida entre orgs. Para staging alcanza; documentarlo como riesgo para producción. Throttle propio en /api/oauth/token (p. ej. 30/min por client_id+IP) y en /api/c2p/*.Pregunta 6
D18La referencia de API (openapi.yaml, Scalar) se reescribe al modelo correcto: server de staging real, flujo OAuth (securitySchemes.oauth2.clientCredentials), sin tokenC2P, Notifications como webhook saliente. Además se genera un openapi exportable para mandarle a Sean como archivo: el Scalar de staging está detrás del SSO de CIS (ADR-004) y Soterex no tiene acceso.Sean necesita el contrato

2. Entregas (todas en feature/api-c2p-entrante, en este orden) ​

C1 — ADRs y documentación funcional ​

  • ADR-012 "Dirección de la integración: Soterex llama a CIS (C2P entrante) y OAuth 2.0 Client Credentials" (D1–D11, D14–D17).
  • ADR-005 no se toca: la comisión la sigue mandando Soterex (D13). En ADR-012 aclarar que ahora viaja en el request de SendRequest.
  • Corregir el Análisis Funcional de doc/functional/2026-07-24-soterex-integracion/: en 00-resumen, 03-user-flows, 04-diagramas-actividad y 06-preguntas-abiertas (#2 y #2b) hay que agregar CORREGIDO (2026-09-30), con el mismo estilo que ya usan esos archivos. No reescribir la historia.
  • Actualizar CLAUDE.md: el bloqueante #2b se cierra y M5 cambia de forma.

C2 — OAuth: clientes, secrets, tokens ​

  • Migraciones api_clients y api_client_secrets; modelo ApiClient con HasApiTokens.
  • POST /api/oauth/token (D2–D4). Tiempo constante al comparar, sin revelar si falló el client_id o el secret (ambos → invalid_client). Actualiza last_used_at. Audita la emisión (sin el token).
  • Middleware auth.c2p: Bearer de Sanctum, tokenable ApiClient activo, ability c2p, no vencido, IP permitida si hay allowlist.
  • Comandos artisan (D6–D8): api-client:generate-secret (local, imprime secret y hash-b64), api-client:create {name} --secret-hash-b64=, api-client:rotate-secret {client} --secret-hash-b64= --overlap=24h, api-client:revoke-secret {client} {secret_id}, api-client:list (nunca imprime secrets ni hashes). Verificar que run-artisan-command.yml pase bien un argumento base64 largo (sin espacios, puede tener =).
  • Tests: las dos formas de auth, secret malo, cliente inactivo, secret vencido o revocado, solapamiento (los dos secrets valen), token vencido → 401, grant_type incorrecto.

C3 — SendRequest y Cancel ​

  • fee obligatorio en el request (D13), guardado en transactions.fee.
  • MTCN aleatorio con índice único y reintento (D11).
  • Columnas nuevas en transactions: api_client_id, external_transaction_id (el transaction_id de Soterex, único por cliente), sub_status_code y sub_status_message si no existen. Revisar las columnas actuales antes de crear.
  • POST /api/c2p/v1/SendRequest (D9–D12), POST /api/c2p/v1/Cancel (D14). Validaciones y códigos exactamente como el spec.
  • Extraer el servicio de cancelación compartido con TransactionController::cancel.
  • Verificar punta a punta que una tx creada por API aparece en Transacciones y en Pago, se puede pagar, descuenta Holding (principal + fee) y caja, y sale en Reportes con su comisión.
  • Tests de cada código de error del spec y del ciclo completo.

C4 — Notifications salientes y limpieza ​

  • Outbox y notifications:deliver (D15); hook en pay y en el cancel iniciado por CIS.
  • Limpieza del modelo pull (D16), incluyendo la pantalla de Configuración y sus tests.
  • Si hace falta prender el scheduler en staging para el outbox, no se toca Terraform: documentarlo como paso pendiente, porque requiere el ok de Carlos.

C5 — Contrato y entregables para Soterex ​

  • Reescribir doc/site/public/openapi.yaml (D18).
  • doc/integracion/2026-09-30-soterex-staging.md, en español para Carlos, con:
    1. El mail de respuesta a Sean, en inglés, listo para copiar, respondiendo las 7 preguntas con valores reales de staging y lo que cambia en producción. Las credenciales quedan como <<CLIENT_ID>>/<<CLIENT_SECRET>>, porque se mandan aparte y 1 a 1 (el mail va con mucha gente en copia).
    2. Lo que le pedimos a Soterex en el mismo mail: la URL de Notifications y su método de auth, si quieren IP allowlist en producción, contacto técnico para la prueba, y que confirmen la vigencia del MTCN. Además, avisarles que el body de SendRequest lleva fee (obligatorio), con su formato.
    3. Pasos de Carlos a la mañana, en orden y con los comandos exactos: revisar el PR → mergear a main → pasar a staging → generar el secret local → correr el workflow → probar con curl contra staging → mandar el mail → mandar las credenciales por canal seguro.
    4. Ejemplos curl del token, SendRequest y Cancel, con respuestas de muestra sin valores sensibles.
  • Adjunto para Sean: el openapi exportado (D18).

3. Lo que queda fuera (a propósito) ​

  • Deploy a staging, merge a main, crear el cliente real, Terraform (scheduler, WAF). Todo eso necesita el ok de Carlos y lo hace él a la mañana siguiendo C5.3.
  • Producción (nunca aplicada).
  • Vencimiento automático de MTCN (D12) y el prefondeo notificado por API (pendiente #5 de CIS-EC).
  • Cualquier motor o tabla de comisiones: la comisión la manda Soterex (D13).

4. Pendientes que siguen abiertos ​

#QuéQuién
1D11 y D13 confirmados por Carlos el 2026-09-30: MTCN aleatorio y único; la comisión la manda Soterex—
2Que Soterex confirme que manda fee en el request de SendRequestSoterex
3Vigencia del MTCN (default 30 días, provisional)Soterex / CIS
4URL de Notifications de Soterex y cómo se autentica CIS contra ellaSoterex
5Si quieren IP allowlist en producciónSoterex
6Si Soterex espera un Notification también de los CANCELLED que pidió élSoterex

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