Mensajería post venta

El recurso de la API de mensajería te permitirá obtener mensajes de una orden en particular, 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_availableFecha 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 mercadolibre (MLA, MLB, etc)
resource Corresponde a la orden que pertenece (orders)
resource_id El ID de la orden
status Estado del mensaje
moderation_status Estado de moderación del mensaje

Obtener mensajes

Para obtener mensajes de una orden en particular deberás asociar el order_id con este recurso realizando un GET.

Llamada:

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

Ejemplo:

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

Posibles parámetros extras:

Estos parámetros pueden ser utilizados para determinar la cantidad de los mensajes recuperados en el GET.

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

Ejemplo:

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

&offset={compensación} >> número entero positivo

Ejemplo:

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

Respuesta:

{
    "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 venta que tengas de un comprador tendrás un email enmascarado diferente. Es decir, si el mismo comprador te compra dos productos diferentes en distintos momentos, se generarán emails para cada venta.
  • Los mails de contacto del comprador comenzarán a verse de manera enmascarada lo que hará que aumenten la cantidad de caracteres (entre 55 y 60).

Obtener mensajes por ID

Request:

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

Ejemplo de respuesta:

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

Crear mensajes

En caso de que el from sea el vendedor se pasará en from.user_id el seller.id de la órden.

Llamada:

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

Notas: El “application_id” solo es requerido cuándo el Access Token no tiene el APP ID incorporado.

Ejemplo:

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: El atributo attachments se obtiene de la respuesta del POST de attachments. (Ver sección adjuntos).

Enviar adjunto

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

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

Obtener adjunto

Para obtener un mensaje adjunto se deberá 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": []
}

 

Para finalizar, siguiendo todos estos pasos el POST deberá quedar de la siguiente manera…

Ejemplo:

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


}

Respuesta:

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

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.

Llamada:

GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN

Parámetros (opcionales)

Para recibir un listado de órdenes específicas, deberás enviar los IDs separados por coma (…&orders_id=id1,id2,…,):
orders_id=$ORDERS_ID

Por otro lado, para recibir el role del usuario en la orden. Ejemplo comprador: …&role=buyer – Ejemplo vendedor: …&role=seller) tendrás que hacerlo con el siguiente parámetro: role=$ROLE

Modos de uso

Si deseas obtener todas las órdenes con mensajes pendientes de leer como vendedor deberás realizar la siguiente llamada:

Sin role:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN

Aclaración: En caso de no especificar un role o que el mismo sea inválido (diferente de “buyer” o “seller”), por defecto el recurso asumirá que el role es “seller”.

Con role:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&role=seller

Para obtener todas las órdenes con mensajes pendientes de leer como comprador deberás realizar la siguiente llamada:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&role=buyer

En caso que quieras obtener la cantidad de mensajes pendientes de leer para las órdenes deberás hacerlo de la siguiente manera:

CURL -X GET https://api.mercadolibre.com/messages/pending_read?access_token=$ACCESS_TOKEN&orders_id=123,124,125

Respuesta:
En caso de que la respuesta de la api sea satisfactoria. Nos devolverá un JSON similar al siguiente:

{
    "user_id": "1234512314",
    "results": [
        {
            "order_id": "19912312312”
            "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 ya sea para todas las órdenes del usuario o para las órdenes que el usuario específica) o si el usuario especifica dentro del parámetro “orders_id” órdenes de las cuales no forma parte, la respuesta será similar a la siguiente:

{
    "user_id": "1234512314",
    "results": []
}

Nota: Éste 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 bloquear mensajes ya sea porque:

  • El comprador bloqueó el envío de mensajes.
  • Después de un periodo de tiempo el envío del mensaje es bloqueado automáticamente.

Vía API podrás encontrarlos bajo el status “Bloqueada” 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: null

  • blocked: conversation is closed to sending/receiving messages
  • – substatus: Blocked_by_time: Conversation has been blocked automatically after 60 days.
    – substatus: Blocked_by_buyer: Conversation has been blocked due to buyer request.

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

Errores post

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

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

Errores GET mensajes por orden

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

Para obtener más información sobre cómo utilizar este servicio sin salir de Mercado Libre ingresa aquí.

Siguiente:
Recibe notificaciones.

Please rate this