Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 21/12/2022

Reasons to communicate

To initiate post-sale messages with Mercado Envíos 2 (Fulfillment, Cross docking and Drop off ) you must update your integration and the seller should choose a reason to communicate (action guide). Otherwise, you will receive the error blocked_by_conversation_started_by_seller. With the following resources, sellers have to choose a reason to start the conversation with the buyer and will have a number of messages available to send.


Available templates according the site

The template is a predefined text made available by Mercado Libre, which the seller cannot modify.


“REQUEST_VARIANTS” template

In english:

Hello, If you need to specify something about the option of the product you bought, please tell me now so I can prepare it before sending it. Thank you

For MLM, MCO and MLC:

Hola, Si necesitas especificar algo sobre la opción del producto que compraste, por favor indícamelo ahora así puedo prepararlo antes de enviarlo. Gracias

For MLB:

Olá, Se você precisa especificar algo sobre a opção do produto que comprou, por exemplo, a cor, por favor, informe agora e assim podemos prepará-lo antes do envio. Obrigado.


“REQUEST_BILLING_INFO” template

In english:

Hello,To attach the invoice for your purchase I need the following information: - Name and surname - RFC - Address - Postal code

For MLM:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • RFC
  • Domicilio
  • Código postal

For MCO:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • Tipo y número de documento
  • Email
  • Domicilio
  • Código postal
  • Código de municipio
  • Código de departamento

Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/action_guide/packs/20000000000

Response:

{
   "options":[
      {
         "id":"REQUEST_VARIANTS",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"template",
         "templates":[
            {
               "id":"TEMPLATE___REQUEST_VARIANTS___1",
               "vars":null
            }
         ],
         "actionable":true,
         "child_options":null,
         "cap_available":1
      },
      {
         "id":"REQUEST_BILLING_INFO",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"template",
         "templates":[
            {
               "id":"TEMPLATE___REQUEST_BILLING_INFO___1",
               "vars":null
            }
         ],
         "actionable":true,
         "child_options":null,
         "cap_available":1
      },
      {
         "id":"SEND_INVOICE_LINK",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"free_text",
         "templates":null,
         "actionable":true,
         "char_limit":350,
         "child_options":null,
         "cap_available":1
      },
      {
         "id":"OTHER",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"free_text",
         "templates":null,
         "actionable":true,
         "char_limit":350,
         "child_options":null,
         "cap_available":1
      }
   ]
}

Response fields

char_limit: is the maximum number of characters accepted in the option ( "OTHER" o "SEND_INVOICE_LINK").
The REQUEST_VARIANTS option is only available in the Cross docking and Drop off shipment types.
Within the template type options (REQUEST_VARIANTS and REQUEST_BILLING_INFO) we have the template id, which must be used in the POST to send the message.


Check number of available messages

Within the reasons tree, the categories can have the option of sending a message to the buyer and you can recognize them with the cap_available field:

  • If it is 0 (zero), the seller will not be able to send messages to the buyer
  • If it is 1 (one) or more, indicate the quantity available to ship.

Remember that the message will have limited characters and will keep the moderations of a normal message (only for OTHER and SEND_INVOICE_LINK).
In the event that the vendor has consumed the cap of messages available to send, if he re-enters an open field section (OTHER), the response will return an error that it is no longer possible to do so, and he must wait for the buyer reply.


Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/action_guide/packs/200000000000/caps_available

Response:

[
   {
      "option_id":"REQUEST_VARIANTS",
      "cap_available":1
   },
   {
      "option_id":"REQUEST_BILLING_INFO",
      "cap_available":1
   },
   {
      "option_id":"SEND_INVOICE_LINK",
      "cap_available":1
   },
   {
      "option_id":"OTHER",
      "cap_available":1
   }
]

Send message according to option_id

After looking for the available options for the pack_id, you should send the message as the following POST. Remember that, after the buyer responds, the following messages must be sent directly through the post /messages.
The option_id available to are:

  • “REQUEST_VARIANTS”: Request variant data
  • “REQUEST_BILLING_INFO”: Request billing information
  • “SEND_INVOICE_LINK”: Send link for billing
  • “OTHER”: Others, free field

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/action_guide/packs/$PACK_ID/option
{
    "option_id": $OPTION_ID,
    "template_id": $TEMPLATE_ID
}

