Mensagens de pós venda

O recurso da API do sistema de mensagens vai permitir que você obtenha mensagens de um pacote em particular (tanto se este contém uma ou várias ordens), crie novas mensagens no sistema e envie ou receba arquivos em anexo. Vamos ver como usá-la!


Conteúdos

Descrição de 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_availableData 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) ou por link de redes sociais (SOCIAL_NETWORK_LINK) ou por links encurtados (LINK_SHORT_URL).


Quais encurtadores de URL vamos moderar?

-Bitly

-Bl.ink

-Polr

-Rebrandly

-T2M

-TinyURL

-URL Shortener by Zapier

-Yourls

Obter mensagens por order

Para obter as mensagens de uma order em particular, você deverá fazer uma consulta utilizando o order_id:

Importante: Para MLA e MLC não deve mais usar este recurso, uma vez que já está disponível a funcionalidade de mensagens por carrinho de compra (pack).

Chamada:

curl -X GET https://api.mercadolibre.com/messages/orders/order_id?access_token=$ACCESS_TOKEN”

Exemplo:

curl -X GET https://api.mercadolibre.com/messages/orders/2053577644?access_token=$ACCESS_TOKEN”

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 mensagens de um 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: esta nova maneira de trabalhar entrará em produção em datas diferentes dependendo do país e terá um mês de retrocompatibilidade a partir da data de início correspondente:

Mercado Livre Chile: em produção desde 10 de julho.

Mercado Livre Argentina: em produção desde 15 de julho.

Mercado Livre Brasil: a definir.

Mercado Livre Colombia, Venezuela, Peru, México e Uruguay: a definir.

Chamada:

curl -X GET “https://api.mercadolibre.com/messages/packs/$pack_id/sellers/$user_id?access_token=$ACCESS_TOKEN”

Exemplo:

curl -X GET “https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?access_token=$ACCESS_TOKEN&limit=2&offset=1”

Resposta:

{
    "paging": {
        "limit": 2,
        "offset": 1,
        "total": 31
    },
    "conversation_status": {
        "path": "/packs/2000000089077943/seller/415458330",
        "status": "active",
        "substatus": null,
        "status_date": "2019-04-08T16:36:30.000Z",
        "status_update_allowed": false,
        "claim_id": null,
        "shipping_id": null
    },
    "messages": [
        
            "id": "2c92808469fea23a0169febf14580001",
            "site_id": "MLA",
            "client_id": 123,
            "from": {
                "user_id": "415458330",
                "email": "test_user_83388960@testuser.com",
                "name": "Juan Pablo Robledo"
            },
            "status": "IN_MODERATION",
            "text": "Test message ToUserId",
            "message_date": {
                "received": "2019-04-08T20:58:49.000Z",
                "available": null,
                "notified": null,
                "created": "2019-04-08T20:58:49.000Z",
                "read": "2019-04-08T20:58:52.000Z"
            },
            "message_moderation": {
                "status": "NON_MODERATED",
                "reason": "none",
                "by": "none",
                "moderation_date": null
            },
            "message_attachments": [
                
                    "filename": "415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d.pdf",
                    "original_filename": "Ayuda-Memoria-Arduino-ELINSI.pdf",
                    "type": "application/octet-stream",
                    "size": 225677,
                    "potential_security_threat": false,
                    "creation_date": "2019-04-08T20:58:49.000Z"
                
            ],
            "message_resources": [
                
                    "id": "2000000089077943",
                    "name": "packs"
                },
                
                    "id": "415458330",
                    "name": "seller"
                
            
        },
        
            "id": "2c92808469fea23a0169febdb0570000",
            "site_id": "MLA",
            "client_id": 123,
            "from": {
                "user_id": "415458330",
                "email": "test_user_83388960@testuser.com",
                "name": "Juan Pablo Robledo"
            },
            "status": "IN_MODERATION",
            "text": "Test message ToUserId",
            "message_date": {
                "received": "2019-04-08T20:57:18.000Z",
                "available": null,
                "notified": null,
                "created": "2019-04-08T20:57:18.000Z",
                "read": "2019-04-08T20:57:22.000Z"
            },
            "message_moderation": {
                "status": "NON_MODERATED",
                "reason": "none",
                "by": "none",
                "moderation_date": null
            },
            "message_attachments": [
                
                    "filename": "415460047_a96d8dea-38cd-4402-938e-80a1c134fc5d.pdf",
                    "original_filename": "Ayuda-Memoria-Arduino-ELINSI.pdf",
                    "type": "application/octet-stream",
                    "size": 225677,
                    "potential_security_threat": false,
                    "creation_date": "2019-04-08T20:57:19.000Z"
                
            ],
            "message_resources": [
                
                    "id": "2000000089077943",
                    "name": "packs"
                },
                
                    "id": "415458330",
                    "name": "seller"
                
            
        
    
}

 

