Cambios de la Admin API de PrestaShop 9.2: contratos de transportistas y respuestas

Un cliente API puede dejar de funcionar aunque la URL que llama no haya cambiado. Un campo obligatorio puede describirse con más precisión, una entidad ausente puede producir ahora un fallo explícito o el resultado de una consulta puede pasar por una ruta interna de mapeo distinta. Son cuestiones de contrato que merecen tests específicos.

PrestaShop 9.2 RC1 incluye trabajo en el dominio de transportistas y la API, además de un cambio para consultas CQRS que devuelven listas. Este artículo examina esos cambios concretos y sus implicaciones de integración. Presupone familiaridad con la Admin API y no repite los fundamentos de autenticación ni de API Platform.

La revisión está actualizada a fecha de 26 de septiembre de 2026. RC1 sigue siendo un objetivo de evaluación; los ejemplos siguientes describen métodos de prueba de contratos, no respuestas verificadas de una tienda en funcionamiento en este proyecto.

Si una respuesta API incluye campos personalizados, incorpore el flujo de integración del módulo Extra Properties a la revisión del contrato en vez de suponer que todos los campos registrados deben exponerse.

El soporte de transportistas abarca el núcleo y el módulo de recursos

El trabajo de transportistas en el núcleo está vinculado al trabajo de recursos en ps_apiresources. La PR integrada en el núcleo identifica correcciones necesarias para que los recursos de transportistas funcionen bien, incluidos argumentos escalares de consulta, contexto moderno de tienda y comprobación de productos ausentes. Cambio de dominio de transportistas y API n.º 42022.

Para los desarrolladores de clientes, la consecuencia inmediata es registrar ambas versiones. «Núcleo 9.2» no describe por completo el inventario de recursos instalado en una tienda concreta. Antes de adoptar una operación, inspeccione la documentación generada en esa instalación y verifique su disponibilidad con una solicitud autorizada en sandbox.

No copie una ruta propuesta en una discusión de incidencia suponiendo que se entregó. Un cambio del núcleo puede dar soporte a un recurso empaquetado por separado, y un comentario de revisión puede describir una iteración anterior. Use conjuntamente el esquema instalado y la revisión de código correspondiente.

Construya el conjunto mínimo de prueba útil para transportistas: un transportista conocido, un producto asociado a la tienda pertinente y un identificador de producto deliberadamente inexistente. Mantenga simples las reglas de envío al principio para no confundir un fallo de validación de dominio con una regla de elegibilidad.

Los esquemas generados de solicitud forman parte del contrato

La misma PR de transportistas aborda la documentación del cuerpo de solicitud derivada de comandos: propiedades omitidas, obligatoriedad y contexto de esquema proporcionado por recursos. También añade gestión de valores predeterminados de operaciones antes del mapeo y la validación. Detalles de esquemas y valores predeterminados.

Esto importa para los clientes generados. Un esquema obsoleto puede hacer que un cliente omita información necesaria para la operación o represente mal valores anidados. Regenerar un cliente sin inspeccionar las diferencias puede introducir cambios mucho más allá de la operación adoptada.

Capture el esquema de referencia y el de la candidata desde sus instalaciones respectivas. Revise campos obligatorios, posibilidad de valores nulos, estructuras de elementos de arrays y valores predeterminados. Confirme qué diferencias afectan a las operaciones que su cliente llama realmente.

Un valor predeterminado documentado no justifica enviar null indiscriminadamente. Valores omitidos, nulos y explícitos pueden tener significados distintos. Pruebe cada estado que pueda producir su aplicación y registre el comportamiento resultante.

Para una operación de escritura, compare la entidad guardada con la solicitud, no solo con el resultado HTTP. Una solicitud puede aceptarse mientras un valor predeterminado produce un resultado distinto de la expectativa de negocio del cliente.

Las entidades ausentes y el alcance de tienda necesitan casos negativos

Un test de contrato significativo incluye un identificador que no puede existir en los datos de prueba. El trabajo de transportistas hace que establecer referencias en un producto desconocido falle explícitamente en vez de no hacer nada en silencio. Comportamiento de productos ausentes.

Su cliente debe tratarlo como una operación de negocio fallida. Registrar una sincronización correcta solo porque se completó una solicitud de transporte ocultaría la distinción.

Pruebe también una entidad real en un contexto de tienda inadecuado. Un identificador global válido no demuestra que una operación sea válida en todas las tiendas. Use el mecanismo de alcance documentado de la operación instalada y verifique la asociación o el valor resultante en la tienda prevista.

Evite sustituir silenciosamente la tienda predeterminada cuando falte contexto. Si su aplicación requiere una operación de una sola tienda, valide ese requisito antes del envío. Una precondición del cliente puede evitar un fallo vago del servidor y dejar más claro el alcance previsto en los registros.

No equipare un resultado vacío de elegibilidad con un error. Una solicitud válida puede no encontrar correctamente ningún transportista elegible. Mantenga ese resultado separado del acceso denegado, un producto no válido o una excepción del servidor.

El mapeo de consultas de listas no implica que cada respuesta tenga una nueva envoltura

Otro cambio de la versión 9.2 envuelve resultados de listas simples de operaciones CQRS que no son de colección bajo una clave interna de mapeo _queryResult. Los resultados asociativos conservan su comportamiento de mapeo existente. La PR explica que la clave permite asignar un resultado de lista a una propiedad de recurso. Mapeo de resultados de listas n.º 42011.

La distinción crucial está entre la entrada interna de mapeo y la representación pública de la respuesta. No diga a todos los clientes API que esperen una propiedad de nivel superior _queryResult. El mapeo del recurso y la serialización determinan la estructura expuesta.

