Gestão de mensagens pós-venda

→Parâmetros
→Obter mensagens por order
→Obter mensagens de um pacote
→Obter mensagens por ID
→Criar mensagens para o comprador
→Carregar e salvar anexo
→Obter anexo
→Erros


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.
email: Email do usuário que enviou a mensagem (secure email da ordem).
name: Nome do usuário que enviou a mensagem.
to: Quem recebe a mensagem.
user_id: ID do usuário que recebeu a mensagem.
email: Email do usuário que recebeu a mensagem (secure email da ordem).
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.
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) ou links de mercado pago (LINK_MERCADOPAGO).


Obter mensagens por order

Importante:
Para MLA e MLC, utilize a funcionalidade consultar mensagens por pack.

Para obter as mensagens de um determinado pedido, você terá que fazer uma consulta associando o order_id:

Chamada:

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

Exemplo:

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

Resposta:


{
    "paging": {
        "limit": 10,
        "offset": 0,
        "threshold": 1000,
        "total": 1
    },
    "results": [
        {
            "message_id": "d13a11809dac44d497d829e9bbbc78ae",
            "date_received": "2019-07-04T20:50:02.124Z",
            "date": "2019-07-04T20:50:02.124Z",
            "date_available": "2019-07-04T20:50:02.124Z",
            "date_notified": "2019-07-04T20:51:33.471Z",
            "date_read": null,
            "from": {
                "user_id": "419059118",
                "email": "ttest.hpz2z6q+2-ogiydkmzvg43tmobs@mail.mercadolivre.com",
                "name": "Test"
            },
            "to": [
                {
                    "user_id": "419067349",
                    "email": "ttest.6hqmq6+2-ogiydkmzvg43tmobx@mail.mercadolivre.com"
                }
            ],
            "subject": "Produto Teste - Não Ofertar",
            "text": {
                "plain": "Olá, tudo bem?"
            },
            "attachments": [],
            "attachments_validations": {
                "invalid_size": [],
                "invalid_extension": [],
                "forbidden": [],
                "internal_error": []
            },
            "site_id": "MLB",
            "resource": "orders",
            "resource_id": "2053577644",
            "status": "available",
            "moderation": {
                "status": "clean",
                "date_moderated": "2019-07-04T20:50:02.177Z",
                "source": "online"
            },
            "conversation_first_message": true
        }
    ],
    "conversation": {
        "status": "active",
        "status_date": null,
        "substatus": null,
        "is_blocking_allowed": false
    }
}

Obter mensageems de un pacote

Para obter as mensagens de um pacote em particular, você deverá fazer uma consulta associando o pack_id e o user_id, relacionados ao vendedor do pacote, com o recurso /messages.
Para conhecer o pack_id, você deverá obter o campo "pack_id" na resposta de /orders/<order_id>

Caso o pack_id contenha um valor null, o order_id deverá ser tomado por default, mantendo o recurso /packs na chamada da API.

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.

Importante:
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.

Chamada:

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

Exemplo:

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

Resposta:

{
   "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",
            "email":"test@test.com.br",
            "name":"User Test"
         },
         "to":{
            "user_id":"2332423234",
            "email":"juliotest@test.com",
            "name":"Julio Test"
         },
         "status":"available",
         "subject":null,
         "text":"Mensagem 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
}
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:
Lembre de incluir na chamada o header "X-Pack-Format": true para obter a resposta atualizada. Se você não enviar, continuará recebendo a resposta antiga baseada na ordem. 

Chamada:

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

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",
    "email": "userfrom.n4tx9d+2-ogeytenjqgi3tomjw@mail.mercadolibre.com",
    "name": "User from"
  },
  "to": [
    
      "user_id": "123456780",
      "email": "userto.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com"
    
  ],
  "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 com header:

{
    "paging": null,
    "conversation_status": null,
    "messages": [
        
            "id": "2c9380846a6fc814016a6fd38fe00007",
            "site_id": "MLA",
            "client_id": 1,
            "from": {
                "user_id": "391302538",
                "email": "fernanda.giustozzi+391302538@mercadolibre.com",
                "name": "Test Test"
            },
            "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"
}

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ê deve adicionar o user_id e o e-mail do vendedor no “form” da mensagem. Além disso, lembre-se de que você tem um limite de 350 caracteres.


Recorda que os caracteres aceitos são de acordo com a norma ISO-8859-1 latin1.



Chamada:

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

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?application_id=$APPLICATION_ID
  -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",
"email" : "test"
},
"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:
A partir de 17 de dezembro de 2020, apenas para Mercado Livre Brasil vamos aplicar o seguinte bloqueio para os pedidos com status canceled da categoria Consumer Eletronics.
{
    "message": "blocked_conversation_send_message_forbidden",
    "error": "conversation_blocked",
    "status": 403,
    "cause": "blocked_by_cancelled_order"
}
Status Erro Mensagem
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
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' \
  -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

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png

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.

ou registre-se para receber as últimas notícias sobre nossa API