Estoque Multi Origem

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.

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

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

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"
}