Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 18/10/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.


Importante:
No caso de você já ter uma integração com a API de Perguntas e tratar as perguntas como notificação de contato (Leads), recomendamos que, ao se inscrever no tópico de Leads, você não ative as notificações de Perguntas, para evitar duplicidade nos 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,whatsapp

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.identification_number: número de identificação do comprador. Apenas se o acesso for público.
  • results.identification_type: tipo de identificação do comprador. Apenas se o acesso for público.
  • results.leads: contém uma lista do leads gerados pelo comprador.
  • leads.id: identificados do lead.
  • 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.
  • call: um comprador aperta o botão de ligar.
  • credit: simulação de crédito.
  • Resposta:

    {
        "results": [
            {
                "id": 2678328,
                "item_id": "MLA1430828018",
                "name": "John Doe",
                "email": "jhon@example.com",
                "phone": "+5491198765432",
                "leads": [
                    {
                        "id": "6b4aebf8-5570-47b8-9224-c1c177621575",
                        "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.