ecommercePostAutorizacion

1. Descripción general

El método ecommercePostAutorizacion permite solicitar una postautorización de un cargo mediante comercio electrónico, como parte de un esquema de procesamiento que contempla una preautorización previa.

En un flujo de autorización en etapas, la postautorización constituye la operación posterior mediante la cual el comercio solicita completar el procesamiento correspondiente a una autorización inicial.

Este mecanismo puede utilizarse en modelos comerciales donde el pago no se procesa íntegramente en una sola operación.

Descripción oficial del WSDL

Procesa la Post-Autorización de un cargo mediante Comercio Electronico.

Consideración importante

La existencia del método ecommercePostAutorizacion no garantiza por sí sola que se admitan capturas parciales, incrementos de importe, capturas múltiples o postautorizaciones fuera de un plazo determinado.

Estas condiciones dependen de las reglas operativas de OEL y de los participantes del procesamiento.

Asimismo, una respuesta satisfactoria de postautorización no debe interpretarse automáticamente como evidencia de liquidación bancaria definitiva.

2. Casos de uso

La postautorización puede resultar útil en operaciones donde el comercio necesita ejecutar una autorización inicial y posteriormente solicitar el procesamiento del importe correspondiente.

Estos escenarios son ejemplos conceptuales. Su disponibilidad debe verificarse para cada comercio y modalidad de procesamiento.

3. Especificaciones técnicas

3.1. Namespace

3.2. Endpoint definido en el WSDL

Los ambientes de desarrollo, pruebas y producción se documentarán en la sección Ambientes.

3.3. SOAPAction

3.4. Elementos SOAP

El WSDL declara request y ecommercePostAutorizacionResult con minOccurs="0". Esto indica opcionalidad estructural, pero no garantiza que el servicio pueda procesar una operación sin los datos funcionalmente necesarios.

4. Autenticación

La operación utiliza el esquema de autenticación definido para OpGateway.

4.1. Encabezado SOAP OpHeader

Ejemplo:

<soap:Header>
  <OpHeader xmlns="https://servidorseguro.operacionesenlinea.com/">
    <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
    <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
  </OpHeader>

Aunque ambos campos son opcionales estructuralmente, el WSDL no establece que puedan omitirse durante una operación real.

4.2. Credenciales del comercio

La solicitud contiene:

• comercioId: identificador del comercio.

• contrasena: credencial utilizada para autenticar la operación.

4.3. Autenticación mediante ecommerceSessionID

De acuerdo con el mecanismo funcional confirmado para Bloomin, el campo contrasena puede recibir un token temporal generado previamente mediante ecommerceSessionID.

El token:

1. Se solicita utilizando las credenciales permanentes del comercio.

2. Se recibe en el campo sessionId.

3. Sustituye el valor de contrasena en la operación posterior.

4. Es de un solo uso.

Ejemplo:

<comercioId>12345</comercioId>
<contrasena>TOKEN_UN_SOLO_USO_POSTAUTH</contrasena>

Importante: si la preautorización original utilizó un token, ese token no debe reutilizarse para la postautorización.

Para ejecutar una nueva operación utilizando este mecanismo, debe obtenerse un token nuevo.

La sustitución de contrasena no demuestra que OpKey1 y OpKey2 puedan exponerse en un navegador. Su manejo seguro debe verificarse por separado.

5. Parámetros de solicitud (Request)

La operación utiliza el modelo cPostAutorizacionReq.

El WSDL define 11 parámetros, en el siguiente orden:

Interpretación de obligatoriedad

• minOccurs="1": campo obligatorio en el XSD.

• minOccurs="0": campo opcional en el XSD.

La obligatoriedad funcional puede ser distinta de la obligatoriedad estructural.

En particular, aunque transaccionId y codigoAprobacion son opcionales en el XSD, no debe asumirse que el Gateway pueda identificar una preautorización previa sin información de correlación suficiente.

6. Descripción detallada de los parámetros

6.1. comercioId

Identificador numérico del comercio que solicita la postautorización.

Tipo: int
Obligatorio en XSD: Sí

Se recomienda utilizar el identificador correspondiente al comercio que originó la preautorización.

