Skip to content

Borrador del mail a Sean — seis consultas de los ajustes v3 ​

Date: 2026-10-07 Plan: Ajustes v3 del cliente GT, §6.2 (S-1 a S-5) y D3-22, entrega G0.5. S-6 (fecha de nacimiento y nacionalidad) se suma el 2026-10-13 desde el plan de los pendientes del Excel, §5 (J0.2): el Excel del cliente dice que esos datos «vienen en el reporte de Soterex».

BORRADOR — NO ENVIADO — lo revisa y lo manda Carlos. No está enviado ni guardado en ningún sistema de correo. Este encabezado y todo lo que está fuera de los bloques de código es para vos y no forma parte del mail.

Para: Sean Rahimi (Soterex / Prutech), contacto técnico de Soterex para las pruebas de integración (ver sign-off, sección 7). Copia: la del hilo "Technical Kick Off CIS APIs"; decidilo vos (ver abajo).

Solo consulta. El mail no propone ningún cambio a C2PController, al OAuth, a SendRequest ni a Cancel (P3-13). Si una respuesta de Soterex pide tocar la integración, es otro plan.

Qué conviene decidir antes de mandarlo ​

  1. ¿Va con el mail del sign-off o aparte?

    • [ ] Aparte, en el mismo hilo (lo que recomiendo). El mail del 6/10 (borrador) ya tiene siete secciones, tres adjuntos y pide lo que sí bloquea (URL de Notifications y secret del HMAC). Estas cinco no bloquean el sandbox y compiten con eso por la atención de Sean. Mandalo cuando el sign-off ya haya salido: el mail cita secciones suyas.
    • [ ] Junto con el del 6/10. Pegá las seis preguntas como una sección 7 de ese mail, sin el saludo, el párrafo de apertura ni la firma de este borrador. Es un solo contacto con Sean, pero el mail queda más largo.

    D3-22 dice "un solo mail" para las cinco preguntas originales (la sexta es de J0.2); cualquiera de las dos opciones lo cumple.

  2. Idioma. [ ] Español (el idioma de este borrador). [ ] Inglés: todos los mails anteriores a Sean y el sign-off están en inglés. Abajo van las dos versiones con el mismo contenido; mandá una sola.

  3. La pregunta 1 (prefondeo). [ ] Va ahora. [ ] Espera. G13 (alerta de reposición y confirmaciones de tesorería) quedó para después, así que la respuesta no se usa hasta entonces. Está redactada para no pedirle a Soterex que defina un mensaje nuevo de la API: pregunta solo cómo y dónde le comunican hoy cada prefondeo a CIS. Recomiendo que vaya igual: cuesta un párrafo, evita otra vuelta con Sean cuando G13 se retome, y el mail del 6/10 ya le pidió la plantilla del estado de cuenta, que puede contestarla sola.

  4. La pregunta 3 (RS-) ya la contesta casi toda la especificación de Soterex: define el transaction_id de SendRequest como su referencia "RS-" (stipend-spec.txt, líneas 28-29 y 93: "Our RS- reference. The correlation key", "unique, never reused"). Lo único que falta confirmar es que el "RS-xxxxx" que el cliente ve en su reporte es ese mismo dato. El plan la escribió el 2026-10-04, antes de que se integrara la especificación. [ ] La dejo como confirmación de una línea. [ ] La saco y quedan cuatro preguntas.

  5. Copia. [ ] Solo Sean. [ ] También quien lleve el negocio de Soterex (Paul Brown recibió las confirmaciones del 04/09 y pidió que CIS siga produciendo los reportes). Las preguntas 1, 2 y 5 las puede contestar mejor alguien de operación que Sean; el mail le pide que las reenvíe.

  6. La lista de países. [ ] No se adjunta (lo que dice el mail alcanza para que Sean la reconozca). [ ] Se adjunta la hoja de países sola, exportada del Excel del cliente. El .xlsx completo no se manda ni se sube al repo: sus capturas tienen datos personales (ver el README de doc/reference/2026-10-02-respuesta-ajustes-v2/). La hoja de países no los tiene, pero hay que exportarla a mano.

  7. Las citas al sign-off. El mail remite a las secciones 1.2, 1.3, 1.4 y 8 (puntos 5 y 6) del documento del 6/10. Si lo mandás antes que el sign-off, sacá las citas o adjuntalo.

  8. Lo que el mail dice que hacemos "mientras tanto" es lo que implementan los PRs de G9 (#92: el «C-» en el reporte de Cumplimiento) y de G10 (#93: la lista de países), abiertos y sin mergear al 2026-10-07. Si no los mergeás, o cambiás un valor por defecto (por ejemplo apagás el prefijo), corregí esas líneas.

Dos cosas del plan que cambiaron (para que no se te cuelen) ​

  • S-4: "hoy un transaction_id repetido da 2001" ya no es cierto. Lo escribió el plan del 2026-10-04 (D3-22, §6.2 y la fila RV3-91). Desde el PR #80 (mergeado el 2026-10-05) un SendRequest con un transaction_id ya usado devuelve la transacción original con COD_009, status: ACCEPTED y su estado actual en dtc_estatus, aunque los datos del request sean otros, y no aplica los datos nuevos (solo anota en la auditoría qué campos diferían, nunca los valores). El 2001 está retirado (sign-off, 1.4 y Apéndice C). El riesgo sigue, pero cambió de forma: antes era un rechazo visible; ahora, si el Salesforce de Soterex modifica una transacción reenviándola con el mismo RS-, la respuesta parece un éxito y el cambio no entra. Por eso la pregunta 4 lo dice con esas palabras, citando la sección 1.4. El plan (D3-22, §6.2 S-4 y RV3-91) sigue diciendo 2001: no reescribí esas tres frases (el plan se conserva como se escribió), pero el recuadro «Estado de la ejecución» del plan ya avisa que quedaron viejas.
  • S-3 es una confirmación y no una pregunta abierta, por lo de arriba (punto 4 de las decisiones).

Lo que el mail afirma y de dónde sale ​

Todo esto lo verifiqué leyendo el código y los documentos. No corrí tests, no probé nada contra Staging, y nada se probó contra un Soterex real (el propio sign-off lo dice en su "Honest scope").

Lo que dice el mailFuente
Un SendRequest con un transaction_id ya usado devuelve la original con COD_009, status: ACCEPTED y el estado actual en dtc_estatus, sin aplicar los datos nuevos; CIS anota qué campos difirieronC2PController.php:100-105 (el replay se resuelve antes de validar), :488-505 (replay()) y :514-557 (differingFields()); sign-off 1.4
Cancel de una transacción cobrada se rechaza con CODE_010; de una ya cancelada es idempotente (COD_000)C2PController.php:236-244; sign-off 1.5
Corregir una transacción es cancelar y crear otra con un RS- nuevo; previous_transaction_id es opcional y vincula la nueva con la anterior. Es la regla de CIS, no algo que Soterex haya confirmadoSign-off 1.2 y 2.2; Transaction.php:259-266 (replacements()); plan de alineación C2P, D14 y fila 20; el campo viene de las confirmaciones de CIS del 04/09, no de la Operación 2 de su especificación
El sub_status que mande Soterex en Cancel viaja en la notificación CANCELLED; sin él, CXL_SENDERSign-off 1.5 y Apéndice A
Cancel exige el token de 10 dígitos exactos (2101, 2102, 2103)C2PController.php:357-359; sign-off 1.3
La especificación de Soterex no tiene ningún mensaje de prefondeo; en nuestra API solo existen SendRequest, Cancel y el disparador del sandbox, y el prefondeo se carga a mano por POST /prefondeostipend-spec.txt (no hay "prefund"; "funds" aparece solo en el vencimiento, línea 135, y en la pregunta de devolución de fondos de Cancel, línea 206); routes/api.php:152-155 y :384-394; plan v3, RV3-56
En la carta de Soterex el MTCN figura como «C-» más 10 dígitos y el Payment PIN como esos mismos 10 dígitosLo vio Carlos el 2026-08-07: 01-flujo-del-pago, sección 1.2 ("El PIN es el MTCN"). No está en la especificación de Soterex (stipend-spec.txt no menciona ningún prefijo)
La especificación define el transaction_id como "Our RS- reference. The correlation key", única y sin reutilizarstipend-spec.txt:28-29 y :93
Hoy la referencia de cada pago en los extractos es el MTCN; el RS- (soterex_transaction_id) solo se ve en el detalle de la transacciónTreasuryStatementService.php:120, 169, 335, 420; TransaccionDetalleView.vue:582
La lista de países del cliente tiene 255 filas y los encabezados «Global Country Values», «#» y «Translation - Spanish»Plan v3, RV3-75 y G10 (el .xlsx no está en el repo)
"Mientras tanto": «C-» en el MTCN del reporte y no en el PIN, apagable; códigos ISO alpha-2; «#» como contador; no se cargan Chipre del Norte, Irlanda del Norte, Somalilandia ni «Santo Tomas»; Kosovo y Antillas Holandesas con XK y ANCuerpos de los PRs #92 y #93 (sin mergear); QC-27 y QC-28 del plan

El mail (español) ​

Asunto: Re: Technical Kick Off CIS APIs — seis consultas (solo preguntas)

Hola Sean:

Les dejamos seis consultas que surgieron al revisar con el equipo de CIS cómo se va a usar la integración. Son solo
preguntas: no piden ningún cambio en la API y ninguna bloquea las pruebas del sandbox, aunque la 4 conviene tenerla antes
de operar con montos reales. Si alguna la contesta mejor otra persona de su equipo, les agradecemos que se la reenvíen.
Debajo de cada una va lo que hacemos mientras no tengamos respuesta.

1. Prefondeo
¿Cómo le comunica Soterex a CIS cada prefondeo (el dinero que Soterex le adelanta a CIS para pagar): por la API, por
mail, en el estado de cuenta o de otra forma? Su especificación no tiene ningún mensaje de prefondeo y hoy CIS carga cada
uno a mano en su herramienta. Si el prefondeo solo figura en el estado de cuenta (cuya plantilla pedimos en el mail
anterior), nos alcanza con que nos lo confirmen.
Mientras tanto: seguimos cargándolo a mano.

2. Prefijo «C-» del MTCN
En la carta de Soterex al beneficiario que vimos, el MTCN figura como «C-» más 10 dígitos, y el Payment PIN como esos
mismos 10 dígitos.
(a) ¿Su carta y su Salesforce siguen mostrándolo así?
(b) ¿Qué forma guardan y cuál envían en Cancel: los 10 dígitos que devuelve SendRequest en entityResponse.token (los que
    exige Cancel, sección 1.3 del documento de sign-off) o la forma con «C-»?
(c) ¿Necesitan el «C-» en los listados que produce CIS, como el reporte de pagos del día siguiente y el estado de cuenta?
Mientras tanto: en los reportes de CIS mostramos el MTCN con «C-» y el PIN sin él (es un parámetro que se puede apagar),
y la API no cambia: el token sigue siendo de 10 dígitos.

3. Referencia «RS-»
Su especificación define el transaction_id de SendRequest como su referencia «RS-» (la clave de correlación, única y sin
reutilizar). El equipo de CIS ve un «RS-xxxxx» por pago en uno de sus reportes. ¿Confirman que es exactamente el
transaction_id que ustedes envían en SendRequest, con el prefijo, y que es el mismo que figura en su reporte de pagos y en
su estado de cuenta? Es una confirmación distinta de la del punto 5 de la sección 8 del sign-off (cómo se devuelve el RS-).
Mientras tanto: la referencia de cada pago en nuestros estados de cuenta es el MTCN. Si lo confirman, mostraríamos el RS-
como referencia secundaria.

4. Modificar una transacción ya enviada
Cuando algo que ya enviaron tiene que cambiar (por ejemplo, el nombre del beneficiario), ¿qué hace Soterex? Entendemos
que es cancelar y crear una transacción nueva con otro RS-, con el anterior en previous_transaction_id, como dice la
sección 1.2 del sign-off, cuya confirmación por escrito pedimos en el punto 6 de la sección 8. Acá preguntamos solo lo que
ese punto no cubre:
(a) ¿Qué sub_status (code y message) envían en ese Cancel?
(b) ¿Alguna vez reenvían el SendRequest con el mismo transaction_id esperando que se actualice?
(c) ¿La transacción modificada queda con un estado propio en Soterex, y viaja algo de eso hacia CIS?
Lo preguntamos porque, hoy, un SendRequest con un transaction_id ya usado devuelve la transacción original (COD_009,
status ACCEPTED y su estado actual en dtc_estatus) sin aplicar los datos nuevos (sección 1.4 del sign-off): un cambio
reenviado así no entraría, y la respuesta no lo avisa con un rechazo. Un Cancel de una transacción ya cobrada se rechaza
con CODE_010.
Mientras tanto: el contrato sigue como está en la sección 1.2 del sign-off (corregir es cancelar y crear una transacción
nueva con un RS- nuevo). No cambiamos nada.

5. Lista de países
El equipo de CIS nos pasó una lista de 255 países con los encabezados «Global Country Values», «#» y «Translation -
Spanish», para el campo «país de la identificación» de uno de sus reportes. Parece la exportación de un picklist.
¿Es el picklist de países de su Salesforce? Si lo es:
(a) ¿Con qué código viaja cada valor: ISO 3166-1 alpha-2, otro código o la etiqueta en inglés?
(b) ¿«#» es un simple contador o el orden del picklist?
(c) ¿Qué código llevan las entradas que no tienen código ISO (Chipre del Norte, Irlanda del Norte, Somalilandia), Kosovo y
    las Antillas Holandesas? Nosotros usamos XK y AN para estas dos últimas.
Mientras tanto: usamos el código ISO alpha-2 de cada país, tomamos «#» como un contador (los desplegables siguen en orden
alfabético) y no cargamos las entradas sin código ISO.

