API para Desarrolladores

Una API REST en JSON para leer y actualizar datos de Mi Fiestashop desde fuera del sitio: catálogo, categorías, pedidos y clientes. Pensada para socios e integraciones externas.

URL base: https://www.mifiestashop.com/api/v1

Todas las respuestas son JSON. Las de lista vienen envueltas como { "data": [...], "meta": { "total", "limit", "offset" } }; las de un solo recurso como { "data": {...} }.

¿Cómo obtengo una llave? Se generan desde el panel de administración, en Parámetros Avanzados → API para Desarrolladores. Cada llave elige sus propios permisos (scopes) y se puede revocar en cualquier momento sin afectar a las demás.

Autenticación

Cada solicitud necesita un header Authorization con tu llave como Bearer token:

Authorization: Bearer mfs_live_xxxxxxxxxxxxxxxxxxxxxxxx

Ejemplo completo con curl:

curl https://www.mifiestashop.com/api/v1/products \
  -H "Authorization: Bearer mfs_live_xxxxxxxxxxxxxxxxxxxxxxxx"

A diferencia del webservice de PrestaShop (Basic Auth con la llave como usuario y contraseña vacía), esta API usa Bearer — el estándar que ya esperan la mayoría de los clientes HTTP y SDKs modernos. La llave nunca se guarda en texto plano en nuestra base de datos: solo su hash, así que si la pierdes hay que generar una nueva.

Errores

Los errores siempre tienen esta forma, con un code estable para manejarlos por código (no por el texto de message, que puede cambiar):

{
  "error": {
    "code": "invalid_status",
    "message": "\"status\" debe ser uno de: Pendiente, Pagado, ..."
  }
}

Status	Cuándo pasa
401	Falta el header Authorization, o la llave no existe / fue revocada.
403	La llave es válida pero no tiene el scope que este endpoint requiere.
404	El recurso no existe (o el producto/categoría está inactivo).
422	La solicitud es válida como JSON pero los datos no pasan alguna validación (falta un campo, un status inválido, etc.).
429	Reservado para límites de tasa futuros — ver el aviso más abajo.
502	PrestaShop o Supabase no respondieron correctamente. Reintenta más tarde.

Límites de tasa: todavía no hay un límite estricto por llave. No lo trates como ilimitado — un uso abusivo puede llevar a que se revoque la llave manualmente mientras se agrega un límite real. Si tu integración necesita hacer muchas solicitudes seguidas, escríbenos.

Productos

Precio y existencia siempre vienen en vivo desde PrestaShop — nunca están cacheados ni son editables por esta API. El nombre, descripción, categoría e imágenes se pueden mejorar con PATCH sin tocar esos dos campos.

GET

/products

Lista productos activos.

Requiere products:read

Parámetro	Descripción
limit	Máximo 100 por página. Default 50.
offset	Para paginar. Default 0.
category	Filtra por id de categoría (ver Categorías).
search	Busca por nombre o SKU (contiene, sin distinguir mayúsculas/acentos).

curl "https://www.mifiestashop.com/api/v1/products?category=270&limit=20" \
  -H "Authorization: Bearer mfs_live_..."

{
  "data": [
    {
      "id": 83101,
      "sku": "VELA-BENGALA",
      "name": "Vela de Bengala",
      "description": "Vela de Bengala para pastel...",
      "price": 10,
      "category_id": 270,
      "category_label": "Velas",
      "image": "https://.../83101/33604.webp",
      "url": "https://www.mifiestashop.com/83101-vela-de-bengala.html"
    }
  ],
  "meta": { "total": 1072, "limit": 20, "offset": 0 }
}

GET

/products/:id

Detalle de un producto.

Requiere products:read

curl https://www.mifiestashop.com/api/v1/products/83101 \
  -H "Authorization: Bearer mfs_live_..."

PATCH

/products/:id

Actualiza los campos descriptivos de un producto existente en PrestaShop.

Requiere products:write

Campo	Descripción
name	Texto.
description	Texto.
images	Arreglo de URLs.
category_label	Texto (etiqueta legible, no cambia la categoría real del producto).

curl -X PATCH https://www.mifiestashop.com/api/v1/products/83101 \
  -H "Authorization: Bearer mfs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"description": "Nueva descripción mejorada"}'

