Cómo Migrar al Informe Producido V2

El Servicio de Notificación V1 API está ahora obsoleto y será eliminado como parte de la versión 2026.4.0 de IPF.
Si está utilizando el servicio de Notificación de Pagos, debe migrar a la V2.API antes de entonces.

Por qué querría migrar

El informe producido V1 está estrechamente vinculado al núcleo IPF Supported Message Definitions, específicamente el pain.001.001.09 y pain.002.001.10 definiciones.

A medida que avanza el desarrollo de IPF, se introducirán versiones más recientes de las definiciones de mensajes ISO. Como resultado, no podemos garantizar que el ProducedReport funcionará correctamente al utilizar un pain.001 mensaje de una versión futura (por ejemplo,pain.001.001.10).
Una limitación similar existe la PDS objetos adjuntos al Informe Producido V1. Estos objetos no especifican su tipo o versión, lo que hace imposible que el consumidor deduzca la estructura de lo proporcionado. PDS objetos.

El informe producido V2 está diseñado para ser independiente de la versión, garantizando la compatibilidad independientemente de la versión del mensaje ISO que se esté utilizando o generando. Además, el informe V2 proporciona PDS tipo y versión, permitiendo a los consumidores inferir la estructura de lo proporcionado PDS objetos.

Diferencias en la Estructura de Datos

Las principales diferencias entre los Informes Producidos V1 y V2 giran en torno a la versionado de los mensajes ISO producidos y PDS objetos.

Mensajes ISO

  • V1 ProducedReport:

    • El report el campo es de tipo com.iconsolutions.iso20022.message.definitions.payments_initiation.pain002.CustomerPaymentStatusReportV10

    • El pain001 el campo es de tipo com.iconsolutions.iso20022.message.definitions.payments_initiation.pain001.CustomerCreditTransferInitiationV09.

En esta versión, los mensajes ISO están estrechamente vinculados a las definiciones de mensajes específicas mencionadas anteriormente, lo que reduce la flexibilidad.

  • V2 ProducedReport:

    • Ambos el report y pain001 los campos se han actualizado para utilizar el IsoMessageWrapper Java tipo.

    • Este cambio desacopla los mensajes ISO producidos de las definiciones exactas de los mensajes. En su lugar, el envoltorio proporciona la definición del mensaje ISO, permitiendo a los consumidores inferir la estructura del mensaje ISO subyacente.

public record IsoMessageWrapper(String messageDefinition,
                                JsonNode isoMessage) {
}

PDS Objetos

  • V1 ProducedReport:

    • Contiene únicamente el name y content de un PDS objeto. Haciendo el PDS la inferencia de la estructura del contenido es más desafiante para los consumidores.

  • V2 ProducedReport:

    • Utiliza el nuevo PdsObjectWrapper Java tipo que incluye dos nuevos campos:`typeName` y version.

  • Estos campos permiten a los consumidores inferir la estructura de la base subyacente. PDS contenido más fácilmente.

public record PdsObjectWrapper(String name,
                               String typeName,
                               Integer version,
                               JsonNode content) {
}

Eliminación del NotificationEnvelope campo de resultado

El V1 NotificationEnvelope incluido un result campo, que fue utilizado internamente por el Resequenciador de la aplicación del servicio de notificaciones. Dado que este campo no es necesario para el informe producido, ha sido eliminado en la V2.NotificationEnvelope modelo.

Comparación

A continuación se encuentran JSON representaciones de cadena del mismo informe producido tanto para la V1 como para la V1 APIs.