El WSDL no describe expresamente el comportamiento cuando los identificadores de comercio de ambas operaciones son distintos.

6.2. contrasena

Credencial utilizada para autenticar la solicitud.

Tipo: string
Obligatorio en XSD: No

Puede contener la contraseña permanente del comercio o un token de sesión de un solo uso.

Para integraciones desde navegador, el token temporal permite evitar la exposición de la contraseña permanente.

6.3. modo

Parámetro que representa el modo de operación.

Tipo: string
Obligatorio en XSD: No

El contrato no define un catálogo de valores ni su relación exacta con los ambientes disponibles.

6.4. monto

Importe de la postautorización solicitada.

Tipo: decimal
Obligatorio en XSD: Sí

Ejemplo:

<monto>1250.00</monto>

El WSDL no especifica:

• Moneda.

• Importe mínimo o máximo.

• Cantidad de decimales admitidos.

• Si el importe debe ser igual al de la preautorización.

• Si se permite un importe menor.

• Si se permite un importe mayor.

• Si pueden realizarse múltiples postautorizaciones sobre una autorización inicial.

Estas reglas deben confirmarse antes de implementar escenarios de captura parcial o ajuste de importes.

6.5. transaccionId

Identificador de la transacción.

Tipo: string
Obligatorio en XSD: No

Este campo es relevante para establecer la relación entre la postautorización y los registros de la operación original.

Se recomienda conservar el identificador devuelto por ecommercePreAutorizacion.

Sin embargo, el WSDL no confirma:

• Si debe utilizarse exactamente el identificador de la preautorización.

• Si debe generarse uno nuevo.

• Si el identificador debe coincidir con el enviado originalmente.

• Si funciona como llave de idempotencia.

La regla de correlación deberá confirmarse con OEL.

6.6. codigoAprobacion

Código de aprobación relacionado con la operación.

Tipo: string
Obligatorio en XSD: No

Ejemplo:

<codigoAprobacion>APR-DEMO-001</codigoAprobacion>

Este parámetro merece especial atención porque también aparece en la respuesta de ecommercePreAutorizacion.

Su presencia en ambos métodos permite identificar una posible relación funcional entre la autorización inicial y la operación posterior.

No obstante, el contrato no especifica que el código de aprobación deba reutilizarse obligatoriamente ni que sea suficiente para identificar la operación original.

Recomendación: conservar el código devuelto por la preautorización y confirmar con OEL cuándo debe incluirse en la postautorización.

6.7. referencia

Referencia comercial o administrativa.

Tipo: string
Obligatorio en XSD: No

Puede utilizarse para relacionar la operación con una reserva, pedido o servicio.

No se define longitud máxima ni formato.

6.8. dirIp

Dirección IP relacionada con la operación.

Tipo: string
Obligatorio en XSD: No

El WSDL no especifica si corresponde al comprador, al servidor o a otro origen.

6.9. deviceId

Identificador de dispositivo.

Tipo: string
Obligatorio en XSD: No

Aunque el campo aparece en una operación de comercio electrónico, el WSDL no explica su utilización específica en este contexto.

No debe asumirse que sea obligatorio para todas las integraciones ni que deba contener un identificador de terminal física.

6.10. subcomercio

Campo destinado a proporcionar información relacionada con un subcomercio.

Tipo: string
Obligatorio en XSD: No

Su formato, significado exacto y reglas de utilización deben confirmarse con OEL.

6.11. version

Parámetro de versión.

Tipo: string
Obligatorio en XSD: No

El WSDL no define si representa una versión de integración, protocolo, aplicación o dispositivo.

Tampoco publica valores admitidos.

7. Diferencias respecto de ecommercePreAutorizacion

La postautorización no utiliza la misma estructura de solicitud que la preautorización.

Implicación técnica

La postautorización no solicita nuevamente los campos de tarjeta presentes en cTCReq.

En su lugar, incorpora identificadores y datos relacionados con una operación anterior.

Esta diferencia estructural es consistente con un procesamiento en etapas.

Sin embargo, el WSDL no especifica el mecanismo interno utilizado por el Gateway para localizar la autorización original.

