Motivos para comunicar

Importante:
A partir de agora, para iniciar as mensagens de pós-venda com o Mercado Envios 2 (Fulfillment, Cross docking, Drop off e Flex) você deve atualizar sua integração e o vendedor pode escolher um motivo para se comunicar (action guide). Caso contrário, você receberá o erro blocks_by_conversation_started_by_seller.

Conteúdos

→ Consultar as opções de comunicação disponíveis
→Consultar a quantidade disponível de mensagens pós-venda
→Enviar mensagem de acordo com a opção
→Erros


Consultar as opções de comunicações disponíveis

Com os recursos a seguir, os vendedores precisam escolher um motivo para iniciar a conversa com o comprador e terão uma série de mensagens disponíveis para enviar.


Templates disponíveis segundo país

O template é um texto pré-definido disponibilizado pelo Mercado Livre, que o vendedor não pode modificar.


Template de “REQUEST_VARIANTS”

Para MLA, MLM, MCO, MLC:

Hola, Si necesitas especificar algo sobre la opción del producto que compraste, por favor indícamelo ahora así puedo prepararlo antes de enviarlo. Gracias

Para MLB:

Olá, se você precisa especificar algo sobre a opção do produto que comprou, por exemplo, a cor, por favor, informe agora e assim podemos prepará-lo antes do envio. Obrigado.


Template de “REQUEST_BILLING_INFO”

Para MLA:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • DNI
  • Domicilio
  • Código postal

Para MLM:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • RFC
  • Domicilio
  • Código postal

Para MCO:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • Tipo y número de documento
  • Email
  • Domicilio
  • Código postal
  • Código de municipio
  • Código de departamento

Para MLU:

Para adjuntarte la factura de tu compra necesito los siguientes datos:

  • Nombre y apellido
  • Cédula

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/20000000000

Resposta:


{
   "options":[
      {
         "id":"REQUEST_VARIANTS",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"template",
         "templates":[
            {
               "id":"TEMPLATE___REQUEST_VARIANTS___1",
               "vars":null
            }
         ],
         "actionable":true,
         "child_options":null,
         "cap_available":1
      },
      {
         "id":"REQUEST_BILLING_INFO",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"template",
         "templates":[
            {
               "id":"TEMPLATE___REQUEST_BILLING_INFO___1",
               "vars":null
            }
         ],
         "actionable":true,
         "child_options":null,
         "cap_available":1
      },
      {
         "id":"SEND_INVOICE_LINK",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"free_text",
         "templates":null,
         "actionable":true,
         "char_limit":350,
         "child_options":null,
         "cap_available":1
      },
      {
         "id":"DELIVERY_PROMISE",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"TEMPLATE",
         "templates":[
            {
               "id":"TEMPLATE___DELIVERY_PROMISE___1",
               "texts":{
                  "mla":{
                     "html":"Hola,
Entregaremos tu compra %s entre las %d y las %d hs."
                  },
                  "mlb":{
                     "html":"Olá,
Entregaremos sua compra %s entre %d e %d h."
                  },
                  "mlc":{
                     "html":"Hola,
Entregaremos tu compra %s entre las %d y las %d hs."
                  },
                  "mco":{
                     "html":"Hola,
Entregaremos tu compra %s entre las %d y las %d hs."
                  },
                  "mlu":{
                     "html":"Hola,
Entregaremos tu compra %s entre las %d y las %d hs."
                  }
               },
               "vars":[
                  {
                     "id":"TEMPLATE___DELIVERY_PROMISE___1___VAR___INIT",
                     "type":"NUMBER"
                  },
                  {
                     "id":"TEMPLATE___DELIVERY_PROMISE___1___VAR___LIMIT",
                     "type":"NUMBER"
                  }
               ]
            }
         ],
         "actionable":true,
         "char_limit":null,
         "child_options":[
            
         ],
         "cap_available":1
      },
      {
         "id":"OTHER",
         "internal_description":"This is an example...",
         "enabled":true,
         "type":"free_text",
         "templates":null,
         "actionable":true,
         "char_limit":350,
         "child_options":null,
         "cap_available":1
      }
   ]
}
}

Campos da resposta

char_limit: é o número máximo de caracteres aceitos na opção.


