Documentation for a newer release is available. View Latest

Guía de migración de Inquiry API V2

Cambios de especificación desde V1

La Inquiry API V2 se introdujo para eliminar todos los endpoints relacionados con /payment-objects y unificar los parámetros de búsqueda de los cuatro endpoints de /views/summaries/. Se han realizado los siguientes cambios:

  • Todos los endpoints se han actualizado para tener una ruta que comience con /api/v2. Por ejemplo:

    • /views/summaries/recalls → /api/v2/views/summaries/recalls

    • /catalogue/process-objects/message-logs → /api/v2/catalogue/process-objects/message-logs

    • etc.

  • Endpoints de Payment Object eliminados:

    • /all/payment-objects

    • /all/payment-objects/{odsObjectId}

    • /all/payment-objects/{paymentObjectId}/history

    • Se ha eliminado cada endpoint de /catalogue/payment-objects/ (p. ej., /catalogue/payment-objects/PAIN_001_CREDIT_TRANSFER_TRANSACTION)

  • Los parámetros de búsqueda de los cuatro endpoints de búsqueda de /views/summaries/ se han unificado. Anteriormente, estos cuatro endpoints de API tenían una mezcla de campos de búsqueda similares y únicos; ahora cada endpoint puede consultarse utilizando cualquiera de los parámetros de búsqueda combinados. Este cambio se ha introducido ya que custom summary mappings permiten a los clientes poblar cualquier campo en un Summary, independientemente del tipo de recorrido. Esto afecta a los siguientes endpoints:

    • /api/v2/views/summaries/payments

    • /api/v2/views/summaries/recalls

    • /api/v2/views/summaries/batches

    • /api/v2/views/summaries/bulks

  • La clase de respuesta para todos los endpoints de /views/summaries/ ha cambiado a SummaryView, eliminando el uso de las clases distintas PaymentSummaryView, RecallSummaryView, BulkSummaryView y BatchSummaryView. Las cuatro clases obsoletas extendían SummaryView sin cambios funcionales; la estructura y la respuesta de la API siguen siendo coherentes con la implementación de V1. Esto afecta a los siguientes endpoints:

    • /api/v2/views/summaries/payments

    • /api/v2/views/summaries/payments/{unitOfWorkId}

    • /api/v2/views/summaries/recalls

    • /api/v2/views/summaries/recalls/{unitOfWorkId}

    • /api/v2/views/summaries/batches

    • /api/v2/views/summaries/batches/{unitOfWorkId}

    • /api/v2/views/summaries/bulks

    • /api/v2/views/summaries/bulks/{unitOfWorkId}

Migración de conectores de cliente

El módulo ods-inquiry-client se ha actualizado para admitir las Inquiry APIs V1 y V2. La configuración por defecto (ods.inquiry.client.version=2) habilita la instanciación de las Inquiry Client APIs V2 y no necesita ser modificada explícitamente.

Si ya estás usando las client APIs V1 y no quieres migrar a las client APIs V2, debes actualizar tu configuración para sobrescribir la versión del cliente de la siguiente forma: ods.inquiry.client.version=1
Esto garantizará que las client APIs V1 puedan habilitarse y no será necesario un cambio de código. Consulta la documentación del cliente V1 de Inquiry API en V1 Inquiry API client documentation para más información sobre las client APIs V1 que se pueden habilitar.

Las V2 Client APIs disponibles se enumeran a continuación. La configuración de las Client API vive bajo ods.inquiry.client, y todas las propiedades listadas a continuación deben ir con este prefijo.

Tabla 1. Configurar V2 Client APIs
Property Default Notes

summaries.enabled

false

Habilita el bean Summaries cuando se establece en true

details.enabled

false

Habilita el bean Details cuando se establece en true

process-flow-graphs.enabled

false

Habilita el bean ProcessFlowGraphs cuando se establece en true

process-objects.enabled

false

Habilita el bean ProcessObjects cuando se establece en true

custom-objects.enabled

