Bienvenido a la API de Mercasist v1.0

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

URL Base

https://api.mercasist.com/

Una solicitud GET a la URL base desde un navegador redirige a esta documentacion. Desde un cliente de API (sin token) devuelve informacion basica:

{
    "name": "Mercasist API",
    "version": "1.0",
    "documentation": "https://api.mercasist.com/docs/",
    "resources": ["publicaciones", "ordenes", "inventario"]
}

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
POST Crear 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
201 Created El recurso fue creado
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
409 Conflict El recurso ya existe (por ejemplo, un modelo/SKU repetido)
429 Too Many Requests Se alcanzo un limite de uso; reintentar despues de Retry-After segundos
500 Internal Server Error Error interno del servidor

Formato de Error

{
    "error": "Descripcion del error"
}

Limites de Uso

Para proteger el servicio, cada cuenta tiene los siguientes limites. Si una solicitud supera cualquiera de ellos, la API no la procesa y responde 429 Too Many Requests.

Limite Maximo Descripcion
Solicitudes por minuto 300 Solicitudes de los ultimos 60 segundos
Solicitudes por dia 10.000 Se reinicia a la medianoche, hora de Venezuela (UTC-4)
Solicitudes simultaneas 20 Solicitudes en curso al mismo tiempo
Modificaciones de publicaciones por minuto 60 PUT y PATCH en /publicaciones/{id}. Cada modificacion se aplica en MercadoLibre en el momento

Los limites cuentan todas las solicitudes autenticadas de la cuenta, en todos los endpoints. Las solicitudes rechazadas con 429 no cuentan. Si tu integracion necesita limites mayores, escribe a soporte@mercasist.com.

Headers de Cuota

Cada respuesta a una solicitud autenticada informa el estado de la cuota:

Header Descripcion
X-RateLimit-Limit Maximo de solicitudes por minuto de la cuenta
X-RateLimit-Remaining Solicitudes que quedan en la ventana del ultimo minuto
X-RateLimit-Limit-Day Maximo de solicitudes por dia de la cuenta
X-RateLimit-Remaining-Day Solicitudes que quedan en el dia
Retry-After Solo en respuestas 429: segundos a esperar antes de reintentar

Respuesta 429

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
    "error": "Límite de 300 solicitudes por minuto alcanzado. Reintenta en 12 segundos.",
    "limite": "minuto",
    "maximo": 300,
    "reintentar_en": 12
}

El campo limite indica cual limite se alcanzo: minuto, dia, simultaneos o escrituras (modificaciones de publicaciones).

Recomendacion: ante un 429, espera los segundos de Retry-After antes de reintentar. Para sincronizar muchos datos, recorre las paginas una tras otra en lugar de pedirlas todas en paralelo.

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": [
                {
                    "id": 4821,
                    "id_ml": "180934567890",
                    "variaciones": "Color:Gris",
                    "cantidad": 30,
                    "sku": "13793"
                }
            ],
            "asociaciones_inventario": [
                {
                    "id_inventario": 5512,
                    "inventario_hash": "7F3A9C",
                    "modelo": "TAZA-BL-11",
                    "titulo": "Taza blanca 11oz",
                    "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 id (identificador para actualizar su disponibilidad via PUT/PATCH), id_ml (null en publicaciones ST), variaciones, cantidad y sku
asociaciones_inventario array Articulos de inventario asociados (solo los del mismo usuario): id_inventario (para consultarlo en /inventario/{id}), inventario_hash (codigo Mercasist), modelo, titulo, cantidad (unidades del articulo por cada unidad vendida de la publicacion) 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": [
            {
                "id": 4821,
                "id_ml": "180934567890",
                "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). Solo para publicaciones sin variaciones; si la publicacion tiene variaciones usar variaciones
variaciones opcional array Disponibilidad por variacion: arreglo de objetos {id, disponibilidad}, donde id es el de variaciones[].id en el detalle de la publicacion y disponibilidad un entero >= 0. Solo se envian las variaciones a cambiar; las demas conservan su cantidad. Si algun elemento es invalido no se actualiza ninguna. En ML se aplica en un solo cambio. Solo para publicaciones con variaciones
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: Disponibilidad por Variacion

Los id se obtienen de variaciones[].id en GET /publicaciones/{id}.

curl -X PATCH "https://api.mercasist.com/publicaciones/12345" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "variaciones": [
             { "id": 4821, "disponibilidad": 5 },
             { "id": 4822, "disponibilidad": 0 }
         ]
     }'

Respuesta:

{
    "data": {
        "id": 12345,
        "actualizado": ["variaciones"],
        "variaciones": [
            { "id": 4821, "disponibilidad": 5 },
            { "id": 4822, "disponibilidad": 0 }
        ]
    }
}

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 La publicacion tiene variaciones; la disponibilidad se actualiza con variaciones[].disponibilidad Se envio disponibilidad a una publicacion con variaciones
400 La publicacion no tiene variaciones; use disponibilidad Se envio variaciones a una publicacion sin variaciones
400 variaciones[n].id no corresponde a una variacion activa / esta repetido; variaciones[n].disponibilidad debe ser un entero >= 0 Elemento invalido en variaciones; no se actualiza ninguna variacion
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.

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": {
                "id": 4410238,
                "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,
                    "impuesto": {
                        "nombre": "IVA",
                        "porcentaje": 16
                    }
                }
            ],
            "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. Los precios de los articulos incluyen sus impuestos