V1 ProducedReport 
{
  "uniqueId": "29786d8ae74d4f798476a068568ac5d3",
  "envelope": {
    "context": {
      "unitOfWorkId": "a9d84622-4e00-44e2-8705-7a42029c2754",
      "clientRequestId": "client-request-id-uXTNk",
      "processingEntity": "unit-of-work-KUvgO",
      "associationId": "a9d84622-4e00-44e2-8705-7a42029c2754"
    },
    "processFlowEvent": {
      "class": "com.iconsolutions.ipf.processingdata.process.ProcessFlowEvent",
      "eventId": "DebtorCT-Scheme Rules Validated-1",
      "eventName": "Scheme Rules Validated",
      "processFlowDefinitionId": "DebtorCT",
      "processFlowId": "DebtorCT",
      "causedBy": "caused-by-ipyDQ",
      "processFlowSequence": 1,
      "status": {
        "originatingStatus": "Booking",
        "resultingStatus": "Completed",
        "globalStatus": "Completed"
      },
      "reasonCode": "1",
      "reasonText": "Invalid credit account number",
      "content": "flow-event-content-MlWxm",
      "createdAt": "2025-10-31T10:26:49.690Z"
    },
    "matchingSetting": {
      "domainEvent": "Scheme Rules Validated",
      "processFlow": "DebtorCT",
      "status": "ACCC",
      "transport": "kafka",
      "endpoints": [
        {
          "topic": "PAYMENT_STATUS_NOTIFICATION"
        }
      ],
      "proprietary": "validated"
    },
    "result": {
      "completedExceptionally": false,
      "numberOfDependents": 1,
      "done": false,
      "cancelled": false
    }
  },
  "report": {
    "grpHdr": {
      "msgId": "578db9ec-d71f-43fb-9954-4320f6f4",
      "creDtTm": "2025-10-31T10:26:49.750390909Z"
    },
    "orgnlPmtInfAndSts": [
      {
        "txInfAndSts": [
          {
            "orgnlInstrId": "instrId-1",
            "txSts": "ACCC",
            "stsRsnInf": [
              {
                "rsn": {
                  "cd": "1"
                },
                "addtlInf": [ "additionalInfo" ]
              }, {
                "rsn": {
                  "prtry": "validated"
                },
                "addtlInf": [ "additionalInfo" ]
              }
            ]
          }
        ]
      }
    ],
    "orgnlGrpInfAndSts": {
      "orgnlMsgNmId": "pain.001.001.09",
      "orgnlNbOfTxs": "1"
    },
    "splmtryData": [ ]
  },
  "pain001": {
    "grpHdr": {
      "nbOfTxs": "1"
    },
    "pmtInf": [
      {
        "cdtTrfTxInf": [
          {
            "pmtId": {
              "instrId": "instrId-1"
            }
          }
        ]
      }
    ],
    "splmtryData": [ ]
  },
  "customData": [
    {
      "name": "BusinessData",
      "content": "custom-business-data"
    }, {
      "name": "IPFProcessingData",
      "content": "custom-processing-data"
    }
  ],
  "pdsData": [
    {
      "name": "Csm",
      "content": {
        "value": "STET"
      }
    }, {
      "name": "ClientSpecificBusinessData",
      "content": {
        "someField": "someValue"
      }
    }
  ]
}
V2 ProducedReport 
{
  "uniqueId": "29786d8ae74d4f798476a068568ac5d3",
  "envelope": {
    "context": {
      "unitOfWorkId": "a9d84622-4e00-44e2-8705-7a42029c2754",
      "clientRequestId": "client-request-id-uXTNk",
      "processingEntity": "unit-of-work-KUvgO",
      "associationId": "a9d84622-4e00-44e2-8705-7a42029c2754"
    },
    "processFlowEvent": {
      "eventId": "DebtorCT-Scheme Rules Validated-1",
      "eventName": "Scheme Rules Validated",
      "processFlowDefinitionId": "DebtorCT",
      "processFlowId": "DebtorCT",
      "causedBy": "caused-by-ipyDQ",
      "processFlowSequence": 1,
      "status": {
        "originatingStatus": "Booking",
        "resultingStatus": "Completed",
        "globalStatus": "Completed"
      },
      "reasonCode": "1",
      "reasonText": "Invalid credit account number",
      "content": "flow-event-content-MlWxm",
      "createdAt": "2025-10-31T10:26:49.690Z"
    },
    "matchingSetting": {
      "domainEvent": "Scheme Rules Validated",
      "processFlow": "DebtorCT",
      "status": "ACCC",
      "transport": "kafka",
      "endpoints": [
        {
          "topic": "PAYMENT_STATUS_NOTIFICATION"
        }
      ],
      "proprietary": "validated"
    }
  },
  "report": {
    "messageDefinition": "pain.002.001.10",
    "isoMessage": {
      "grpHdr": {
        "msgId": "578db9ec-d71f-43fb-9954-4320f6f4",
        "creDtTm": "2025-10-31T10:26:49.750390909Z"
      },
      "orgnlPmtInfAndSts": [
        {
          "txInfAndSts": [
            {
              "orgnlInstrId": "instrId-1",
              "txSts": "ACCC",
              "stsRsnInf": [
                {
                  "rsn": {
                    "cd": "1"
                  },
                  "addtlInf": [ "additionalInfo" ]
                }, {
                  "rsn": {
                    "prtry": "validated"
                  },
                  "addtlInf": [ "additionalInfo" ]
                }
              ]
            }
          ]
        }
      ],
      "orgnlGrpInfAndSts": {
        "orgnlMsgNmId": "pain.001.001.09",
        "orgnlNbOfTxs": "1"
      }
    }
  },
  "pain001": {
    "messageDefinition": "pain.001.001.09",
    "isoMessage": {
      "grpHdr": {
        "nbOfTxs": "1"
      },
      "pmtInf": [
        {
          "cdtTrfTxInf": [
            {
              "pmtId": {
                "instrId": "instrId-1"
              }
            }
          ]
        }
      ],
      "splmtryData": [ ]
    }
  },
  "customData": [
    {
      "name": "BusinessData",
      "content": "custom-business-data"
    }, {
      "name": "IPFProcessingData",
      "content": "custom-processing-data"
    }
  ],
  "pdsData": [
    {
      "name": "Csm",
      "typeName": "Csm",
      "version": 1,
      "content": {
        "value": "STET"
      }
    }, {
      "name": "ClientSpecificBusinessData",
      "typeName": "ClientJavaClass",
      "version": 3,
      "content": {
        "someField": "someValue"
      }
    }
  ]
}

