Bienvenido a la API de Mercasist v1.0

La API de Mercasist te permite integrar tu sistema con nuestra plataforma para gestionar publicaciones, inventario y mas.

URL Base

https://api.mercasist.com/

Formato de Respuesta

Todas las respuestas de la API estan en formato JSON con codificacion UTF-8.

// Respuesta de un recurso individual
{
    "data": { ... }
}

// Respuesta de listados (con paginacion)
{
    "data": [ ... ],
    "pagination": {
        "total": 235,
        "limit": 50,
        "offset": 0,
        "page": 1,
        "total_pages": 5,
        "has_more": true
    }
}

Metodos HTTP Soportados

Metodo Descripcion
GET Obtener recursos
PUT Actualizar recurso completo
PATCH Actualizar campos especificos

Autenticacion

La API de Mercasist utiliza tokens de acceso para autenticar las solicitudes. Debes incluir tu token en cada peticion.

Importante: Para obtener tu access_token, debes solicitarlo al equipo de soporte de Mercasist. Contacta a soporte@mercasist.com indicando tu cuenta y el uso que le daras a la API.

Metodo 1: Header Authorization (Recomendado)

Incluye el token en el header Authorization usando el esquema Bearer:

Authorization: Bearer tu_access_token

Metodo 2: Query Parameter

Alternativamente, puedes pasar el token como parametro en la URL:

https://api.mercasist.com/publicaciones?token=tu_access_token

Ejemplo con cURL

curl -X GET "https://api.mercasist.com/publicaciones" \
     -H "Authorization: Bearer tu_access_token"

Errores de Autenticacion

Codigo Error Descripcion
401 Token requerido No se proporciono ningun token
401 Token invalido El token no es valido o ha expirado

Codigos de Error

La API utiliza codigos de estado HTTP estandar para indicar el resultado de las operaciones.

Codigo Significado Descripcion
200 OK La solicitud fue exitosa
207 Multi-Status Algunos campos se actualizaron, otros fallaron
400 Bad Request Error en los parametros enviados
401 Unauthorized Token invalido o no proporcionado
404 Not Found El recurso solicitado no existe
405 Method Not Allowed Metodo HTTP no permitido para este endpoint
500 Internal Server Error Error interno del servidor

Formato de Error

{
    "error": "Descripcion del error"
}

Listar Publicaciones

Obtiene la lista de publicaciones del usuario autenticado con soporte para paginacion.

GET /publicaciones

Descripcion

Retorna las publicaciones del usuario autenticado. Por defecto lista solo las publicaciones con estatus Activo; el estatus se puede cambiar con el parametro status.

Parametros de Filtro

Parametro Tipo Default Descripcion
status opcional string Activo Filtra por estatus. Valores: Activo, Pausado, Finalizado, Eliminado, under_review
tipo opcional string ALL Filtra por tipo de publicacion. Valores: ML (MercadoLibre), ST (tienda), ALL (todas)
q opcional string - Busqueda por id, titulo (varias palabras), id de MercadoLibre, SKU o SELLER_SKU
cuenta opcional integer - Filtra por id de la cuenta de MercadoLibre
categoria opcional string - Filtra por id de categoria de MercadoLibre
tienda_oficial opcional string - Filtra por tienda oficial. Valores: si (con tienda), no (sin tienda) o un id numerico de tienda
descripcion opcional string - Filtra por descripcion. Valores: si (con descripcion), no (sin descripcion)
variaciones opcional string - Filtra por variaciones. Valores: si (con variaciones), no (sin variaciones)
asociacion opcional string - Filtra por asociacion de inventario. Valores: asociado, sin_asociacion, incompleta, sin_variacion
cashea opcional string - Filtra por asociacion Cashea. Valores: si (asociado), no (no asociado)
divisa opcional string - Filtra por precio en divisa. Valores: si (con precio en divisa), no (sin precio en divisa)
sort opcional string pub_desc Ordenamiento. Valores: pub_desc, pub_asc, alfa_asc, alfa_desc, precio_desc, precio_asc, calidad_desc, calidad_asc

Parametros de Paginacion

