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
→Revisar mensajes bloqueados
→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), links acortados (LINK_SHORT_URL) o por ser un mensaje automático de integrador (AUTOMATIC_MESSAGE).

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.
- Los Mime Type permitidos de los archivos son:
text/plain
image/png
image/jpeg
image/heif
image/heic
application/pdf
application/msword
application/vnd.ms-excel
text/xml,application/xml
application/octet-stream
Si quieres subir alguno que no esté en la lista, la API devolverá un HTTP Status Code 400.

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.
Si el mensaje que quieres enviar es para solicitar datos de facturación, deberás utilizar el recurso /packs/$pack_id/fiscal_documents/billing/request_buyer_info de carga de facturas.

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.
- Si necesitas insertar un enlace en el que se pueda hacer clic, puedes hacerlo utilizando la función href. Por ejemplo: "<a href="su_url"> Su link de seguimiento </a>".

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
}

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.

Importante:

Este bloqueo solo aplica para Brasil. En Argentina y México ya no está vigente.

La compra tiene una mediación en curso.

Vía API podrás encontrarlos bajo el status “Blocked” en un nuevo apartado llamado “conversation”:

Llamada:

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

Ejemplo:

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

Respuesta:

{
    "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:

En el caso que la conversación tenga el substatus de blocked_by_payment, significa el pago todavía no fue realizado por el comprador o que el mismo aún no fue impactado. Una order no se encuentra paga cuando tiene alguno de los siguientes status: payment_required, payment_in_process o partially_paid. Este bloqueo es temporal hasta que se realice el pago y el mismo haya impactado en la orden.
La actualización del pago en la orden puede no ser instantánea, por lo que es prudente esperar por lo menos 60 segundos para asegurarse que el mismo haya impactado en la order.

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

Importante:

Este error solo aplica para 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"
}

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.