Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade
Última atualização em 19/07/2024

Pessoas interessadas

Importante:
Este recurso está disponível para veículos e imóveis em todos os sites.

O atributo "channels" será depreciado em nossa API. Em seu lugar, "contact_types" será o novo padrão. Ambos atributos podem ser utilizados por enquanto, mas em breve apenas "contact_types" estará disponível. Por favor, atualizem suas chamadas de API para utilizar "contact_types" em vez de "channels" nos valores de entrada.

O recurso /vis/users/$USER_ID/leads/seller permite ao vendedor obter dados de contato dos compradores interessados em suas publicações. Para receber notificações sobre os clientes interessados, você deve se inscrever no tópico VIS Leads, e após receber a notificação, consultar o recurso de /leads.



Consultar interessados nos itens do vendedor

Agora, o vendedor pode consultar todos os dados de contato dos interessados, com a possibilidade de fazer paginação utilizando o parâmetro offset, que indica a posição do primeiro elemento a ser obtido, e o parâmetro limit, que indica o número máximo de elementos a obter. Além disso, os dados podem ser filtrados por um período específico, utilizando os parâmetros date_from e date_to. Para uma pesquisa mais específica, pode utilizar o parâmetro contac_types, que representa o tipo de contato a devolver.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/users/$USER_ID/leads/buyers?offset=$OFFSET&limit=$LIMIT&date_from=$DATE_FROM&date_to=$DATE_TO&contact_types=$CONTACT_TYPES

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/users/806525693/leads/buyers?offset=0&limit=10&dateFrom=2023-06-15&dateTo=2023-06-22&contact_types=true&contac_types=credit,question,whatsap

Valores de entrada

Atributo Tipo de dados Descrição Obrigatório Valor padrão
USER_ID int Identificador do vendedor. Sim -
OFFSET int Posição do primeiro elemento na lista de itens. Não 0
LIMIT int Número máximo de elementos na lista de itens. Não 10
date_from string Data de início da pesquisa. Formatos permitidos: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02 Não 7 dias antes da data atual.
date_to string Data do fim da pesquisa. Formatos permitidos: 2006-01-02T15:04:05Z 2006-01-02T15:04:05 2006-01-02 Não Data atual.
*channels string Tipo de contatos a devolver. Se não for enviado, são devolvidos todos os tipos de contatos. Não Todos os tipos de contato.
contact_types string Tipo de contatos a devolver. Se não for enviado, são devolvidos todos os tipos de contatos. Não Todos os tipos de contacto.
item_id string Identificador do item, formato MLX1234567. Não -
Nota:
*O atributo "channels" será depreciado em nossa API. Em seu lugar, "contact_types" será o novo padrão .

Campos de la respuesta

  • results: contém uma lista de resultados.
  • results.id: identificador do comprador.
  • results.item_id: identificador do item.
  • results.name: nome do comprador. Apenas se o acesso for público.
  • results.email: e-mail do comprador. Apenas se o acesso for público.
  • results.phone: número de telefone do comprador. Apenas se o acesso for público.
  • results.leads: contém uma lista do leads gerados pelo comprador.
  • leads.uuid: deprecado (substituir por leads.id).
  • leads.external_id: identificador externo do lead.
  • leads.contact_type: tipo de lead.
  • leads.item_id: identificador do item.
  • leads.created_at: data de criação do lead.
  • leads.status: estado do lead.
  • paging: contém informações de paginação.
  • paging.offset: posição do primeiro elemento a ser devolvido.
  • paging.limit: número máximo de elementos por página.
  • paging.total: número total de elementos.
  • date_from: data inicial dos resultados.
  • date_to: data final dos resultados.

Tipos de Leads Disponíveis (contact_types)

    Importante:
    Nem todos os tipos de contatos estarão disponíveis para todos os usuários. A disponibilidade de contatos pode variar de acordo com a vertical e o tipo de usuário.
  • whatsapp: um comprador aperta o botão de WhatsApp.
  • question: um comprador faz uma pergunta.
  • whatsapp_intervention: intervenção de WhatsApp.
  • call: um comprador aperta o botão de ligar.
  • credit: simulação de crédito.
  • quotation: cotação de real estate do imóvel.
  • view: mostrar telefone no anúncio.
  • schedule: agendamento em real estate.

Resposta:

