Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 07/10/2024

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.

Nota:
Quando consultar oa /messages/packs/pack_id/sellers/seller_id as mensagens serão marcadas como lidas. Caso você não queira marcá-los como lidos, execute o GET com o parâmetro mark_as_read = false e a consulta será: /messages/packs/pack_id/sellers/seller_id?mark_as_read = false.
Lembre-se de que o restante dos recursos não marcará as mensagens como lidas.
O rate limit deste recurso é de 500rpm.

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
}
Nota:
No final da resposta, você pode ver o número máximo de caracteres que o vendedor pode enviar (seller_max_message_length).

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. 

Nota:
O rate limit deste recurso é de 500rpm.

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"]
}'
Notas:
- O atributo attachments se obtém da resposta do POST de attachments. Veja como Carregar e salvar um anexo.
- Se não for preciso anexar um arquivo, a seção "attachments" deve ser eliminada do JSON.
- Caso necessite inserir um link clicável no texto, pode inserir usando a função href. Por exemplo: "<a href="sua_url"> Seu link de rastreio </a>".

Erros

Importante:
Agora bloqueamos a mensageria em ordens com status cancelled de todas as categorias. Caso tenha uma conversa em aberto anterior a mudança, as mensagens pós-venda estarão disponíveis.
{
    "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
Notas:
- O POST deve ser realizado como form.data com key: value > file = referência ao file (isto é, o próprio arquivo).
- O arquivo deve ter um tamanho máximo de 25 MB.
- Poderão ser trocadas fotos, manuais de instruções, notas fiscais e outros arquivos anexados em formato JPG, PNG, PDF e TXT de até 25 MB.

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.

Nota:
A resposta obtida deverá ser anexada na mensagem desejada.

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.