Mensagens de pós venda

O recurso da API do sistema de Mensagens vai permitir que você obtenha mensagens de uma ordem em particular, crie novas mensagens no sistema e envie ou receba anexos. 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.)
resource Relativo à ordem a que pertence (orders)
resource_id ID da ordem
status Status da mensagem
moderation_status Status de moderação da mensagem
- clean
- rejected
- pending: para casos em que a moderação está em processo
- non_moderated: para casos velhos que não é aplicada a moderação
moderation.date_moderated Data em que foi impactada a informação da moderação.
moderation.source Modalidade da moderação.
moderation.reason Motivo pelo qual foi moderada a mensagem. Este campo aparece só quando a moderação está embaixo o status “rejected”.

Obter mensagens

Para obter mensagens de uma ordem em particular, você deverá associar o order_id com o recurso /messages Chamada:
GET ".../messages/orders/$order_id"
Exemplo:
 curl -X GET “https://api.mercadolibre.com/messages/orders/{resource_id}?access_token=$ACCESS_TOKEN”
Resposta:
{
    "paging": {
        "limit": 2,
        "offset": 1,
        "total": 10
    },
    "results": [
        {
            "_id": "43b450d6bd3f47fb94394041b26c519f",
            "message_id": "43b450d6bd3f47fb94394041b26c519f",
            "date_received": "2016-11-07T15:03:14.978Z",
            "date": "2016-11-07T15:03:14.978Z",
            "date_available": "2016-11-07T15:03:14.978Z",
            "date_notified": "2016-11-07T15:05:50.179Z",
            "date_read": "2016-11-08T22:43:17.767Z",
            "from": {
                "user_id": "76601286",
                "email": "mailfrom.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com",
                "name": null
            },
            "to": [
                {
                    "user_id": "106459677",
                    "email": "mailto.lj36rj8+2-ogeytenjqgi3tomjw@test.mercadolibre.com"
                }
            ],
            "subject": null,
            "text": {
                "plain": "Mensaje de pruebas desde api publica con attachment. Multiples 'to' "
            },
            "attachments": [
                {
                    "size": "103584",
                    "type": "image/png",
                    "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                    "filename": "76601286_51a2e39b-7ff6-48ef-85f8-3025676db43e.png",
                    "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
                }
            ],
            "attachments_validations": null,
            "headers": null,
            "site_id": "MLA",
            "resource": "orders",
            "resource_id": "1125027671",
            "status": "available",
           
            "moderation": {
               "status": "rejected",
       "date_moderated": "2019-03-11T11:55:55.379Z",
       "source": "online",
       "reason": "out_of_place_language"

            },
            "client_id": 1000
        },
        {
            "_id": "37befd545a2d436f89e672b33990ef8b",
            "message_id": "37befd545a2d436f89e672b33990ef8b",
            "date_received": "2016-11-07T14:56:02.500Z",
            "date": "2016-11-07T14:56:02.500Z",
            "date_available": "2016-11-07T14:56:02.500Z",
            "date_notified": "2016-11-07T14:57:46.659Z",
            "date_read": "2016-11-07T15:19:08.967Z",
            "from": {
                "user_id": "76601286",
                "email": "mailfrom.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com",
                "name": null
            },
            "to": [
                {
                    "user_id": "106459677",
                    "email": "mailto.lj36rj8+2-ogeytenjqgi3tomjw@test.mercadolibre.com"
                }
            ],
            "subject": null,
            "text": {
                "plain": "Mensaje de pruebas desde api publica con attachment. Multiples 'to' "
            },
            "attachments": [
                {
                    "size": "103584",
                    "type": "image/png",
                    "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                    "filename": "76601286_51a2e39b-7ff6-48ef-85f8-3025676db43e.png",
                    "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
                }
            ],
            "attachments_validations": null,
            "headers": null,
            "site_id": "MLA",
            "resource": "orders",
            "resource_id": "1125027671",
            "status": "available",
            
            "moderation": {
                "status": "clean",
       "date_moderated": "2019-03-13T09:34:26.450-04:00",
       "source": "online"

            },
            "client_id": 1000
        }
    ]
}
Notas:
  • Por cada venda que você tiver de um comprador, terá um email mascarado diferente. Isto é, se o mesmo comprador comprar dois produtos diferentes em diversos momentos, um email será gerado para cada venda.
  • Os e-mails ofuscados terão maior longitude, aumentando o número de caracteres (entre 55 e 60).

Obter mensagens por ID

Exemplo de resposta:
{
  "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"

  }
}

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

No from da mensagem deve enviar o seller_id da ordem. Chamada:
POST "https://api.mercadolibre.com/messages?access_token=$ACCESS_TOKEN"
Exemplo:
curl -X POST \  'https://api.mercadolibre.com/messages?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 '{
	"attachments":[
		"62867623_14fd3771-f258-4280-8f1c-808eb0f92bea.jpg"  
],
    "from": {
        "user_id": 236900XXX
    },
    "to": [
        {
            "user_id": 237052XXX,
            "resource": "orders",
            "resource_id": 1236236XXX,
            "site_id": "MLA"
        }
    ],
    "subject": "Prueba",
    "text": {
    
        "plain": "Prueba Mensajeria"
    }
}'
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):

Para receber uma lista de ordens específicas, você deverá enviar os IDs separados por vírgula (...&orders_id=id1,id2,...,): orders_id=$ORDERS_ID Além disso, para receber o role (função) de usuário na ordem. Exemplo comprador: …&role=buyer - Exemplo vendedor: …&role=seller) deverá utilizar o seguinte parâmetro: role=$ROLE

Modos de uso

Caso você queira obter todas as ordens com mensagens ainda não lidas como vendedor, deverá realizar a invocação abaixo: Sem role:
CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN
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". Com role:
CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&role=seller
Para obter todas as ordens com mensagens ainda não lidas como comprador, você deverá realizar a invocação abaixo:
CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&role=buyer
Caso você queira obter a quantidade de mensagens ainda não lidas para as ordens, deverá fazer conforme detalhado abaixo:
CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&orders_id=123,124,125
Resposta: Se a resposta da api for satisfatória, retornará um JSON similar ao seguinte:
{
    "user_id": "1234512314",
    "results": [
        {
            "order_id": "19912312312”
            "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: null
  • blocked: 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 bloqueda
{
  "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 ordem

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