Para una extensión que implemente un recurso adecuado, verifique una lista con datos y una vacía. El resultado vacío importa porque el código suele tratarlo como datos ausentes o un tipo inesperado. El cliente debe recibir la representación documentada en ambos casos.

Si mantiene instantáneas de contratos, compare la estructura analizada en vez del formato irrelevante o el orden de propiedades. Una comprobación útil verifica el tipo y los valores esperados del campo. Una comparación de texto bruto puede fallar por cambios inofensivos de serialización y pasar por alto un desajuste semántico en otro lugar.

Este cambio es una mejora específica de mapeo. No demuestra que todas las operaciones de colección o todos los clientes existentes necesiten reescribirse.

La exposición de Extra Properties añade una dimensión de contrato de datos

Cuando una integración adopta una propiedad recién registrada, trátela como parte del contrato de negocio. Defina su propietario, tipo, significado del valor vacío y alcance de tienda o idioma antes de permitir que otro sistema la escriba.

No deduzca la carga externa de la etiqueta administrativa de un campo. Inspeccione el esquema de recurso instalado y un ejemplo verificado de respuesta. Conserve el espacio de nombres del módulo y la representación exacta compatible en el mapeo de su cliente.

Un campo puede estar disponible en un formulario administrativo sin que una integración esté configurada o autorizada para consumirlo. A la inversa, un valor expuesto puede heredar los permisos de la entidad superior en vez de tener una política separada a nivel de campo. Verifique ese comportamiento en la documentación actual de la función y en la instalación.

Para una propiedad nueva, añada casos de ciclo completo: escribir un valor válido, leerlo, borrarlo si se admite, rechazar un valor no válido y verificar que una segunda tienda permanece igual. Mantenga esos casos separados de los campos normales de producto para que los fallos identifiquen la nueva superficie de extensión.

Si no usa Extra Properties, no amplíe la carga de escritura de su cliente solo porque la candidata pueda exponerlas. Adopte únicamente los campos que necesita su contrato de negocio.

Construir un pequeño flujo de comparación de contratos

El siguiente auxiliar Python compara el inventario de rutas y métodos de dos archivos JSON OpenAPI guardados localmente. No accede a una tienda, no se autentica ni valida el comportamiento de operaciones:

import json
from pathlib import Path

METHODS = {"get", "post", "put", "patch", "delete", "head", "options"}

def operations(filename):
    document = json.loads(Path(filename).read_text(encoding="utf-8"))
    return {
        (method.upper(), path)
        for path, item in document.get("paths", {}).items()
        for method in item
        if method.lower() in METHODS
    }

before = operations("baseline-openapi.json")
after = operations("candidate-openapi.json")
print("Added:", sorted(after - before))
print("Removed:", sorted(before - after))

Use los nombres de archivo de los esquemas exportados que realmente guardó. Un inventario sin cambios sigue requiriendo una comparación de esquemas de las operaciones usadas. Los parámetros de solicitud, esquemas de cuerpo, esquemas de respuesta y permisos pueden cambiar sin añadir ni eliminar una ruta.

Después de la comparación estática, ejecute una pequeña batería con registros sintéticos: lectura autorizada, escritura válida, entrada no válida, entidad ausente, resultado vacío y alcance de tienda pertinente. Inspeccione el resultado persistente de cada escritura.

No capture tokens en los datos de prueba ni registre en el repositorio respuestas brutas de producción. Oculte identificadores cuando corresponda y use datos sintéticos de clientes para que las pruebas del contrato puedan compartirse con seguridad con los mantenedores.

Distinguir soporte ausente de soporte incompatible

Si una operación falta en el esquema de la candidata, regístrela como no disponible en ese par de versiones. No envíe una solicitud supuesta ni interprete un fallo de enrutamiento como prueba de que la nueva implementación de dominio está rota.

Si la operación existe pero rechaza una carga documentada, conserve el fragmento de esquema, la solicitud depurada y la respuesta. Es otra clase de problema de compatibilidad que puede comunicarse con un desajuste de contrato preciso.

Para los clientes generados, conserve la revisión del código generado junto al esquema exportado. De lo contrario, un desarrollador podría probar un servidor actual con un cliente antiguo y atribuir al servidor la elección de serialización del cliente. Reproduzca con una solicitud mínima compatible antes de cambiar cualquiera de las partes.

Estas distinciones hacen accionable un informe de migración de API: operación no disponible, desajuste de esquema, defecto de serialización y fallo de validación de negocio señalan responsables distintos.

Publicar el cliente para un par de versiones identificado

Una declaración de compatibilidad debe identificar las versiones del núcleo y del módulo de recursos, las operaciones adoptadas y las limitaciones. Si falta una operación nueva, desactive explícitamente la función dependiente en vez de fallar después durante un flujo sin relación.

Cuando una operación devuelva un resultado incierto después de agotarse el tiempo de espera, concilie antes de repetir una escritura importante. Las mejoras de esquema de la versión 9.2 no eliminan los modos de fallo de los sistemas distribuidos.

Por tanto, la tarea principal del desarrollador es acotada: inspeccionar el contrato real del recurso, probar los cambios de transportistas y mapeo de los que depende y conservar pruebas de que las suposiciones del cliente siguen siendo válidas. Es más fiable que tratar la nueva versión como una invitación a regenerarlo todo a ciegas.

Para conocer el contexto de la plataforma subyacente, consulte nuestra guía de la Admin API de PrestaShop 9 y aplique las comprobaciones específicas de versión anteriores a la instalación que esté evaluando.

Al elegir una extensión, explore los módulos PrestaShop 9 de PrestaSuite y contraste la compatibilidad de versiones y los requisitos de integración documentados con sus propios resultados de pruebas.