8. Ejemplo de solicitud SOAP 1.1

El siguiente ejemplo representa una solicitud estructural de postautorización.

Para ilustrar la relación entre ambas operaciones, se utilizan identificadores ficticios que podrían haberse conservado de una preautorización anterior.

Estos valores de correlación son ilustrativos; las reglas exactas deben confirmarse con OEL.

8.1. Encabezados HTTP

8.2. Solicitud XML

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Header>
    <OpHeader
        xmlns="https://servidorseguro.operacionesenlinea.com/">
      <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
      <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
    </OpHeader>
  </soap:Header>

  <soap:Body>
    <ecommercePostAutorizacion
        xmlns="https://servidorseguro.operacionesenlinea.com/">

8.3. Consideraciones

1. Todos los valores son ficticios.

2. La solicitud utiliza un token nuevo, diferente del que se habría utilizado en la preautorización.

3. El ejemplo incluye transaccionId y codigoAprobacion para ilustrar una posible correlación con la operación original.

4. El ejemplo no demuestra que esos valores sean suficientes para ejecutar una postautorización real.

5. Se omiten los parámetros opcionales cuyo uso no está definido.

6. El orden de los elementos incluidos corresponde al modelo cPostAutorizacionReq.

7. La dirección IP utilizada está reservada para documentación.

9. Parámetros de respuesta (Response)

El método devuelve el elemento ecommercePostAutorizacionResult, de tipo cPostAutorizacionResp.

El WSDL define 15 parámetros.

9.1. comercioId

Identificador del comercio al que corresponde la respuesta.

Se recomienda verificar su correspondencia con el identificador enviado.

9.2. terminalId

Identificador de terminal reportado por el Gateway.

Aunque el método corresponde a comercio electrónico, el modelo de respuesta contempla este campo.

El WSDL no describe su significado específico para esta operación.

9.3. transaccionId

Identificador de transacción devuelto por el servicio.

Se recomienda conservarlo para trazabilidad y conciliación.

El contrato no confirma si corresponde al identificador original de la preautorización o a otro identificador.

9.4. fechaTransaccion y horaTransaccion

Datos temporales de la operación.

Ambos son de tipo string, sin formato ni zona horaria definidos en el WSDL.

9.5. monto

Importe reportado por el servicio.

Se recomienda compararlo con el importe solicitado y con las reglas aplicables a la preautorización original.

9.6. referencia

Referencia devuelta por el servicio.

Puede resultar útil para relacionar la operación con los registros internos del comercio.

9.7. numeroControl

Número de control asociado con el procesamiento.

El contrato no define su formato ni su utilización obligatoria en operaciones posteriores.

9.8. codigoRespuesta

Código funcional de respuesta.

Debe interpretarse conforme al catálogo oficial de OEL.

9.9. procReturnMsg

Mensaje relacionado con el resultado del procesamiento.

9.10. ccErrorCode

Código complementario de resultado o error.

El WSDL no proporciona el catálogo correspondiente.

9.11. ccReturnMsg

Mensaje complementario del Gateway.

9.12. codigoAprobacion

Código de aprobación devuelto por el servicio, cuando corresponda.

Se recomienda conservarlo junto con los datos de la postautorización.

No debe suponerse que siempre coincida con el código de aprobación de la preautorización original.

9.13. afiliacion

Dato de afiliación reportado por el servicio.

Su significado y formato exactos deben confirmarse.

9.14. afiliacionEmpresa

Dato de afiliación de empresa reportado por el servicio.

El WSDL no proporciona reglas de interpretación para este campo.

10. Ejemplo de respuesta SOAP 1.1

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>
    <ecommercePostAutorizacionResponse
        xmlns="https://servidorseguro.operacionesenlinea.com/">

Consideraciones

• Todos los datos son ilustrativos.

• Los códigos 0 no deben interpretarse automáticamente como aprobación.

• La respuesta real puede omitir los elementos opcionales.

• La presencia de codigoAprobacion no sustituye la interpretación de los códigos funcionales.

• El ejemplo no representa una operación bancaria real.

11. Ciclo de procesamiento: preautorización y postautorización

