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

Estoque Multi Origem

Importante:
A iniciativa estará em produção a partir de outubro de 2024, começando pelo México
Os endpoints estarão disponíveis para teste, a partir da segunda semana de setembro 2024. Será necessário simular o fluxo utilizando mocks criados desde a integração.

Uma vez liberados os endpoints poderá realizar testes ao solicitar a ambientação de seus usuários de TEST da Argentina através do seguinte formulário, as ativações serão realizadas as sextas feiras (cada 15 dias).

O Estoque Multi Origem tem como objetivo permitir representar um vendedor (seller_id) que tem mais de um local ou loja.
O endgame juntamente com a iniciativa de Preços por Variação é permitir itens de um mesmo vendedor com estoque distribuído em suas diferentes localizações.
Inclui-se o conceito de um seller_warehouse, para representar um vendedor que tem a possibilidade de contar com mais de uma localização ou loja.

Nesta documentação, você encontrará informações importantes para cada um dos fluxos que serão impactados por esta iniciativa, começando por:

  • Gestão de localizações
  • Gestão de estoque por localização

Gestão de vendedores

No início, selecionamos uma lista de vendedores que atualmente operam com múltiplos armazéns, que terão esta experiência disponível, permitindo-lhes assim gerir as suas localizações ou lojas.
Para identificar os usuários que estão configurados com mais de uma localização ou loja, utilizaremos o tag warehouse_management no user_id.
Consulte a api de users para saber se um usuário opera em modo multi origem.


Chamada:

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

Exemplo:

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

Resposta:


{
    "id": 1008002397,
    "nickname": "TETE9326760",
    "registration_date": "2021-10-27T14:48:55.000-04:00",
    "first_name": "Test",
    "last_name": "Test",
    "gender": "",
    "country_id": "MX",
    "email": "test_user_19653740@testuser.com",
    "identification": {...},
    "address": {...},
    "phone": {...},
    "alternative_phone": {...},
    "user_type": "normal",
    "tags": [
        "normal",
        "warehouse_management",
        "mshops",
        "messages_as_seller"
    ],
    "logo": null,
    "points": 1,
    "site_id": "MLM",
    "permalink": "http://perfil.mercadolibre.com.mx/TETE9326760",
    "seller_experience": "NEWBIE",
    "bill_data": {...},
    "seller_reputation": {...},
    "buyer_reputation": {...},
    "status": {...},
    "secure_email": "ttest.y25p1f@mail.mercadolibre.com.mx",
    "company": {...},
    "credit": {...},
    "context": {...},
    "registration_identifiers": []
}

Gestão de localizações

No início, selecionamos uma lista de vendedores que atualmente operam com múltiplos armazéns, que terão esta experiência disponível, permitindo-lhes assim gerir as suas localizações ou lojas.

Nota:
A possibilidade de criar localizações para um mesmo seller_id está disponível apenas pela conta de cada vendedor por meio do front do Mercado Livre.

Cada vendedor manterá uma única logística base, ou seja, um vendedor com várias localizações operará, por exemplo, em (cross_docking) Mercado Envios Coleta. Por outro lado, o fluxo de Estoque Multi Origem não se aplica para Mercado Envios1.


Busca de lojas de um usuário

Para identificar as lojas criadas por cada usuário, você poderá utilizar o seguinte endpoint:

Chamada:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/stores/search?tags=stock_location -H 'Authorization: Bearer $ACCESS_TOKEN'

Exemplo:

curl -X GET https://api.mercadolibre.com/users/1008002397/stores/search?tags=stock_location -H 'Authorization: Bearer $ACCESS_TOKEN'

Resposta:


