Recibir notificaciones de stock de fulfillment

Configura tu aplicación con las notificaciones de Mercado Libre y podrás elegir la opción fbm stock operations para suscribirte a las de stock de fulfillment.

Consultar operaciones

Obtén el listado de las operaciones de stock para un inventory_id en particular.

Parámetros

inventory_id: lista de identificadores separados por coma.
seller_id: identificador del vendedor.
date_from: fecha de inicio de la búsqueda. Si no lo defines en el GET, por default son 15 días.
date_to: fecha final de búsqueda. Si no lo defines en el GET, por default es la fecha actual.
type: tipo de operación (inbound_reception, sale_confirmation, etc.)
external_references

• external_references.shipment_id: identificador del envío al comprador.

limit: cantidad de registros a devolver por “página” de resultados.
sort: identificador del campo y orden de búsqueda.

Llamada:

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

Ejemplo:

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

Ejemplo con 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?

Respuesta:

{
    "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": []
}

Reglas

• En el search de operaciones, el rango máximo de consulta son 60 días
• El filtro de fechas no es obligatorio, pero si no las pones trae los últimos 15 días

Ejemplo con filtros disponibles:

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

Ejemplo con filtros seleccionados:

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

Posibles errores

Respuesta con error:

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

Ejemplo de errores

Status	Mensaje	Error	Descripción
400	The field ‘seller_id’ is required	validation_error	No se encuentra el parámetro seller_id
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	El parámetro limit de la llamada debe ser mayor a 0
400	Date range can’t be greater than “60” days	validation_error	El rango de fechas excede el límite permitido por días
400	The field date_from and date_to are required	validation_error	Los campos date_from y date_to son requeridos
400	The field date_from and date_to are required	validation_error	El campo date_from no puede ser más grande o igual que el campo date_to
403	Access denied for user 30265782	forbidden	El caller no está autorizado a acceder al recurso
401	No autorizado	unauthorized
429	Too many request	too_many_request	El usuario ha superado el número de request permitidas por minuto
500	Internal server error	internal_error	Error interno




Modo de búsqueda por scroll

Trabajar con scroll + limit

El scroll se utiliza para obtener el listado de las operaciones de stock para un inventory_id en particular.

El limit es la cantidad de registros a devolver por “página” de resultados y scroll es el atributo que permite paginar los resultados. Para utilizarlo debes:

• Obtener en el resultado un campo scroll que expira a los 5 minutos.
• Agregar a la consulta el scroll obtenido en el primer GET. Si no utilizas el parámetro limit, por default se establece el máximo 1000 resultados por página.

Llamada para consultar las operaciones:

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

Respuesta:

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

Agregamos el scroll obtenido en el 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 seguir obteniendo las próximas páginas de resultados basta con hacer el mismo GET hasta llegar al final. Solo cuando scroll = null significa que llegamos al final y no hay más resultados.




Consultar operaciones con ID

Puedes obtener el detalle de una operación en particular ejecutada sobre el stock que el vendedor tiene almacenado en los centros de Fulfillment.

Parámetro

operation_id: identificador de id de operation

Llamada:

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

Ejemplo:

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

Respuesta:

{
    "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",
   }
     ]   
}

Ejemplo de errores

Status	Mensaje	Error	Descripción
400	Invalid operation_id abc34567	invalid_param	Parámetro inválido
403	The caller is not authorized to access this resource	forbidden	El caller no está autorizado a acceder al recurso
401	No autorizado	unauthorized	El caller no está autenticado en la plataforma
404	Operation not found	not_found	No se encuentra la operación solicitada
500	Internal server error	internal_error	Error Interno al obtener la información



Nota:
La fecha de consulta retorna hasta el día -1. En este caso, retorna las operaciones desde el 29/06 hasta el 27/07, o sea no incluye el día 28.

Campos de la respuesta

Paging


• limit: cantidad de registros a devolver por “página” de resultados. Por default será 1000
• scroll: scroll a partir del cual se continúa la búsqueda. Cuando devuelve scroll = null significa que no tiene más registros en la próxima página. Las reglas del scroll son:

