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

Message management

Importante:
Important: The query resources (GET) share a rate limit of 500 rpm,and the write resources (POST/PUT) also share a rate limit of 500 rpm among themselves.

Parameters

message_id: Message id.
date_created: Date of creation.
date: Date a message is saved.
date_received: Date a message is received.
date_available:Date a message went through moderation.
date_notified: Date a message was notified to counterparty.
date_read: Date a message was read by counterparty.
from: A message sender.
user_id: Id of user who sent message.
to: A message recipient.
user_id: Id of user who received message.
subject: Email subject.
text: Message text.
plain: Message plain text.
attachments: Attached files.
attachments_validations: Attachment validation.
invalid_size: If attachment size is invalid.
invalid_extension: Invalid attachment extension.
internal_error: Internal error.
site_id: Mercado Libre (MLA, MLB, etc.) site.
resource: Corresponding to order it pertains to (orders).
resource_id: Order ID.
status: Message status.
moderation_status: Message moderation status

  • clean
  • rejected
  • pending: for cases that moderation is in process.
  • non_moderated: for old cases that moderation not apply moderation.

moderation.date_moderated: Date the moderation information impacted.

moderation.source Moderation mode.

moderation.reason Reason why the message was moderated. Currently, this moderation can be for inappropriate language (OUT_OF_PLACE_LANGUAGE), for social network links (SOCIAL_NETWORK_LINK), for shortened links (LINK_SHORT_URL), for being an automatic message from integrator (AUTOMATIC_MESSAGE), for personal information (PERSONAL_DATA), Mercado Pago links (LINK_MERCADOPAGO), external payment media links (ML_LINKS_PAYPAL) or for evasion of the claim (EVASION_CLAIM_SELLER).

Get messages by pack

To know the pack_id, you must obtain the “pack_id” field in the response of /orders /$ORDER_ID. If the pack id contains a null value, must take the order id by default, keeping the resource /packs in the API request.

The messages moderated by the counterpart will not be visible and the messages themselves will be visible.

Note:
When request /messages/packs/pack_id/sellers/seller_id the messages will be marked as read. In case you don't want to mark them as read, perform the GET with the mark_as_read = false parameter and the query will be: /messages/packs/pack_id/sellers/seller_id?mark_as_read=false.
Remember that the rest of the resources will not mark the messages as read.

Request:

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

Example:

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

Response;


{
   "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
}
Note:
At the response end, you can see the maximum number of characters that the seller can send (seller_max_message_length).

Errors

Status Error Message
403 User access token invalid for resource {resource_id} User without access to order
400 The limit param must be greater than 0 The “limit” request param must be greater than 0
400 Invalid offset param Invalid “Offset” param
400 Invalid limit param Invalid “limit” param

Get messages by ID

To know the messages associated with a pack, you must make a query to the resource /messages.

Request:

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

Response example without 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"

  
}

Updated response example with header:

{
    "paging": null,
    "conversation_status": null,
    "messages": [
        
            "id": "2c9380846a6fc814016a6fd38fe00007",
            "site_id": "MLA",
            "client_id": 1,
            "from": {
                "user_id": 391302538,
            },
            "status": "available",
            "text": "newMessage",
            "message_date": {
                "received": "2019-04-30T19:58:17.000Z",
                "available": "2019-04-30T19:58:17.000Z",
                "notified": null,
                "created": "2019-04-30T19:58:17.000Z",
                "read": "2019-04-30T20:24:48.000Z"
            },
            "message_moderation": {
                "status": "clean",
                "reason": null,
                "source": "online",
                "moderation_date": "2019-04-30T19:58:17.000Z"
            },
            "message_attachments": [
                
                    "filename": "391302538_b6498e76-5af0-4206-aaeb-2aa6e754263e.jpg",
                    "original_filename": "319176.jpg",
                    "type": "image/jpeg",
                    "size": 661635,
                    "potential_security_threat": false,
                    "creation_date": "2019-04-30T19:58:17.000Z"
                
            ],
            "message_resources": [
                
                    "id": "2000000094354573",
                    "name": "packs"
                },
                
                    "id": "391302235",
                    "name": "sellers"
}

Errors

Status Error Message
403 Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4 User without access to a certain message
400 The specified message id does not exists The specified message does not exist
404 The message with id: a could not be retrieved from storage The message with id: a could not be retrieved from storage. Try again in a few seconds.


Create message for a buyer

To send a message to your buyer, you have the 350 characters limit and remember that we accept those characters included in the ISO-8859-1 latin1 standard and the emoticons from this list.

Request:

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

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330"&application_id=$APPLICATION_ID?tag=post_sale
  -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"]
}'
Notes:
- The attachments attribute is obtained from the attachment POST response. Learn more how upload and save attachment.
- If you don't need to attach a file, you can remove the "attachments" section in the JSON.
- If you need to insert a link that can be clicked, you can do so using the href function. For example: "<a href="your_url"> Your tracking link </a>".

