API de administración de PrestaShop 9: guía práctica para desarrolladores
La nueva API de administración de PrestaShop 9 es una de las novedades arquitectónicas más importantes de la generación PrestaShop 9.
Está diseñada para mejorar la antigua API Webservice con un modelo de seguridad más moderno, operaciones orientadas al negocio y una arquitectura ampliable mediante módulos.
La nueva API se basa en:
- API Platform 3;
- OAuth2 autenticación y autorización;
- comandos y consultas CQRS;
- permisos de alcance;
- documentación OpenAPI/Swagger;
- recursos API definidos por módulos.
Por ello resulta especialmente interesante para desarrolladores que crean:
- integraciones ERP;
- integraciones PIM;
- sincronización de existencias;
- plataformas de proveedores;
- conexiones SaaS;
- sistemas de gestión de pedidos;
- servicios de informes;
- herramientas de automatización.
Esta guía explica la arquitectura, cómo funciona la autenticación, cómo crear clientes y cómo los desarrolladores de módulos pueden aprovechar la API.
Nota sobre versiones: Este artículo se verificó el 22 de septiembre de 2026 con la documentación actual para desarrolladores de PrestaShop 9. La API de administración evoluciona constantemente; consulta siempre la especificación OpenAPI generada para la versión exacta de la tienda que integres.
Por qué PrestaShop creó una nueva API de administración
La antigua API Webservice de PrestaShop está estrechamente ligada a las operaciones CRUD heredadas de ObjectModel.
El proyecto PrestaShop señala varias limitaciones de ese enfoque antiguo:
- gestión limitada de permisos y seguridad;
- funciones CRUD básicas;
- arquitectura heredada;
- mantenimiento más difícil;
- dependencia estrecha de ObjectModel.
La nueva API de administración persigue objetivos distintos.
Está diseñada para ser:
- más segura;
- más fácil de auditar;
- más alineada con operaciones de negocio;
- más acorde con los estándares modernos;
- ampliable mediante módulos.
Esto es importante.
Una API de comercio electrónico moderna no debe limitarse a exponer registros de base de datos.
Debe exponer operaciones que el negocio entienda.
API Platform 3: base de HTTP/API
PrestaShop 9 utiliza API Platform 3 para la nueva API de administración.
API Platform proporciona infraestructura para:
- rutas;
- recursos API;
- serialización;
- validación;
- generación de OpenAPI;
- interfaz Swagger UI;
- proveedores de datos;
- procesadores.
PrestaShop integra después su arquitectura de aplicación en ese framework.
El resultado no es simplemente el CRUD estándar de API Platform.
Los endpoints nativos pueden invocar consultas y comandos CQRS de PrestaShop.
CQRS: lecturas y escrituras como operaciones de negocio
PrestaShop utiliza CQRS desde su migración a Symfony.
CQRS separa las operaciones que:
leer datos
de las operaciones que:
cambiar el estado
La API de administración reutiliza ese trabajo.
Según la arquitectura oficial:
- una operación de lectura puede ejecutar una consulta CQRS;
- una operación de listado puede usar una fábrica de datos de cuadrícula;
- una operación de escritura puede ejecutar un comando CQRS.
Esto ayuda a mantener un comportamiento coherente entre el Back Office y la API.
Por qué es importante CQRS
Imagina dos formas de modificar un producto.
Enfoque de base de datos directa
solicitud API
→ UPDATE ps_product ...
Esto puede omitir:
- validación;
- hooks;
- reglas de dominio;
- entidades relacionadas.
Enfoque de comando de aplicación
solicitud API
→ recurso API
→ comando CQRS
→ manejador de aplicación
→ reglas de dominio
El segundo modelo suele ser más fácil de mantener coherente con el resto de la aplicación.
También facilita probar el comportamiento de la API.
La API de administración está habilitada por defecto
La documentación oficial actual de PrestaShop indica que la API de administración está disponible de serie en PrestaShop 9.
Aun así, debes configurar clientes API y permisos antes de que una aplicación externa pueda utilizarla.
La ruta del Back Office para gestionar clientes es:
Parámetros avanzados
→ API de administración
Desde allí los administradores pueden crear clientes API y asignarles permisos.
Producción requiere HTTPS
La API de administración de PrestaShop exige acceso seguro en producción.
En desarrollo puede relajarse la comprobación HTTPS para trabajo local, pero en producción se requiere HTTPS seguro.
No crees integraciones que dependan de desactivar la seguridad del transporte.
Las credenciales y tokens API son sensibles.
Nunca deben transmitirse mediante HTTP sin cifrar en una red de producción.
OAuth2 es el modelo de autenticación
La API de administración utiliza OAuth2.
OAuth2 distingue varios conceptos:
- cliente;
- servidor de recursos;
- servidor de autorización;
- token de acceso;
- alcances.
En la configuración predeterminada de PrestaShop:
Aplicación externa = cliente
PrestaShop = servidor de recursos
PrestaShop = servidor de autorización
PrestaShop también puede trabajar con un servidor de autorización externo.
Client Credentials para integraciones servidor a servidor
Para integraciones habituales entre máquinas, la documentación de PrestaShop recomienda el flujo OAuth2 Client Credentials .
Ejemplos típicos:
- ERP → PrestaShop;
- PIM → PrestaShop;
- WMS → PrestaShop;
- Servicio SaaS → PrestaShop.
No hace falta iniciar sesión como usuario humano en cada solicitud API.
La integración recibe:
client_id
client_secret
y los intercambia por un token de acceso.
Crear un cliente API en el Back Office
Ve a:
Parámetros avanzados
→ API de administración
→ Añadir nuevo cliente API
La configuración del cliente incluye campos como:
- nombre del cliente;
- ID de cliente;
- descripción;
- tiempo de vida;
- estado de habilitación;
- permisos de alcance.
Utiliza un nombre de cliente descriptivo.
Bien:
Sincronización del stock de almacén
Mal:
api2
Meses después, los administradores deberían reconocer de inmediato para qué sirve esa credencial.
Guarda el secreto del cliente inmediatamente
La documentación de la API de administración de PrestaShop advierte que el secreto de cliente generado solo se muestra una vez.
Guárdalo de forma segura al crear el cliente.
No lo incluyas en:
- control de versiones;
- configuración pública;
- sistemas de incidencias;
- capturas de pantalla;
- registros.
Usa secretos de entorno o un sistema dedicado de gestión de secretos cuando estén disponibles.
Crear clientes API desde CLI
PrestaShop también proporciona un comando de consola:
bin/console prestashop:api-client create CLIENT_ID
Por ejemplo:
bin/console prestashop:api-client create warehouse-sync
Opciones adicionales permiten configurar:
- nombre;
- descripción;
- permisos de alcance;
- duración del token.
La documentación también muestra una opción --all-scopes , pero advierte contra el uso de todos los permisos en integraciones reales de producción.
Aplicar el principio de mínimos privilegios
Cada cliente API debe tener únicamente los permisos necesarios.
Un servicio de sincronización de existencias puede necesitar acceso a productos o inventario.
No debería recibir automáticamente permisos para:
- gestionar módulos no relacionados;
- editar todos los clientes API;
- acceder a operaciones de clientes no relacionadas.
Si se roba un token, los permisos limitados reducen el daño potencial.
Una integración, un cliente
Evita utilizar el mismo cliente API para:
- ERP;
- CRM;
- automatización de marketing;
- almacén;
- informes.
Asigna un cliente propio a cada servicio.
Ventajas:
- credenciales separadas;
- permisos diferenciados;
- revocación individual;
- mejor auditabilidad.
Si la plataforma de marketing se ve comprometida, puedes revocar solo ese cliente.
Obtener un token de acceso
Con el servidor de autorización interno de PrestaShop, el endpoint de tokens es:
/admin-api/access_token
La documentación oficial utiliza una solicitud similar a:
curl --location 'https://shop.example.com/admin-api/access_token' \
--form 'grant_type="client_credentials"' \
--form 'client_id="warehouse-sync"' \
--form 'client_secret="YOUR_CLIENT_SECRET"' \
--form 'scope[]="product_read"' \
--form 'scope[]="product_write"'
El servidor de autorización devuelve un token de acceso.
Después la aplicación utiliza ese token en las solicitudes API.
Enviar el token Bearer
Las solicitudes autenticadas usan:
Authorization: Bearer YOUR_ACCESS_TOKEN
Por ejemplo:
curl --location \
'https://shop.example.com/admin-api/api-client/infos' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Los endpoints disponibles dependen de la versión instalada de PrestaShop y de los módulos habilitados.
No codifiques como fijas las suposiciones de un artículo de blog.
Utiliza la documentación API generada por la tienda de destino.
Los permisos forman parte de la solicitud de token
Un detalle importante de OAuth es que un cliente puede disponer de muchos permisos, pero el token de acceso se emite para los solicitados.
Por ejemplo:
el cliente permite:
product_read
product_write
customer_group_read
Un token concreto podría solicitar únicamente:
product_read
Ese token tendrá capacidades más limitadas.
Esto ayuda a reducir todavía más los privilegios.
Un permiso faltante provoca un error de autorización
Si un endpoint requiere un permiso que tu token no contiene, PrestaShop devuelve un error de autorización.
Ese es exactamente el comportamiento deseado.
Una integración debe fallar claramente en lugar de realizar silenciosamente operaciones sin permiso.
Gestiona explícitamente los códigos de estado HTTP en tu cliente API.
Los tokens de acceso caducan
La configuración de clientes API incluye la duración de los tokens.
Las aplicaciones deben prever que los tokens de acceso caducarán.
No consideres un token de acceso como credencial permanente.
Un cliente robusto:
- obtiene un token;
- lo almacena de forma segura en caché;
- controla su vencimiento;
- solicita uno nuevo cuando es necesario.
No solicites un token nuevo antes de cada llamada API salvo que tu arquitectura lo necesite realmente.
PrestaShop siempre es el servidor de recursos
La documentación de PrestaShop hace una distinción importante.
La tienda siempre es el servidor de recursos que sirve los recursos protegidos.
El servidor de autorización puede ser:
- el propio PrestaShop;
- un servidor de autorización externo.
Esto permite a organizaciones avanzadas integrar infraestructura centralizada de identidad si es necesario.
Servidores de autorización externos
La arquitectura de PrestaShop admite proveedores de autorización externos.
Puede resultar útil en entornos grandes que ya utilizan una infraestructura OAuth centralizada.
La documentación oficial ofrece conceptos de integración y un ejemplo con un servidor de autorización externo.
Esto es más complejo que el flujo interno predeterminado.
Úsalo solo si tu infraestructura necesita realmente autorización centralizada.
Documentación Swagger
Una de las grandes ventajas de API Platform es la documentación automática.
PrestaShop expone información Swagger/OpenAPI para que los desarrolladores exploren la API.
En desarrollo, el Back Office ofrece un enlace a Swagger.
Esto es muy útil porque la página Swagger refleja la API que expone la instalación real.
JSON de OpenAPI
La documentación de la API de administración puede exponerse en formato OpenAPI.
La documentación oficial menciona:
/admin-api/docs.json
Esta especificación puede importarse en herramientas como:
- Postman;
- clientes compatibles con Insomnia;
- generadores de código OpenAPI.
Esto es mucho más seguro que mantener manualmente una lista de estructuras de endpoints en otro proyecto.
Generar documentación API desde CLI
PrestaShop también proporciona:
php bin/console prestashop:generate:apidoc
La salida puede redirigirse:
php bin/console prestashop:generate:apidoc > api-spec.json
Casos de uso:
- documentación API;
- generación de clientes;
- comparación de versiones;
- pruebas de contrato;
- CI.
Versionar la especificación API
Para una integración grande, guarda las especificaciones OpenAPI generadas de las versiones de PrestaShop compatibles.
Después compara las versiones.
Por ejemplo:
prestashop-9.0-api.json
prestashop-9.1-api.json
Un diff puede mostrar:
- endpoints nuevos;
- campos modificados;
- valores requeridos nuevos.
Esto permite abordar la compatibilidad de forma proactiva.
Los módulos pueden añadir recursos API
La nueva API está diseñada para permitir ampliaciones mediante módulos.
PrestaShop detecta clases de recursos API de los módulos cuando se sigue la convención esperada.
La ubicación documentada en el módulo es:
src/ApiPlatform/Resources
Esto permite que un módulo añada sus propios recursos API.
El endpoint está disponible cuando el módulo está instalado y habilitado.
Los módulos pueden definir sus propios permisos
Las funciones API definidas por módulos deben tener permisos propios.
Ejemplos:
security_audit_read
security_audit_write
supplier_import_read
supplier_import_run
Esto es mejor que exigir acceso genérico demasiado amplio.
Un conector SaaS puede recibir exactamente los permisos que necesita.
Los recursos API usan atributos PHP
La integración de API Platform de PrestaShop utiliza atributos PHP para configurar recursos.
Esto mantiene la configuración del endpoint cerca de la clase DTO/recurso.
Conceptualmente:
#[ApiResource(
operations: [
// API operation definitions
]
)]
class ExampleResource
{
// fields
}
PrestaShop también ofrece operaciones personalizadas orientadas a CQRS para conectar recursos con comandos y consultas.
Los proveedores gestionan las lecturas
Para recursos API integrados con CQRS, las abstracciones Provider gestionan las operaciones de lectura.
PrestaShop incluye proveedores para:
- consultas de un recurso;
- listas y datos de cuadrícula.
El proveedor recibe la configuración del recurso API, convierte los datos en la consulta necesaria y la despacha.
Los procesadores gestionan las escrituras
Las operaciones de escritura utilizan abstracciones Processor.
Solicitudes como:
- POST;
- PUT;
- PATCH;
- DELETE;
pueden vincularse con comandos CQRS.
Esto crea una ruta clara:
solicitud HTTP
→ recurso API
→ procesador
→ comando CQRS
→ bus de comandos
→ manejador
Por qué es útil para módulos comerciales
Imagina un módulo de importación de proveedores.
El Back Office necesita:
- estado de la cola;
- iniciar importación;
- reintentar los fallos;
- consultar estado del proveedor.
Un panel SaaS puede necesitar las mismas operaciones.
En lugar de crear endpoints específicos como:
/modules/mymodule/run.php?secret=...
el módulo puede adoptar la arquitectura de la API de administración.
Esto proporciona:
- OAuth2;
- permisos de alcance;
- documentación API coherente;
- enrutamiento del framework;
- respuestas estándar.
No conviertas cada trabajo largo en una única solicitud API
La API de administración no elimina la necesidad de colas.
Una solicitud como:
POST /admin-api/import-all-products
no debería permanecer abierta dos horas mientras se procesan 100.000 productos.
Un modelo mejor:
POST /imports
→ 202 Accepted
→ identificador de tarea
Después:
GET /imports/{id}
puede devolver el estado.
El trabajador se ejecuta por separado.
Diseñar operaciones asíncronas
Para procesos grandes:
API
→ crear tarea
→ cola
→ proceso de trabajo
→ progreso
Esto aporta latencia previsible a la API.
La integración puede consultar el estado periódicamente o recibir un webhook si el módulo lo implementa.
Hacer idempotentes las escrituras
Las redes fallan.
Los clientes reintentan.
Supongamos que una integración envía:
crear correspondencia de producto del proveedor
y se agota el tiempo de espera después de que el servidor completó la operación.
Si un reintento crea otra asignación, aparece un duplicado.
Utiliza:
- identificadores externos estables;
- restricciones de unicidad;
- claves de idempotencia cuando corresponda.
Un reintento seguro no debería producir un segundo efecto de negocio.
Limitar la tasa de operaciones costosas
Incluso clientes autenticados pueden sobrecargar accidentalmente una tienda.
Un error de programación puede enviar miles de solicitudes por segundo.
Protege los endpoints personalizados costosos con:
- paginación razonable;
- límites de lote;
- limitación de tasa cuando corresponda.
No expongas un endpoint que devuelva 500.000 productos completos en una sola respuesta.
Paginar listas
Las operaciones API de listado deben tener límites.
Prefiere:
page
limit
filters
en lugar de:
dame todo el catálogo
Para la sincronización, las lecturas incrementales suelen ser más eficientes.
Usar sincronización incremental
Si un sistema externo de informes ya conoce el catálogo de ayer, no debería descargarlo todo cada hora.
Utiliza:
- marcas de tiempo de modificación;
- cursores;
- ID de eventos externos;
- puntos de control específicos del dominio.
Esto reduce:
- tráfico de API;
- carga de CPU;
- carga de base de datos.
Gestionar explícitamente errores HTTP
Tu integración debe distinguir:
- 400: error de validación;
- 401: problema de autenticación;
- 403: permiso faltante;
- 404: recurso inexistente;
- 409: conflicto cuando corresponda;
- 429: límite de tasa si tu infraestructura lo aplica;
- 5xx: fallo del servidor.
No reintentes todos los errores.
Un campo requerido ausente no se validará después de diez reintentos.
Registrar identificadores de correlación
Para integraciones complejas, asigna un ID de correlación a cada solicitud o trabajo.
Así los registros pueden relacionar:
solicitud externa
→ solicitud API
→ comando CQRS
→ tarea en segundo plano
→ llamada al proveedor
Esto simplifica enormemente el soporte.
Nunca registrar secretos
No registres:
- secreto de cliente;
- token Bearer completo;
- cabeceras de autorización.
Elimina los datos sensibles de los registros de solicitudes.
Si las herramientas de depuración capturan solicitudes HTTP completas, restringe el acceso y limita su conservación.
Rotar credenciales
Prepara un proceso de rotación de secretos de cliente.
No esperes hasta sospechar una filtración.
Una integración madura puede:
- crear un cliente de sustitución;
- desplegar un secreto nuevo;
- verificar el tráfico;
- desactivar el cliente antiguo.
Los clientes separados lo hacen sencillo.
API de administración frente a Webservice heredado
El Webservice heredado sigue existiendo en el ecosistema PrestaShop, pero la nueva API de administración es la arquitectura moderna introducida con PrestaShop 9.
Para nuevas integraciones, evalúa primero la API de administración.
Los motivos incluyen:
- OAuth2;
- permisos de alcance;
- API Platform;
- CQRS;
- extensibilidad con módulos;
- documentación OpenAPI generada.
No reescribas una integración heredada estable solo por moda.
Pero evita ampliar la deuda técnica heredada cuando la API moderna ya cumple los requisitos.
Arquitectura de integración sugerida
Una integración de producción podría verse así:
ERP / PIM
↓
token OAuth2
↓
API de administración de PrestaShop
↓
CQRS
↓
Lógica de negocio
↓
Base de datos
Tareas grandes:
API → cola → proceso de trabajo
La API es el límite de acceso.
La cola gestiona los trabajos largos.
Lista de comprobación de seguridad
- HTTPS en producción
- Un cliente API por integración
- Permisos de alcance mínimos
- Secretos almacenados de forma segura
- Tokens no registrados
- Expiración de tokens gestionada
- Clientes antiguos desactivados
- Entradas validadas
- Operaciones grandes asíncronas
- Errores de API supervisados
Lista de comprobación de desarrollo
- Consultar Swagger actual
- Exportar especificación OpenAPI
- Probar permisos necesarios
- Probar un token caducado
- Probar un token no válido
- Probar un permiso faltante
- Probar errores de validación
- Probar reintentos
- Probar paginación
- Probar módulo deshabilitado
Preguntas frecuentes
¿La API de administración de PrestaShop 9 está activada por defecto?
Sí. La documentación oficial actual indica que viene incluida en PrestaShop 9, pero los clientes y permisos deben configurarse.
¿Qué autenticación utiliza la API de administración?
OAuth2.
¿Qué tipo de concesión debe usar una integración servidor a servidor?
PrestaShop recomienda el flujo Client Credentials para integraciones servidor a servidor.
¿Qué framework impulsa la API de administración?
API Platform 3.
¿La API de administración utiliza CQRS?
Sí. PrestaShop integra recursos API con los comandos y consultas CQRS existentes.
¿Dónde puedo crear un cliente API?
En el Back Office, en Parámetros avanzados → Admin API, o con el comando de consola prestashop:api-client comando de consola.
¿Cuál es la URL del token de acceso?
Con el servidor de autorización interno, el endpoint documentado es /admin-api/access_token.
¿Pueden los módulos añadir endpoints?
Sí. La extensibilidad mediante módulos es un objetivo clave de la nueva API. Los recursos de módulos pueden cargarse desde src/ApiPlatform/Resources.
¿Está disponible Swagger?
Sí. API Platform genera documentación de API y PrestaShop proporciona acceso Swagger/OpenAPI para la API de administración.
¿Debo conceder todos los permisos a una integración?
No. La documentación de PrestaShop recomienda explícitamente limitar cada cliente a los permisos mínimos necesarios.