compradorobjectid (se puede reutilizar como id_comprador al crear una orden), nick, nombre, telefono, email, puntaje
articulosarrayObjetos con id_articulo, id_ml, titulo, sku, sku_variacion, cantidad, precio (incluye el impuesto) e impuesto ({nombre, porcentaje} o null)
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": {
            "id": 3981144,
            "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,
                "impuesto": null
            }
        ],
        "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

Crear Orden

Crea una orden manual, igual que "Nueva orden" en la web: tipo NML (canal "Usuario"), en estatus Abierta. Dispara los mismos eventos que una orden nueva creada en la web.

POST /ordenes
Eventos de orden nueva: se envian las plantillas de mensajeria configuradas para "orden nueva" (correo y WhatsApp al comprador), se aplican las reglas de descuento de inventario, se avisa por WhatsApp al vendedor y se actualiza la web abierta. Con "notificar": false no se envian las plantillas al comprador; lo demas se aplica igual.

Campos (Body JSON)

Campo Tipo Descripcion
comprador opcional object Comprador nuevo: {nombre, email, telefono, cedula}. nombre es obligatorio (maximo 150 caracteres). Se envia comprador o id_comprador, uno de los dos
id_comprador opcional integer ID de un comprador existente del usuario (el comprador.id de cualquier orden)
articulos REQUERIDO array Lineas de la orden (maximo 100): objetos {id_publicacion, id_variacion, cantidad, precio, impuesto}. Ver la tabla siguiente
moneda opcional string Codigo de moneda permitido para el pais del usuario (ej: USD). Por defecto, la moneda preferida del usuario para ordenes o su moneda local
origen opcional string Origen de la orden (ej: Instagram). Por defecto (o si viene vacio) API. Si ya existe en los origenes del usuario se usa el nombre registrado, sin importar mayusculas; si no existe se agrega, para poder usarlo en las reglas y plantillas que filtran por origen
notificar opcional boolean true por defecto. Con false no se envian las plantillas de mensajeria al comprador

Campos de cada Articulo

Campo Tipo Descripcion
id_publicacion REQUERIDO integer ID de una publicacion del usuario, activa o pausada (el id de /publicaciones)
id_variacion opcional integer ID de una variacion activa de la publicacion. Obligatorio si la publicacion tiene variaciones
cantidad REQUERIDO integer Unidades (mayor que 0)
precio opcional number Precio unitario en la moneda de la orden (impuesto incluido). Si no se envia se usa el de la publicacion; si la publicacion tiene otra moneda, en Venezuela se convierte entre Bs y USD con la tasa BCV y en los demas casos hay que enviar el precio. Se recomienda enviarlo como numero; como texto se aceptan "1234,56", "1.234,56" o "1,234.56", y se rechazan los ambiguos como "15.000"
impuesto opcional object {nombre, porcentaje}, ej: {"nombre": "IVA", "porcentaje": 16}. El mismo impuesto debe tener el mismo porcentaje en todas las lineas