Errors

Important:
We block messaging on canceled status orders of all categories. Only if there is a conversation prior to the change, the messaging will be unblocked for the seller within 30 days of the buyer's message.
{
    "message": "blocked_conversation_send_message_forbidden",
    "error": "conversation_blocked",
    "status": 403,
    "cause": "blocked_by_cancelled_order"
}
Status Error Message
400 The text has character/s that is/are not supported. The message content is too long, max characters allowed are 350
400 The message content is too long, max characters allowed are 350 When you send an unsupported character, for example: UTF-8.
403 You can not send the message because a mediation is in process Blocked message error. This error only applies to Brazil.
403 You can not send the message because the purchase is Mercado Envíos Full and has not been yet delivered Shipping error managed by Fulfillment (Mercado Libre)
403 Access denied for user {from.user_id} to order {to.resource_id} The user “from” doesn´t have access to the order
403 Receiver does not belong to order {to.resource_id} The recipient of the message does not belong to the order
400 The field 'to.user_id' is required Message without receiver (need to add "to")
400 Invalid ‘to’ user id Invalid “to” user id
400 Sender and received must not be equals The user “from” and “to” are equal
400 The field 'to.email' must be a secure email If the user_id is 0 and the email not be a secure_email
400 The field 'to.resource' is required The field 'to.resource' is required
400 Invalid field 'to.resource' Invalid resource attribute
400 The field 'to.site_id' is required Request without site_id
400 The field 'to.site_id' has an invalid value Invalid ite_id attribute
400 A JSON body is required Post without Json body
400 The field 'from' is required Message without ‘from’
400 Access token is required Request without access token
400 Application id is required Access token without application_id

Upload and save messages

To attach a file in the message, you need to save it first. Then, when the attachment is sent, the file id is returned as response.
Request:

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/attachments?tag=post_sale&site_id=SITE_ID
Notes:
- The POST needs to be made form.data with key: value > file = reference to file (that is, the file itself).
- The file needs to have a maximum 25 MB size.
- You can exchange pictures, instruction manuals, invoices, and any other attachments of up to 25 MB in JPG, PNG, PDF and TXT format.

Example:

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'

In this case, the server will respond with a JSON containing file id in case of a successful request.

Note:
The response obtained should be attached to the intended message.

Response;

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

Status Error Message
500 File can not be saved, try it later Problemas al almacenar el archivo
400 File attached is empty Empty or null attachment
400 File name cannot include characters like /, \ File name cannot include characters like /, \
400 File attachment is bigger than 25 Mb. File attachment is bigger than 25 Mb.
400 The message exceeds the allowed number of attachments: 25 The message exceeds the allowed number of attachments: 25
400 The queryparam 'site_id' is required Request without site_id

Get attachment

To get an attached message, you need to make a GET.
Request:

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

Example:

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

Response;

If the request is successful, the call will return the requested file. In case the file cannot be accessed, the server response will be the following:

Error

Status Error Message
500 File can not be saved, try it later File can not be saved, try it later

Next: Pending messages.