Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.![circulos azuis em degrade](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevImgs/230801158836-ImgMS--1-.png)
Documentação do
Gestão de mensagens
Parâmetros
message_id: Id de mensagem.
date_created: Data de criação.
date: Data em que a mensagem é salva.
date_received: Data de recepção da mensagem.
date_available: Data em que a mensagem passou por moderação.
date_notified: Data em que a contraparte foi notificada da mensagem.
date_read: Data em que a contraparte leu a mensagem.
from: Quem envia a mensagem.
user_id: ID do usuário que enviou a mensagem.
to: Quem recebe a mensagem.
user_id: ID do usuário que recebeu a mensagem.
subject: Assunto do email.
text: Texto da mensagem.
plain: Texto plano da mensagem.
attachments: Anexos.
attachments_validations: Validações de anexos.
invalid_size: Tamanho de anexo inválido.
invalid_extension: Extensão de anexo inválida.
internal_error: Erro interno.
site_id: Site do Mercado Livre (MLA, MLB, etc.).
message_resources: Contém uma lista com IDs relacionados à mensagem, descrevendo a que recurso cada um pertence.
:resource: Relativo à ordem a que pertence (orders).
resource_id: ID da ordem.
status: Status da mensagem (available - moderated - rejected - pending_translation).
moderation_status: Status de moderação da mensagem.
moderation.status: Resultado do processo de moderação.
- clean
- rejected
- pending: para casos em que a moderação estiver em processo.
- non_moderated: para casos antigos nos quais a moderação não foi aplicável.
moderation.date_moderated Data em que a informação de moderação impactou.
moderation.source Modalidade da moderação.
moderation.reason Motivo pelo qual a mensagem foi moderada. Atualmente, esta moderação pode ser por causa de linguagem inapropriada (OUT_OF_PLACE_LANGUAGE), por link de redes sociais (SOCIAL_NETWORK_LINK), links encurtados (LINK_SHORT_URL), por ser uma mensagem automática do integrador (AUTOMATIC_MESSAGE), por informações pessoais (PERSONAL_DATA), links de mercado pago (LINK_MERCADOPAGO), links de meios de pagamento externos (ML_LINKS_PAYPAL) ou por mensagens que buscam evadir de uma reclamação (EVASION_CLAIM_SELLER).
Obter mensagens de um pacote
Para conhecer o pack_id, você deverá obter-lo na resposta de /orders/$ORDER_ID. Caso o pack_id seja null, o order_id deverá ser tomado por default, mantendo o recurso /packs. As mensagens enviadas pelos compradores, que forem moderadas, não estarão visíveis. Por outro lado, as mensagens do vendedor, ainda que moderadas, estarão visíveis.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/$PACK_ID/sellers/$USER_ID?tag=post_sale
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?limit=2&offset=1?tag=post_sale
Resposta:
{
"paging": null,
"conversation_status": null,
"messages": [{
"id": "bbc07e1dab2443959cc723a01a1381d4",
"site_id": "MLB",
"client_id": 7158647239075991,
"from": {
"user_id": 688297726
},
"to": {
"user_id": 481239105
},
"status": "available",
"subject": null,
"text": "Hola comprador!",
"message_date": {
"received": "2020-12-22T13:47:35.000Z",
"available": "2020-12-22T13:47:35.000Z",
"notified": "2020-12-22T13:47:36.000Z",
"created": "2020-12-22T13:47:35.000Z",
"read": null
},
"message_moderation": {
"status": "clean",
"reason": null,
"source": "online",
"moderation_date": "2020-12-22T13:47:35.000Z"
},
"message_attachments": null,
"message_resources": [{
"id": "4237726634",
"name": "packs"
},
{
"id": "688297726",
"name": "sellers"
}
],
"conversation_first_message": false
}],
"seller_max_message_length": 0,
"buyer_max_message_length": 0
}
Erros
Status | Error | Mensagem |
---|---|---|
403 | User access token invalid for resource {resource_id} | Usuário sem acesso à ordem |
400 | The limit param must be greater than 0 | O param “limit” do request deve ser maior ao 0 |
400 | Invalid offset param | Param “offset” inválido |
400 | Invalid limit param | Param “limit” inválido |
Obter mensagens por ID
Para conhecer as mensagens associadas a um pack, você deverá fazer uma consulta ao recurso /messages.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/$MESSAGE_ID?tag=post_sale
Exemplo de resposta sem 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"
}
Exemplo de resposta atualizada (com 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 | Mensagem |
---|---|---|
403 | Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4 | Usuário sem acesso a uma determinada mensagem |
400 | The specified message id does not exists | A mensagem solicitada não existe |
404 | The message with id: a could not be retrieved from storage | Mensagem não encontrada no servidor, tente novamente em alguns segundos |
404 | The message with id: a could not be retrieved from storage | Mensagem não encontrada no servidor. Tente novamente em alguns segundos |
Criar mensagens para um comprador
Para enviar uma mensagem ao seu comprador, você tem um limite de 350 caracteres e lembre-se de que aceitamos os caracteres da norma ISO-8859-1 latin1 e os emoticones dessa listagem.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/$PACK_ID/sellers/$USER_ID?tag=post_sale
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?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"]
}'
Erros
{
"status_code": 403,
"code": "forbidden",
"message": "blocked_conversation_send_message_forbidden"
}
Status | Erro | Mensagem |
---|---|---|
400 | The text has character/s that is/are not supported. | Quando você envia um caracter não admitido, por exemplo: UTF-8. |
400 | The message content is too long, max characters allowed are 350 | A mensagem excede o limite de 350 caracteres |
403 | You can not send the message because a mediation is in process | Erro de mensagem bloqueada. Este erro aplica apenas ao Brasil. |
403 | You can not send the message because the purchase is Mercado Envíos Full and has not been yet delivered | Erro de envio gerenciado pelo Fulfillment (Mercado Livre) |
403 | Access denied for user {from.user_id} to order {to.resource_id} | O user “from” não tem acesso ao pedido |
403 | Receiver does not belong to order {to.resource_id} | O destinatário da mensagem não pertence ao pedido |
400 | The field 'to.user_id' is required | Mensagem sem receptor (é necessário adicionar "to") |
400 | Invalid ‘to’ user id | User id “to” inválido |
400 | Sender and received must not be equals | O user “from” e “to” são iguais |
400 | The field 'to.email' must be a secure email | Se o user_id for 0 e o e-mail não for um secure_email |
400 | The field 'to.resource' is required | O atributo "recurso" não pode ser encontrado |
400 | Invalid field 'to.resource' | Atributo resource inválido |
400 | The field 'to.site_id' is required | Request sem site_id |
400 | The field 'to.site_id' has an invalid value | Atributo site_id inválido |
400 | A JSON body is required | Post sen Json body |
400 | The field 'from' is required | Mensagem sem ‘from’ |
400 | Access token is required | Request sem access token |
400 | Application id is required | Access token sem application_id |
Carregar e salvar um anexo
Para anexar um arquivo na mensagem, deverá ser, primeiramente, salvo. Depois, quando um anexo é enviado, a id do anexo é retornada como resposta.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/attachments?tag=post_sale&site_id=SITE_ID
Exemplo:
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.
Resposta:
{
"id": "210438685_59f0f034-db1b-4ea6-8c5e-1d34e2092482.jpg"
}
Status | Erro | Mensagem |
---|---|---|
500 | File can not be saved, try it later | Problemas ao armazenar o arquivo |
400 | File attached is empty | Attachment vazio ou nulo |
400 | File name cannot include characters like /, \ | O nome do arquivo não pode ter caracteres como /, \ |
400 | File attachment is bigger than 25 Mb. | O tamanho do arquivo excede 25 Mb. |
400 | The message exceeds the allowed number of attachments: 25 | A mensagem excede o número permitido de anexos: 25 |
400 | The queryparam 'site_id' is required | Request sem o site_id |
Obter anexo
Para obter um anexo deverá realizar uma chamada GET.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/attachments/$ATTCHMENT_ID?tag=post_sale&site_id=SITE_ID
Exemplo:
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
Resposta:
Se o request for bem-sucedido, a chamada retornará o arquivo solicitado. Caso não seja possível acessar o arquivo, a resposta do servidor será a seguinte:
Erros
Status | Erro | Mensagem |
---|---|---|
500 | File can not be saved, try it later | Não foi possível obter o arquivo solicitado |
Siguiente: Mensagens pendentes.