Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 10/10/2024

Gestión de mensajes

Importante:
Importante: Los recursos de consulta (GET) comparten un límite de 500 rpm, y los recursos de escritura (POST/PUT) también comparten entre sí un límite de 500 rpm.

Parámetros

message_id: ID del mensaje.
date_created: fecha de creación.
date: fecha en que se guarda el mensaje.
date_received: fecha en que se recibió el mensaje.
date_available: fecha en el que el mensaje ha pasado por moderación.
date_notified: fecha en el que el mensaje ha sido notificado a la contraparte.
date_read: fecha en el que el mensaje fue leído por la contraparte.
from: quién envía el mensaje.
user_id: ID del usuario que envió el mensaje.
to: quién recibe el mensaje.
user_id: ID del usuario que recibió el mensaje.
subject: subject del email.
text: texto del mensaje.
plain: texto plano del mensaje.
attachments: archivos adjuntos.
attachments_validations: validaciones de adjuntos.
invalid_size: si el tamaño del adjunto es inválido.
invalid_extension: extensión del adjunto inválido.
internal_error: error interno.
site_id: sitio de Mercado Libre (MLA, MLB, etc.).
message_resources: contiene una lista con IDs relacionados al mensaje, describiendo a qué recurso pertenece cada uno.
status: estado del mensaje (available - moderated - rejected - pending_translation).
moderation.status: resultado del proceso de moderación.

  • clean
  • rejected
  • pending: para casos que la moderación está en proceso
  • non_moderated: para casos viejos que no aplicó la moderación

moderation.date_moderated: fecha en que se impactó la información de moderación.

moderation.source: modalidad de la moderación.

moderation.reason: razón por la cual se moderó el mensaje. Actualmente, esta moderación puede ser por lenguaje inapropiadoa (OUT_OF_PLACE_LANGUAGE), por link de redes sociales (SOCIAL_NETWORK_LINK), links acortados (LINK_SHORT_URL), por ser un mensaje automático de integrador (AUTOMATIC_MESSAGE), por información personal (PERSONAL_DATA), links de Mercado Pago (LINK_MERCADOPAGO), links de medios de pagos externos (ML_LINKS_PAYPAL) o por evasiones al reclamo (EVASION_CLAIM_SELLER).


Obtener mensajes por pack

Para conocer el pack_id, debes obtenerlo en la respuesta de /orders/$ORDER_ID. En caso que el pack id sea null, debes tomar por defecto el order id, manteniendo el recurso /packs. Los mensajes moderados por la contraparte no serán visibles y sí podrán verse los mensajes propios.

Nota:
Cuando consultes a /messages/packs/pack_id/sellers/seller_id los mensajes se marcarán como leídos. En caso que no quieras marcarlos como leídos, realiza el GET con el parámetro mark_as_read = false y la consulta será: /messages/packs/pack_id/sellers/seller_id?mark_as_read=false.
Recuerda que el resto de recursos no marcarán los mensajes como leídos.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/$PACK_ID/sellers/$USER_ID?tag=post_sale

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?limit=2&offset=1?tag=post_sale

Respuesta:

{
   "paging":{
      "limit":10,
      "offset":0,
      "total":3
   },
   "conversation_status":{
        "path": "/packs/2000000089077943/seller/415458330",
        "status": "active",
        "substatus": null,
        "status_date": "2020-12-05T20:01:46.000Z",
        "status_update_allowed": false,
        "claim_id": null,
        "shipping_id": null
    },
   "messages":[
      {
         "id":"fd1d2e37ad004ede9e0bf25d1215002d",
         "site_id":"MLB",
         "client_id":123456789,
         "from":{
            "user_id": 123456789000,
         },
         "to":{
            "user_id": 2332423234,
         },
         "status":"available",
         "subject":null,
         "text":"Mensaje de test",
         "message_date":{
            "received":"2020-12-05T20:01:46.000Z",
            "available":"2020-12-05T20:01:46.000Z",
            "notified":"2020-12-05T20:01:46.000Z",
            "created":"2020-12-05T20:01:46.000Z",
            "read":null
         },
         "message_moderation":{
            "status":"clean",
            "reason":null,
            "source":"online",
            "moderation_date":"2020-12-05T20:01:46.000Z"
         },
         "message_attachments":null,
         "message_resources":[
            {
               "id":"000011122344",
               "name":"packs"
            },
            {
               "id":"475684066",
               "name":"sellers"
            }
         ],
         "conversation_first_message":false
      }
   ],
   "seller_max_message_length":350,
   "buyer_max_message_length":3500
}
Nota:
Al final de la respuesta puede ver la cantidad máxima de caracteres que puede enviar el vendedor (seller_max_message_length).