Parametro Tipo Default Descripcion
limit opcional integer 25 Cantidad de resultados por pagina (maximo 25)
offset opcional integer 0 Numero de registros a saltar desde el inicio

Ejemplo de Solicitud

# Primera pagina (25 resultados por defecto)
curl -X GET "https://api.mercasist.com/publicaciones" \
     -H "Authorization: Bearer tu_access_token"

# Con limite personalizado
curl -X GET "https://api.mercasist.com/publicaciones?limit=20" \
     -H "Authorization: Bearer tu_access_token"

# Segunda pagina
curl -X GET "https://api.mercasist.com/publicaciones?limit=20&offset=20" \
     -H "Authorization: Bearer tu_access_token"

# Solo publicaciones pausadas de MercadoLibre, ordenadas por precio
curl -X GET "https://api.mercasist.com/publicaciones?status=Pausado&tipo=ML&sort=precio_desc" \
     -H "Authorization: Bearer tu_access_token"

# Busqueda por titulo, SKU o id
curl -X GET "https://api.mercasist.com/publicaciones?q=zapatos%20deportivos" \
     -H "Authorization: Bearer tu_access_token"

Respuesta Exitosa

{
    "data": [
        {
            "id": 12345,
            "id_ml": "MLM1234567890",
            "tipo": "ML",
            "titulo": "Producto de Ejemplo",
            "sku": "PROD-001",
            "precio": 299.99,
            "moneda": {
                "nombre": "Peso Mexicano",
                "simbolo": "$"
            },
            "precio_divisa": {
                "precio": 15.50,
                "moneda": "Dolar"
            },
            "disponibilidad": 15,
            "descripcion": "Descripcion detallada del producto...",
            "garantia": "Garantia del vendedor: 30 dias",
            "tipo_publicacion": "gold_special",
            "status": "Activo",
            "link_ml": "https://articulo.mercadolibre.com.mx/MLM-1234567890",
            "link_tienda": "https://mitienda.mst-shops.com/producto-item-9754128",
            "imagenes": [
                "https://http2.mlstatic.com/D_123456-MLM12345678_012025-O.jpg",
                "https://http2.mlstatic.com/D_789012-MLM12345678_012025-O.jpg"
            ],
            "categoria": {
                "nombre": "Computacion > Laptops",
                "id_ml": "MLM1652"
            },
            "cuenta_ml": {
                "nick": "MI TIENDA",
                "id_ml": "89435936"
            },
            "peso_kg": 1.5,
            "atributos": [
                {
                    "id": "BRAND",
                    "valor": "HP"
                }
            ],
            "variaciones": [
                {
                    "variaciones": "Color:Gris",
                    "cantidad": 30,
                    "sku": "13793"
                }
            ],
            "asociaciones_inventario": [
                {
                    "inventario_hash": "a1b2c3d4",
                    "cantidad": 10,
                    "variacion": null
                }
            ],
            "cashea_sku": [],
            "token": "43c3ff82dae9a4373b34178eb755cd47"
        }
    ],
    "pagination": {
        "total": 235,
        "limit": 25,
        "offset": 0,
        "page": 1,
        "total_pages": 10,
        "has_more": true
    }
}

Campos de Paginacion

Campo Tipo Descripcion
total integer Numero total de publicaciones disponibles
limit integer Limite de resultados aplicado (util si se ajusto al maximo)
offset integer Offset aplicado en la consulta
page integer Numero de pagina actual (comenzando en 1)
total_pages integer Numero total de paginas disponibles
has_more boolean Indica si hay mas resultados despues de esta pagina

Campos de Publicacion

