Mensajería posventa

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. Recuerda que si desarrollas esta funcionalidad, debes conocer cuáles son los mensajes automáticos que generan una mala experiencia.

Contenidos

→Descripción de parámetros
    ↳Moderamos urls acortadas
→Obtener mensajes por pack
→Obtener mensajes por ID
→Cargar, guardar mensajes
→Crear mensajes para un comprador
→Obtener adjunto
→Mensajes pendientes de leer
    ↳Parámetros opcionales
→Mensajes pendientes de leer filtrado por resource
    ↳Modos de uso
→Marcar mensajes como leídos
→Posibles errores
    ↳Errores comunes
    ↳Errores al obtener mensajes por ID
    ↳Errores POST
    ↳Errores GET mensajes por pack
    ↳Errores GET attachments
    ↳Errores POST attachments
    ↳Errores PUT mensajes marcados como no leídos

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).


Moderamos 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á hasta el 15 de enero de 2020 de retrocompatibilidad. Vea cuándo estará disponible en cada país:
- 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 México: productivo el 23 de septiembre.
- Mercado Libre Colombia, Venezuela, Perú y Uruguay: productivo el 2 de octubre.

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:
- La zona horaria para las fechas de mensajería son UTC.
- 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:
Incluye 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:

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

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

curl -X 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. Mira cómo cargar y 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:

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

Ejemplo:

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

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

Ejemplo:

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

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

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

Ejemplo:

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

Respuesta:

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


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: El campo 'to.user_id' es requerido
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": []
}

Siguiente: Recibe notificaciones.

Forma parte de nuestra comunidad