Errores

Status Error Mensaje
403 User access token invalid for resource {resource_id} Usuario sin acceso a la orden
400 The limit param must be greater than 0 El param “limit” del request debe ser mayor a 0
400 Invalid offset param Param “offset” inválido
400 Invalid limit param Param “limit” inválido

Obtener mensajes por ID

Para conocer los mensajes asociados a un pack, deberás hacer una consulta al recurso /messages. 

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/$MESSAGE_ID?tag=post_sale

Ejemplo de respuesta sin header:

{
  "message_id": "0033b582a1474fa98c02d229abcec43c",
  "date_received": "2016-09-01T05:15:25.821Z",
  "date": "2016-09-01T05:15:25.821Z",
  "date_available": "2016-09-01T05:15:25.821Z",
  "date_notified": "2016-09-01T05:17:42.945Z",
  "date_read": "2016-09-01T21:31:19.606Z",
  "from": {
    "user_id": 123456789,
  },
  "to": [
    
      "user_id": 123456780,    
  ],
  "subject": "Test Item subject",
  "text": {
    "plain": "Ejemplo de texto"
  },
  "attachments": [
    {}
  ],
  "attachments_validations": {
    "invalid_size": [
    ],
    "invalid_extension": [
    ],
    "forbidden": [
    ],
    "internal_error": [
    
  },
  "site_id": "MLA",
  "resource": "orders",
  "resource_id": "1234567871",
  "status": "available",
  "moderation": {
  	"status": "clean",
      "date_moderated": "2019-03-13T09:34:26.450-04:00",
      "source": "online"

  
}

Ejemplo de respuesta actualizada (con header):

{
	"paging": null,
	"conversation_status": null,
	"messages": [{
		"id": "fd1d2e37ad004ede9e0bf25d1215002d",
		"site_id": "MLB",
		"client_id": 123456789,
		"from": {
			"user_id": 123456789000
		},
		"to": {
			"user_id": 2332423234
		},
		"status": "available",
		"subject": null,
		"text": "Mensaje de test",
		"message_date": {
			"received": "2020-12-05T20:01:46.000Z",
			"available": "2020-12-05T20:01:46.000Z",
			"notified": "2020-12-05T20:01:46.000Z",
			"created": "2020-12-05T20:01:46.000Z",
			"read": null
		},
		"message_moderation": {
			"status": "clean",
			"reason": null,
			"source": "online",
			"moderation_date": "2020-12-05T20:01:46.000Z"
		},
		"message_attachments": null,
		"message_resources": [{
				"id": "000011122344",
				"name": "packs"
			},
			{
				"id": "475684066",
				"name": "sellers"
			}
		],
		"conversation_first_message": false
	}]
}

Errores

Status Error Mensaje
403 Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4 Usuario sin acceso a un determinado mensaje
400 The specified message id does not exists No existe el mensaje pedido
404 The message with id: a could not be retrieved from storage Mensaje no encontrada en el servidor, intentar nuevamente en algunos segundos
404 The message with id: a could not be retrieved from storage Mensaje no encontrado en el servidor. Intente nuevamente en unos segundos


Crear mensajes para un comprador

Para enviar un mensaje a tu comprador, tienes un límite de 350 caracteres y recuerda que permitimos aquellos caracteres incluidos en la norma ISO-8859-1 latin1 y los emoticones de esta lista.

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/$PACK_ID/sellers/$USER_ID?tag=post_sale

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'postman-token: 167b4f47-cb87-2b27-2a3c-cfb012df9314' \
  -H 'x-client-id: 8794217632667367' \
  -d 
{
	"from": {
		"user_id": "415458330",
	},
	"to": {
		"user_id": "415460047"
	},
	"text": "Test message ToUserId 2",
	"attachments": ["415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d.pdf"]
}
https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?tag=post_sale
Notas:
- El atributo attachments se obtiene de la respuesta del POST de attachments. Mira cómo cargar y guardar adjuntos.
- En caso de no necesitar adjuntar un archivo, debes eliminar la sección “attachments” del JSON. 
- Si necesitas insertar un enlace en el que se pueda hacer clic, puedes hacerlo utilizando la función href. Por ejemplo: "<a href="su_url"> Su link de seguimiento </a>".

Errores

Importante:
Ahora bloqueamos la mensajería en órdenes con estado cancelled de todas las categorías. En caso de tener una conversación abierta previo a la fecha mencionada, la mensajería estará disponible.
{
    "status_code": 403,
    "code": "forbidden",
    "message": "blocked_conversation_send_message_forbidden"
}
Status Error Mensaje
400 The text has character/s that is/are not supported. Cuando envías un caracter no admitido, por ejemplo: UTF-8.
400 The message content is too long, max characters allowed are 350 Mensaje excede el límite de 350 caracteres
403 You can not send the message because a mediation is in process Error por mensaje bloqueado. Este error solo aplica para Brasil.
403 You can not send the message because the purchase is Mercado Envíos Full and has not been yet delivered Error por envío gestionado por Fulfillment (Mercado Libre)
403 Access denied for user {from.user_id} to order {to.resource_id} El user “from” no tiene acceso a la orden
403 Receiver does not belong to order {to.resource_id} El receptor del mensaje no pertenece a la orden
400 The field 'to.user_id' is required Mensaje sin receptor (falta agregar “to”)
400 Invalid ‘to’ user id User id “to” inválido
400 Sender and received must not be equals El user “from” y “to” son iguales
400 The field 'to.email' must be a secure email Si el user_id es 0 y el email no es un secure_email
400 The field 'to.resource' is required No se encuentra el atributo “resource”
400 Invalid field 'to.resource' Atributo resource inválido
400 The field 'to.site_id' is required Request sin site_id
400 The field 'to.site_id' has an invalid value Atributo site_id inválido
400 A JSON body is required Post sin Json body
400 The field 'from' is required Mensaje sin ‘from’
400 Access token is required Request sin access token
400 Application id is required Access token sin application_id

Cargar y guardar adjuntos

Para adjuntar un archivo dentro del mensaje primero deberá ser guardado. Luego, cuando se envía un adjunto, se devuelve el id del archivo como respuesta.


Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/attachments?tag=post_sale&site_id=SITE_ID
Notas:
- El POST debe realizarse como form.data con key: value > file = referencia al file (es decir el archivo en sí).
- El archivo debe tener un tamaño máximo de 25 MB.
- Podrán intercambiarse fotos, manuales de instrucciones, facturas y demás archivos adjuntos en JPG, PNG, PDF y TXT de hasta 25 MB.

Ejemplo:

curl -X POST \
  'https://api.mercadolibre.com/messages/attachments?tag=post_sale&site_id=MLA
' \
  -H 'Authorization: Bearer $ACCESS_TOKEN'
  -H 'content-type: multipart/form-data;' \
  -F 'file=@/home/user/.../Adjunto.jpg'

En este caso el servidor responderá con un JSON que contendrá el id del archivo en caso que el request haya sido exitoso.

Nota:
La respuesta obtenida se deberá anexar en el mensaje deseado.

Respuesta:

{
  "id": "210438685_59f0f034-db1b-4ea6-8c5e-1d34e2092482.jpg"
}

Status Error Mensaje
500 File can not be saved, try it later Problemas al almacenar el archivo
400 File attached is empty Attachment vacío o nulo
400 File name cannot include characters like /, \ El nombre del archivo no puede tener caracteres como /, \
400 File attachment is bigger than 25 Mb. El tamaño del archivo excede los 25 Mb.
400 The message exceeds the allowed number of attachments: 25 El mensaje excede la cantidad permitida de adjuntos: 25
400 The queryparam 'site_id' is required Request sin el site_id

Obtener adjunto

Para obtener un mensaje adjunto se deberá hacer una llamada GET.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/attachments/$ATTCHMENT_ID?tag=post_sale&site_id=SITE_ID

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png?tag=post_sale&site_id=MLA

Respuesta:

Si el request es exitoso, la llamada devolverá el archivo solicitado. En caso de que no sea posible acceder al archivo la respuesta del servidor será la siguiente:

Status Error Mensaje
500 File can not be saved, try it later No se pudo obtener el archivo solicitado

Siguiente: Mensajes pendientes.