{
  
    "results": [
        {
            "id": 2678328,
            "item_id": "MLA1430828018",
            "name": "John Doe",
            "email": "jhon@example.com",
            "phone": "+5491198765432",
            "leads": [
                {
                    "id": "6b4aebf8-5570-47b8-9224-c1c177621575",
                    "uuid": "6b4aebf8-5570-47b8-9224-c1c177621575",
                    "channel": "question",
                    "contact_type": "question",
                    "created_at": "2024-05-14T14:15:39Z",
                    "external_id": "12776297658",
                    "item_id": "MLA1430828018",
                    "buyer_id": 2678328,
                    "status": "active"
                }
            ]
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 10,
        "total": 1
    },
    "date_from": "2024-05-14",
    "date_to": "2024-05-24"
}


Erros possíveis

Erros na busca de interessados.

Error_code Tipo Mensagem de erro Motivos
400 Bad Request { "message": "invalid date range", "error": "bad_request", "status": 400, "cause": [ "start date is greater than end date" ] } A data de início é posterior à data de fim da pesquisa.
400 Bad Request { "message": "invalid start date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2021-01-021\": extra text: \"1\"" ] } Data de início com formato inválido.
400 Bad Request { "message": "invalid end date", "error": "bad_request", "status": 400, "cause": [ "parsing time \"2024-01-022\": extra text: \"2\"" ] } Data de fim com formato inválido.
Parâmetro do indicador de linha de crédito com formato inválido.
400 Bad Request { "code": "bad_request", "message": "invalid format USER_ID" } Identificador com formato inválido.
400 Bad Request { "message": "error decoding search params", "error": "bad_request", "status": 400, "cause": [ "schema: invalid path \"contact_types\"" ] } Parâmetro inválido.
400 Bad Request { "message": "invalid lead type", "error": "bad_request", "status": 400, "cause": [ "invalid lead type: invalid " ] } Tipo de contato inválido.
403 Forbidden { "code": "forbidden", "message": "invalid token caller" } Access token não pertence ao vendedor.
403 Forbidden { "blocked_by": "PolicyAgent", "path": "/v1/users/806525693/leads/buyers?scope=test-public", "code": "PA_UNAUTHORIZED_RESULT_FROM_POLICIES", "status": 403, "message": "At least one policy returned UNAUTHORIZED." } Acesso ao endpoint sem access token.
403 Forbidden { "code": "forbidden", "message": "invalid token" } Access token inválido ou expirado.
429 Too many requests { "code":"too_many_requests", "message":"quota exceeded" } Foram efetuados muitos pedidos. Aguarde um momento antes de tentar novamente.

Obter detalhes de um lead

Quando o Mercado Livre notifica a criação de um novo lead relacionado com os interessados, o faz mencionando o ID na mensagem, para obter o detalhe você deve utilizar este identificador no recurso /vis/leads/$LEAD_ID. O qual proporcionará o detalhe correspondente.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/leads/$LEAD_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/vis/leads/3f2dedf2-dfbd-4981-a726-40b13aa172ff

Valores de entrada

Atributo Tipo de dado Descrição Obrigatório Valor padrão
leadID string Identificador do lead. Sim -

Campos de la respuesta

  • id: identificador do contato.
  • contact_type: tipo de contato.
  • item_id: identificador do item.
  • created_at: data em que o lead foi criado.
  • external_id: identificador externo do lead.
  • status: status do lead.
  • buyer_id: identificador do comprador.
  • name: nome do comprador. Apenas se o acesso for público.
  • email: e-mail do comprador. Apenas se o acesso for público.
  • phone: telefone do comprador. Apenas se o acesso for público.

Resposta: HTTP 200

{
    "id": "44115522",
    "item_id": "MLB4037459422",
    "created_at": "2024-02-14T00:00:00Z",
    "contact_type": "whatsapp",
    "external_id": "13864821",
    "status": "active",
    "buyer_id": 1091441589,
    "name": "Test Test",
    "email": "john@example.com",
    "phone": "+55 01 1111-1111"
}

Erros possíveis

Erros na pesquisa do detalhe do lead.

Error_code Tipo Mensagem de erro Motivos
400 Bad Request { "code": "bad_request", "message": "missing lead_id" } Identificador incorreto ou inexistente.
400 Bad Request { "code": "bad_request", "message": "invalid callerID" } O caller ID não está presente ou não está correto.
400 Bad Request { "code": "bad_request", "message": "invalid clientID" } O client ID proporcionado não está presente ou não está correto.
403 Forbidden { "code": "forbidden", "message": "invalid token caller" } Access token não pertence ao vendedor.
403 Forbidden { "blocked_by": "PolicyAgent", "path": "/vis/leads/142536", "code": "PA_UNAUTHORIZED_RESULT_FROM_POLICIES", "status": 403, "message": "At least one policy returned UNAUTHORIZED." } Acesso ao endpoint sem Access token.
403 Forbidden { "code": "forbidden", "message": "invalid token" } Access token inválido ou expirado.
404 Not Found { "code": "not_found", "message": "lead not found" } O identificador proporcionado não está associado a nenhum lead do usuário.
429 Too many requests { "code":"too_many_requests", "message":"quota exceeded" } Muitos pedidos realizados. Por favor, aguarde um momento antes de tentar novamente.