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. Lembre de conhecer quais são as mensagens automaticas que geram uma má experiencia.

Conteúdos

→Descrição de parâmetros
    ↳Quais encurtadores de URL vamos moderar?
→Obter mensagens de um pacote
→Obter mensagens por ID
→Carregar, salvar um anexo
→Criar mensagens para o comprador
→Obter anexos
→Mensagens ainda não lidas
    ↳Parâmetros opcionais
→Mensagens de leitura pendente filtradas por resource
    ↳Modos de uso
→Marcar mensagens como lidas
→Revisar mensagens bloqueadas
→Possíveis erros
    ↳Erros comuns
    ↳Erros na obtenção de mensagens por ID
    ↳Erros POST
    ↳Erros GET mensagens por pack
    ↳Erros GET attachments
    ↳Erros POST attachments
    ↳Erros PUT mensagens marcadas como não lidas

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_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) 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 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á até 15 de janeiro de 2020 de retrocompatibilidade. Veja quando estará disponível em cada país:
- Mercado Libre Chile: em produção desde 10 de julho.
- Mercado Libre Argentina: em produção desde 15 de julho.
- Mercado Livre Brasil: em produção desde 21 de agosto.
- Mercado Libre México: em produção desde 23 de setembro. 
- Mercado Libre Colombia, Venezuela, Peru e Uruguay: em produção desde 2 de outubro.

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:
- Lembre-se também de que o fuso horário das datas é UTC.
- 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. 

Notas:
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 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:

curl -X 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:

curl -X 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. Veja como Carregar, 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>".


Obter anexos

Para obter um anexo deverá realizar uma chamada GET.


Chamada:

curl -X GET https://api.mercadolibre.com/messages/attachments/{attachment_id}?access_token=$ACCESS_TOKEN

Exemplo:

curl -X GET 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.


Parâmetros opcionais:

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


Mensagens de leitura pendente filtradas por resource

Chamada:

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

Exemplo:

curl -X GET 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”.

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

curl -X PUT https://api.mercadolibre.com/messages/mark_as_read/$MESSAGES_ID?access_token=$ACCESS_TOKEN

Exemplo:

curl -X PUT 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

Para reduzir spam e mensagens desnecessárias, nas mensagens pos venda, existe a possibilidade de algumas mensagens serem bloqueadas porque:

  • O comprador decide bloquear a recepção de mensagens.
  • O prazo para recebimento de mensagens expirou e só será reaberto se o comprador assim o decidir.
  • Existe uma mediação entre o comprador e o vendedor.
  • A compra é feita com Fullfillment e o pacote ainda não foi entregue.
  • Importante:
    Esse bloqueio se aplica apenas ao Brasil. Na Argentina e no México, não está mais em vigor.
  • A compra tem uma mediação em andamento.

Através da API, você pode encontrá-los com o status "Blocked" em uma nova seção chamada "conversation":


Chamada:

curl -X GET https://api.mercadolibre.com/messages/packs/$PACK_ID/sellers/$SELLER_ID?access_token=$ACCESS_TOKEN

Exemplo:

curl -X GET https://api.mercadolibre.com/messages/packs/22175467/sellers/32086568493?access_token=$ACCESS_TOKEN

Resposta:

{
    "paging": {
        "limit": 10,
        "offset": 0,
        "total": 4
    },
    "conversation_status": {
        "path": "/packs/22175467/sellers/32086568493",
        "status": "blocked",
        "substatus": "blocked_by_buyer",
        "status_date": "2020-01-10T19:58:04.317Z",
        "status_update_allowed": false,
        "claim_ids": null,
        "shipping_id": null
    },
    "messages": [. . . ]
}

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

- substatus: Blocked_by_payment


status_date: Represents the date when conversation status was recorded.

Nota:
No caso de a conversa ter o substatus blocked_by_payment, isso significa que o pagamento ainda não foi feito pelo comprador ou que ainda não foi impactado. Esse bloqueio é temporário até que o pagamento seja efetuado e tenha impactado na ordem. Uma ordem não é paga quando possui um dos seguintes status: payment_required, payment_in_process ou partially_paid.
A atualização do pagamento na ordem pode não ser instantânea, é prudente aguardar pelo menos 60 segundos para garantir que ele tenha impactado na ordem.


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": []
}

Mensagem não encontrada no servidor, tentar novamente em alguns segundos

{
	"message": "The message with id: a could not be retrieved from storage",
	"error": "not_found",
	"status": 404,
	"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):

Importante:
Este erro se aplica apenas ao Brasil.
{
    "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": []
}

Mensagem não encontrada no servidor, tentar novamente em alguns segundos:

{
    "message": "The message with id: a could not be retrieved from storage",
    "error": "not_found",
    "status": 404,
    "cause": []
}

Próximo: Recebimento de notificações.