6. Fecha de nacimiento y nacionalidad del beneficiario
El equipo de CIS nos dice que la fecha de nacimiento y la nacionalidad del beneficiario figuran en el reporte que produce
Soterex. Su especificación de SendRequest no trae esos dos datos. ¿Pueden mandarlos en SendRequest, o solo figuran en el
reporte? Si pueden mandarlos, ¿en qué campo, y la nacionalidad viaja como código de país (¿cuál?) o como texto?
Mientras tanto: los carga el cajero al pagar (la nacionalidad, de un desplegable con la lista de países) y la API no cambia.
Si nos confirman que van a mandarlos, lo vemos aparte antes de tocar nada.

Gracias. Quedamos atentos.

Saludos,
Carlos

El mail (inglés) ​

Mismo contenido, para el caso de que lo mandes en inglés como los anteriores.

Subject: Re: Technical Kick Off CIS APIs — six questions (questions only)

Hi Sean,

Here are six questions that came up when we went through, with the CIS team, how the integration will be used. They are
questions only: none asks for a change to the API and none blocks sandbox testing, although we would like to have the 4th
before handling real amounts. If someone else on your team is better placed to answer any of them, please forward it.
Under each one we say what we do while we have no answer.

1. Prefunding
How does Soterex tell CIS about each prefunding (the money Soterex advances to CIS so it can pay): through the API, by
e-mail, in the account statement or some other way? Your specification has no prefunding message, and today CIS enters
each one by hand in its own tool. If the prefunding only appears in the account statement (the template of which we asked
for in our previous e-mail), it is enough for us to know that.
Meanwhile: we keep entering it by hand.