El siguiente flujo representa una propuesta lógica de integración.

Etapa 1. Solicitar preautorización

El comercio invoca ecommercePreAutorizacion con los datos de la operación.

Etapa 2. Evaluar la respuesta

El integrador verifica los códigos funcionales para determinar si la preautorización fue aceptada.

Etapa 3. Conservar los identificadores

Se registran los datos necesarios para relacionar la operación inicial con solicitudes posteriores.

Etapa 4. Determinar la necesidad de postautorización

Cuando corresponda y se cumplan las condiciones operativas, el comercio decide solicitar la postautorización.

Etapa 5. Preparar autenticación

Si se utiliza ecommerceSessionID, se obtiene un token nuevo de un solo uso.

Etapa 6. Construir la solicitud

El comercio prepara cPostAutorizacionReq, incluyendo los identificadores de correlación requeridos por OEL.

Etapa 7. Invocar ecommercePostAutorizacion

La aplicación envía la solicitud SOAP.

Etapa 8. Interpretar la respuesta

Se evalúan los códigos y mensajes devueltos.

Etapa 9. Actualizar la operación comercial

El sistema registra el resultado confirmado y actualiza el estado interno del pedido, reserva o servicio.

Etapa 10. Conciliar

Se conservan los datos necesarios para seguimiento y conciliación.

Diagrama conceptual

Este diagrama representa una secuencia propuesta para el integrador, no una garantía de estados internos o movimientos de fondos del Gateway.

12. Correlación con la preautorización original

Uno de los aspectos más importantes de ecommercePostAutorizacion es identificar correctamente la operación previa.

Información disponible

La respuesta de ecommercePreAutorizacion puede contener:

• comercioId.

• transaccionId.

• codigoAprobacion.

• monto.

• fechaTransaccion.

• horaTransaccion.

• referenciaTransaccionBancaria.

Por su parte, ecommercePostAutorizacion recibe:

• comercioId.

• transaccionId.

• codigoAprobacion.

• monto.

• referencia.

Aspecto pendiente

El WSDL no define cuál de estos campos constituye la llave principal de correlación.

Tampoco especifica si debe utilizarse el mismo transaccionId o uno nuevo.

Recomendación de integración

El sistema del comercio debería conservar una relación interna entre:

Los identificadores exactos que deben enviarse al Gateway deberán validarse mediante documentación operativa o pruebas de integración.

13. Manejo de errores

La operación puede presentar errores de autenticación, validación, comunicación o procesamiento.

El WSDL no incluye un catálogo completo de errores.

Los escenarios de preautorización no localizada, vencida o importe no permitido son situaciones que el integrador debe contemplar; el WSDL no proporciona códigos específicos para ellas.

14. Prevención de operaciones duplicadas

Una postautorización puede tener consecuencias financieras.

Por ello, los reintentos deben controlarse cuidadosamente.

14.1. Identificación

Se recomienda registrar cada intento de postautorización y relacionarlo con la preautorización original.

14.2. Idempotencia

El WSDL no confirma que transaccionId actúe como llave de idempotencia.

Por tanto, no debe asumirse que reenviar la misma solicitud impida un procesamiento duplicado.

14.3. Timeout

Una interrupción de comunicación no demuestra que la postautorización haya fallado.

El Gateway podría haber recibido o procesado la solicitud antes de que se interrumpiera la comunicación.

14.4. Reintentos

Ante un resultado indeterminado:

1. Conservar los identificadores de la operación.

2. Registrar el intento.

3. Consultar o conciliar el estado mediante los mecanismos habilitados.

4. Evitar reenviar la postautorización hasta determinar el resultado anterior.

Obtener un token nuevo no elimina el riesgo de duplicar una operación.

15. Seguridad y protección de datos

15.1. Credenciales permanentes

La contraseña permanente del comercio debe permanecer protegida en componentes seguros.

15.2. Token temporal

Cuando se utilice ecommerceSessionID, cada postautorización debe emplear un token nuevo.

El token no debe registrarse en logs ni exponerse en direcciones URL.

15.3. Encabezado OpHeader

El WSDL declara OpHeader para esta operación.

