transferenciaSaldo

El método trasferenciaSaldo permite solicitar una transferencia de saldo entre dos comercios registrados en la plataforma de Operaciones en Línea (OEL), mediante el servicio SoapAliados.

La operación identifica un comercio de origen, desde el cual se solicita transferir un importe, y un comercio de destino, al cual se dirige dicho importe.

La solicitud también permite proporcionar un identificador de transacción, un concepto, una descripción complementaria y hasta tres referencias para relacionar el movimiento con los registros del sistema integrador.

Como resultado, el servicio devuelve información del aliado, ambos comercios, el monto procesado, identificadores de la operación y códigos funcionales de respuesta.

Importante: esta operación solicita un movimiento financiero. No debe confundirse con una consulta de saldo ni con una transferencia bancaria SPEI.

Nombre exacto de la operación

Aunque el término habitual en español es transferencia, el contrato utiliza:

trasferenciaSaldo

Este nombre debe respetarse exactamente en el elemento SOAP, la respuesta y el encabezado SOAPAction.

El tipo de datos, en cambio, utiliza la palabra completa:

• Request: cTransferenciaSaldoReq

• Response: cTransferenciaSaldoResp

Información del servicio

Endpoint de producción

Endpoint de desarrollo

La disponibilidad de este ambiente y la autorización para realizar transferencias deben verificarse con OEL.

Autenticación

La operación utiliza la cabecera SOAP OpHeader y las credenciales del aliado incluidas en el objeto request.

Cabecera SOAP — OpHeader

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

Credenciales del aliado

Parámetros de solicitud (Request)

La operación recibe un objeto request de tipo cTransferenciaSaldoReq, compuesto por once parámetros.

Los campos se presentan en el orden exacto establecido por el WSDL.

Identificación de los comercios

origen_comercioId

Identifica el comercio desde el cual se solicita transferir el saldo.

El comercio debe estar activo, pertenecer al mismo aliado que el destinatario y contar con permisos especiales.

destino_comercioId

Identifica el comercio que recibirá el saldo transferido.

El comercio de destino debe pertenecer al mismo aliado y contar con permisos especiales.

Identificación de la transferencia

transaccionId

Por seguridad, se recomienda generar un identificador único por operación lógica y conservarlo durante todo su ciclo de vida.

Monto de la transferencia

monto

Representa el importe solicitado.

Concepto y descripción

concepto

Permite indicar el motivo general de la transferencia.

descripcion

Permite incorporar información complementaria sobre el movimiento.

Referencias adicionales

Los campos referencia1, referencia2 y referencia3 permiten incorporar identificadores complementarios del sistema integrador.

Por ejemplo, pueden utilizarse para relacionar una transferencia con un folio interno, una operación administrativa o un proceso de conciliación.

Estos son ejemplos de uso propuesto. OEL no define un significado obligatorio para cada referencia.

Ejemplo XML Request — SOAP 1.1

Petición HTTP

Cuerpo SOAP

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    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>
    <trasferenciaSaldo
        xmlns="https://servidorseguro.operacionesenlinea.com/">
      <request>
        <claveAliado>ALIADO_DEMO</claveAliado>
        <contrasena>CLAVE_ALIADO</contrasena>
        <origen_comercioId>12345</origen_comercioId>
        <destino_comercioId>67890</destino_comercioId>
        <transaccionId>TRF-DEMO-000001</transaccionId>
        <monto>100.00</monto>
        <concepto>AJUSTE_DEMO</concepto>
        <descripcion>Transferencia de ejemplo</descripcion>
        <referencia1>REF-DEMO-001</referencia1>
        <referencia2>REF-DEMO-002</referencia2>
        <referencia3>REF-DEMO-003</referencia3>
      </request>
    </trasferenciaSaldo>

Todos los identificadores, credenciales y valores son ficticios.

Este ejemplo ilustra la estructura XML y no debe ejecutarse contra producción sin sustituir las credenciales y confirmar la autorización de ambos comercios.

Parámetros de respuesta (Response)

El servicio devuelve el elemento trasferenciaSaldoResponse, que puede contener trasferenciaSaldoResult, de tipo cTransferenciaSaldoResp.