ProducedReport Java Mapas de tipo

Para ayudar con la adopción del nuevo modelo, proporcionamos el completo mappings para Java referencias.

IMPORTANTE

El nuevo modelo aprovecha Java registros, que introducen un cambio clave en la forma en que se accede a los campos. Los campos que anteriormente se accedían mediante getters ahora se acceden directamente por nombre:

  • Old:`producedReport.getEnvelope()`

  • Nuevo:`producedReport.envelope()`

Old Model New Model

com.iconsolutions.ipf.product.notification.api.model.ProducedReport

com.iconsolutions.ipf.product.notification.api.model.v2.ProducedReport

com.iconsolutions.ipf.product.notification.api.model.NotificationEnvelope

com.iconsolutions.ipf.product.notification.api.model.v2.NotificationEnvelope

com.iconsolutions.ipf.core.shared.domain.context.ProcessingContext

com.iconsolutions.ipf.product.notification.api.model.v2.ProcessingContext

com.iconsolutions.ipf.processingdata.process.ProcessFlowEvent

com.iconsolutions.ipf.product.notification.api.model.v2.ProcessFlowEvent

com.iconsolutions.ipf.core.shared.domain.event.Status

com.iconsolutions.ipf.product.notification.api.model.v2.ProcessFlowEvent.Status

com.iconsolutions.ipf.product.notification.api.model.PaymentStatusNotification

com.iconsolutions.ipf.product.notification.api.model.v2.PaymentStatusNotification

com.iconsolutions.ipf.product.notification.api.model.Endpoint

