Stock actualizado

Identificador del evento: stock.updated

En pocas palabras

IDPOS le avisa de que cambió el stock de un ítem en un almacén. El aviso trae el stock total que quedó, no la diferencia, junto con los identificadores del ítem y del almacén en el canal de venta externo al que están vinculados.

Cuándo llega

Cada vez que cambia el stock de un ítem en un almacén de IDPOS, por ejemplo por una venta, una compra, un ajuste o un traslado. Llega un evento por cada ítem que cambia. Si el stock de un mismo ítem y almacén cambia varias veces dentro del mismo segundo, IDPOS puede unificar esos cambios en un solo evento: recibirá como máximo un evento por segundo por ítem y almacén.

Solo llega cuando se cumplen estas condiciones:

Condición	Cómo se reconoce
El almacén está vinculado a un canal de venta externo.	Trae warehouse_remote_id. Los almacenes sin vínculo no generan el evento.
El ítem tiene su identificador en ese canal.	Trae item_remote_id.
El cambio se origina en IDPOS.	Los cambios de stock que provienen de una integración externa no generan el evento.

Importante: trae el stock total, no la diferencia

quantity es el stock total del ítem en ese almacén en el momento en que IDPOS prepara el aviso. No es lo que se sumó ni lo que se restó: no lo acumule. Reemplace con este valor el stock que tiene guardado.

quantity es un número entero: la parte decimal se descarta. Un stock de 2,7 llega como 2.

Para qué le sirve

• Mantener el stock de su tienda en línea o de su canal de venta externo igual al de IDPOS.
• Evitar vender un ítem que ya no tiene stock en el almacén.
• Conciliar el inventario de su sistema con el de IDPOS por ítem y por almacén.

Qué hacer al recibirlo

1. Verifique la firma.

   Calcule el HMAC con el cuerpo crudo y compárelo con X-Webhook-Signature. Si no coincide, no procese el evento. Los pasos están en Autenticación y firma.

2. Responda 2xx de inmediato.

   Guarde el evento en una cola y responda sin esperar a procesarlo. Si tarda más que el tiempo de espera, IDPOS lo trata como fallido y lo reintenta.

3. Descarte los duplicados.

   Si ya procesó ese event_id del cuerpo, ya verificado, no lo procese otra vez.

4. Procese el evento en segundo plano.

   Guarde quantity como el stock actual del ítem (item_uuid) en el almacén (warehouse_uuid). Para actualizar su canal externo, use item_remote_id y warehouse_remote_id. Como quantity es el total, procesar dos veces el mismo evento no cambia el resultado.

Cómo descartar duplicados y quedarse con el dato más reciente

Este evento no trae data.id, así que no aplica la segunda clave event_type + data.id de otros eventos.

Necesidad	Qué usar
Descartar un evento repetido	El event_id del cuerpo, después de verificar la firma.
Quedarse con el stock más reciente	El timestamp del sobre: es la fecha y hora en que IDPOS generó el evento y no cambia entre reintentos. Compárelo por cada par item_uuid y warehouse_uuid y descarte el evento si es más antiguo que el que ya aplicó.

No use item_uuid y warehouse_uuid como clave para descartar duplicados. Identifican el stock del ítem en el almacén, y cada cambio nuevo llega como un evento distinto con esos mismos valores.

Ejemplo

stock.updated.json

{
  "event_id": "01J9ZP4R6T8V2X5Z7B9D1F3H5K",
  "event_type": "stock.updated",
  "timestamp": "2026-10-12T16:20:07Z",
  "api_version": "v1",
  "data": {
    "item_uuid": "3e5a7c9b-1d3f-4a5b-8c7d-9e1f3a5b7c92",
    "item_sku": "BEB-001",
    "item_name": "Gaseosa 500 ml",
    "warehouse_uuid": "5f7b9d1a-3c5e-4b7a-9d2f-1a3c5e7b9d04",
    "warehouse_name": "Almacén principal",
    "quantity": 38,
    "item_remote_id": "49012345678901",
    "warehouse_remote_id": "71234567890"
  }
}

Campos

Cómo leer las tablas: el tipo aparece debajo del nombre del campo y «nulo» indica que puede venir como null. Los demás términos están en la guía de lectura de campos.

Sin tienda ni fecha del cambio

Este evento no trae el objeto store ni una fecha del cambio. El almacén (warehouse_uuid) indica dónde cambió el stock.

Ítem

Campo	Descripción
item_uuid string (UUID)	Identificador del ítem en IDPOS
item_sku string	Código del ítem (SKU)
item_name string	Nombre del ítem

Almacén

Campo	Descripción
warehouse_uuid string (UUID)	Identificador del almacén en IDPOS
warehouse_name string	Nombre del almacén

Stock

Campo	Descripción
quantity entero	Stock total del ítem en el almacén. No es la diferencia. La parte decimal se descarta

Canal de venta externo

Campo	Descripción
item_remote_id string	Identificador del ítem en el canal de venta externo
warehouse_remote_id string	Identificador del almacén en el canal de venta externo