Campo Tipo Descripcion
id integer ID unico de la publicacion en Mercasist
id_ml string|null ID de MercadoLibre (ej: MLM1234567890). null en publicaciones de stock (ST)
tipo string Tipo de publicacion: ML (MercadoLibre) o ST (stock/tienda)
titulo string Titulo de la publicacion
sku string Codigo SKU del producto (en ML combina el SKU propio con el atributo SELLER_SKU)
precio float|null Precio del producto
moneda object Moneda del precio: nombre y simbolo
precio_divisa object|null Precio en divisa alterna configurada: precio y moneda. null si no aplica
disponibilidad integer|null Cantidad disponible en stock
descripcion string|null Descripcion del producto (en ML se usa la descripcion de MercadoLibre)
garantia string|null Texto de la garantia
tipo_publicacion string|null Tipo de publicacion en ML (ej: gold_special, gold_pro)
status string Estado: Activo, Pausado o Finalizado
link_ml string|null URL directa a la publicacion en MercadoLibre
link_tienda string|null URL de la publicacion en la tienda Mercasist (mst-shops)
imagenes array Lista de URLs de las imagenes
categoria object|null Categoria: nombre (arbol completo) e id_ml
cuenta_ml object|null Cuenta de MercadoLibre asociada: nick e id_ml. null en publicaciones ST
peso_kg float|null Peso del producto en kilogramos
atributos array Atributos de la ficha tecnica: objetos con id y valor
variaciones array Variaciones activas: objetos con variaciones, cantidad y sku
asociaciones_inventario array Asociaciones al inventario: inventario_hash, cantidad y variacion
cashea_sku array SKUs de los articulos Cashea asociados
token string Hash unico de la publicacion

Obtener Detalle de Publicacion

Obtiene la informacion detallada de una publicacion especifica.

GET /publicaciones/{id}

Parametros

Parametro Tipo Descripcion
id REQUERIDO integer ID de la publicacion en Mercasist

Ejemplo de Solicitud

curl -X GET "https://api.mercasist.com/publicaciones/12345" \
     -H "Authorization: Bearer tu_access_token"

Respuesta Exitosa

{
    "data": {
        "id": 12345,
        "id_ml": "MLM1234567890",
        "tipo": "ML",
        "titulo": "Producto de Ejemplo",
        "sku": "PROD-001",
        "precio": 299.99,
        "moneda": {
            "nombre": "Peso Mexicano",
            "simbolo": "$"
        },
        "precio_divisa": null,
        "disponibilidad": 15,
        "descripcion": "Descripcion detallada del producto...",
        "garantia": "Garantia del vendedor: 30 dias",
        "tipo_publicacion": "gold_special",
        "status": "Activo",
        "link_ml": "https://articulo.mercadolibre.com.mx/MLM-1234567890",
        "link_tienda": "https://mitienda.mst-shops.com/producto-item-9754128",
        "imagenes": [
            "https://http2.mlstatic.com/D_123456-MLM12345678_012025-O.jpg"
        ],
        "categoria": {
            "nombre": "Computacion > Laptops",
            "id_ml": "MLM1652"
        },
        "cuenta_ml": {
            "nick": "MI TIENDA",
            "id_ml": "89435936"
        },
        "peso_kg": 1.5,
        "atributos": [
            {
                "id": "BRAND",
                "valor": "HP"
            }
        ],
        "variaciones": [
            {
                "variaciones": "Color:Gris",
                "cantidad": 30,
                "sku": "13793"
            }
        ],
        "asociaciones_inventario": [],
        "cashea_sku": [],
        "token": "43c3ff82dae9a4373b34178eb755cd47"
    }
}

Errores

Codigo Error Descripcion
404 Publicacion no encontrada No existe una publicacion con ese ID o no pertenece al usuario

Actualizar Publicacion

Actualiza los campos de una publicacion existente. La edicion de campos solo se permite en publicaciones con estatus Activo o Pausado. El cambio de estado (campo status) si se permite sobre otros estatus, por ejemplo para reactivar una publicacion finalizada.

PUT PATCH /publicaciones/{id}
Nota: Los cambios se sincronizan automaticamente con MercadoLibre para publicaciones de tipo ML.

Parametros de URL

Parametro Tipo Descripcion
id REQUERIDO integer ID de la publicacion en Mercasist

Campos Actualizables (Body JSON)