A opção REQUEST_VARIANTS está disponível apenas nos tipos de envio cross docking e drop off.
A opção de DELIVERY_PROMISE, só estará disponível para envios Flex.
Dentro das opções de tipo de template (REQUEST_VARIANTS e REQUEST_BILLING_INFO) temos o id do template, que deve ser usado no POST para envio da mensagem.


Consultar a quantidade disponível de mensagens pós-venda

Dentro da árvore de motivos, as categorias podem ter a opção de enviar uma mensagem ao comprador e você pode reconhecê-los com o campo cap_available:

  • Se for 0 (zero), o vendedor não poderá enviar mensagens ao comprador
  • Se for 1 (um) ou mais, indique a quantidade disponível para envio

Lembre-se que a mensagem terá caracteres limitados e manterá as moderações de uma mensagem normal (apenas para OTHER e SEND_INVOICE_LINK).
Caso o vendedor tenha consumido o limite de mensagens disponíveis para envio, se ele entrar novamente em uma seção de campo aberto (OTHER), a resposta retornará um erro de que não é mais possível fazê-lo, e ele deverá aguardar a resposta do comprador.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID/caps_available

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/200000000000/caps_available

Resposta:

[
   {
      "option_id":"REQUEST_VARIANTS",
      "cap_available":1
   },
   {
      "option_id":"REQUEST_BILLING_INFO",
      "cap_available":1
   },
   {
      "option_id":"SEND_INVOICE_LINK",
      "cap_available":1
   },
   {
      "option_id":"DELIVERY_PROMISE",
      "cap_available":1
   },
   {
      "option_id":"OTHER",
      "cap_available":1
   }
]

Enviar mensagem de acordo com a opção

Após procurar as opções disponíveis para o pack_id, você deve enviar a mensagem como o seguinte POST. Lembre-se de que, após a resposta do comprador, as seguintes mensagens devem ser enviadas diretamente com o post /messages.
Conheça os option_id disponibilizados pelos sites:


Sitio / Option_id “REQUEST_VARIANTS”:
Solicitar dados de variações		 “REQUEST_BILLING_INFO”:
Solicitar informações de faturamento		 “SEND_INVOICE_LINK”:
Enviar link para faturamento		 “OTHER”:
Outros, campo livre		 “DELIVERY_PROMISE”:
Informar promessa de entrega
MLA
MLB
MLM
MCO
MLC
MLU

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/$PACK_ID/option -H 'Content-Type: application/json'  
{
    "option_id": $OPTION_ID,
    "template_id": $TEMPLATE_ID
}

Exemplo com REQUEST_BILLING_INFO (Tipo template):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000000/option -H 'Content-Type: application/json'  
{
    "option_id": "REQUEST_BILLING_INFO",
    "template_id": "TEMPLATE___REQUEST_BILLING_INFO___1"
}

Resposta de mensagem enviada:

{
    "id": "94353d192b9640e8b1ed3c77aa406f39",
    "to": {
        "user_id": 618491100,
        "name": "Test Test"
    },
    "status": "available",
    "text": "Este es un template para solicitar datos de facturación: ",
    "message_date": {
        "received": "2020-09-09T19:07:24.890Z",
        "available": "2020-09-09T19:07:25.056Z",
        "notified": null,
        "created": "2020-09-09T19:07:24.890Z",
        "read": null
    },
    "message_moderation": {
        "status": "clean",
        "reason": null,
        "source": "online",
        "moderation_date": "2020-09-09T19:07:25.056Z"
    }
}
Nota:
No campo text será o conteúdo enviado correspondente ao template.

Exemplo com OTHER (Tipo texto livre):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000000/option -H 'Content-Type: application/json'  \
{
    "option_id": "OTHER",
    "text": "Cómo estás María, estaría necesitando de..."
}

Resposta de mensagem enviada corretamente:

{
    "id": "94353d192b9640e8b1ed3c77aa406f39",
    "to": {
        "user_id": 618491100,
        "name": "Test Test"
    },
    "status": "available",
    "text": "Cómo estás María, estaría necesitando de...",
    "message_date": {
        "received": "2020-09-09T19:07:24.890Z",
        "available": "2020-09-09T19:07:25.056Z",
        "notified": null,
        "created": "2020-09-09T19:07:24.890Z",
        "read": null
    },
    "message_moderation": {
        "status": "clean",
        "reason": null,
        "source": "online",
        "moderation_date": "2020-09-09T19:07:25.056Z"
    }
}
Nota:
O campo text tem o conteúdo enviado no body da chamada.