El WSDL define 14 parámetros.

1. Identificación del aliado

Nota: el nombre exacto es aliadoId, con d minúscula. Otros métodos de SoapAliados utilizan aliadoID.

2. Comercio de origen

Estos campos identifican el establecimiento desde el cual se solicita transferir el saldo.

3. Comercio de destino

Estos campos identifican el establecimiento destinatario.

4. Información de la transferencia

5. Resultado funcional

Ejemplo XML Response — SOAP 1.1

El siguiente ejemplo incluye los catorce campos definidos en cTransferenciaSaldoResp, respetando su orden en el WSDL.

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

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

Notas sobre el ejemplo

Todos los datos son ficticios.

Los valores 0 de codigoRespuesta y ccErrorCode son ilustrativos. No establecen que dichos códigos representen necesariamente una transferencia aprobada.

Algunos campos pueden estar ausentes en respuestas reales.

El ejemplo tampoco confirma que los saldos de ambos comercios hayan sido efectivamente actualizados.

Interpretación de la respuesta

Resultado funcional

La aplicación debe interpretar codigoRespuesta, ccErrorCode y mensajeRespuesta conforme al catálogo de resultados confirmado por OEL.

Una respuesta HTTP 200 OK no debe considerarse prueba suficiente de que los fondos fueron transferidos.

Correspondencia de comercios

Se recomienda comprobar que:

• origen_comercioId corresponda al comercio que solicitó transferir los fondos.

• destino_comercioId corresponda al destinatario autorizado.

• transaccionId corresponda a la operación lógica esperada.

• monto coincida con el importe autorizado.

Código de aprobación

Cuando se devuelva, codigoAprobacion podrá conservarse como dato de seguimiento.

No debe utilizarse como único indicador de éxito sin confirmar su significado funcional.

Verificación financiera posterior

Cuando el servicio confirme satisfactoriamente una transferencia, se recomienda consultar el saldo de ambos comercios mediante saldoComercio.

Sin embargo, el contrato no garantiza que los saldos se actualicen inmediatamente ni que la diferencia entre ellos sea exactamente igual al importe transferido, ya que podrían existir otros movimientos o reglas operativas.

Flujo operativo recomendado

Paso 1. Identificar al aliado

Obtener las credenciales autorizadas para ejecutar operaciones financieras mediante SoapAliados.

Paso 2. Identificar ambos comercios

Determinar los identificadores de origen y destino.

Paso 3. Validar la autorización

Comprobar que el sistema o usuario solicitante tenga facultades para realizar la transferencia.

Paso 4. Consultar el saldo de origen

Invocar saldoComercio para conocer el importe disponible reportado por OEL.

Esta consulta no reserva fondos ni garantiza la aceptación posterior de la transferencia.

Paso 5. Validar el importe

Verificar que el monto sea válido y corresponda a una operación autorizada.

Paso 6. Generar un identificador

Asignar un transaccionId único en el sistema integrador.

Paso 7. Construir la solicitud SOAP

Incluir OpHeader, credenciales, comercios, monto y los campos complementarios necesarios.

Paso 8. Enviar la transferencia

Invocar trasferenciaSaldo mediante HTTPS.

Paso 9. Procesar la respuesta

Evaluar los códigos funcionales y comprobar los identificadores y el monto devueltos.

Paso 10. Registrar el resultado

Actualizar el estado interno de la operación únicamente cuando exista una confirmación funcional válida.

Paso 11. Verificar los saldos

Cuando corresponda, consultar saldoComercio para ambos establecimientos.

Paso 12. Conciliar

Relacionar la operación con los registros administrativos y financieros disponibles.

Este flujo es una recomendación para integradores de Bloomin y no implica que OEL garantice reservas de fondos, actualización inmediata o procesamiento atómico.

Tiempo de espera

Si el integrador no recibe respuesta, la transferencia podría encontrarse en cualquiera de estas situaciones:

• La solicitud no llegó al servicio.

• La solicitud fue recibida, pero no procesada.

• La solicitud fue procesada y rechazada.

• La transferencia fue ejecutada, pero la respuesta no llegó al cliente.

Recomendación de implementación