Nota:

  • Já não contará com o e-mail mascarado do comprador


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:

GET “https://api.mercadolibre.com/messages/{message_id}?access_token=$ACCESS_TOKEN”
Header:
key: “X-Pack-Format”
value: true

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"
                
            
        
    
}

 

Carregar, 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:

POST “https://api.mercadolibre.com/messages/attachments?access_token=$ACCESS_TOKEN”

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?access_token=ACCESS_TOKEN' \
  -H 'content-type: multipart/form-data;' \
  -F 'file=@/home/user/.../Adjunto.jpg'

Neste caso, o servidor responderá com um JSON contendo a id do arquivo se o request foi bem-sucedido.
Nota: A resposta obtida deverá ser anexada na mensagem desejada. Resposta:

{
  "id": "210438685_59f0f034-db1b-4ea6-8c5e-1d34e2092482.jpg"
}


Criar mensagens para o comprador

Para enviar uma mensagem para seu comprador, você deverá adicionar no "from" da mensagem o user_id e o email do vendedor. Chamada:

POST "https://api.mercadolibre.com/messages/packs/$pack_id/sellers/$user_id?access_token=$ACCESS_TOKEN"

Exemplo:

curl -X POST \  'https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?access_token=$ACCESS_TOKEN"&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. (Ver Carregar, salvar um anexo).

  • Se não for preciso anexar um arquivo, a seção "attachments" deve ser eliminada do JSON.


Obter anexos

Para obter um anexo deverá realizar uma chamada GET. Chamada:

GET “https://api.mercadolibre.com/messages/attachments/{attachment_id}?access_token=$ACCESS_TOKEN” 

Exemplo:

https://api.mercadolibre.com/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png?access_token=$ACCESS_TOKEN

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:

{
    "message": "File can not be accessed, try it later",
    "error": null,
    "status": 500,
    "cause": []
}

Caso o access token não seja enviado, a mensagem será:

{
    "message": "Access token is required",
    "error": "bad_request",
    "status": 400,
    "cause": []
}


Mensagens ainda não lidas

Esta opção vai lhe permitir obter as mensagens ainda não lidas no Mercado Livre de todas as ordens existentes ou somente daquelas especificadas. Além disso, você também vai poder definir o role (função) de usuário para cada caso, comprador ou vendedor. Para obter essas informações, você terá que realizar o GET abaixo. Chamada:

GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN

Parâmetros opcionais:

-“role”: “buyer”/”seller”


Mensagens de leitura pendente filtradas por resource

Chamada:

GET https://api.mercadolibre.com/messages/unread/${resource}?access_token=$ACCESS_TOKEN

Exemplo:

https://api.mercadolibre.com/messages/unread/packs/1234/sellers/2345?access_token=$ACCESS_TOKEN

Resposta:

{ 	
"user_id": 2345, 
"results": [ { 
"resource": "/packs/1234/sellers/2345", "count": 1 
} ] 
}

Modos de uso

Caso você queira obter todas as ordens com mensagens ainda não lidas como vendedor, deverá realizar a chamada abaixo:

CURL -X GET https://api.mercadolibre.com/messages/unread?access_token=$ACCESS_TOKEN&role=$ROLE

Os valores possíveis para ROLE são “buyer” ou “seller”.

Aclaração: Em caso de não especificar um role ou se este for inválido (diferente de “buyer” ou “seller”), por padrão, o recurso assumirá que o role é "seller".

Resposta: Se a resposta da api for satisfatória, retornará um JSON similar ao seguinte:

{ 	
"user_id": 378136913, 
"results": [ { 
"resource": "/packs/1977056109/sellers/378136913", "count": 1 
} ] 
}

 

Nessa resposta você verá:

  • ID do usuário que realizou a solicitação (“user_id”).

  • Mensagens ainda não lidas (“count”).

  • Cada ordem disponível (“order_id”).

Por último, se não houver mensagens ainda não lidas, quer para todas as ordens do usuário ou para as ordens que o usuário especificar) ou se o usuário especificar dentro do parâmetro “orders_id” ordens das quais não faz parte, a resposta será similar à seguinte:

{
    "user_id": "1234512314",
    "results": []
}

Nota: Este é um recurso privado, portanto, se você realizar uma invocação sem access_token, vai obter um erro 400.

Solicitação sem access token:

{
    "message": "Access token required",
    "error": "bad_request",
    "status": 400,
    "cause": []
}


Marcar mensagens como lidas

Com a chamada PUT, você poderá marcar as mensagens como lidas no Mercado Livre passando os IDs que quiser ler na URL. Nota: As mensagens devem ser separadas por vírgula (,); caso contrário, não serão reconhecidas como mensagens diferentes. Chamada:

PUT /messages/mark_as_read/:messages_id

Exemplo:

https://api.mercadolibre.com/messages/mark_as_read/id1,id2,id3?access_token=$ACCESS_TOKEN