Mandar price, stock o quantity devuelve 422 read_only_field a propósito: siempre vienen en vivo de PrestaShop en todo el sitio, editarlos por aquí daría una falsa sensación de control sobre el inventario real. Ver Decisiones de diseño.

Categorías

Solo lectura por ahora (ver Decisiones de diseño).

GET

/categories

Lista categorías activas.

Requiere categories:read

Parámetro	Descripción
limit	Máximo 200. Default 100.
offset	Para paginar. Default 0.

GET

/categories/:id

Detalle de una categoría.

Requiere categories:read

Pedidos

Los pedidos creados por esta API se validan igual que el checkout público: el precio de cada artículo se vuelve a consultar en vivo en PrestaShop, nunca se confía en el que mande quien llama a la API.

GET

/orders

Lista pedidos, más recientes primero.

Requiere orders:read

Parámetro	Descripción
limit	Máximo 100. Default 20.
offset	Para paginar. Default 0.

GET

/orders/:id

Detalle de un pedido.

Requiere orders:read

POST

/orders

Crea un pedido nuevo.

Requiere orders:write

Campo	Descripción
items	Arreglo de `{ "id": 83101, "qty": 2 }`. Hasta 50 artículos.
customer_name	Texto, requerido.
customer_email	Email válido, requerido.
customer_phone	Texto, requerido.
shipping_address	Texto, requerido.
shipping_cost	Número ≥ 0. Default 0.
payment_method	Texto, opcional.

curl -X POST https://www.mifiestashop.com/api/v1/orders \
  -H "Authorization: Bearer mfs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{"id": 83101, "qty": 2}],
    "customer_name": "Ana Torres",
    "customer_email": "ana@example.com",
    "customer_phone": "5512345678",
    "shipping_address": "Calle 123, Col. Centro, CDMX",
    "shipping_cost": 99
  }'

PATCH

/orders/:id

Actualiza el status de un pedido.

Requiere orders:write

Campo	Descripción
status	Uno de: `Pendiente`, `Pagado`, `Pago Aceptado`, `Enviado`, `Entregado`, `Cancelado`.

curl -X PATCH https://www.mifiestashop.com/api/v1/orders/412 \
  -H "Authorization: Bearer mfs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "Enviado"}'

Clientes

Solo lectura por ahora (ver Decisiones de diseño).

GET

/customers

Lista clientes activos.

Requiere customers:read

Parámetro	Descripción
limit	Máximo 100. Default 20.
offset	Para paginar. Default 0.
search	Busca por nombre o email.

GET

/customers/:id

Detalle de un cliente.

Requiere customers:read

Permisos (scopes)

Cada llave elige sus propios permisos al crearse, desde el admin. Una llamada con una llave sin el scope requerido recibe 403.

Scope	Permite
products:read	GET /products, GET /products/:id
products:write	PATCH /products/:id
categories:read	GET /categories, GET /categories/:id
orders:read	GET /orders, GET /orders/:id
orders:write	POST /orders, PATCH /orders/:id
customers:read	GET /customers, GET /customers/:id

Decisiones de diseño

Esta API está inspirada en el webservice de PrestaShop, pero no es una copia — donde el original es ambiguo, fue difícil de usar en la práctica, o hubiera prometido algo que este sitio no puede garantizar de verdad, se hizo diferente a propósito:

Precio y stock nunca son editables. Todo el sitio (tienda, POS, esta API) lee precio y existencia en vivo directo de PrestaShop, sin caché. Permitir editarlos por aquí rompería esa garantía para el resto del sitio.

No se pueden crear productos nuevos. Un producto que no existe todavía en PrestaShop no se puede vender ni aparece en ningún otro lado del sitio — "crearlo" solo en esta API no serviría de nada. Editar productos que ya existen sí es real y aparece de inmediato.

Categorías, solo lectura. Su jerarquía y traducciones son de las partes más delicadas de PrestaShop; el sitio ya sincroniza los nombres reales cada hora, así que no había necesidad de duplicar esa responsabilidad aquí todavía.

Clientes, solo lectura. Los datos de clientes vienen de PrestaShop hacia nuestra base, no al revés — crear un cliente nuevo aquí requeriría escribirlo directo en el webservice real de PrestaShop, algo que este proyecto no ha probado todavía lo suficiente como para ofrecerlo con confianza.

Cualquiera de estos límites puede cambiar — si tu integración necesita algo que hoy no está disponible, dínoslo.