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

Obter mensagens

Para obter mensagens de uma ordem em particular, você deverá associar o order_id com este recurso realizando um GET.

Chamada:

GET ".../messages/orders/$order_id"

Exemplo:

 curl -X GET “https://api.mercadolibre.com/messages/orders/{resource_id}?access_token=$ACCESS_TOKEN”

Possíveis parâmetros extra:

Estes parâmetros podem ser utilizados para determinar a quantidade de mensagens recuperadas no GET.

&limit={límite} >> número inteiro positivo

Exemplo:

curl -X GET “https://api.mercadolibre.com/messages/orders/{order_id}?access_token=$ACCESS_TOKEN&limit=10”

&offset={compensação} >> número inteiro positivo

Exemplo:

curl -X GET “https://api.mercadolibre.com/messages/orders/{order_id}?access_token=$ACCESS_TOKEN&limit=10&offset=1”

Resposta:

{
    "paging": {
        "limit": 2,
        "offset": 1,
        "total": 270
    },
    "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": "non_moderated",
            "moderation": {
                "status": "non_moderated"
            },
            "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": "non_moderated",
            "moderation": {
                "status": "non_moderated"
            },
            "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 emails de contato do comprador começarão a ser visualizados de forma mascarada, aumentando o número de caracteres (entre 55 e 60).

Obter mensagens por ID

Request:

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

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

Criar mensagens

Se o from for o vendedor, o seller.id da ordem será passado em from.user_id.

Chamada:

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

Nota: O “application_id” apenas é requerido quando o Access Token não tem o APP ID incorporado.

Exemplo:

curl -i -X POST -H "Content-Type: application/json" -H “X-Client-Id: {application id}” -d
'{
    "from": {
        "user_id": 123435,
    },
    "to": [
        {
            "user_id": 9191923,
            "resource": "orders",
            "resource_id": 2223213,
            "site_id": "MLA"
        }
    ],
    "text": {
        "plain": "Plain text message here"
    }
}’ https://api.mercadolibre.com/messages?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID

Nota: O atributo attachments se obtém da resposta do POST de attachments. (Ver seção anexos).

Enviar anexos

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-i-XPOST-H"Content-Type: multipart/form-data"-F"file=@/home/user/file""https://api.mercadolibre.com/messages/attachments?access_token=$ACCESS_TOKEN"

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

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


Para finalizar, seguindo todos esses passos, o POST deverá ficar da seguinte maneira…

Exemplo:

{
    "from": {
      "user_id": 123455677
    },
    "to": [
        {
            "user_id": 72345286,
            "resource": "orders",
            "resource_id": 1234567671,
            "site_id": "MLA"
        }
    ],
    "text": {
      "plain" : "Mensaje de pruebas"
    },
  	"attachments" : ["76602286_52a2e39b-7ff6-48ef-85f8-3025676db43a.png" ]


}

Resposta:

[
    {
        "message_id": "d2345e6e7bb844469ae79623018223af",
        "date_received": "2016-11-14T20:46:49.678Z",
        "date": "2016-11-14T20:46:49.678Z",
        "date_available": "2016-11-14T20:46:49.678Z",
        "date_notified": null,
        "date_read": null,
        "from": {
            "user_id": "123455677",
            "email": "userseller.n4tx9d+2-ogeytenjqgi3tomjw@mail.mercadolibre.com",
            "name": null
        },
        "to": [
            {
                "user_id": "72345286",
                "email": "userbuyer.3fd70y+2-ogeytenjqgi3tombx@mail.mercadolibre.com"
            }
        ],
        "subject": null,
        "text": {
            "plain": "Mensaje de pruebas"
        },
        "attachments": [
            {
                "size": "103584",
                "type": "image/png",
                "date": "Tue, 25 Oct 2016 22:56:47 GMT",
                "filename": "76602286_52a2e39b-7ff6-48ef-85f8-3025676db43a.png",
                "original_filename": "Captura de pantalla 2016-10-20 a las 2.26.09 p.m..png"
            }
        ],
        "attachments_validations": null,
        "site_id": "MLA",
        "resource": "orders",
        "resource_id": "1125027671",
        "status": "available",
        "moderation": {
            "status": "non_moderated"
        }
    }
]

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 bloqueou o envio de mensagens.
  • Após um período de tempo, o envio da mensagem é automaticamente bloqueado.

Via API você poderá encontrá-las sob o status “Bloqueada” 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: Conversation has been blocked automatically after a period of time.
    – substatus: Blocked_by_buyer: Conversation has been blocked due to buyer request.

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

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

Messaging is blocked:
403: You can not send the message because the conversation is blocked by buyer.

403: You can not send the message because the conversation has been blocked by time.

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.

Qualifique entre 1 e 5