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 28/08/2024

Envios Fulfillment

Importante:
Atualmente, essa modalidade de envio está disponível para vendedores da Argentina, Brasil, México, Chile e Colômbia.

Envios Full é um serviço integral do Mercado Livre, projetado para simplificar e otimizar a gestão logística dos vendedores. Com o Envios Full, não apenas cuidamos dos seus envios, mas também armazenamos o seu estoque e preparamos cada pedido para envio imediato assim que a venda é concretizada.


Saiba mais sobre:

Obter el inventory_id

Para consultar o estoque e as operações do item no fulfillment, você deve primeiro obter o inventory_id, que é o código que identifica o item quando ele está em execução. Para isso, consulte o inventory_id através do recurso /items.

Nota:
Quando o item possui variações, terá uma identificação de inventory_id por variação

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB1557246024

Resposta:

{
  "id": "MLB1557246024",
  "site_id": "MLB",
  "title": "Kit Capa Chuva Test 228",
  "subtitle": null,
  "seller_id": 384324657,
  "category_id": "MLB22675",
  "official_store_id": null,
  "price": 87,
  "base_price": 87,
  "original_price": null,
  "inventory_id": "LCQI05831",
  "currency_id": "BRL",
  "initial_quantity": 50,
  "available_quantity": 50,
  "sold_quantity": 0,
  "sale_terms": []
}

Consultar o estoque do vendedor

Além, você pode verificar o estoque total de um vendedor em todos os depósitos de fulfillment e descobrir o status de peças não disponíveis.

Nota:
Lembre-se que só disponibilizamos a informação correspondente aos últimos 12 meses, considerando o dia atual da consulta.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/inventories/$INVENTORY_ID/stock/fulfillment

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/inventories/LCQI05831/stock/fulfillment

Resposta:

{
    "inventory_id": "LCQI05831",
    "total": 20,
    "available_quantity": 5,
    "not_available_quantity": 15,
    "not_available_detail":[
        {
            "status": "damage",
            "quantity": 2
        },
        {
            "status": "lost",
            "quantity": 1
        },
        {
            "status": "noFiscalCoverage"
            "quantity": 5
        },
        {
            "status": "withdrawal",
            "quantity": 5
        },
        {
            "status": "internal_process",
            "quantity": 1
        },
        {
            "status": "transfer",
            "quantity": 1
        }
    ],
    "external_references": [
        {
        "type": "item",
        "id": "MLB1557246024",
        "variation_id": 4742223403
      }
   ]
}

Campos da resposta

total: é a soma dos campos available_quantity y not_available_quantity.
available_quantity: quantidade de ítems disponíveis para venda.
not_available_quantity: total de itens não disponíveis para venda.
not_available_detail: detalhe de status dos ítems não disponíveis.

  • damaged: total dos itens corrompido (inclui damaged seller, meli e carrier).
  • lost: total dos itens que foram perdidos e não foram encontrados.
  • withdrawal: total de itens reservados para retirada.
  • internal_process: total de itens reservados por processos de qualidade de depósito.
  • transfer: total reservado a ser transferido do depósito.
  • noFiscalCoverage: total de itens que não estão à venda porque não têm cobertura fiscal ou tributária.
  • not_supported: todos os itens inseridos são não identificáveis ​​ou processáveis.
external_references: informações sobre a relação do inventory com a publicação no marketplace e uma identificação de tipo.
type: tipo de relacionamento entre publicação e estoque armazenado.
id: identificador do item relacionado ao inventory.
variation_id: identificador da variação associada ao inventory.



Erros

Resposta com erro:

{
    "status": 403,
    "error": "forbidden",
    "message": "User 281349747 cannot access to seller_product ESZJ28231",
    "cause": []
}

Possíveis erros

Status Mensagem Erro Descrição
404 Inventory not found with id: ESZJ28232 seller_product_not_found O inventory não foi encontrado
400 The field inventory_id has an invalid value validation_error Parâmetro inválido
403 The caller is not authorized to access this resource forbidden O caller não está autorizado a acessar o recurso
401 No autorizado unauthorized O caller não está autenticado na plataforma
429 Too many request too_many_request O usuário excedeu o número de request permitidas por minuto
500 Internal server error internal_error Erro interno ao obter as informações