Ejemplo de Solicitud

curl -X POST "https://api.mercasist.com/ordenes" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "comprador": {"nombre": "Juan Perez", "email": "juan@correo.com", "telefono": "04141234567", "cedula": "V12345678"},
         "moneda": "USD",
         "origen": "Instagram",
         "articulos": [
             {"id_publicacion": 90211, "cantidad": 2, "precio": 25.00, "impuesto": {"nombre": "IVA", "porcentaje": 16}},
             {"id_publicacion": 90350, "id_variacion": 5521, "cantidad": 1}
         ]
     }'

Respuesta Exitosa (201)

Devuelve la orden creada en data, con la misma estructura del detalle de orden. Si la orden se guardo pero fallo alguno de los eventos de orden nueva (por ejemplo, un error al armar una plantilla), responde igual 201 e incluye un campo advertencia con los eventos que fallaron. Las reglas de descuento de inventario se aplican aunque fallen las plantillas.

Errores Comunes

Codigo Error Descripcion
400 Se requiere el comprador Falta comprador o id_comprador, o se enviaron los dos
400 La publicación ... tiene variaciones: indica id_variacion La publicacion tiene variaciones activas y no se indico cual
400 La publicación ... tiene una moneda distinta a la de la orden Hay que enviar el precio en la moneda de la orden
400 Publicación ... no encontrada La publicacion no existe o no pertenece al usuario
Importante: cada solicitud exitosa crea una orden nueva. Si tu sistema reintenta un POST (por ejemplo, tras un error de red), verifica antes en /ordenes que la orden no se haya creado, para no duplicarla.

Listar Articulos de Inventario

Obtiene los articulos de inventario del usuario autenticado, con su stock por almacen y soporte para paginacion.

GET /inventario

Descripcion

Cada articulo incluye sus datos (modelo/SKU, codigo Mercasist, titulo, precio, categoria), el stock por almacen calculado a partir de sus movimientos, la disponibilidad en la logistica Mercasist, imagenes, proveedores, tags y las publicaciones asociadas. Los filtros son los mismos del listado de inventario de la web.

Parametros

Parametro Tipo Default Descripcion
estatus opcional string activos Filtra por estatus: activos, inactivos o todos
categoria opcional integer - Filtra por id de categoria
asociacion opcional string - Filtra por publicaciones asociadas: asociado, sin_asociacion, finalizadas (asociado a publicaciones finalizadas o eliminadas), mercasist, sin_mercasist (publicaciones Mercasist), ml, sin_ml (publicaciones de MercadoLibre)
logistica opcional string - Disponibilidad en la logistica Mercasist: con_stock, agotado o nunca (nunca enviados)
modelo opcional string - Modelo (SKU) exacto. Util para que un sistema externo ubique un articulo por su SKU
q opcional string - Busqueda libre: parte del modelo, palabras del titulo, id del articulo o codigo Mercasist
sort opcional string modelo_asc Ordenamiento: modelo_asc, modelo_desc, titulo_asc, titulo_desc, precio_asc, precio_desc o recientes
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

# Articulos activos (por defecto)
curl -X GET "https://api.mercasist.com/inventario" \
     -H "Authorization: Bearer tu_access_token"

# Ubicar un articulo por su modelo (SKU)
curl -X GET "https://api.mercasist.com/inventario?modelo=TAZA-BL-11&estatus=todos" \
     -H "Authorization: Bearer tu_access_token"

# Articulos sin publicaciones asociadas, los mas recientes primero
curl -X GET "https://api.mercasist.com/inventario?asociacion=sin_asociacion&sort=recientes" \
     -H "Authorization: Bearer tu_access_token"

Respuesta Exitosa