{
    "paging":
    {
        "limit": 50,
        "total": 2,
    },
    "results":
    [
        {
            "id": "100",
            "user_id": "200",
            "description": "minha loja",
            "status": "active",
            "location": {
                "address_id": 501,
                "address_line": "Calle 31 Pte 260",
                "street_name": "Calle 31 Pte",
                "street_number": 260,
                "latitude": 21.1637963,
                "longitude": -86.8737132,
                "city": "Cancún/Benito Juárez",
                "state": "Quintana Roo",
                "country": "Mexico",
                "zip_code": "77518"
            },
            "tags": [
                "stock_location" 
            ],
            "network_node_id": "MXP123451"
        },
        {
            "id": "101",
            "user_id": "200",
            "description": "minha loja 2",
            "status": "active",
            "location": {
                "address_id": 502,
                "address_line": "Calle 30 Pte 300",
                "street_name": "Calle 30 Pte",
                "street_number": 300,
                "latitude": 21.1637963,
                "longitude": -86.8737132,
                "city": "Cancún/Benito Juárez",
                "state": "Quintana Roo",
                "country": "Mexico",
                "zip_code": "77518"
    },
    "tags": [
        "stock_location" 
    ],
    "network_node_id": "571615"
}

Criação de itens Multiwarehouse

Nota:
Se você usar o POST atual para publicar um item multiwarehouse, ele ficará com status: “paused” e substatus: “out_of_stock” até que o PUT seja realizado para atualizar o estoque e distribuí-lo por loja. O campo "available_quantity” será desconsiderado.

Para a criação de novos itens, tanto tradicionais quanto de catálogo (itens com “catalog_listing”:true e “catalog_product_id”), os vendedores com a tag "warehouse_management" (configuração de multi-origem) podem usar o seguinte recurso, que será responsável pela criação do item e pela atribuição de estoque às lojas.


Chamada:

curl POST --'https://api.mercadolibre.com/items/multiwarehouse' -H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -d 
{
    "title": "Item Lata de tomate ",
    "category_id": "MLB455668",
    "price": 1000,
    "listing_type_id": "gold_special",
    "currency_id": "ARS",
    ...
    "channels": [
        "marketplace"
    ],
    "stock_locations": [
        {
            "store_id": "0001",
            "network_node_id": "MXP123451",
            "quantity": 10
        },
        { 
            "store_id": "0002",
            "network_node_id": "MXP571615",      
            "quantity": 5
        },
        { 
            "store_id": "0003",
            "network_node_id": "MXP725258",
            "quantity": 20
        }
    ] 
}

Considerações:

  • Tanto o store_id quanto o network_node_id estarão na resposta da busca pelas lojas do vendedor.

Gestão de estoque por localização

Nota:
Ao consultar o detalhe de estoque, será retornado um header chamado "x-version", o qual terá um valor inteiro (do tipo long) que representará a versão atual de /stock. Este header deve ser enviado ao realizar chamadas PUT em /stock. Se não for enviado, retornará um bad request (status code: 400). Adicionalmente, caso a versão enviada não seja a última, retornará um conflict (status code: 409).

Para modificar o estoque por localização, utilize a seguinte chamada, é necessário enviar o user_product_id, o store_id e o network_node_id.



Se a loja não tiver estoque atribuído previamente, será atribuída esta quantidade. Se a loja já tiver estoque atribuído, será atribuída a nova quantidade indicada.


Chamada:

curl -X PUT https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID/stock/type/seller_warehouse -H 'x-version: $HEADER' -H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -d '{
"locations": [
   {
        "store_id": "0001",
        "network_node_id": "",
        "quantity": $STOCK_QUANTITY
   },
   { 
        "store_id": "0002",
        "network_node_id": "",
        "quantity": $STOCK_QUANTITY
   },
   { 
        "store_id": "0003",
        "network_node_id": "",
        "quantity": $STOCK_QUANTITY
   }
]
}

Exemplo:

curl -X PUT https://api.mercadolibre.com/user-products/MLBU206642488/stock/type/seller_warehouse -H 'x-version: 1' -H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -d '{
{
"locations": [
   {
        "store_id": "0001",
        "network_node_id": "MXP123451",
        "quantity": 10
   },
   { 
        "store_id": "0002",
        "network_node_id": "MXP571615",
        "quantity": 5
   },
   { 
        "store_id": "0003",
        "network_node_id": "MXP725258",
        "quantity": 20
   }
]
}

Diante de qualquer erro nas validações, não vamos persistir a informação de estoque enviada e retornaremos erro com o detalhe do motivo da falha de cada uma das lojas:


Exemplo de erro 400 Bad Request:

{
  "message": "[store does not belong to seller: 3242,523423 - store not found: 777 - store is not configured to be a stock location: 5344,62222]"
  "error": "bad_request",
  "status": 400
}

Mensagens de erro possíveis:

  • “store does not belong to seller: {store_id1, store_id2,...}”: Indica que as lojas não pertencem ao mesmo vendedor do produto.
  • “store not found: {store_id1, store_id2,...}”: Indica que as lojas não existem ou foram desativadas.
  • “store is not configured to be a stock location: {store_id1, store_id2,...}”: Indica que as lojas não estão configuradas para multi-origem.
  • “invalid network_node_id for stores: {store_id1, store_id2,...}”: Indica que o node enviado não corresponde ao atribuído à loja.

Obter detalhe do estoque

Para consultar o estoque das lojas, você pode utilizar o seguinte endpoint indicando o user product.

Chamada:

curl -X GET https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID/stock -H 'Authorization: Bearer $ACCESS_TOKEN'

Exemplo:


{
   "locations": [
       {
           "type": "seller_warehouse",
           "network_node_id": "MXP123451",
           "store_id": 9876543,
           "quantity": 15
       },
       {
           "type": "seller_warehouse",
           "network_node_id": "MXP571615",
           "store_id": 9876553,
           "quantity": 15
       }
   ],
   "user_id": 1234,
   "id": "MLBU206642488"
}