Consultar detalhe do estoque não disponível

Este recurso retorna informações adicionais sobre as unidades armazenadas que não estão disponíveis para venda, descrevendo alguns atributos ou condições particulares destes.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/inventories/$INVENTORY_ID/stock/fulfillment?include_attributes=conditions

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/inventories/YLXH33638/stock/fulfillment?include_attributes=conditions

Resposta:

{
  "inventory_id": "YLXH33638",
  "total": 20,
  "available_quantity": 5,
  "not_available_quantity": 15,
  "not_available_detail": [
    {
      "status": "damaged",
      "quantity": 2,
      "conditions": [
        {
          "condition": "arrived_damaged",
          "quantity": 1
        },
        {
          "condition": "damaged_in_full",
          "quantity": 1  (meli+carrier)
        }
      ]
    },
    {
      "status": "lost",
      "quantity": 1
    },
    {
      "status": "not_supported",
      "quantity": 3,
      "conditions": [
        {
          "condition": "dimensions_exceeds",
          "quantity": 1
        },
        {
          "condition": "flammable",
          "quantity": 1
        },
        {
          "condition": "multiple_identifier",
          "quantity": 1
        }
      ]
    }
  ]
}

Os status possíveis são damaged, not_supported, lost, withdrawal, no_fiscal_coverage, internal_process e transfer.

Os status com informações adicionais são:

Damaged: Possui informações sobre as unidades danificadas armazenadas no centro de distribuição que permite aos integradores atuarem se estão danificadas no centro ou se chegaram danificadas.
Not supported: Possui informações de produtos not supported (NS) em estoque, ou seja, produtos que não podem ser colocados à venda por problema de identificação ou por pertencerem a categorias inadequadas.

Saiba mais sobre as condições pelas quais identificamos um produto como danificado ou não atende aos requisitos para entrar no centro de distribuição. Também se aplica aos produtos inseridos e que posteriormente detectamos um problema.

Status Not available Condition Descrição do produto
damaged arrived_damaged Chegou danificado pelo vendedor
damaged_in_full Está danificado dentro do centro ou pela transportadora (carrier)
not supportted dimensions_exceeds Excede as dimensões de armazenamento permitidas do centro de processamento
expiration_problem Teve um problema relacionado ao seu vencimento
package_problem Não há embalagem ou não é apropriado para o centro de distribuição
flammable É inflamável ou explosivo
regulation_problem Não cumpre os regulamentos para o tipo de produto, por exemplo, selo de saúde
other Qualquer condição não especificada nos pontos anteriores
multiple_identifier Tem o código universal duplicado (EAN)
empty_identifier Não tem ID / etiqueta de vendedor ou EAN no banco de dados do centro
multiple_sku Tem dois ou mais SKUs do Mercado Livre
invalid_identifier Tem o código universal errado
return_problem Foi devolvido pelo comprador por não atender à qualidade especificada na venda

Consultar operações

Em seguida, você pode obter a lista de operações de estoque para um determinado inventory_id.


Parâmetros

inventory_id: listagem de identificadores separados por vírgula.
seller_id: identificador do vendedor.
date_from: data de início da pesquisa. Se não definido no GET, por padrão, são 15 dias.
date_to: data de término da pesquisa. Se não definido no GET, por padrão, é a data atual.
type: tipo de operação (inbound_reception, sale_confirmation, etc.)
external_references

  • external_references.shipment_id: identificador de envio ao comprador.

limit: quantidade de registros a serem retornados por "página" dos resultados.
sort: identificador de campo e ordem de pesquisa.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/stock/fulfillment/operations/search?seller_id=$SELLER_ID&inventory_id=$INVENTORY_ID&date_from=$aaammdd&date_to=$aaammdd

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/stock/fulfillment/operations/search?seller_id=384324657&inventory_id=DEHW09303&date_from=2020-06-01&date_to=2020-06-30