Campo Tipo Descripcion
precio opcional number Nuevo precio (debe ser mayor a 0)
moneda opcional string Codigo de moneda ML (ej: MXN, USD). Solo se permite junto con precio
disponibilidad opcional integer Cantidad disponible (entero >= 0)
titulo opcional string Nuevo titulo (no puede estar vacio)
descripcion opcional string Nueva descripcion del producto
sku opcional string Nuevo SKU del producto
garantia opcional object Objeto {tipo, nro, unit}. Ej: {"tipo":"Garantía del vendedor","nro":30,"unit":"días"}. Para quitarla: {"tipo":"Sin garantía"}
tienda_oficial opcional string|null ID de la tienda oficial en ML, o null para quitarla. Solo aplica a publicaciones ML
tipo_publicacion opcional string Tipo de publicacion ML (ej: gold_special, gold_pro). Solo aplica a publicaciones ML
dimensiones opcional object Objeto {peso, alto, ancho, largo} (peso en kg, resto en cm). Se admite un subconjunto de campos; solo se actualizan los enviados
precio_divisa opcional object Objeto {precio, id_moneda} donde id_moneda es el ID de una divisa del usuario. Enviar precio 0 o vacio elimina el precio en divisa
status opcional string Transicion de estado: Pausado, Activo (reactivar) o Finalizado

Ejemplo: Actualizar Precio

curl -X PUT "https://api.mercasist.com/publicaciones/12345" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "precio": 349.99
     }'

Ejemplo: Actualizar Multiples Campos

curl -X PATCH "https://api.mercasist.com/publicaciones/12345" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "precio": 349.99,
         "moneda": "MXN",
         "disponibilidad": 20,
         "titulo": "Producto Actualizado - Oferta Especial"
     }'

Ejemplo: Garantia, Dimensiones y Precio en Divisa

curl -X PATCH "https://api.mercasist.com/publicaciones/12345" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "sku": "PROD-001",
         "garantia": { "tipo": "Garantía del vendedor", "nro": 30, "unit": "días" },
         "dimensiones": { "peso": 1.5, "alto": 10, "ancho": 20, "largo": 30 },
         "precio_divisa": { "precio": 15.50, "id_moneda": 7 }
     }'

Ejemplo: Cambiar Estado (pausar / reactivar / finalizar)

# Pausar
curl -X PATCH "https://api.mercasist.com/publicaciones/12345" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{ "status": "Pausado" }'

# Reactivar
curl -X PATCH "https://api.mercasist.com/publicaciones/12345" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{ "status": "Activo" }'

Respuesta Exitosa

{
    "data": {
        "id": 12345,
        "actualizado": ["precio", "disponibilidad", "titulo"],
        "precio": 349.99,
        "disponibilidad": 20,
        "titulo": "Producto Actualizado - Oferta Especial"
    }
}

Respuesta Parcial (207 Multi-Status)

Cuando algunos campos se actualizan correctamente pero otros fallan:

{
    "data": {
        "id": 12345,
        "actualizado": ["titulo"],
        "titulo": "Nuevo Titulo",
        "errores": ["Error al actualizar precio en MercadoLibre"]
    }
}

Errores Comunes

Codigo Error Causa
400 Se requiere el parametro id No se especifico el ID de la publicacion
400 Body JSON requerido No se envio el cuerpo JSON con los campos a actualizar
400 Campos no permitidos Se intento actualizar un campo no permitido
400 El campo moneda solo se permite junto con precio Se envio moneda sin precio
400 El precio debe ser un numero mayor a 0 Precio invalido
400 La disponibilidad debe ser un entero >= 0 Disponibilidad invalida
400 tienda_oficial / tipo_publicacion solo aplica a publicaciones ML Se intento editar un campo exclusivo de ML en una publicacion de stock (ST)
400 precio_divisa requiere id_moneda / id_moneda no valido Falta el id de divisa o no pertenece al usuario
400 status invalido (valores permitidos: Pausado, Activo, Finalizado) Se envio un valor de status no soportado
400 No se puede modificar una publicacion con estatus... Se intento editar campos de una publicacion Finalizada (el cambio de status si se permite)
404 Publicacion no encontrada El ID no existe o no pertenece al usuario

Listar Ordenes

Obtiene la lista de ordenes del usuario autenticado con soporte para paginacion. Recurso de solo lectura.