Ante un resultado indeterminado, se recomienda conservar el intento original y evitar reenvíos automáticos hasta confirmar el estado de la transferencia con OEL.

Casos de uso

Transferencia entre comercios asociados

Un aliado autorizado puede solicitar el movimiento de saldo desde un comercio hacia otro, sujeto a las reglas de OEL.

La operación puede formar parte de procesos administrativos que requieran transferir saldos entre establecimientos.

Este uso está condicionado a que OEL permita el movimiento y a que exista autorización de las partes correspondientes.

Ajustes internos autorizados

El sistema integrador puede utilizar concepto, descripcion y las referencias para identificar el motivo administrativo de una transferencia.

Conciliación entre establecimientos

El identificador de transacción y los campos de origen y destino permiten relacionar el movimiento con los registros de ambos comercios.

Códigos de respuesta y errores

El servicio contempla tres campos de resultado:

Escenarios de prueba recomendados

Estos son escenarios recomendados de certificación, no comportamientos confirmados por el contrato.

Recomendaciones de seguridad y control financiero

Autorización explícita

Permitir transferencias únicamente a usuarios o procesos con facultades para mover fondos entre comercios.

Validación de beneficiario

Confirmar que el comercio de destino corresponda al destinatario autorizado antes de ejecutar la solicitud.

Verificación de saldo

Consultar el saldo de origen y aplicar las validaciones internas correspondientes, sin asumir que la consulta garantiza fondos disponibles en el momento de la transferencia.

Control de duplicados

Mantener identificadores únicos y estados internos para evitar que una misma solicitud de negocio se envíe varias veces.

Separación de funciones

Para operaciones sensibles, considerar controles de aprobación distintos de los usuarios que preparan las transferencias.

Registro de auditoría

Conservar los comercios involucrados, el monto, el identificador de transacción, las referencias, la fecha de solicitud y el resultado funcional.

Protección de credenciales

No registrar OpKey1, OpKey2, claveAliado ni contrasena en logs o respuestas públicas.

Manejo de estados indeterminados

No interpretar automáticamente una interrupción de comunicación como una transferencia rechazada.

Conciliación

Contrastar los movimientos con los saldos y reportes financieros disponibles.

Estas medidas son recomendaciones de implementación de OEL para sus integradores; no constituyen garantías funcionales proporcionadas por el WSDL.

Relación con otros métodos

Relación con saldoComercio

saldoComercio es una operación de consulta.

trasferenciaSaldo solicita un movimiento de fondos.

La consulta previa puede ayudar a verificar la disponibilidad reportada, pero no garantiza la ejecución de la transferencia.

Relación con estadoDeCuenta

Los movimientos generados por trasferenciaSaldo aparecen en el resultado de estadoDeCuentay se identifican mediante las categorias de OTROCARGO y OTROABONO.

Esta correspondencia debe verificarse durante la integración.

Diferencias respecto a saldoComercio

Diferencia principal: trasferenciaSaldo no devuelve un saldo final. Si el integrador necesita conocer los saldos posteriores, deberá utilizar otra operación, como saldoComercio, sujeto a las condiciones de actualización de OEL.

Particularidades del contrato XML

1. Nombre exacto de la operación

El WSDL utiliza:

<trasferenciaSaldo>

No utiliza:

<transferenciaSaldo>

La misma regla aplica al SOAPAction y al elemento trasferenciaSaldoResponse.

2. Tipos con ortografía diferente

Los tipos definidos en el WSDL son:

cTransferenciaSaldoReq
cTransferenciaSaldoResp

Estos nombres sí incluyen la primera «n» de transferencia.

3. Identificadores de origen y destino

Los nombres exactos son:

<origen_comercioId>12345</origen_comercioId>
<destino_comercioId>67890</destino_comercioId>

Se utilizan guiones bajos después de origen y destino.

4. Capitalización de aliadoId

La respuesta utiliza:

<aliadoId>100</aliadoId>

No debe sustituirse por aliadoID, utilizado en otros métodos.

Las recomendaciones de seguridad, autorización, conciliación, prevención de duplicados y manejo de errores se presentan como orientación para la integración y no como comportamientos confirmados del servicio.