Exemplo com filtros:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/stock/fulfillment/operations/search?seller_id=384741716&inventory_id=NFWV18668&date_from=2020-06-29&date_to=2020-07-28&type=SALE_CONFIRMATION&external_references.shipment_id=1111?

Resposta:

{
    "paging": {
        "total": 4,
        "scroll": ""
    },
    "results": [
        {
            "id": 306811273,
            "seller_id": 384324657,
            "inventory_id": "DEHW09303",
            "date_created": "2020-06-18T18:43:26Z",
            "type": "ADJUSTMENT",
            "detail": {
                "available_quantity": -5,
                "not_available_quantity": 5,
                "not_available_detail": [
                    {
                        "status": "lost",
                        "quantity": 5
                    }
                ]
            },
            "result": {
                "total": 100,
                "available_quantity": 95,
                "not_available_quantity": 5,
                "not_available_detail": [
                    {
                        "status": "lost",
                        "quantity": 5
                    }
                ]
            },
            "external_references": []
        },
        {
            "id": 306745917,
            "seller_id": 384324657,
            "inventory_id": "DEHW09303",
            "date_created": "2020-06-18T18:15:13Z",
            "type": "SALE_CANCELATION",
            "detail": {
                "available_quantity": 10,
                "not_available_detail": []
            },
            "result": {
                "total": 100,
                "available_quantity": 100,
                "not_available_quantity": 0,
                "not_available_detail": []
            },
            "external_references": [
                {
                    "type": "shipment_id",
                    "value": "28312959315"
                }
            ]
        },
        {
            "id": 306718974,
            "seller_id": 384324657,
            "inventory_id": "DEHW09303",
            "date_created": "2020-06-18T18:02:33Z",
            "type": "SALE_CONFIRMATION",
            "detail": {
                "available_quantity": -10,
                "not_available_detail": []
            },
            "result": {
                "total": 90,
                "available_quantity": 90,
                "not_available_quantity": 0,
                "not_available_detail": []
            },
            "external_references": [
                {
                    "type": "shipment_id",
                    "value": "28312961122"
                }
            ]
        },
        {
            "id": 306705012,
            "seller_id": 384324657,
            "inventory_id": "DEHW09303",
            "date_created": "2020-06-18T17:55:42Z",
            "type": "INBOUND_RECEPTION",
            "detail": {
                "available_quantity": 100,
                "not_available_detail": []
            },
            "result": {
                "total": 100,
                "available_quantity": 100,
                "not_available_quantity": 0,
                "not_available_detail": []
            },
            "external_references": [
                {
                    "type": "inbound_id",
                    "value": "0001"
                }
            ]
        }
    ],

    "filters": [],
    "available_filters": [],
    "available_sort": [],
    "sort": [], 
    "available_sorts": []
}

