Mensajería post venta
El recurso de la API de mensajería te permitirá obtener mensajes de un paquete en particular (tenga este una o varias órdenes), crear nuevos mensajes en el sistema como así también enviar o recibir archivos adjuntos. ¡Veamos cómo usarla!
Contenidos
Descripción de parámetros
message_id Id del mensaje
date_created Fecha de creación
date Fecha en que se guarda el mensaje
date_received Fecha en que se recibió el mensaje
date_available Fecha en el que el mensaje ha pasado por moderación
date_notified Fecha en el que el mensaje ha sido notificado a la contraparte
date_read Fecha en el que el mensaje fue leído por la contraparte
from Quién envía el mensaje
user_id El id del usuario que envió el mensaje
email El email del usuario que envió el mensaje (secure email de la orden)
name El nombre del usuario que envió el mensaje
to Quién recibe el mensaje
user_id El id del usuario que recibió el mensaje
email El email del usuario que recibió el mensaje (secure email de la orden)
subject Subject del email
text Texto del mensaje
plain Texto plano del mensaje
attachments Archivos adjuntos
attachments_validations Validaciones de adjuntos
invalid_size Si el tamaño del adjunto es inválido
invalid_extension Extensión del adjunto inválido
internal_error Error interno
site_id El sitio de Mercado Libre (MLA, MLB, etc.)
message_resources Contiene una lista con IDs relacionados al mensaje, describiendo a qué recurso pertenece cada uno.
status Estado del mensaje
moderation.status Resultado del proceso de moderación
- clean
- rejected
- pending: para casos que la moderación está en proceso
- non_moderated: para casos viejos que no aplicó la moderación
moderation.date_moderated Fecha en que se impactó la información de moderación
moderation.source Modalidad de la moderación
moderation.reason Razón por la cual se moderó el mensaje. Actualmente, esta moderación puede ser por lenguaje inapropiadoa (OUT_OF_PLACE_LANGUAGE), por link de redes sociales (SOCIAL_NETWORK_LINK) o por links acortados (LINK_SHORT_URL).
Vamos a moderar las urls acortadas por:
-
Bitly
-
Bl.ink
-
Polr
-
Rebrandly
-
T2M
-
TinyURL
-
URL Shortener by Zapier
-
Yourls
Obtener mensajes por pack
Para obtener los mensajes de un paquete en particular deberás hacer una consulta asociando el pack_id y el user_id, correspondiente al vendedor del paquete, con el recurso /messages.
Para conocer el pack_id, deberás obtener el campo “pack_id” en la respuesta de /orders/<order_id>
En caso que el pack id contenga un valor null, se deberá tomar por defecto el order id, manteniendo el recurso /packs en la llamada a la API.
Los mensajes moderados por la contraparte no serán visibles y sí podrán verse los mensajes propios.
Importante: esta manera de trabajar quedará productiva en diferentes fechas y tendrá un mes de retrocompatibilidad a partir de cada fecha correspondiente:
Mercado Libre Chile: productivo el 10 de julio.
Mercado Libre Argentina: productivo el 15 de julio.
Mercado Livre Brasil: productivo el 21 de agosto.
Mercado Libre Colombia, Venezuela, Perú, México y Uruguay: a definir.
Llamada:
curl -X GET “https://api.mercadolibre.com/messages/packs/$pack_id/sellers/$user_id?access_token=$ACCESS_TOKEN”
Ejemplo:
curl -X GET “https://api.mercadolibre.com/messages/packs/2000000089077943/sellers/415458330?access_token=$ACCESS_TOKEN&limit=2&offset=1”
Respuesta:
{
"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"
}
Notas:
-
Ya no contarás con el email enmascarado del comprador.
Obtener mensajes por ID
Para conocer los mensajes asociados a un pack, deberás hacer una consulta al recurso /messages.
Nota: Ten en cuenta incluir en la llamada el header “X-Pack-Format”: true para obtener la respuesta actualizada. Si no lo envías, seguirás recibiendo la respuesta antigua basada en la orden.
Llamada:
GET “https://api.mercadolibre.com/messages/{message_id}?access_token=$ACCESS_TOKEN”
Header: key: “X-Pack-Format” value: true
Ejemplo de respuesta sin 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"
}
Ejemplo de respuesta con 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"
}
Cargar, guardar mensajes
Para adjuntar un archivo dentro del mensaje primero deberá ser guardado. Luego, cuando se envía un adjunto, se devuelve el id del archivo como respuesta.
Llamada:
POST “https://api.mercadolibre.com/messages/attachments?access_token=$ACCESS_TOKEN”
Notas:
-
El POST debe realizarse como form.data con key: value > file = referencia al file (es decir el archivo en sí).
-
El archivo debe tener un tamaño máximo de 25 MB.
-
Podrán intercambiarse fotos, manuales de instrucciones, facturas y demás archivos adjuntos en JPG, PNG, PDF y TXT de hasta 25 MB.
Ejemplo:
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'
En este caso el servidor responderá con un JSON que contendrá el id del archivo en caso que el request haya sido exitoso.
Nota: la respuesta obtenida se deberá anexar en el mensaje deseado.
Respuesta:
{
"id": "210438685_59f0f034-db1b-4ea6-8c5e-1d34e2092482.jpg"
}
Crear mensajes para un comprador
Para enviar un mensaje a tu comprador, deberás agregar en el “from” del mensaje el user_id y el email del vendedor.
Llamada:
POST "https://api.mercadolibre.com/messages/packs/$pack_id/sellers/$user_id?access_token=$ACCESS_TOKEN"
Ejemplo:
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:
-
El atributo attachments se obtiene de la respuesta del POST de attachments. (Ver cargar, guardar adjuntos).
-
En caso de no necesitar adjuntar un archivo, debes eliminar la sección “attachments” del JSON.
Obtener adjunto
Para obtener un mensaje adjunto se deberá hacer una llamada GET. Llamada:
GET “https://api.mercadolibre.com/messages/attachments/{attachment_id}?access_token=$ACCESS_TOKEN”
Ejemplo:
https://api.mercadolibre.com/messages/attachments/76601286_5946e4c4-168a-45fd-945e-b8f0c306c58d.png?access_token=$ACCESS_TOKEN
Respuesta: Si el request es exitoso, la llamada devolverá el archivo solicitado. En caso de que no sea posible acceder al archivo la respuesta del servidor será la siguiente:
{
"message": "File can not be accessed, try it later",
"error": null,
"status": 500,
"cause": []
}
En caso de que no se envíe el access token el mensaje será:
{
"message": "Access token is required",
"error": "bad_request",
"status": 400,
"cause": []
}
Mensajes pendientes de leer
Esta opción te permitirá obtener los mensajes pendientes de leer en Mercado Libre de todas las órdenes existentes o sólo las especificadas. Además, también podrás definir el role del usuario para cada caso, ya sea comprador o vendedor. Para obtener la información mencionada deberás realizar el GET que se muestra a continuación.
Parámetros opcionales
-“role”: “buyer”/”seller”
Mensajes pendientes de leer filtrado por resource
Llamada:
GET https://api.mercadolibre.com/messages/unread/${resource}?access_token=$ACCESS_TOKEN
Ejemplo:
https://api.mercadolibre.com/messages/unread/packs/1234/sellers/2345?access_token=$ACCESS_TOKEN
Respuesta:
{
"user_id": 2345,
"results": [ {
"resource": "/packs/1234/sellers/2345", "count": 1
} ]
}
Modos de uso
Si deseas obtener todas las órdenes con mensajes pendientes de leer como vendedor deberás realizar la siguiente llamada:
CURL -X GET https://api.mercadolibre.com/messages/unread?access_token=$ACCESS_TOKEN&role=$ROLE
Los valores posibles para ROLE son “buyer” o “seller”.
Aclaración: En caso de no especificar un role o que el mismo sea inválido (diferente de “buyer” o “seller”), el recurso devolverá todos los casos.
Respuesta:
En caso de que la respuesta de la api sea satisfactoria. Nos devolverá un JSON similar al siguiente:
{
"user_id": 378136913,
"results": [ {
"resource": "/packs/1977056109/sellers/378136913", "count": 1
} ]
}
En esta respuesta visualizarás
-
ID del usuario que hizo la petición (“user_id”).
-
Mensajes pendientes de leer (“count”).
-
Cada orden que disponemos (“order_id”).
Por último, en caso de no tener mensajes pendientes de leer, la respuesta será similar a la siguiente:
{
"user_id": "1234512314",
"results": []
}
Nota: este es un recurso privado por lo que si realizas una llamada sin access_token obtendrás un error 400.
Petición sin access token:
{
"message": "Access token required",
"error": "bad_request",
"status": 400,
"cause": []
}
Marcar mensajes como leídos
Con esta llamada PUT podrás marcar los mensajes como leídos en Mercado Libre pasando los IDs que desees leer en la URL.
Nota: los mensajes deben estar separados por coma (,) caso contrario no serán reconocidos como mensajes diferentes.
Llamada:
PUT /messages/mark_as_read/:messages_id
Ejemplo:
https://api.mercadolibre.com/messages/mark_as_read/id1,id2,id3?access_token=$ACCESS_TOKEN
Respuesta:
{
"message": "Messages marked as read successfully",
"status": 200
}
Revisar mensajes bloqueados
Con el fin de disminuir el spam y mensajes innecesarios, dentro de mensajería post venta existe la posibilidad de que algunos mensajes sean bloqueados porque:
-
El comprador decide bloquear la recepción de mensajes.
-
El plazo para recibir mensajes caducó y sólo será reabierto si el comprador así lo decide.
-
Existe una mediación entre el comprador y el vendedor.
-
La compra está hecha con Fulfillment y el paquete todavía no fue entregado o tiene una medición en curso.
Vía API podrás encontrarlos bajo el status “Blocked” en un nuevo apartado llamado “conversation”:
Llamada:
https://api.mercadolibre.com/messages/orders/{resource_id}?access_token=$ACCESS_TOKEN
Respuesta:
{
"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.
Posibles errores
Errores comunes
Request sin access token:
{
"message": "Access token is required",
"error": "bad_request",
"status": 400,
"cause": [ ]
}
Errores al obtener mensajes por id
Usuario sin acceso a un determinado mensaje:
{
"message": "Access denied for user 30265782 to message with id 006b9b2df38f452b80402041ae86f6d4",
"error": "forbidden",
"status": 403,
"cause": [ ]
}
No existe el mensaje pedido:
{
"message": "The specified message id does not exists",
"error": "bad_request",
"status": 400,
"cause": []
}
Mensaje no encontrado en el servidor, intente nuevamente en algunos segundos
{
"message": "The message with id: a could not be retrieved from storage",
"error": "not_found",
"status": 404,
"cause": []
}
Errores POST
Error por mensaje bloqueado
{
"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"
}
Error por envío gestionado por Fulfillment (Mercado Libre)
{
"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"
}
Mensaje sin receptor (falta agregar “to”): 400: The field 'to.user_id' is required
User id “to” inválido: 400:Invalid ‘to’ user id
El user “from” y “to” son iguales: 400: Sender and received must not be equals
El user “from” no tiene acceso a la orden: 403: Access denied for user {from.user_id} to order {to.resource_id}
Si el user_id es 0 y el email no es un secure_email: 400: The field 'to.email' must be a secure email
El receptor del mensaje no pertenece a la orden: 403: Receiver does not belong to order {to.resource_id}
No se encuentra el atributo “resource”: 400: The field 'to.resource' is required
Atributo resource inválido: 400: Invalid field 'to.resource'
Request sin 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 sin Json body: 400: A JSON body is required
Mensaje sin ‘from’: 400: The field 'from' is required
Request sin access token: 400: Access token is required
Access Token sin application_id: 400: Application id is required
Errores GET mensajes por pack
Usuario sin acceso a la orden: 403: User access token invalid for resource {resource_id}"
El param “limit” del request debe ser mayor a 0: 400: The limit param must be greater than 0
Param “offset” inválido: 400: Invalid offset param
Param “limit” inválido: 400: Invalid limit param
Errores GET attachments
No se pudo obtener el archivo solicitado: 500: File can not be accessed, try it later
Errores Post attachments
Problemas al almacenar el archivo: 500: File can not be saved, try it later
Attachment vacío o nulo: 400: File attached is empty
El nombre del archivo no puede tener caracteres como: /, \ 400: File name cannot include characters like /, \
El tamaño del archivo excede los 25 Mb. 400: File attachment is bigger than 25 Mb.
El mensaje excede la cantidad permitida de adjuntos: 25 400: The message exceeds the allowed number of attachments: 25
Errores PUT mensajes marcados como no leídos
IDs de mensajes inválidos o vacíos
{
"message": "Messages id empty or invalid.",
"error": "bad_request",
"status": 400,
"cause": []
}
ID de mensaje inexistente
{
"message": "The specified message id: a does not exists",
"error": "bad_request",
"status": 400,
"cause": []
}
ID de mensajes que corresponden a diferentes órdenes
{
"message": "Not allowed messages from multiple orders",
"error": "bad_request",
"status": 400,
"cause": []
}
Mensaje no encontrado en el servidor, intente nuevamente en algunos segundos
{
"message": "The message with id: a could not be retrieved from storage",
"error": "not_found",
"status": 404,
"cause": []
}
Para obtener más información sobre cómo utilizar este servicio sin salir de Mercado Libre ingresa aquí.
Siguiente: Recibe notificaciones.