{
    "data": [
        {
            "id": 5512,
            "hash": "7F3A9C",
            "modelo": "TAZA-BL-11",
            "titulo": "Taza blanca 11oz",
            "descripcion": "Ceramica, apta para microondas",
            "estatus": "activo",
            "precio": 4.5,
            "moneda": "USD",
            "categoria": {
                "id": 12,
                "titulo": "Cocina"
            },
            "impuesto": null,
            "imagenes": [
                "https://storage.mercas.ist/inventario_articulos/iv_6650a1.jpg"
            ],
            "stock": {
                "total": 120,
                "mercasist": 0,
                "almacenes": [
                    {
                        "id": 3,
                        "titulo": "Principal",
                        "principal": true,
                        "tipo": "regular",
                        "cantidad": 100
                    },
                    {
                        "id": 7,
                        "titulo": "Tienda Centro",
                        "principal": false,
                        "tipo": "regular",
                        "cantidad": 20
                    }
                ]
            },
            "proveedores": [
                {
                    "id": 4,
                    "nombre": "Distribuidora X",
                    "costo": 2.1,
                    "moneda": "Dolar"
                }
            ],
            "tags": ["temporada"],
            "asociaciones": [
                {
                    "id_publicacion": 90211,
                    "tipo": "ML",
                    "id_ml": "MLV123456789",
                    "titulo": "Combo 2 tazas blancas 11oz",
                    "status": "Activo",
                    "cuenta_ml": "MITIENDA",
                    "variacion": null,
                    "cantidad": 2
                }
            ]
        }
    ],
    "pagination": {
        "total": 1,
        "limit": 25,
        "offset": 0,
        "page": 1,
        "total_pages": 1,
        "has_more": false
    }
}

Campos del Articulo

Campo Tipo Descripcion
idintegerID del articulo de inventario
hashstringCodigo Mercasist del articulo (6 caracteres). Es el mismo valor que inventario_hash en las asociaciones de /publicaciones
modelostringModelo (SKU), unico por usuario
titulostringTitulo del articulo
descripcionstring|nullDescripcion del articulo
estatusstringactivo o inactivo
preciofloatPrecio del articulo
monedastringCodigo de la moneda del precio (si el articulo no tiene una propia, la del usuario)
categoriaobject|nullid y titulo de la categoria
impuestoobject|nullnombre y porcentaje. Solo lectura
imagenesarrayURLs de las imagenes, la principal primero
stockobjecttotal (suma de entradas menos salidas en todos los almacenes), mercasist (disponible en la logistica Mercasist) y almacenes: id, titulo, principal, tipo (regular o compuesto) y cantidad. El stock de un almacen compuesto es la suma de sus almacenes componentes
proveedoresarrayProveedores del articulo: id, nombre, costo y moneda del costo
tagsarrayNombres de los tags del articulo
asociacionesarrayPublicaciones asociadas (solo las del mismo usuario): id_publicacion (para consultarla en /publicaciones/{id}), tipo (ML o ST = Mercasist), id_ml, titulo, status, cuenta_ml, variacion y cantidad (unidades de este articulo por cada unidad vendida de la publicacion)

Obtener Detalle de Articulo

Obtiene un articulo de inventario especifico, con la misma estructura del listado.

GET /inventario/{id}

Parametros

Parametro Tipo Descripcion
id REQUERIDO integer ID del articulo de inventario

Ejemplo de Solicitud

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

Respuesta Exitosa

{
    "data": {
        "id": 5512,
        "hash": "7F3A9C",
        "modelo": "TAZA-BL-11",
        // ... mismos campos que en el listado
    }
}

Errores

Codigo Error Descripcion
404 Artículo de inventario no encontrado El ID no existe o no pertenece al usuario
401 Token requerido / Token invalido Falta el token o no es valido

Crear Articulo de Inventario

Crea un articulo de inventario con las mismas validaciones del formulario de la web. Opcionalmente registra su stock inicial por almacen.

POST /inventario

Campos (Body JSON)