Regras

  • Na pesquisa de operações, o intervalo máximo de consulta é 60 dias
  • O filtro de data não é obrigatório, mas se não colocar retorna os últimos 15 dias
  • Exemplo com filtros disponíveis:

    "available_filters": [
            {
                "id": "inventory_id",
                "name": "Inventory  id"
            },
            {
                "id": "date_from",
                "name": "Date created from"
            }
    ]

    Exemplo com filtros selecionados:

    "filters": {      
            {
               "id": "inventory_id",
                "name": "Inventory  id"
                "values": [
                      "ESZJ28231"
                ]
            }
    ]

    Possíveis erros

    Resposta com erro:

    {
        "status": 403,
        "message": "User 281349747 cannot access to inventory ESZJ28231",
        "error": "forbidden",
        "cause": []
    }

    Exemplos de erros

    Status Mensagem Erro Descrição
    400 The field ‘seller_id’ is required validation_error O parâmetro seller_id não foi encontrado
    400 The field ‘type’ has an invalid value validation_error Parâmetro inválido
    400 The limit param must be greater than 0 validation_error O parâmetro limite da chamada deve ser maior que 0
    400 Date range can’t be greater than “60” days validation_error O intervalo de datas excede o limite permitido por dias
    400 The field date_from and date_to are required validation_error Os campos date_from e date_to são obrigatórios
    400 The field date_from and date_to are required validation_error O campo date_from não pode ser maior ou igual ao campo date_to
    403 Access denied for user 30265782 forbidden O chamador não está autorizado a acessar o recurso
    401 No autorizado unauthorized
    429 Too many request too_many_request O usuário excedeu o número de solicitações permitidas por minuto
    500 Internal server error internal_error Erro interno


    Modo de pesquisa pelo scroll

    Trabalhar com scroll + limit

    O scroll é utilizado para obter a listagem das operações de stock para um inventory_id específico.

    O limit é a quantidade de registros a serem retornados por "página" de resultados e scroll é o es el atributo que permite paginar os resultados. Para usar você deve:

    • Obtenha um campo scroll no resultado que expira após 5 minutos.
    • Adicione o scroll conseguido no primeiro GET à consulta. Se você não usar o parâmetro limit, por padrão, o máximo de 1000 resultados por página será definido.

    Chamada para consultar as operações:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/stock/fulfillment/operations/search?seller_id=$SELLER_ID&inventory_id=$INVENTORY_ID&date_from=$aaammdd&date_to=$aaammdd

    Resposta:

    "scroll":"YXBpY29yZS1pdGVtcw==:ZHMtYXBpY29yZS1pdGVtcy0wMQ==:DXF1ZXJ5QW5kRmV0Y2gBAAAAABIu7AgWMXl6anF3SU5SMVNaQXFxTkZubHBqQQ=="

    Adicionamos o scroll conseguido no paso anterior:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/stock/fulfillment/operations/search?seller_id=$SELLER_ID&inventory_id=$INVENTORY_ID&date_from=$aaammdd&date_to=$aaammdd&scroll=YXBpY29yZS1pdGVtcw==:ZHMtYXBpY29yZS1pdGVtcy0wMQ==:DXF1ZXJ5QW5kRmV0Y2gBAAAAABIu7AgWMXl6anF3SU5SMVNaQXFxTkZubHBqQQ==

    Para continuar obtendo as próximas páginas de resultados, faça o mesmo GET até chegar ao fim. Somente quando scroll = null significa que chegamos ao fim e não há mais resultados.


    Consultar operações com ID

    Você pode obter os detalhes de uma determinada operação executada no estoque que o vendedor armazenou nos centros de distribuição Fulfillment.


    Parâmetros


    operation_id: identificador de id de operation


    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/stock/fulfillment/operations/$OPERATION_ID

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/stock/fulfillment/operations/329663159

    Resposta:

    {
        "id": "329663159",
        "seller_id": 404584692,
        "inventory_id": "FIWU34511"
        "date_created": "2020-06-29T13:45:13Z"
        "type": "SALE_CONFIRMATION"   
        "detail":{
               "available_quantity": -1
         "not_available_detail":[]
         },
        "result":{
               "total": 1
               "available_quantity": 0
         "not_available_detail":[
             {
                "status": "damaged",
                "quantity": 1,
             }
         ]
         },
         "external_references":[
       {
          "type": "shipment_id",
          "value": "28518304587",
       }
         ]   
    }

    Exemplo de erros

    Status Mensagem Erro Descrição
    400 Invalid operation_id abc34567 invalid_param Parâmetro inválido
    403 The caller is not authorized to access this resource forbidden O chamador não está autorizado a acessar o recurso
    401 No autorizado unauthorized O autor da chamada não está autenticado na plataforma
    404 Operation not found not_found A operação solicitada não pode ser encontrada
    500 Internal server error internal_error Erro interno ao obter as informações

    Campos da resposta

    Paging

    • limit: quantidade de registros a serem retornados por “página” dos resultados. Por padrão, será 1000.
    • scroll: scroll a partir do qual a pesquisa continua. Quando devolve scroll = null significa que não tem mais registros na próxima página. As regras são:

    - No resultado, vai obter um campo scroll que expira em 5 minutos.
    - Deverá adicionar à consulta scroll igual ao campo obtido anteriormente.
    - Se não utilizar o parâmetro limit, serão restituídos por defeito 1000 itens do total. Você poderá adicionar um limite máximo de 1000.
    - Para continuar obtendo as próximas páginas de resultados, é só fazer o mesmo GET à chamada até chegar ao fim da listagem.

    results: listagem das operações encontradas.

    • id: identificador de operação de estoque.
    • seller_id: identificador do vendedor.
    • inventory_id: identificador do produto no depósito.
    • date_created: data de criação da operação (tipo date UTC).
    • type: tipo de operação executada (ingresso, venda, venda cancelada etc.).

    result: status de estoque.

    • available_quantity: quantidade de produtos disponíveis para venda.
    • not_available_quantity: total de produtos que não são disponíveis.
    • not_available_detail: detalhe de status das diferentes unidades não disponíveis.

    status: estado do item não disponível.
    quantity: quantidade de itens no status atribuído.
    external_references: referências às entidades que geram a operação.

    • type: a princípio eles podem ser do tipo "external reference".
    • shipment_id: identificador do envio para o comprador.

    Tipos de operações

    Esses tipos de operações refletem as interações dos diferentes fluxos nas unidades armazenadas.


    Inbound

    inbound_reception Novo estoque: o processo inbound disponibiliza unidades para venda no fluxo de acesso. Podem ter:
    Entrada de unidades que chegaram danificadas.
    Entrada de unidades sem cobertura tributária (aplica-se apenas ao Brasil).
    fiscal_coverage_ajustment: ajuste de cobertura tributária (aplica-se apenas ao Brasil).


    Outbound

    sale_confirmation: confirma a reserva de unidades para venda.
    sale_cancelation: cancelar a reserva de unidades para la venda.
    sale_delivery_cancelation
    Venda não entregue: não foi possível entregar ao comprador e devolver o depósito.
    sale_return: devolução de vendas pelo comprador.


    Withdrawal

    Este é o pedido de retirada do vendedor.

    withdrawal_reservation: unidades de reserva para retirada de estoque.
    withdrawal_cancelation: cancelamento total ou parcial da reserva de retirada, a reserva de unidades para retirada de estoque é cancelada.
    withdrawal_delivery: o vendedor remove fisicamente as unidades reservadas.
    withdrawal_removal: remoção do estoque por abandono de retirada.
    withdrawal_discarded: retirada de estoque solicitada pelo vendedor.


    Transfer

    Este é a ação interna do estoque do Mercado Livre, não do vendedor.

    transfer_reservation: unidades são reservadas para transferência ou retirada multiwarehouse.
    transfer_ajustment: após inspecionar as unidades, o status da qualidade é determinado e o reabastecimento é available ou damaged.
    transfer_delivery: unidades entram em transferência.


    Quarantine

    É a gestão interna do controle de qualidade.

    quarantine_reservation: reservam unidades pela área de qualidade para inspeção.
    quarantine_restock: após inspecionar as unidades, determine o status da qualidade e reabasteça como available ou damaged.
    lost_refund: retirada definitiva de unidades perdidas (reembolsadas).
    damaged_removal: remoção e reembolso por unidades danificadas no full.
    disposed_tained defasado porque o produto está contaminado.
    disposed_expired defasado porque o produto está vencido.


    Removal QA

    É uma saída gerenciada internamente.

    removal_reservation: após inspecionar as unidades, o status da qualidade é determinado e eles são retiradas.
    removal_completion: unidades com baixa qualidade são removidas.
    stranded_disposal_removal: retirada de estoque por falta de rotação.


    Ajustes de estoque

    ajustement: ajustes internos de estoque gerados pela operação.
    identification_problem_remove: quando um produto foi inserido com um SKU incorreto. Ao realizar a reidentificação ela é cancelada.
    identification_problem_add: quando um produto foi inserido com um SKU incorreto. Ao realizar a reidentificação, a assinatura é cancelada e o estoque do novo SKU é adicionado.