GET /ordenes

Descripcion

Retorna las ordenes del usuario (se excluyen siempre las de estatus interno Pendiente y Carrito). Cada orden incluye los mismos datos que el reporte Excel de ordenes: comprador, articulos, calificaciones, y la informacion de pago/envio (MercadoPago, MercadoEnvio internacional y de Venezuela, notificaciones de envio y campos de pago).

Parametros

Parametro Tipo Default Descripcion
status opcional string activas Filtra por estatus: activas, finalizadas, canceladas o todas
fecha_inicio opcional string - Fecha minima de la orden (formato YYYY-MM-DD, inclusive)
fecha_fin opcional string - Fecha maxima de la orden (formato YYYY-MM-DD, inclusive)
tipo opcional string todas Filtra por tipo de orden: ML, NML, TIENDA, WA, CASHEA
cuenta opcional integer - Filtra por id de la cuenta de MercadoLibre
origen opcional string - Filtra por origen de la orden
q opcional string - Busqueda libre: nick, nombre o email del comprador y titulo del articulo; o por id de orden, id de MercadoLibre, id de articulo o id Cashea
sort opcional string orden_desc Ordenamiento: orden_desc, orden_asc (por fecha de orden), pago_desc, pago_asc (por fecha de pago)
limit opcional integer 20 Cantidad de resultados por pagina (maximo 20)
offset opcional integer 0 Numero de registros a saltar desde el inicio

Ejemplo de Solicitud

# Ordenes activas (por defecto)
curl -X GET "https://api.mercasist.com/ordenes" \
     -H "Authorization: Bearer tu_access_token"

# Finalizadas, ordenadas por fecha de pago
curl -X GET "https://api.mercasist.com/ordenes?status=finalizadas&sort=pago_desc&limit=20" \
     -H "Authorization: Bearer tu_access_token"

# Ordenes de MercadoLibre en un rango de fechas
curl -X GET "https://api.mercasist.com/ordenes?tipo=ML&fecha_inicio=2026-01-01&fecha_fin=2026-01-31" \
     -H "Authorization: Bearer tu_access_token"

# Busqueda por comprador, titulo o id
curl -X GET "https://api.mercasist.com/ordenes?q=juan%20perez" \
     -H "Authorization: Bearer tu_access_token"

Respuesta Exitosa

{
    "data": [
        {
            "id": 18288114,
            "id_ml": null,
            "estatus": "Abierta",
            "canal": "Usuario",
            "tipo": "NML",
            "origen": null,
            "cuenta_ml": null,
            "moneda": "U$S",
            "fecha": "2026-07-10 14:32:05",
            "total": 14.99,
            "comprador": {
                "nick": null,
                "nombre": "Victor Guzman",
                "telefono": "04124989895",
                "email": "admin@mercasist.com",
                "puntaje": 0
            },
            "articulos": [
                {
                    "id_articulo": 44119,
                    "id_ml": null,
                    "titulo": "Cámara Para Exteriores Tipo Bullet Lente 3.6mm",
                    "sku": "F44119",
                    "sku_variacion": null,
                    "cantidad": 1,
                    "precio": 14.99
                }
            ],
            "calificacion_enviada": null,
            "calificacion_recibida": null,
            "mercadopago": [],
            "mercadoenvio": null,
            "notificaciones_envio": [],
            "mercadoenvio_ve": null,
            "pago_campos": []
        }
    ],
    "pagination": {
        "total": 1,
        "limit": 20,
        "offset": 0,
        "page": 1,
        "total_pages": 1,
        "has_more": false
    }
}

Campos de la Orden

