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"

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	La base de datos no respondió 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 se administran desde el panel de la tienda — no 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 el catálogo.

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: se administran desde el panel de la tienda, 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 el catálogo, 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

Algunos límites son a propósito:

Precio y stock nunca son editables. Todo el sitio (tienda, POS, esta API) lee precio y existencia del mismo catálogo, que se administra desde el panel. Permitir editarlos por aquí se saltaría ese control.

No se pueden crear productos nuevos. Los productos se dan de alta desde el panel de la tienda (con precio, inventario y fotos). Editar productos que ya existen sí es real y aparece de inmediato.

Categorías, solo lectura. Su jerarquía define la navegación y las ligas de toda la tienda, así que se administra solo desde el panel.

Clientes, solo lectura. Las cuentas de clientes se crean cuando el cliente se registra en la tienda; esta API solo las consulta.

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