Example with REQUEST_BILLING_INFO (template type):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/action_guide/packs/2000000000000000/option
{
    "option_id": "REQUEST_BILLING_INFO",
    "template_id": "TEMPLATE___REQUEST_BILLING_INFO___CBT"
}

Message sent response:

{
   "id": "428ec614c7b84f72856c8514a235add6",
   "to": {
       "user_id": 667304586,
       "name": "Test Test"
   },
   "status": "available",
   "text": "Hello,
To attach the invoice for your purchase I need the following information:
- Name and surname
- RFC
- Address
- Postal code",
   "message_date": {
       "received": "2021-01-15T20:45:13.338Z",
       "available": "2021-01-15T20:45:13.367Z",
       "notified": null,
       "created": "2021-01-15T20:45:13.338Z",
       "read": null
   },
   "message_moderation": {
       "status": "clean",
       "reason": null,
       "source": "online",
       "moderation_date": "2021-01-15T20:45:13.367Z"
   }
}
Note:
The text field has the submitted content corresponding to the template.

Example with OTHER (Free text type):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/messages/action_guide/packs/2000000000000000/option
{
    "option_id": "OTHER",
    "text": "text in english",
    "text_translated": "texto en español o portugues" 
}

Response of message sent successfully:

{
   "id": "13c9d7814de4469296acee84103fd741",
   "to": {
       "user_id": 667304586,
       "name": "Test Test"
   },
   "status": "available",
   "text": "text in english",
   "message_date": {
       "received": "2021-01-15T20:39:38.054Z",
       "available": "2021-01-15T20:39:38.089Z",
       "notified": null,
       "created": "2021-01-15T20:39:38.054Z",
       "read": null
   },
   "message_moderation": {
       "status": "clean",
       "reason": null,
       "source": "online",
       "moderation_date": "2021-01-15T20:39:38.089Z"
   }
}
Note:
The text field has the content sent in the request body.

Moderate message response:

{
    "id": "94353d192b9640e8b1ed3c77aa406f39",
    "to": {
        "user_id": 618491100,
        "name": "Test Test"
    },
    "status": "moderated",
    "text": "Cómo estás María, estaría necesitando de...",
    "message_date": {
        "received": "2020-09-09T19:02:11.438Z",
        "available": null,
        "notified": null,
        "created": "2020-09-09T19:02:11.438Z",
        "read": null
    },
    "message_moderation": {
        "status": "rejected",
        "reason": "out_of_place_language",
        "source": "online",
        "moderation_date": "2020-09-09T19:02:11.697Z"
    }
}

Response fields

status: message status. For example: available or moderated
message_moderation:
status: moderation status of the message.
reason: moderation status. For example: out_of_place_language moderation for inappropriate language.



Errors

As an excepted case

- Manufacturing time products

Example:

Soon

Response:

Soon

The seller may use after-sales messaging without restrictions.


Status (error) Message Detail
400 - bad_request The text is invalid For exceeding the 350 character limit (option OTHER and SEND_INVOICE_LINK)
403 - limit_exceeded You are not allowed to execute the option OTHER again Quantity (cap) not available
403 - forbidden This package has the conversation blocked, please check blocked messages You have an open conversation, you must use the /messages resource
404 - not_found The option selected is not valid Option_id invalid
409 - conflict There is another request locking this operation This error occurs because the seller executes several simultaneous options on the same sale and, to prevent more caps from being made than available, we create a "Lock" of the service on the seller and the sale, which is released when the option is finished.
403 - forbidden The conversation is blocked Pack_id with blocked messages
403 - forbidden You are not allowed to access the information of the pack $PACK_ID Seller is not authorized to consult the information of that pack id
400 - bad_request The template $TEMPLATE_ID is invalid Template_id invalid
500 - internal_server_error Internal server error Internal error

Next: Post-sale messages management.