Plan — Alinear la API C2P al contrato con Soterex
Date: 2026-10-05 Compromiso con Soterex: martes 2026-10-06, sandbox alineado y documento de sign-off enviado.
Fuentes:
- La especificación de Soterex, aceptada como contrato definitivo el 2026-08-14:
doc/reference/2026-08-12-especificacion-soterex/(PDF ystipend-spec.txt). - La cadena de mails "Technical Kick Off CIS APIs" (2026-08-04 a 2026-09-30), en especial las confirmaciones escritas de CIS del 2026-08-14 y del 2026-09-04 y el mail de Paul Brown del 2026-08-27.
- El código de
mainal 2026-10-05.
Qué es esto: la API C2P (ADR-012) se construyó sobre el spec v1.4 viejo (el de Zoom), no sobre la especificación de Soterex ni sobre lo que CIS confirmó por escrito. Este plan cierra todas las diferencias. Varias son bloqueantes: tal como está hoy, el Cancel de Soterex fallaría siempre y ninguna notificación se daría por entregada.
Revisado por tres revisores independientes (especificación, código, huecos) el 2026-10-05. Esta versión incorpora sus hallazgos.
Actualización 2026-10-05 (decisiones de Carlos, durante la ejecución). Este plan se deja como se escribió y se ejecutó; lo que cambió después está marcado en cada lugar con «Actualización» y registrado en los ADR:
- Comisión (D2b reemplazada): el tarifario provisional de Guatemala son 50.00 USD fijos por transacción, para cualquier monto, sembrados en todos los ambientes, producción incluida, y editables por país en Parámetros → Comisiones. Ya no es el 1 % ni «en producción no se siembra nada». Ver ADR-018 (Actualización).
- Replay:
dtc_estatusdelCOD_009es el estado actual de la transacción (ACCEPTED,PAIDoCANCELLED), no siempreACCEPTED. Ver ADR-017 §2.- Riesgos que se dejan como están, y el scheduler apagado por ahora: registrados en ADR-017, «Riesgos y decisiones de Carlos (2026-10-05)». Los pasos 4 a 6 de §7 (dry-run,
terraform applydel scheduler, cargar URL y secret y pasar a real) quedan en pausa hasta que Soterex mande la URL y el secret.
1. Diferencias encontradas
| # | Tema | Contrato (especificación + confirmaciones de CIS) | Hoy | Gravedad |
|---|---|---|---|---|
| 1 | sub_status en Cancel | Opcional: "the current callers do not populate them; build for them to be absent" | Obligatorio (2109/2110) | Bloqueante: todo Cancel de Soterex se rechaza |
| 2 | Body de la notificación | Anidado en notificationData, campos distintos por estado (Operación 4) | Plano, los mismos campos para todo | Bloqueante: Soterex lo rechaza con 400 |
| 3 | sub_status en PAID | "Must not be sent on PAID" | Se manda {code:"0", message:"PAID"} | Bloqueante |
| 4 | CANCELLED notificado | time + sub_status.code + sub_status.message obligatorios | Sin time | Bloqueante |
| 5 | Acuse de la notificación | messageCode (COD_000, COD_002, COD_003; CODE_004 = duplicado, 200) | Se lee codResponse === 'COD_000' | Bloqueante: todo se reintenta y termina FAILED |
| 6 | Firma del webhook | HMAC-SHA256 sobre timestamp.body, X-CIS-Signature (hex minúscula), X-CIS-Timestamp (epoch s, UTC), X-CIS-Key-Id, tolerancia 300 s (CIS, 04/09) | HTTP Basic, sin firma | Bloqueante: "not negotiable" para Soterex |
| 7 | Replay | Todo create con un transaction_id ya visto devuelve la transacción original con COD_009 (especificación y CIS, 04/09) | Igual al alta (COD_001) si el payload coincide; 2001 si difiere | Bloqueante: un reintento con un dato reformateado se rechaza |
| 8 | fee en SendRequest | La Operación 2 no lo manda: el proveedor lo calcula y lo devuelve ("fee — We store principal plus fee as the transaction total") | Obligatorio en el request (2016); CIS no calcula nada | Bloqueante: todo create según la especificación rebota |
| 9 | CANCELLED por Cancel de Soterex | Se confirma con notificación CANCELLED (CIS, 14/08) | No se notifica | Alta |
| 10 | FAILED a demanda en sandbox | Disparos PAID, CANCELLED y FAILED a demanda (CIS, 14/08; Paul, 27/08) | No existe | Alta: Soterex no cierra su etapa Build sin esto |
| 11 | Nombre del vencimiento | expiration_date, formato yyyy-MM-dd (desviación 3) | expirate_date, Y-m-d H:i:s | Alta |
| 12 | Nombre de la sucursal | paying_office (desviación 4) | zoom_office | Alta |
| 13 | Tipos de amount y fee | Texto ("500.00") en toda respuesta (CIS, 04/09) | Número en SendRequest y Cancel; fee número en la notificación | Alta |
| 14 | Respuesta de SendRequest | code: "COD_000", message: "Transaction successful"; entityResponse.transaction_id = la referencia del proveedor | COD_001, "RECORD INSERTED SUCCESSFULLY"; se devuelve el RS- de Soterex | Media |
| 15 | Rechazos de negocio | HTTP 200, status: "REJECTED", entityResponse como texto (Operaciones 2 y 3) | HTTP 400, code: "CODE_002", entityResponse.errorDetails[] | Alta |
| 16 | Cancel de una ya cobrada | HTTP 200, forma de rechazo, CODE_010 "Transaction already collected" (CIS, 04/09) | HTTP 400, error 2108 | Alta |
| 17 | Cancel de una inexistente | CODE_001 "Transaction not found" (especificación y CIS, 04/09) | HTTP 400, error 2108 | Alta |
| 18 | Respuesta de Cancel | COD_000, "Cancellation successful", entityResponse: {transaction_id, token} | COD_002, y además amount | Media |
| 19 | Vencimiento | "After this date the funds are no longer collectable" | expires_at no se aplica en ningún lado | Alta |
| 20 | previous_transaction_id | Opcional en SendRequest; la cadena original→reemplazo visible para operaciones (CIS, 04/09) | No existe | Media |
| 21 | Notificaciones a demanda en sandbox | Disparar PAID, CANCELLED y FAILED contra una transacción elegida | No existe | Alta |
| 22 | Envelope en 429 y 500 | "Every response carries the same envelope" | {"message": ...} de Laravel | Media |
| 23 | Vocabularios cerrados | Estados (terminal/intermedio) y errores (significado, HTTP, reintentable) | No están entregados | Alta (checklist) |
| 24 | Documento de sign-off | Prometido el 04/09 | No existe | Alta |
| 25 | error_description del token | — | En español | Baja |
| 26 | Textos largos y montos enormes | Rechazo de negocio | Error 500 (varchar 255, decimal(12,2)) | Media |
| 27 | amount y fee en el request | Decimal (Salesforce puede mandar número o texto) | Solo texto (si llega número: 2005) | Media |
2. Decisiones
| # | Decisión |
|---|---|
| D1 | El contrato es la especificación de Soterex + sus cuatro desviaciones + lo que CIS confirmó el 14/08 y el 04/09. Donde la especificación no dice nada, mandan las confirmaciones de CIS. Todo lo demás se copia exacto: nombres, anidado, literales (ACCEPTED, REJECTED). |
| D2 | La comisión la calcula CIS, como dice la especificación (Carlos, 2026-10-05). fee deja de ser parte del request: si Soterex lo manda, se ignora y se registra en la auditoría si difiere del calculado. CIS lo calcula con un tarifario por país de destino configurable (tramos de monto con monto fijo, porcentaje o ambos, como pidió CIS-EC en el requerimiento #2 del 2026-08-07), lo guarda en la transacción al crearla y lo devuelve en la respuesta. Cambiar el tarifario no toca transacciones existentes. Si ningún tramo cubre el monto, el alta se rechaza con 2026. Reemplaza en parte a ADR-005 (la comisión no la fijaba CIS) y la D13 de ADR-012 (fee obligatorio en el request): ADR-018. |
| D2b | El tarifario real lo define Tesorería (Teresa). Mientras tanto, solo fuera de producción, se carga un tarifario provisional para Guatemala: un tramo único del 1 % del principal (el mismo ejemplo de la especificación: 500.00 → 5.00), rotulado "PROVISIONAL — reemplazar por la tabla de Tesorería". En producción no se siembra nada: sin tarifario, el alta se rechaza. Actualización 2026-10-05: reemplazada por decisión de Carlos. El provisional son 50.00 USD fijos por transacción, para cualquier monto, sembrado en todos los ambientes (producción incluida) y editable por país; el 500.00 → 5.00 ya no sale del tarifario sembrado (da 50.00), y en producción ya no se rechaza por falta de tarifario. Ver ADR-018. |
| D3 | Todos los rechazos de negocio van con HTTP 200, status: "REJECTED", el código específico en code (por ejemplo "2002"), un message diagnóstico que nombre el campo, y entityResponse como texto. Sin dtc_estatus, salvo CODE_010 (ver §4.3). Los códigos 2000/2100 se mantienen. |
| D4 | entityResponse.transaction_id es la referencia de CIS (el id UUID de la transacción), como en las tablas de las Operaciones 2 y 3. El RS- viaja en el request y en todas las notificaciones. Se deja escrito en el sign-off y se pide confirmación. |
| D5 | El webhook se firma con HMAC-SHA256 y deja de usar HTTP Basic. El secret lo provee Soterex; el Admin lo carga en Configuración, cifrado, con un key_id de texto libre (el que indique Soterex; si no indica, k1). Se firma siempre con el secret activo más reciente; el anterior se conserva hasta su vencimiento solo para poder volver atrás. En modo real sin secret activo, la entrega falla y se reintenta: nunca se manda sin firmar. |
| D6 | Se notifica CANCELLED en toda cancelación: la de operaciones de CIS, la que pide Soterex por Cancel y la del vencimiento. Solo en la transición real ACCEPTED→CANCELLED: un re-cancel idempotente o el que pierde la carrera no encola nada. |
| D7 | El MTCN vence. expiration_date es el último día en que se puede cobrar. Vencida ⇔ hoy (America/Guatemala) > expires_at como fecha; expires_at nulo = no vence. La misma regla en pay() y en el comando. Una vencida no se puede pagar, y el comando la cancela y notifica CANCELLED con CXL_EXPIRED. 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. |
| D8 | En producción no hay FAILED: un cobro se completa (PAID) o la transacción sigue pendiente hasta que se paga, se cancela o vence. En el sandbox, FAILED se puede disparar a demanda para que Soterex pruebe su manejo, como se comprometió el 14/08. |
| D9 | Las notificaciones a demanda del sandbox no cambian el estado de la transacción. Solo mandan la notificación, quedan auditadas, y en producción la ruta no existe (404). Para probar CODE_010, un operador de CIS paga la transacción desde la UI de staging cuando Sean lo pide. |
| D10 | No se piden ni se aplican allowlists de IP (Carlos, 2026-10-05). En el sign-off: CIS no exige allowlist; la IP de salida de producción se informa cuando se provisione (producción tiene NAT Gateway en el Terraform). |
| D11 | El contacto técnico de Soterex es Sean Rahimi. El de CIS y su escalamiento quedan como placeholder para Carlos en el sign-off. |
| D12 | Solo se notifican transacciones que entraron por la API (api_client_id no nulo), en todos los caminos: pago, cancelación por UI, Cancel y vencimiento. El comando de vencimiento también actúa solo sobre esas: los datos de demo de staging no vencen ni notifican. |
| D13 | Liquidación y fondos (texto para el sign-off): la cancelación es inmediata y sincrónica, sin ventana de liquidación; una transacción no cobrada no consume prefondeo (se debita solo al cobrar, principal más comisión), así que cancelarla no mueve fondos. |
| D14 | Secuencia de estados (texto para el sign-off): ACCEPTED es intermedio; PAID y CANCELLED son terminales. Una cancelada o vencida nunca pasa a PAID; una corrección es cancel-and-recreate con un RS- nuevo y previous_transaction_id. |
| D15 | Los sub_status por defecto (CXL_*) se arman solo dentro de la notificación. Las columnas sub_status_code y sub_status_message de la transacción guardan solo lo que mandó Soterex, como hoy (el reporte de Cumplimiento las lee). |
3. Lo que queda abierto con Soterex (no frena esta noche)
- El tarifario real de comisiones (D2b): lo define Tesorería de CIS, no Soterex. Hasta entonces el sandbox usa el 1 % provisional. (Actualización 2026-10-05: el provisional son 50.00 USD fijos, también en producción; ver ADR-018.)
- El secret del HMAC para el sandbox (y su
key_id), y la URL de Notifications. - Las plantillas del reporte de pagos del día siguiente y del estado de cuenta, como parte de la especificación de la Operación 4. CIS mantiene los dos reportes durante el paralelo y después del go-live (lo pidió Paul el 27/08).
- La vigencia del MTCN: 60 días salvo que digan otra cosa.
- Que el RS- no se repita en
entityResponse(D4): pedir confirmación.
4. El contrato objetivo
4.1 SendRequest
Request: los campos de la Operación 2 de la especificación, sin fee (D2), más:
previous_transaction_id(texto, opcional).amountacepta número o texto. Mayor que cero, hasta 2 decimales, hasta9999999999.99(2005 si no).fee: si viene, se ignora. 2016 y 2017 quedan fuera de uso (se listan como retirados en el sign-off).- La comisión (D2):
fee = fijo + amount × porcentaje / 100del tramo del tarifario del país de destino que contiene aamount(min_amount≤ amount ≤max_amount, este último opcional), redondeado a 2 decimales (half-up). Si ningún tramo activo lo contiene: rechazo2026("fee: No fee schedule covers this amount for the destination country"). - Ningún texto puede provocar un 500. Códigos nuevos para textos de más de 255 caracteres:
| Código | Campo |
|---|---|
2018 | transaction_id |
2019 | first_name |
2020 | last_name |
2021 | phone |
2022 | alien_number |
2023 | full_name_of_minor |
2024 | previous_transaction_id |
2025 | email |
Alta (HTTP 200):
{
"code": "COD_000",
"status": "ACCEPTED",
"dtc_estatus": "ACCEPTED",
"message": "Transaction successful",
"entityResponse": {
"transaction_id": "<id de la transacción en CIS>",
"token": "4907241455",
"amount": "500.00",
"fee": "5.00",
"expiration_date": "2026-12-04"
}
}(fee calculado con el tarifario provisional del 1 %. Actualización 2026-10-05: con el provisional vigente, 50.00 USD fijos, el fee de este ejemplo (y el de los payloads de §4.5, con el mismo monto) es "50.00"; el resto del JSON no cambia.)
Replay: todo SendRequest con un transaction_id que ya existe para ese cliente devuelve lo mismo que el alta original, con "code": "COD_009" y "message": "Duplicate request: original transaction returned", aunque el payload sea distinto. Las diferencias se registran en la auditoría (qué campos difieren, sin valores) y no se rechaza. Desaparece el 2001, también en el camino de la carrera por el índice único. Actualización 2026-10-05 (decisión de Carlos): «lo mismo que el alta» tiene una sola excepción. dtc_estatus del replay es el estado actual de la transacción (ACCEPTED, PAID o CANCELLED) y no siempre ACCEPTED; code (COD_009), status (ACCEPTED), message y entityResponse no cambian. Una ACCEPTED vencida que c2p:expire todavía no canceló sigue diciendo ACCEPTED: se informa el estado guardado, no se deduce. Ver ADR-017 §2.
Rechazo (HTTP 200), por ejemplo sin first_name:
{
"code": "2002",
"status": "REJECTED",
"message": "first_name: The field is required",
"entityResponse": "No transaction was created"
}4.2 Cancel
Request: sub_status es opcional. null, {}, o con code y message vacíos cuentan como ausente. Si llega uno solo, se completa el otro con el valor por defecto. Se rechaza con 2110 solo si code o message no son texto, y con 2111 si superan 255 caracteres.
Éxito y re-cancel idempotente (HTTP 200):
{
"code": "COD_000",
"status": "ACCEPTED",
"dtc_estatus": "CANCELLED",
"message": "Cancellation successful",
"entityResponse": { "transaction_id": "<id en CIS>", "token": "4907241455" }
}4.3 Rechazos de Cancel (HTTP 200)
| Caso | code | dtc_estatus | message | entityResponse |
|---|---|---|---|---|
| Transacción ya cobrada | CODE_010 | PAID | Transaction already collected | "The beneficiary already collected this transaction" |
No existe para ese cliente, o el token no coincide | CODE_001 | — | Transaction not found | "No transaction exists with the provided ID" |
| Validación (2100-2111) | el código | — | diagnóstico con el campo | "No cancellation was applied" |
Se busca siempre por api_client_id + transaction_id + token: una transacción de otro cliente da CODE_001, así que distinguir "cobrada" de "no existe" no expone nada ajeno.
4.4 Envelope de 429 y 500 en /api/c2p/*
- 429:
{"code": "CODE_429", "status": "ERROR", "message": "Too many requests, retry after N seconds"}+Retry-After. Reintentable. - 500:
{"code": "CODE_500", "status": "ERROR", "message": "Internal error, retry with backoff"}. Reintentable (SendRequest y Cancel son idempotentes). - El endpoint de token sigue el estándar OAuth (
error,error_description, en inglés).
4.5 Notificaciones (Operación 4)
POST a la URL de Soterex, Content-Type: application/json. Todas las fechas y horas en America/Guatemala.
PAID:
{
"notificationData": {
"transaction_id": "RS-54689",
"status": "PAID",
"amount": "500.00",
"fee": "5.00",
"date": "2026-10-06",
"hour": "14:32",
"paying_office": "<PDV que pagó>"
}
}dateyhour: los del pago, no los del envío.paying_office, nunca vacío: el nombre del PDV de la transacción; si no tiene, el del PDV de la caja de la que salió el pago; si tampoco, el nombre del país.- Sin
sub_status. Sinbcv_authorization(no aplica en Guatemala; se omite).
CANCELLED:
{
"notificationData": {
"transaction_id": "RS-54689",
"status": "CANCELLED",
"time": "2026-10-06 14:32:00",
"sub_status": { "code": "CXL_SENDER", "message": "Cancelled at sender request" }
}
}time es el momento en que la cancelación se aplicó en CIS, nunca el time del request.
sub_status.code | Cuándo | message |
|---|---|---|
| El que mandó Soterex | Cancel por la API con sub_status | el que mandó |
CXL_SENDER | Cancel por la API sin sub_status | Cancelled at sender request |
CXL_CIS | Cancelación desde la pantalla de CIS | según el motivo: cancelada_remitente → Cancelled at sender request; ajuste_beneficiario → Beneficiary data needs correction; ajuste_monto → Amount needs correction; motivo nuevo o vacío → Cancelled by CIS operations |
CXL_EXPIRED | Vencimiento | MTCN expired without being collected |
CXL_SANDBOX | Disparo a demanda (si el request no trae sub_status) | Sandbox on-demand notification |
FAILED (solo el disparo a demanda del sandbox): la forma de la especificación (amount, fee, date, hour, sub_status), con {"code": "FLD_SANDBOX", "message": "Sandbox-triggered failure"}.
Firma:
- El payload se guarda al encolar. En cada intento, justo antes del POST: se serializa el payload (
json_encode), se toma un timestamp nuevo, se calcula el HMAC sobre"{timestamp}.{body}"y se manda ese mismo string (Http::withBody($body, 'application/json')). El timestamp y la firma nunca se guardan: un reintento lleva un timestamp nuevo dentro de los 300 s. - Headers:
X-CIS-Timestamp(epoch s, UTC),X-CIS-Signature(HMAC-SHA256 en hex minúscula),X-CIS-Key-Id.
Resultado de la entrega:
| Respuesta de Soterex | Resultado |
|---|---|
200 y messageCode COD_000, COD_002 o COD_003 | Entregada (warning en el log si no corresponde al estado enviado) |
200 y messageCode CODE_004 | Entregada (duplicado) |
200 sin messageCode, con uno desconocido, o cuerpo no JSON | Reintento |
| 3xx | Falla definitiva (no se siguen redirecciones) |
| 400, 401, 403, 404, 415 y cualquier otro 4xx salvo 429 | Falla definitiva |
| 429, 5xx, timeout (30 s) o error de red | Reintento |
Reintentos: en los ciclos del scheduler, con esperas mínimas de 1, 5, 15 y 60 minutos (el scheduler de AWS corre cada 5 minutos, así que en la práctica son múltiplos de 5). Después, falla definitiva.
Falla definitiva: queda registrada en la auditoría (NOTIFICATION_FAILED, sin PII), el estado de la notificación se ve en el detalle de la transacción (entregada, pendiente o fallida, con el último error), y se puede reenviar con php artisan notifications:retry {id} (vuelve a pendiente; se firma de nuevo al enviarse).
Modo mock (el default de staging): devuelve el acuse de la especificación según el estado (messageCode COD_000 para PAID, COD_002 para CANCELLED, COD_003 para FAILED) y calcula igual los headers de firma, sin red.
4.6 Notificaciones a demanda (solo sandbox)
POST /api/c2p/v1/sandbox/notify, con el mismo OAuth que SendRequest y Cancel:
{ "transaction_id": "RS-54689", "status": "PAID", "sub_status": null, "bad_signature": false }status:PAID,CANCELLEDoFAILED. Arma la notificación con los datos de la transacción y la fecha y hora actuales, la encola y responde:json{ "code": "COD_000", "status": "ACCEPTED", "message": "Notification queued", "entityResponse": { "transaction_id": "RS-54689", "status": "PAID", "notification_id": "<id>" } }paying_officecon la misma regla de §4.5; si la transacción no tiene PDV ni pago,SANDBOX.sub_statusopcional para CANCELLED y FAILED; si no viene, el de la tabla de §4.5.bad_signature: truefirma con un secret inválido, para que Soterex pruebe que su endpoint lo rechaza (ítem del checklist).- No cambia el estado de la transacción ni toca saldos (D9). Solo transacciones del mismo cliente: si no existe,
CODE_001como en §4.3. En producción la ruta no existe.
5. Entregas
Un solo branch: docs/plan-alineacion-contrato-c2p (el de este plan), un PR contra main, commits con prefijo K1…K8. Orden y prioridad: K1, K2, K3, K6, K4, K5, K8, K7. K7 se escribe al final y documenta solo lo que quedó hecho.
| # | Entrega | Qué incluye | Terminado cuando |
|---|---|---|---|
| K1 | SendRequest y Cancel (§4.1 a §4.4) y comisión (D2) | Tarifario por país (tabla de tramos: país, min_amount, max_amount opcional, fixed_fee, percent, activo, descripción), servicio de cálculo, fee fuera del request (ignorado si viene, auditado si difiere), rechazo 2026, tarifario provisional de GT al 1 % solo fuera de producción (migración de datos condicionada al ambiente; D2b) (Actualización 2026-10-05: reemplazado por 50 USD fijos sembrados en todos los ambientes, producción incluida; ver ADR-018), ADR-018. Además: códigos y mensajes, expiration_date como fecha, amount/fee como texto en respuestas y número o texto en requests, replay COD_009 sin 2001, rechazos HTTP 200, CODE_010/CODE_001, sub_status opcional, códigos de largo, topes de monto, previous_transaction_id (migración; se ve en el detalle de la transacción nueva y de la original), entityResponse.transaction_id = id de CIS, envelope de 429/500, error_description del token en inglés | Un test por forma de respuesta que compare el JSON entero. Un test por fila de §1 que toca la entrega. Comisión: tramo fijo, porcentaje, fijo + porcentaje, bordes de tramo, redondeo, sin tramo → 2026, fee enviado se ignora, cambiar el tarifario no altera una transacción ya creada, en producción no se siembra (Actualización 2026-10-05: sí se siembra, 50 USD fijos; ver ADR-018) |
| K2 | Notificaciones (§4.5) | Payload por estado; date/hour/time del momento real; paying_office con su regla; CANCELLED en la transición real de UI y API (D6) con la tabla de sub_status; D12; entrega según la tabla; estado visible en el detalle; notifications:retry; auditoría de fallas; mock nuevo | Tests del JSON exacto de PAID y CANCELLED (PAID sin sub_status); un test por fila de la tabla de entrega; re-cancel no encola; cancelación por UI sin motivo lleva message no vacío; transacción sin api_client no notifica |
| K3 | Firma HMAC (§4.5, D5) | Tabla de secrets del webhook (cifrados, key_id, valid_from, expires_at), pantalla en Configuración para cargarlos (sin mostrarlos de vuelta), firma en cada intento, rotación, no mandar sin secret en modo real, sacar HTTP Basic de SoterexClient y los campos usuario/contraseña de la pantalla y de la API (las columnas quedan, sin uso) | Test que recalcula la firma sobre el body enviado; dos intentos llevan timestamps distintos y firmas válidas; rotación: firma el más nuevo; un byte cambiado invalida la firma; modo real sin secret no envía |
| K6 | Scheduler en staging | Terraform: enabled = true en el scheduler de staging. routes/console.php: agregar el comando de vencimiento con everyMinute() (notifications:deliver ya está). Anotar en staging.md el costo y la frecuencia (EventBridge cada 5 min). Sin terraform apply | terraform fmt -check y terraform validate locales (init -backend=false). Carlos corre el plan y el apply |
| K4 | Vencimiento (D7) | pay() rechaza una vencida (código nuevo, aviso en Pago); comando c2p:expire (con --dry-run, lock por fila, solo D12) que cancela y encola CANCELLED con CXL_EXPIRED; TransactionCancellationService::cancel() acepta actor nulo (sistema); vigencia de GT a 60 días por migración y en CountrySeeder | Tests: el último día se puede pagar y el siguiente no (borde de medianoche en Guatemala); el comando solo toca ACCEPTED vencidas con api_client; es idempotente; --dry-run no cambia nada |
| K5 | Disparos a demanda (§4.6) | Ruta solo fuera de producción, PAID/CANCELLED/FAILED, bad_signature, auditoría | Tests: 404 en producción; no cambia estado; solo transacciones del mismo cliente; FAILED con su forma; bad_signature produce una firma que no verifica |
| K8 | ABM del tarifario | Pestaña "Comisiones" en Parámetros (Admin, con el permiso abm_paises): alta, edición y desactivación de tramos por país, validación de que no se solapen, aviso visible si el tarifario es el provisional, auditoría de cada cambio | Tests de API (solapamiento rechazado, auditoría, permiso) y del componente |
| K7 | Documentación | Ver §6 | npm run docs:build en doc/ pasa |
Tests existentes que hay que reescribir, no borrar (afirman el comportamiento viejo):
TransactionC2PApiTest:COD_001,amount/feenuméricos,expirate_date, los 400 conentityResponse.errorDetails, el 2001 por payload distinto, los casos de 2109 y desub_statusincompleto.test_cancel_no_encola_notification_salvo_que_soterex_lo_pidase invierte (D6).- Los tests de entrega que usan
codResponsey el de HTTP Basic pasan amessageCodey HMAC. - Los tests que mandan
feeen SendRequest o esperan 2016/2017: elfeesale del tarifario.
6. Documentación (K7)
doc/integracion/cis-latam-soterex-c2p-openapi-v2.yaml: el contrato nuevo completo, incluido el webhook con la firma, los acuses de Soterex, el endpoint de sandbox y todos los códigos.doc/site/public/openapi.yaml(el sitio de docs de API): también documenta el contrato viejo. Actualizarlo con el nuevo o reemplazar la parte C2P por un puntero, para que no queden dos contratos publicados. Actualizar los docblocks deC2PController,NotificationOutboxServiceySoterexClient.doc/integracion/cis-latam-soterex-c2p-sandbox.postman_collection.json: requests y tests al contrato nuevo; ejemplos de notificación PAID y CANCELLED como en §4.5 con un pre-request script que firma conwebhook_secret; un request para el disparo a demanda. En el repo,client_secretywebhook_secretvan con placeholder.doc/integracion/2026-10-06-c2p-sign-off.md(inglés, para mandar el martes), un punto por ítem del checklist de la página 13 de la especificación:- desviaciones 1 a 4 aceptadas;
feelo calcula CIS con su tarifario y lo devuelve (no va en el request; si llega, se ignora) — D2; - vocabulario de estados (ACCEPTED intermedio; PAID y CANCELLED terminales; FAILED solo a demanda en sandbox, D8);
- lista de errores con significado, HTTP y si es reintentable, incluidos los de §4.1 a §4.4;
- los
sub_statusde §4.5; - idempotencia (§4.1), Cancel en sus casos borde (§4.3), liquidación y fondos (D13), secuencia de estados (D14);
- esquema de firma, rotación y
key_id(D5); - tipos por campo; token estable de hasta 20 caracteres;
entityResponse.transaction_id(D4); - vigencia del MTCN (D7); ambientes y hostnames (sandbox y
api.soterex.cislatam.net); - IPs (D10); los reportes del día siguiente y el estado de cuenta (§3.3);
- aviso de 30 días antes de cambiar certificados o endpoints; transacción real de bajo monto antes de volumen;
- contactos: Sean por Soterex; CIS y escalamiento como placeholder
[CONTACTO CIS]para Carlos.
- desviaciones 1 a 4 aceptadas;
- ADR-017 "El contrato C2P es la especificación de Soterex": lo de §2 y qué reemplaza de ADR-012 (la auth Basic del webhook, el payload plano, el
sub_statusobligatorio, el 2001). - ADR-018 "La comisión C2P la calcula CIS con un tarifario por país": D2 y D2b; reemplaza la parte de ADR-005 que decía que CIS no fija la comisión y la D13 de ADR-012.
doc/integracion/2026-10-06-mail-sean-sandbox-alineado.md: borrador en inglés del mail a Sean para mandar una vez desplegado en staging. Dice solo lo que quedó hecho y verificado; lleva[CLIENT_SECRET]como placeholder (lo completa Carlos). Contenido: credenciales, que el sandbox ya está alineado a su especificación (lista corta de lo que cambió respecto de hoy), adjuntos (sign-off, OpenAPI, collection), y lo que necesitamos de ellos: URL y secret del HMAC con sukey_id, y las plantillas de reportes junto con la especificación de Notifications. No pide IPs. Sean es el contacto técnico.- Análisis funcional y manual: el vencimiento visible en Pago y en el detalle,
previous_transaction_idy el estado de la notificación en el detalle (doc/functional/2026-08-07-pago-con-documentos/,doc/manual/10-pago.md,doc/manual/20-transacciones.md). doc/environments/staging.md: los pasos de §7 ynotifications:retry.
7. Lo que hace Carlos (lunes 2026-10-05)
- Pedirle a Teresa el tarifario real de comisiones (D2b) y cargarlo en Parámetros → Comisiones antes de producción. En staging alcanza el 1 % provisional para las pruebas de Sean. (Actualización 2026-10-05: el provisional son 50 USD fijos y producción arranca con él; la tabla real se carga cuando Teresa la defina, ya no «antes de abrir».)
- Revisar y mergear el PR.
- Promover
mainastaging.
Actualización 2026-10-05: los pasos 4, 5 y 6 quedan en pausa. Carlos todavía no tiene la URL ni el secret de Soterex y la integración sigue en mock, así que el scheduler no se prende por ahora. Se retoman cuando Soterex mande esos datos.
- Correr
php artisan c2p:expire --dry-runen staging (workflow de artisan) para ver qué vencería. terraform planyapplydel scheduler de staging (K6).- Cuando Sean mande la URL y el secret del HMAC: cargarlos en Configuración y pasar Soterex de mock a real.
- Completar
[CONTACTO CIS]en el sign-off y[CLIENT_SECRET]en el borrador del mail, y mandar el mail con el sign-off, la collection y el OpenAPI una vez desplegado en staging.
8. Riesgos
- El tarifario provisional no es el real (D2b): las comisiones del sandbox (1 %) no son las que se van a cobrar. El sign-off lo dice; antes de producción tiene que estar la tabla de Tesorería. (Actualización 2026-10-05: son 50 USD fijos, y rigen también en producción hasta que Tesorería cargue la tabla real; con montos menores a 50 USD la comisión supera al principal, ver ADR-018.)
- Cambia lo que Sean ya podría estar probando con las credenciales del 30/09. El mail se manda recién con todo desplegado, así no ve dos contratos.
- Sin scheduler no se entrega ninguna notificación, ni siquiera el primer intento: el outbox solo se vacía con
notifications:deliver. K6 lo prende, pero el apply es de Carlos. - El vencimiento cancela transacciones reales. Solo las de la API (D12), de a una, con lock, y con un
--dry-runen staging antes de prender el scheduler.