false

Habilita el bean CustomObjects cuando se establece en true

mds-objects.enabled

false

Habilita el bean MdsObjects cuando se establece en true

pds-objects.enabled

false

Habilita el bean PdsObjects cuando se establece en true

Cambios en el conector de cliente desde V1

La diferencia respecto al conjunto de beans de V1 es que los beans PaymentSummaries, BulkSummaries, BatchSummaries y RecallSummaries se han sustituido por el bean Summaries, y el bean PaymentObjects se ha eliminado. Al migrar a las V2 Client APIs, es necesario realizar los siguientes cambios de código:

  • Sustituir el uso de las interfaces de resumen por Summaries. La diferencia entre ellas es que el objeto de solicitud de búsqueda de Summaries requiere una instancia de la clase SummarySearchFields, mientras que las otras, p. ej., PaymentSummaries requieren una instancia de la clase PaymentSummarySearchFields. La nueva clase SummarySearchFields contiene todos los campos disponibles en cada una de las clases de campos de búsqueda de V1.

  • Todos los usos de las clases PaymentSummaryView, RecallSummaryView, BatchSummaryView y BulkSummaryView deben sustituirse por la clase SummaryView. Las cuatro clases obsoletas extendían SummaryView sin cambios funcionales, por lo que la migración es solo un cambio de nombre de clase.

  • Cualquier uso de PaymentObjects debe sustituirse por MdsObjects. La interfaz MdsObjects proporciona la misma funcionalidad que PaymentObjects, pero con cambios de nombres de campos y métodos de paymentObject a mdsObject.

Migración del Test Client

El módulo ods-inquiry-test-client se ha actualizado para admitir las Inquiry APIs V1 y V2. De forma similar a las Client APIs, hay un nuevo conjunto de V2 Test Client APIs disponible a través de la interfaz InquiryClientV2.

Uso

Pueden usarse simultáneamente los Test Clients V1 y V2. Si estás migrando de V1 a V2, deberás actualizar tu suite de tests para utilizar la interfaz InquiryClientV2. El método InquiryClient createInquiryClientV2 devolverá una instancia por defecto de la interfaz InquiryClientV2.

@Configuration
class TestClientConfig {
    @Bean
    InquiryClient inquiryClient(@Value("${inquiry.base.url}") final String baseUrl,
                                @Value("${inquiry.openapi-validation.enabled}") final boolean openApiValidation,
                                final CurrentAuthToken currentAuthToken) {
        return InquiryClient.createInquiryClient(InquiryClientOptions.builder()
                .baseUrl(baseUrl)
                .currentAuthToken(currentAuthToken)
                .requestTimeout(Duration.ofSeconds(60))
                .openApiValidation(openApiValidation)
                .build());
    }

    @Bean
    InquiryClientV2 inquiryClientV2(@Value("${inquiry.base.url}") final String baseUrl,
                                    @Value("${inquiry.openapi-validation.enabled}") final boolean openApiValidation,
                                    final CurrentAuthToken currentAuthToken) {
        return InquiryClient.createInquiryClientV2(InquiryClientOptions.builder()
                .baseUrl(baseUrl)
                .currentAuthToken(currentAuthToken)
                .requestTimeout(Duration.ofSeconds(60))
                .openApiValidation(openApiValidation)
                .build());
    }
}

Cambios del Test Client desde V1

Las diferencias entre las V1 y V2 Test Client APIs son las siguientes:

  • Todas las APIs se han actualizado para utilizar la especificación de Inquiry API V2

  • Las interfaces Payments, Batches, Bulks y Recalls han sido marcadas como obsoletas, para ser sustituidas por la interfaz Summaries1.

    • La interfaz Summaries1 usa la clase SummarySearchFields, mientras que Payments usa la clase PaymentSummarySearchFields

  • La interfaz PaymentObjects se ha eliminado de la interfaz InquiryClient2

    • Debe utilizarse la interfaz MdsObjects en su lugar