Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação
Motivos para comunicar
Consultar as opções de comunicação disponíveis
Com os recursos a seguir, os vendedores precisam escolher um motivo para iniciar a conversa com o comprador e terão uma série de mensagens disponíveis para enviar.
Templates disponíveis segundo país
O template é um texto pré-definido disponibilizado pelo Mercado Livre, que o vendedor não pode modificar.
Template de “REQUEST_VARIANTS”
Para MLA, MLM, MCO, MLC:
Para MLB:
Template de “REQUEST_BILLING_INFO”
Para MLA:
Para MLM:
Para MCO:
Para MLU:
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID?tag=post_sale
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/20000000000?tag=post_sale
Resposta:
{
"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":"DELIVERY_PROMISE",
"internal_description":"This is an example...",
"enabled":true,
"type":"TEMPLATE",
"templates":[
{
"id":"TEMPLATE___DELIVERY_PROMISE___1",
"texts":{
"mla":{
"html":"Hola,
Entregaremos tu compra %s entre las %d y las %d hs."
},
"mlb":{
"html":"Olá,
Entregaremos sua compra %s entre %d e %d h."
},
"mlc":{
"html":"Hola,
Entregaremos tu compra %s entre las %d y las %d hs."
},
"mco":{
"html":"Hola,
Entregaremos tu compra %s entre las %d y las %d hs."
},
"mlu":{
"html":"Hola,
Entregaremos tu compra %s entre las %d y las %d hs."
}
},
"vars":[
{
"id":"TEMPLATE___DELIVERY_PROMISE___1___VAR___INIT",
"type":"NUMBER"
},
{
"id":"TEMPLATE___DELIVERY_PROMISE___1___VAR___LIMIT",
"type":"NUMBER"
}
]
}
],
"actionable":true,
"char_limit":null,
"child_options":[
],
"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
}
]
}
}
Campos da resposta
char_limit: é o número máximo de caracteres aceitos na opção.
A opção REQUEST_VARIANTS está disponível apenas nos tipos de envio cross docking e drop off.
A opção de DELIVERY_PROMISE, só estará disponível para envios Flex.
Nas de tipo de template (REQUEST_VARIANTS e REQUEST_BILLING_INFO) temos o id do template, que deve ser usado no POST para envio da mensagem.
Consultar a quantidade disponível de mensagens pós-venda
Na da árvore de motivos, as categorias podem ter a opção de enviar uma mensagem ao comprador e você pode reconhecê-los com o campo cap_available:
- Se for 0 (zero), o vendedor não poderá enviar mensagens ao comprador
- Se for 1 (um) ou mais, indique a quantidade disponível para envio
Lembre-se que a mensagem terá caracteres limitados e manterá as moderações de uma mensagem normal (apenas para OTHER e SEND_INVOICE_LINK).
Caso o vendedor tenha consumido o limite de mensagens disponíveis para envio, se ele entrar novamente em uma seção de campo aberto (OTHER), a resposta retornará um erro de que não é mais possível fazê-lo, e ele deverá aguardar a resposta do comprador.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID/caps_available?tag=post_sale
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/200000000000/caps_available?tag=post_sale
Resposta:
[
{
"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":"DELIVERY_PROMISE",
"cap_available":1
},
{
"option_id":"OTHER",
"cap_available":1
}
]
Enviar mensagem segundo a opção
Após procurar as opções disponíveis para o pack_id, você deve enviar a mensagem como o seguinte POST. Lembre-se de que, após a resposta do comprador, as seguintes mensagens devem ser enviadas diretamente com o post /messages.
Conheça os option_id disponibilizados pelos sites:
Sitio / Option_id | “REQUEST_VARIANTS”: Solicitar dados de variações |
“REQUEST_BILLING_INFO”: Solicitar informações de faturamento |
“SEND_INVOICE_LINK”: Enviar link para faturamento |
“OTHER”: Outros, campo livre |
“DELIVERY_PROMISE”: Informar promessa de entrega |
---|---|---|---|---|---|
MLA | |||||
MLB | |||||
MLM | |||||
MCO | |||||
MLC | |||||
MLU |
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID/option?tag=post_sale -H 'Content-Type: application/json'
{
"option_id": $OPTION_ID,
"template_id": $TEMPLATE_ID
}
Exemplo com REQUEST_BILLING_INFO (Tipo template):
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000000/option -H 'Content-Type: application/json'
{
"option_id": "REQUEST_BILLING_INFO",
"template_id": "TEMPLATE___REQUEST_BILLING_INFO___1"
}
Resposta de mensagem enviada:
{
"id": "94353d192b9640e8b1ed3c77aa406f39",
"to": {
"user_id": 618491100,
"name": "Test Test"
},
"status": "available",
"text": "Este es un template para solicitar datos de facturación: ",
"message_date": {
"received": "2020-09-09T19:07:24.890Z",
"available": "2020-09-09T19:07:25.056Z",
"notified": null,
"created": "2020-09-09T19:07:24.890Z",
"read": null
},
"message_moderation": {
"status": "clean",
"reason": null,
"source": "online",
"moderation_date": "2020-09-09T19:07:25.056Z"
}
}
Exemplo com OTHER (Tipo texto livre):
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000000/option -H 'Content-Type: application/json' \
{
"option_id": "OTHER",
"text": "Cómo estás María, estaría necesitando de..."
}
Resposta de mensagem enviada corretamente:
{
"id": "94353d192b9640e8b1ed3c77aa406f39",
"to": {
"user_id": 618491100,
"name": "Test Test"
},
"status": "available",
"text": "Cómo estás María, estaría necesitando de...",
"message_date": {
"received": "2020-09-09T19:07:24.890Z",
"available": "2020-09-09T19:07:25.056Z",
"notified": null,
"created": "2020-09-09T19:07:24.890Z",
"read": null
},
"message_moderation": {
"status": "clean",
"reason": null,
"source": "online",
"moderation_date": "2020-09-09T19:07:25.056Z"
}
}
Resposta de mensagem moderada:
{
"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"
}
}
Campos da resposta
status: status da mensagem. Por exemplo: available o moderated
message_moderation:
status: status de moderação de mensagem.
reason: razão para moderação. Por exemplo: out_of_place_language moderação para linguagem imprópria.
Exemplo com DELIVERY_PROMISE:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000000/option -H 'Content-Type: application/json' \
{
"option_id": "DELIVERY_PROMISE",
"template_id": "TEMPLATE___DELIVERY_PROMISE___1",
"vars": [{
"id": "TEMPLATE___DELIVERY_PROMISE___1___VAR___INIT",
"value": 12
},
{
"id": "TEMPLATE___DELIVERY_PROMISE___1___VAR___LIMIT",
"value": 23
}]
}
}
No caso de promessas de entrega que já tenham vencido o prazo, não será permitido enviar a mensagem e receberá o erro:
{
"status_code": 500,
"message": "delivery date is before than today"
}
Resposta de mensagem:
{
"id": "374c945ce97446f5b4a73123adfasdd0e1ed17f",
"status": "available",
"text": "Entregaremos tu compra {hoy/mañana/el próximo día hábil} entre las {initial} y las {final} hs.",
"to": {
"user_id": 667304586,
"name": "Test Test"
},
"message_date": {
"received": "2021-01-11T18:06:46.070Z",
"available": "2021-01-11T18:06:46.450Z",
"notified": null,
"created": "2021-01-11T18:06:46.070Z",
"read": null
},
"message_moderation": {
"status": "clean",
"reason": null,
"source": "online",
"moderation_date": "2021-01-11T18:06:46.450Z"
}
}
Erros
Como um caso excepcional
Temos a seguinte exceção:
- Produtos com tempo de conclusão (manufacturing time)
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000012
Resposta:
{
"cause": "blocked_by_excepted_case",
"error": "bad_request",
"message": "This pack belongs to an excepted case, it is requested to use the messaging resource.",
"status_code": 400
}
Assim, o vendedor pode usar mensagens pós-venda sem restrições.
Status (erro) | Mensagem | Detalhe |
---|---|---|
400 - limit_exceeded | The text is invalid | Por exceder o limite de 350 caracteres (option OTHER e SEND_INVOICE_LINK) |
403 - bad_request | You are not allowed to execute the option OTHER again | Quantidade (cap) não disponível | 403 - forbidden | This package has the conversation blocked, please check blocked messages | Existe uma conversa aberta e deve ser utilizado o recurso de /messages |
404 - not_found | The option selected is not valid | Option_id inválido |
409 - conflict | There is another request locking this operation | Esse erro ocorre porque o vendedor executa várias opções simultâneas sobre a mesma venda e, para evitar que sejam feitos mais caps do que os disponíveis, criamos um "Lock" do serviço no vendedor e na venda, que é liberado ao finalizar a opção. |
403 - forbidden | The conversation is blocked | Pack_id com mensageria bloqueada |
403 - forbidden | You are not allowed to access the information of the pack $PACK_ID | O vendedor não está autorizado a consultar as informações desse pack id |
400 - bad_request | The template $TEMPLATE_ID is invalid | Template_id incorreto |
400 - bad_request | The promise of delivery of the shipping contained in the pack is from a date before today. | Data inválida / expirada para a promessa de entrega. |
500 - internal_server_error | Internal server error | Erro interno |
Seguinte: Gestão de mensagem.