Campo Tipo Descripcion
titulo REQUERIDO string Titulo del articulo (maximo 255 caracteres)
modelo REQUERIDO string Modelo (SKU), unico por usuario (maximo 255 caracteres). Si ya existe responde 409 con el id del articulo existente
precio REQUERIDO number Precio (mayor o igual a 0). Se recomienda enviarlo como numero; como texto se aceptan "1234,56", "1.234,56" o "1,234.56", y se rechazan los ambiguos como "15.000" (puede ser miles o decimales)
moneda opcional string Codigo de moneda permitido para el pais del usuario (ej: USD). Por defecto, la moneda del usuario
descripcion opcional string Descripcion del articulo
categoria opcional integer ID de una categoria del usuario
categoria_titulo opcional string Titulo de categoria: si existe se reutiliza, si no se crea. Si tambien se envia categoria, prevalece categoria
stock opcional array Stock inicial: arreglo de objetos {almacen, cantidad} (id de almacen regular y entero >= 0). Se registra como un movimiento de entrada "Carga inicial por API"

Ejemplo de Solicitud

curl -X POST "https://api.mercasist.com/inventario" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "titulo": "Taza blanca 11oz",
         "modelo": "TAZA-BL-11",
         "precio": 4.5,
         "moneda": "USD",
         "categoria_titulo": "Cocina",
         "stock": [{"almacen": 3, "cantidad": 100}]
     }'

Respuesta Exitosa (201)

{
    "data": {
        "id": 5512,
        "hash": "7F3A9C",
        "modelo": "TAZA-BL-11",
        // ... mismos campos que en el listado
    }
}

Errores Comunes

Codigo Error Descripcion
400 El campo titulo es obligatorio Falta un campo requerido o un valor es invalido
400 Moneda inválida para tu país El mensaje incluye los codigos de moneda permitidos
400 El almacén ... es compuesto El stock de un almacen compuesto se calcula a partir de otros almacenes: no se carga directamente
409 Ya tienes un artículo con ese modelo (SKU) Incluye el id del articulo existente para actualizarlo con PATCH

Actualizar Articulo de Inventario

Actualiza los datos de un articulo. Solo se modifican los campos enviados. El stock no se edita aqui: se usan Stock por almacen o Movimientos.

PUT PATCH /inventario/{id}
Nota: La API no escribe en MercadoLibre. Los cambios de precio y stock llegan a las publicaciones asociadas a traves de la sincronizacion de publicaciones de Mercasist, si la cuenta la tiene activa.

Campos Actualizables (Body JSON)

Campo Tipo Descripcion
titulo opcional string Nuevo titulo (no puede estar vacio, maximo 255 caracteres)
modelo opcional string Nuevo modelo (SKU). Si otro articulo ya lo usa responde 409
precio opcional number Nuevo precio (mayor o igual a 0)
moneda opcional string|null Codigo de moneda permitido para el pais del usuario. null vuelve a usar la moneda del usuario
descripcion opcional string|null Nueva descripcion
categoria opcional integer|null ID de una categoria del usuario, o null para quitarla
categoria_titulo opcional string Titulo de categoria: si existe se reutiliza, si no se crea
estatus opcional string activo o inactivo. Los articulos no se eliminan: se inactivan

Ejemplo: Cambiar Precio e Inactivar

curl -X PATCH "https://api.mercasist.com/inventario/5512" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{"precio": 4.99, "estatus": "inactivo"}'

Respuesta Exitosa

Devuelve el articulo actualizado, con la misma estructura del detalle.

Movimientos de Inventario

Historial de entradas y salidas de un articulo, y registro de nuevos movimientos. El stock de cada almacen es la suma de sus entradas menos sus salidas.

GET POST /inventario/{id}/movimientos

Listar Movimientos (GET)

Devuelve los movimientos del mas reciente al mas antiguo, paginados con limit (por defecto y maximo 50) y offset, con la misma estructura de pagination del listado.

