Receber notificações de estoque de fulfillment

Configure seu aplicativo com notificações do Mercado Livre e você pode escolher a opção fbm stock operations para se inscrever no estoque de fulfillment.

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



Nota:
A data de consulta retorna até day-1, neste caso retorna as operações desde 29.06 até 27.07, ou seja, não inclui dia 28.

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.





Próximo: Retirada em Loja.