com.iconsolutions.ipf.product.notification.api.model.v2.Endpoint

com.iconsolutions.ipf.processingdata.custom.CustomObjectWrapper

com.iconsolutions.ipf.product.notification.api.model.v2.CustomObjectWrapper

com.iconsolutions.ipf.product.notification.api.model.PdsObjectWrapper

com.iconsolutions.ipf.product.notification.api.model.v2.PdsObjectWrapper

Pasos para Migrar

Actualice la configuración del servicio de notificación de pagos para producir mensajes V1.

Por defecto, el servicio de notificación emitirá una V2 ProducedReport. Lo primero que debe hacer antes de adoptar la última versión será configurar la aplicación para que continúe emitiendo una V1 ProducedReport mientras actualiza su consumidor.

payment-status-notification.schema-version = 1

Actualizar Consumidor

Antes de que pueda comenzar a producir mensajes del Servicio de Notificación utilizando el modelo V2, debe primero actualizar su aplicación consumidora para poder manejar los mensajes V2.

La carga útil creada por el Servicio de Notificaciones contiene el encabezado ipf_schema_version, el valor del cual definirá qué versión de la ProducedReport el modelo está contenido dentro.

Encabezado del Mensaje Descripción

ipf_schema_version = 2

El mensaje entrante utiliza el modelo de Informe Producido V2

ipf_schema_version = 1

El mensaje entrante utiliza el modelo de Informe Producido V1

ipf_schema_version no está configurado

El mensaje entrante utiliza el modelo de Informe Producido V1. Esto habrá originado de una versión anterior del Servicio de Notificación que solo contenía el modelo de datos V1.

Al actualizar un consumidor de mensajes del Servicio de Notificación, debe añadir una verificación para el ipf_schema_version encabezado para identificar qué versión del modelo de datos utilizar al manejar el mensaje entrante.

Refiérase a diferencias en la estructura de datos para una comparación detallada entre los modelos V1 y V2.

Una vez que su aplicación consumidora sea capaz de manejar mensajes V2, puede actualizar el Servicio de Notificación de Pagos para comenzar a producir mensajes V2.

Actualizar Extension Puntos

Si ha construido servicio de notificación específico para el cliente y han anulado cualquiera de los Puntos de extensión V1, usted deberá proporcionar el equivalente a V2 por cada uno.

NOTA

Si se proporcionan tanto los puntos de extensión V1 como V2, se utiliza la implementación V2 por defecto.

Extension Punto Java Mapas de tipo

Para ayudar con la adopción de los nuevos puntos de extensión, proporcionamos el completo mappings para Java referencias.

Old Model New Model

com.iconsolutions.ipf.product.notification.api.handler.AdditionalMdsObjectHandler

com.iconsolutions.ipf.product.notification.api.handler.v2.AdditionalMdsObjectHandler

com.iconsolutions.ipf.product.notification.api.processor.PostEventProcessor

com.iconsolutions.ipf.product.notification.api.processor.v2.PostEventProcessor

MessageLogEntryEnricher<com.iconsolutions.ipf.product.notification.api.model.ProducedReport>

MessageLogEntryEnricher<com.iconsolutions.ipf.product.notification.api.model.v2.ProducedReport>

SendTransportMessageConverter<com.iconsolutions.ipf.product.notification.api.model.ProducedReport>

SendTransportMessageConverter<com.iconsolutions.ipf.product.notification.api.model.v2.ProducedReport>

Actualice la configuración del servicio de notificación de pagos para producir mensajes V2.

Ahora que su consumidor puede manejar V2 ProducedReport mensajes, puede configurar la aplicación del servicio de notificaciones para producir mensajes V2.
Puede hacer esto eliminando el valor configurado previamente:

payment-status-notification.schema-version = 1

Puede eliminar la línea por completo o actualizar su valor de la siguiente manera:

payment-status-notification.schema-version = 2