Debe confirmarse el mecanismo seguro de manejo de OpKey1 y OpKey2, especialmente en integraciones desde navegador.

15.4. Datos de tarjeta

cPostAutorizacionReq no contiene campos para número de tarjeta, fecha de vencimiento o código de seguridad.

Esto reduce la necesidad de volver a transmitir dichos datos durante esta etapa.

No obstante, el alcance PCI DSS de la integración depende de su arquitectura completa y de los sistemas involucrados.

15.5. Registros

Se recomienda conservar:

• Identificador del comercio.

• Identificadores de transacción.

• Importe solicitado.

• Importe reportado.

• Código funcional.

• Código complementario.

• Código de aprobación.

• Número de control.

• Referencias y datos de afiliación cuando existan.

No deben almacenarse credenciales permanentes ni tokens activos en registros de auditoría.

16. Restricciones y consideraciones operativas

16.1. Vigencia de la preautorización

El WSDL no especifica durante cuánto tiempo puede ejecutarse una postautorización sobre una autorización previa.

16.2. Capturas parciales

No se confirma si monto puede ser inferior al importe de la preautorización.

16.3. Incrementos de importe

No se confirma si puede solicitarse un importe superior al autorizado inicialmente.

16.4. Capturas múltiples

No se confirma si una misma preautorización puede utilizarse para más de una postautorización.

16.5. Correlación

No se define qué combinación de transaccionId, codigoAprobacion y otros campos identifica obligatoriamente la preautorización.

16.6. Moneda

La solicitud no contiene un campo de moneda.

16.7. Identificadores

El WSDL no define longitudes máximas para transaccionId, codigoAprobacion o referencia.

16.8. deviceId

El significado operativo de deviceId en comercio electrónico requiere confirmación.

16.9. version

El WSDL no define un catálogo de versiones admitidas.

16.10. Respuestas

La interpretación de codigoRespuesta y ccErrorCode requiere el catálogo oficial de OEL.

17. Aspectos pendientes de confirmación

Para completar la documentación operativa de ecommercePostAutorizacion será necesario confirmar:

1. Plazo máximo permitido entre preautorización y postautorización.

2. Requisitos para habilitar postautorizaciones por comercio.

3. Si debe utilizarse el mismo transaccionId de la preautorización.

4. Si codigoAprobacion es obligatorio funcionalmente.

5. Qué identificadores permiten localizar la operación original.

6. Si el importe debe coincidir con el preautorizado.

7. Si se permiten postautorizaciones parciales.

8. Si se permiten importes superiores.

9. Si se permiten múltiples postautorizaciones.

10. Qué ocurre con el importe restante en una postautorización parcial.

11. Reglas de cancelación posteriores a una postautorización.

12. Catálogo de valores para modo.

13. Significado y obligatoriedad de deviceId.

14. Reglas de subcomercio.

15. Significado y valores de version.

16. Reglas de dirIp.

17. Moneda y límites de importe.

18. Catálogo de codigoRespuesta.

19. Catálogo de ccErrorCode.

20. Significado de numeroControl.

21. Reglas de generación de codigoAprobacion.

22. Significado de afiliacion y afiliacionEmpresa.

23. Formato y zona horaria de fecha y hora.

24. Comportamiento ante solicitudes duplicadas.

25. Procedimiento oficial ante timeout.

26. Condiciones de vigencia y consumo del token temporal.

27. Manejo de OpHeader en solicitudes desde navegador.

28. Políticas CORS aplicables.

29. Requisitos de certificación y pruebas.

18. Métodos relacionados

19. Referencias técnicas

Contrato: OpGateway.xml

Definiciones utilizadas:

• ecommercePostAutorizacion.

• cPostAutorizacionReq.

• ecommercePostAutorizacionResponse.

• cPostAutorizacionResp.

• OpHeader.

• SOAPAction de ecommercePostAutorizacion.

Información funcional complementaria: mecanismo de autenticación mediante token temporal de un solo uso, confirmado para ecommerceSessionID.

Estado de la documentación: estructura contractual documentada; pendientes de confirmación las reglas de correlación, vigencia, importes, capturas y comportamiento financiero.