2. The "C-" prefix of the MTCN
On the Soterex letter to the beneficiary that we have seen, the MTCN appears as "C-" plus 10 digits, and the Payment PIN as
those same 10 digits.
(a) Do your letter and your Salesforce still show it that way?
(b) Which form do you store, and which one do you send in Cancel: the 10 digits that SendRequest returns in
    entityResponse.token (the ones Cancel requires, section 1.3 of the sign-off document) or the form with "C-"?
(c) Do you need the "C-" in the listings CIS produces, such as the next-day payment report and the account statement?
Meanwhile: in CIS reports we show the MTCN with "C-" and the PIN without it (a setting we can switch off), and the API
does not change: the token stays at 10 digits.

3. The "RS-" reference
Your specification defines the transaction_id of SendRequest as your "RS-" reference (the correlation key, unique and never
reused). The CIS team sees an "RS-xxxxx" per payment in one of its reports. Can you confirm that it is exactly the
transaction_id you send in SendRequest, prefix included, and that it is the same one that appears in your payment report and
in your account statement? This is a different confirmation from point 5 of section 8 of the sign-off (how the RS- is echoed).
Meanwhile: the reference of each payment in our account statements is the MTCN. If you confirm it, we would show the RS- as a
secondary reference.

4. Changing a transaction that was already sent
When something you already sent has to change (for example the beneficiary's name), what does Soterex do? We understand
it is cancel and create a new transaction with a different RS-, with the old one in previous_transaction_id, as section 1.2
of the sign-off says, and we ask for its written confirmation in point 6 of section 8. Here we ask only what that point
does not cover:
(a) Which sub_status (code and message) do you send on that Cancel?
(b) Do you ever resend the SendRequest with the same transaction_id expecting it to update?
(c) Does the modified transaction get a status of its own in Soterex, and does anything of that travel to CIS?
We ask because, today, a SendRequest with a transaction_id that was already used returns the original transaction (COD_009,
status ACCEPTED and its current status in dtc_estatus) without applying the new data (section 1.4 of the sign-off): a change
resent that way would not take effect, and the response does not flag it with a rejection. A Cancel of a transaction that has
already been collected is rejected with CODE_010.
Meanwhile: the contract stays as in section 1.2 of the sign-off (a correction is cancel and create a new transaction with a
new RS-). We change nothing.

5. Country list
The CIS team gave us a list of 255 countries with the headers "Global Country Values", "#" and "Translation - Spanish", for
the "country of the identification" field of one of its reports. It looks like the export of a picklist. Is it the country
picklist of your Salesforce? If it is:
(a) Which code travels with each value: ISO 3166-1 alpha-2, another code, or the English label?
(b) Is "#" a plain counter or the order of the picklist?
(c) Which code do the entries with no ISO code (Northern Cyprus, Northern Ireland, Somaliland), Kosovo and the Netherlands
    Antilles carry? We use XK and AN for the last two.
Meanwhile: we use the ISO alpha-2 code of each country, take "#" as a counter (dropdowns stay in alphabetical order) and do
not load the entries with no ISO code.

6. Beneficiary date of birth and nationality
The CIS team tells us that the beneficiary's date of birth and nationality appear in the report Soterex produces. Your
SendRequest specification does not carry those two data. Can you send them in SendRequest, or do they only appear in the
report? If you can send them, in which field, and does the nationality travel as a country code (which one?) or as text?
Meanwhile: the cashier enters them when paying (the nationality from a dropdown with the country list) and the API does not
change. If you confirm that you will send them, we will look at it separately before touching anything.

Thank you, and we look forward to your answers.

Best,
Carlos

Cuando contesten ​

Qué destraba cada respuesta. Ninguna cambia la integración sin otro plan.

#Si Soterex contesta…Qué se haceEntrega
1Que sí, por APISe define el mensaje y existe la rama "notifica por API" del paso 2 de tesorería (RV3-56/57); alimenta G13. Es una integración nueva: otro planG13 (afuera por ahora)
1Que noSigue la carga manual; se cierra RV3-56—
2Que ya no usan «C-»Apagar el prefijo (CUMPLIMIENTO_MTCN_PREFIX vacía, sin tocar código)G9 (#92)
2Que mandan el Cancel con «C-»Hoy da 2102: es un tema de integración, otro plan—
3Que sí es el transaction_idSe agrega el RS- como referencia secundaria en los extractos; se cierra la pregunta 17 de 06-preguntas-abiertas-caja y RV3-98Posterior
3Que noSe omite (la regla del cliente)—
4Cancelar y crear con RS- nuevoEs lo que ya dice el sign-off; define si "Transaction Status – Update" de Cumplimiento se queda en el estado vigente (RV3-91)G9
4Reenviar con el mismo RS-Un cambio así hoy no entra y no avisa: es un tema de integración, otro plan—
5Que es su picklistSe cierran los casos dudosos de QC-27 con su código y QC-28 con el orden del «#»G10 (#93)
6Que sí pueden mandarlosEs un cambio de contrato (SendRequest suma dos campos): otro plan, regla P3-13. El combo de nacionalidad (J2) sigue siendo el respaldoPosterior
6Que no, o que solo figuran en su reporteLos sigue cargando el cajero; la nacionalidad sale del combo de países (J2)—

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