Resposta:

{
    "message": "Messages marked as read successfully",
    "status": 200
}


Revisar mensagens bloqueadas

Visando diminuir o spam e as mensagens desnecessárias, dentro das mensagens pós-venda há a possibilidade de bloquear mensagens devido a que:

  • O comprador decidiu bloquear a recepção de mensagens.

  • O prazo para receber mensagens finalizou e só será reabrir se o comprador assim o decide.

  • Existe uma mediação entre o comprador e o vendedor.

  • A compra foi feita com Fulfillment e o pacote ainda não foi entregue ou tem uma mediação.

Via API você poderá encontrá-las sob o status "Bloqued" em uma nova seção chamada "conversation": Chamada:

https://api.mercadolibre.com/messages/orders/{resource_id}?access_token=$ACCESS_TOKEN

Resposta:

{
  "paging": {...},
  "results": [{...},{...}],
  "conversation": {
"status": "blocked",
"substatus": "blocked_by_buyer",
      "status_date": "2017-05-26T13:17:23.511-04:00"
   
}

status: This field allows two values:

active: conversation is open for sending/receiving messages

  • substatus: nullblocked: conversation is closed to sending/receiving messages

  • substatus: Blocked_by_time

  • substatus: Blocked_by_buyer

  • substatus: Bloqued_by_mediation

  • substatus: blocked_by_fulfillment

status_date: Represents the date when conversation status was recorded.


Possíveis erros

Erros comuns

Request sem access token:

{
  "message": "Access token is required",
  "error": "bad_request",
  "status": 400,
  "cause": [ ]
}


Erros na obtenção de mensagens por id

Usuário sem acesso a uma determinada mensagem:

{
  "message": "Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4",
  "error": "forbidden",
  "status": 403,
  "cause": [ ]
}

A mensagem solicitada não existe:

{
    "message": "The specified message id does not exists",
    "error": "bad_request",
    "status": 400,
    "cause": []
}


Erros POST

Erro por mensagem bloqueada

{
  "message": "You can not send the message because a mediation is in process.",
  "error": "blocked_conversation_send_message_forbidden",
  "status": 403,
  "cause": "blocked_by_mediation"
}

Erro por envío gerenciado por Fulfillment (Mercado Livre)

{
    "message": "You can not send the message because the purchase is Mercado Envíos Full and has not been yet delivered.",
    "error": "blocked_conversation_send_message_forbidden",
    "status": 403,
    "cause": "blocked_by_fulfillment"
}

Mensagem sem receptor (falta adicionar "to"): 400: The field 'to.user_id' is required
User id “to” inválido: 400: Invalid ‘to’ user id
User "from" e user "to" são iguais: 400: Sender and received must not be equals
User "from" não tem acesso à ordem: 403: Access denied for user {from.user_id} to order {to.resource_id}
Se o user_id for 0 e o email não for um secure_email: 400: The field 'to.email' must be a secure email
O receptor da mensagem não pertence à ordem: 403: Receiver does not belong to order {to.resource_id}
O atributo "resource" não é achado: 400: The field 'to.resource' is required
Atributo resource inválido: 400: Invalid field 'to.resource'
Request sem site_id: 400:The field 'to.site_id' is required
Atributo site_id inválido: 400: The field 'to.site_id' has an invalid value
Post sem Json body: 400: A JSON body is required
Mensagem sem "from": 400: The field 'from' is required
Request sem access token: 400: Access token is required
Access Token sem application_id: 400: Application id is required


Erros GET mensagens por pack

Usuário sem acesso à ordem: 403: User access token invalid for resource {resource_id}"
O parâm "limit" do request deve ser maior de 0: 400: The limit param must be greater than 0
Parâm “offset” inválido: 400: Invalid offset param
Parâm “limit” inválido: 400: Invalid limit param


Erros GET attachments

O arquivo solicitado não pode ser obtido: 500: File can not be accessed, try it later


Erros Post attachments

Problemas no armazenamento do arquivo: 500: File can not be saved, try it later
Attachment vazio ou nulo: 400: File attached is empty
O nome do arquivo não pode conter caracteres como: /, \ 400: File name cannot include characters like /, \
O tamanho de arquivo ultrapassa os 25 Mb. 400: File attachment is bigger than 25 Mb.
A mensagem ultrapassa a quantidade permitida de anexos: 25 400: The message exceeds the allowed number of attachments: 25


Erros PUT mensagens marcadas como não lidas

IDs de mensagens inválidas ou vazias

{
    "message": "Messages id empty or invalid.",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

ID de mensagens inexistente

{
    "message": "The specified message id: a does not exists",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

ID de mensagens que corresponder a diferentes orders

{
    "message": "Not allowed messages from multiple orders",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Para mais informações sobre como utilizar este serviço sem sair do Mercado Livre clique aqui.

Próximo: Recebimento de notificações.

Faça parte da nossa comunidade