Resposta de mensagem moderada:

{
    "id": "94353d192b9640e8b1ed3c77aa406f39",
    "to": {
        "user_id": 618491100,
        "name": "Test Test"
    },
    "status": "moderated",
    "text": "Cómo estás María, estaría necesitando de...",
    "message_date": {
        "received": "2020-09-09T19:02:11.438Z",
        "available": null,
        "notified": null,
        "created": "2020-09-09T19:02:11.438Z",
        "read": null
    },
    "message_moderation": {
        "status": "rejected",
        "reason": "out_of_place_language",
        "source": "online",
        "moderation_date": "2020-09-09T19:02:11.697Z"
    }
}

Campos da resposta

status: status da mensagem. Por exemplo: available o moderated
message_moderation:
status: status de moderação de mensagem.
reason: razão para moderação. Por exemplo: out_of_place_language moderação para linguagem imprópria.


Exemplo com DELIVERY_PROMISE:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000000/option -H 'Content-Type: application/json'  \
{
  "option_id": "DELIVERY_PROMISE",
  "template_id": "TEMPLATE___DELIVERY_PROMISE___1",
  "vars": [{
      "id": "TEMPLATE___DELIVERY_PROMISE___1___VAR___INIT",
      "value": 12
  },
  {
      "id": "TEMPLATE___DELIVERY_PROMISE___1___VAR___LIMIT",
      "value": 23
  }]
}
}

No caso de promessas de entrega que já tenham vencido o prazo, não será permitido enviar a mensagem e receberá o erro:

{
   "status_code": 500,
   "message": "delivery date is before than today"
}

Resposta de mensagem:

{

    "id": "374c945ce97446f5b4a73123adfasdd0e1ed17f",
    "status": "available",
    "text": "Entregaremos tu compra {hoy/mañana/el próximo día hábil} entre las {initial} y las {final} hs.",
    "to": {
        "user_id": 667304586,
        "name": "Test Test"
    },
    "message_date": {
        "received": "2021-01-11T18:06:46.070Z",
        "available": "2021-01-11T18:06:46.450Z",
        "notified": null,
        "created": "2021-01-11T18:06:46.070Z",
        "read": null
    },
    "message_moderation": {
        "status": "clean",
        "reason": null,
        "source": "online",
        "moderation_date": "2021-01-11T18:06:46.450Z"
    }

}

Erros

Como um caso excepcional

Os seguintes são exceções:
- Produtos Acessórios para Veículos e com tempo de conclusão (manufacturing time)
Lembre-se de que podemos modificar essas exceções sem aviso prévio.

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/messages/action_guide/packs/2000000000000012

Resposta: 

{
   "cause": "blocked_by_excepted_case",
   "error": "bad_request",
   "message": "This pack belongs to an excepted case, it is requested to use the messaging resource.",
   "status_code": 400
}

O vendedor pode usar mensagens pós-venda sem restrições.


Status (erro) Mensagem Detalhe
400 - limit_exceeded The text is invalid Por exceder o limite de 350 caracteres (option OTHER e SEND_INVOICE_LINK)
403 - bad_request You are not allowed to execute the option OTHER again Quantidade (cap) não disponível
404 - not_found The option selected is not valid Option_id inválido
409 - conflict There is another request locking this operation Esse erro ocorre porque o vendedor executa várias opções simultâneas sobre a mesma venda e, para evitar que sejam feitos mais caps do que os disponíveis, criamos um "Lock" do serviço no vendedor e na venda, que é liberado ao finalizar a opção.
403 - forbidden The conversation is blocked Pack_id com mensageria bloqueada
403 - forbidden You are not allowed to access the information of the pack $PACK_ID O vendedor não está autorizado a consultar as informações desse pack id
400 - bad_request The template $TEMPLATE_ID is invalid Template_id incorreto
400 - bad_request The promise of delivery of the shipping contained in the pack is from a date before today. Data inválida / expirada para a promessa de entrega.
500 - internal_server_error Internal server error Erro interno

Seguinte: Gestão de mensagem.

ou registre-se para receber as últimas notícias sobre nossa API