Campo Tipo Descripcion
idintegerID de la orden en Mercasist
id_mlstring|nullID de la orden en MercadoLibre (null si no es ML)
estatusstringEstatus operativo de la orden (ej: Abierta, Pago recibido, Enviada, Entregada, Finalizada)
canalstringCanal de creacion: MercadoLibre, Usuario, Tienda, WhatsApp o Cashea
tipostringTipo interno: ML, NML, TIENDA, WA, CASHEA
origenstring|nullOrigen de la orden
cuenta_mlstring|nullNick de la cuenta ML (solo ordenes ML)
monedastringSimbolo de la moneda
fechastringFecha de la orden (YYYY-MM-DD HH:MM:SS)
totalfloat|nullTotal de la orden (articulos + envio, sin impuestos)
compradorobjectnick, nombre, telefono, email, puntaje
articulosarrayObjetos con id_articulo, id_ml, titulo, sku, sku_variacion, cantidad, precio
calificacion_enviadaobject|nulltipo (Positiva/Neutral/Negativa), concretada, fecha, motivo, descripcion
calificacion_recibidaobject|nullIgual estructura que calificacion_enviada
mercadopagoarrayPagos MercadoPago: id_pago, fecha, monto_total, monto_comision, monto_envio, estatus
mercadoenvioobject|nullMercadoEnvio internacional: servicio, metodo, tracking, receptor_*, status, substatus
notificaciones_envioarrayNotificaciones de envio: fecha, metodo, codigo_rastreo, comentarios
mercadoenvio_veobject|nullMercadoEnvio Venezuela: fecha_pago, transportista, tracking, pago_metodo, pago_metodo_label, pago_monto
pago_camposarrayCampos de pago configurables (Venezuela): objetos {titulo, valor}

Obtener Detalle de Orden

Obtiene la informacion completa de una orden especifica.

GET /ordenes/{id}

Parametros

Parametro Tipo Descripcion
id REQUERIDO integer ID de la orden en Mercasist

Ejemplo de Solicitud

curl -X GET "https://api.mercasist.com/ordenes/18288114" \
     -H "Authorization: Bearer tu_access_token"

Respuesta Exitosa

Devuelve un unico objeto orden (misma estructura que cada item del listado). Ejemplo de una orden ML con pago y envio:

{
    "data": {
        "id": 2000112345,
        "id_ml": "2000112345",
        "estatus": "Entregada",
        "canal": "MercadoLibre",
        "tipo": "ML",
        "cuenta_ml": "MI TIENDA",
        "moneda": "$",
        "fecha": "2026-07-08 09:15:00",
        "total": 349.99,
        "comprador": {
            "nick": "COMPRADOR123",
            "nombre": "Juan Perez",
            "telefono": "555-1234",
            "email": "juan@example.com",
            "puntaje": 5
        },
        "articulos": [
            {
                "id_articulo": 12345,
                "id_ml": "MLM1234567890",
                "titulo": "Producto de Ejemplo",
                "sku": "PROD-001",
                "sku_variacion": null,
                "cantidad": 2,
                "precio": 174.99
            }
        ],
        "calificacion_enviada": {
            "tipo": "Positiva",
            "concretada": true,
            "fecha": "2026-07-12 10:00:00",
            "motivo": null,
            "descripcion": "Excelente comprador"
        },
        "calificacion_recibida": null,
        "mercadopago": [
            {
                "id_pago": "123456789",
                "fecha": "2026-07-08 09:16:00",
                "monto_total": 349.99,
                "monto_comision": 45.50,
                "monto_envio": 0,
                "estatus": "approved"
            }
        ],
        "mercadoenvio": {
            "servicio": "Mercado Envios",
            "metodo": "custom",
            "tracking": "TRACK123456",
            "receptor_nombre": "Juan Perez",
            "receptor_telefono": "555-1234",
            "receptor_ciudad": "Ciudad de Mexico",
            "receptor_estado": "CDMX",
            "status": "delivered",
            "substatus": null
        },
        "notificaciones_envio": [],
        "mercadoenvio_ve": null,
        "pago_campos": []
    }
}

Errores

Codigo Error Descripcion
404 Orden no encontrada El ID no existe o no pertenece al usuario
401 Token requerido / Token invalido Falta el token o no es valido

Proximos Modulos

Estamos trabajando en ampliar la API con nuevas funcionalidades. Proximamente estaran disponibles:

Inventario

Control de stock multi-almacen

Reportes

Estadisticas y analisis de ventas

Mantente informado: Para recibir notificaciones sobre nuevos endpoints, contacta al equipo de soporte.