{
    "data": [
        {
            "id": 880123,
            "fecha": "2026-10-05 14:32:10",
            "tipo": "salida",
            "cantidad": 2,
            "saldo": 120,
            "almacen": {
                "id": 3,
                "titulo": "Principal"
            },
            "anaquel": null,
            "descripcion": "Descuento por orden #482913",
            "id_orden": 482913,
            "id_factura": null
        }
    ],
    "pagination": { // ... }
}
Campo Tipo Descripcion
tipostringentrada o salida
cantidadintegerUnidades del movimiento
saldointegerStock total del articulo despues de ese movimiento
almacenobjectid y titulo del almacen
anaquelobject|nullid y nombre del anaquel
id_ordeninteger|nullOrden que genero el movimiento (descuento automatico por reglas de inventario)
id_facturainteger|nullFactura que genero el movimiento

Registrar Movimiento (POST)

Campo Tipo Descripcion
tipo REQUERIDO string entrada o salida
cantidad REQUERIDO integer Unidades (entero mayor que 0)
almacen REQUERIDO integer ID de un almacen regular del usuario (ver Almacenes)
anaquel opcional integer|null ID de un anaquel de ese almacen
fecha opcional string Fecha del movimiento (YYYY-MM-DD). Por defecto, hoy
descripcion REQUERIDO string Motivo del movimiento (maximo 255 caracteres, sin emojis) 
curl -X POST "https://api.mercasist.com/inventario/5512/movimientos" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{"tipo": "entrada", "cantidad": 24, "almacen": 3, "descripcion": "Compra a proveedor, factura 1050"}'

Responde 201 con el movimiento creado en data y el stock actualizado del articulo en stock. Igual que en la web, una salida no se bloquea si el stock es insuficiente.

Stock por Almacen

Consulta el stock de un articulo o lo fija en uno o varios almacenes.

GET PUT /inventario/{id}/stock

Consultar (GET)

Devuelve en data el objeto stock del articulo (total, mercasist y almacenes).

Fijar Stock (PUT)

Para cada almacen enviado calcula la diferencia contra el stock actual y registra un movimiento "Ajuste por API" de entrada o salida. Los almacenes que no se envian no cambian. Si algun almacen es invalido no se modifica ninguno. Solo se aceptan almacenes regulares.

curl -X PUT "https://api.mercasist.com/inventario/5512/stock" \
     -H "Authorization: Bearer tu_access_token" \
     -H "Content-Type: application/json" \
     -d '{"almacenes": [{"almacen": 3, "cantidad": 80}, {"almacen": 7, "cantidad": 25}]}'

Respuesta Exitosa

{
    "data": {
        "total": 105,
        "mercasist": 0,
        "almacenes": [ // ... ]
    },
    "ajustes": [
        {
            "almacen": { "id": 3, "titulo": "Principal" },
            "anterior": 100,
            "nuevo": 80,
            "diferencia": -20
        },
        {
            "almacen": { "id": 7, "titulo": "Tienda Centro" },
            "anterior": 20,
            "nuevo": 25,
            "diferencia": 5
        }
    ]
}

Almacenes

Lista los almacenes del usuario con sus anaqueles. Los IDs se usan en los campos almacen y anaquel de los demas endpoints de inventario.

GET /inventario/almacenes

Respuesta Exitosa

{
    "data": [
        {
            "id": 3,
            "titulo": "Principal",
            "principal": true,
            "tipo": "regular",
            "componentes": [],
            "incluye_logistica_mercasist": false,
            "anaqueles": [
                { "id": 41, "nombre": "A1" }
            ]
        }
    ],
    "logistica_mercasist": false
}
Campo Tipo Descripcion
tipostringcompuesto o regular (los almacenes creados por integraciones pueden traer otro valor, ej. Normal, y funcionan como regulares). Un almacen compuesto suma el stock de sus componentes y no admite movimientos propios
componentesarrayAlmacenes que suma un almacen compuesto: id y titulo
incluye_logistica_mercasistbooleanSi el almacen compuesto suma tambien la disponibilidad en la logistica Mercasist
logistica_mercasistbooleanSi el usuario tiene el servicio de logistica Mercasist

Proximos Modulos

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

Reportes

Estadisticas y analisis de ventas

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