- En el resultado obtienes un campo scroll que expira en 5 minutos.
- Debes agregar el mismo scroll a la consulta del campo obtenido anteriormente.
- En caso de no utilizar el parámetro limit, devolverá por defecto 1000 operaciones del total. Podrás agregar un limit máximo de 1000.
- Para seguir obteniendo las próximas páginas de resultados, basta con hacer el mismo GET a la llamada hasta llegar al final de la lista.



results: listado de operaciones encontradas.

• id: identificador de la operación de stock.
• seller_id: identificador del seller propietario del inventory.
• inventory_idd: identificador del producto en el depósito.
• date_created: fecha de creación de la operación (tipo date UTC).
• type: tipo de operación ejecutada (ingreso, venta, venta cancelada, etc.).

result: estado del stock

• available_quantity: cantidad de productos disponibles a la venta.
• not_available_quantity: total de productos que no se encuentran disponibles.
• not_available_detail: detalle del estado de las diferentes unidades no disponibles.

status: estado del ítem no disponible.
quantity: cantidad de ítems en el estado asignado.
external_references: referencias a las entidades que generan la operación.

• type: tipo de external reference, en principio pueden ser:
• shipment_id: identificador del envío al comprador.



Tipos de operaciones

Estos tipos de operaciones reflejan las interacciones de los diferentes flujos en las unidades almacenadas.




Inbound

inbound_reception Ingreso de stock: el proceso de inbound disponibiliza a la venta unidades al finalizar el flujo de ingreso. Pueden tener:
Ingreso de unidades que llegaron dañadas.
Ingreso de unidades sin cobertura fiscal (sólo para Brasil).
fiscal_coverage_ajustment: ajuste de cobertura fiscal (sólo para Brasil).




Outbound

sale_confirmation: confirma la reserva de unidades para la venta.
sale_cancelation: cancela la reserva de unidades para la venta.
sale_delivery_cancelation
Venta no entregada: no fue posible entregar al comprador y vuelve al depósito.
sale_return: devolución de ventas por parte del comprador.




Withdrawal

Se trata de la solicitud de retiro del vendedor.

withdrawal_reservation: reservan unidades para un retiro de stock.
withdrawal_cancelation: cancelación total o parcial de reserva de retiro, se cancela la reserva de unidades para un retiro de stock.
withdrawal_delivery: el vendedor retira físicamente las unidades reservadas.
withdrawal_removal: remoción de stock por retiro abandonado.
withdrawal_discarded: remoción de stock solicitado por el seller.




Transfer

Se trata del manejo interno del stock por parte de Mercado Libre, no del vendedor.

transfer_reservation: se reservan unidades para una transferencia o retiro multiwarehouse.
transfer_ajustment: luego de inspeccionar las unidades, se determina el estado de calidad y se hace el restock como available o damaged.
transfer_delivery: ingresan las unidades en transferencia.





Quarantine

Se trata del manejo interno sobre el control de calidad.

quarantine_reservation: reservan unidades por el área de calidad para inspección.
quarantine_restock: luego de inspeccionar las unidades, determina el estado de calidad y se hace el restock como available o damaged.
lost_refund: baja definitiva de unidades extraviadas (reembolsadas).
damaged_removal: remoción y reembolso por unidades dañadas en full.
disposed_tainted rezagado porque el producto está contaminado.
disposed_expired rezagado porque el producto está vencido.





Removal QA

Se trata de un retiro impulsado internamente.

removal_reservation: luego de inspeccionar las unidades, se determina el estado de calidad y se pasan a retiro.
removal_completion: se eliminan las unidades con mal estado de calidad.
stranded_disposal_removal: remoción de stock por falta de rotación.




Ajustes de stock

ajustement: ajustes internos de stock generados por la operación.
identification_problem_remove: cuando un producto fue ingresado con un SKU incorrecto. Al realizar la reidentificación, se da de baja el mismo.
identification_problem_add: cuando un producto fue ingresado con un SKU incorrecto. Al realizar la reidentificación, se da de baja el mismo, y se añade stock del nuevo SKU.





Siguiente: Envío personalizado.