Registrar movimiento de stock

POST

/inventory/movements

curl --request POST \
  --url https://api.posdata.so/public/v1/inventory/movements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "product_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "warehouse_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "type": "in", "quantity": 1, "reason": "example", "reference": "example" }'

• Producción (keys pdk_live_)
• Pruebas (keys pdk_test_, datos de prueba, puede reiniciarse)

Suma (in) o resta (out) stock de un producto sin variantes. Cada caja aplica el movimiento una sola vez, aunque haya vendido sin conexión mientras tanto. Los productos con variantes (VARIANT_STOCK_UNSUPPORTED) y los que se arman con receta (COMPOSITE_STOCK_UNSUPPORTED) todavía no se pueden mover por la API. El cambio llega a las cajas del negocio por su sincronización normal (en segundos si están en línea; si están sin conexión, al reconectarse).

Permiso requerido: inventory:write.

Autorización

• bearerAuth

Parámetros

Parámetros de cabecera

Idempotency-Key

obligatorio

string

<= 255 caracteres /^[A-Za-z0-9_\-:.]{1,255}$/

Obligatorio en todo POST. Un valor único por operación (p. ej. un UUID); reutilízalo solo para reintentar la MISMA operación. Válido 24 h.

Cuerpo de la petición^obligatorio

Tipo de contenidoapplication/json

object

product_id

obligatorio

string formato: uuid

warehouse_id

Por defecto, la bodega predeterminada (o la única bodega activa).

string formato: uuid

type

obligatorio

in suma, out resta.

string

Valores permitidos: in out

quantity

obligatorio

En la unidad base del producto.

integer

>= 1 <= 1000000000

reason

Motivo visible en el historial. Por defecto “Movimiento vía API”.

string

<= 200 caracteres

reference

Tu referencia (orden de compra, pedido…).

string

<= 100 caracteres

Respuestas

201

Creado

Tipo de contenidoapplication/json

Movimiento del libro de inventario (solo se agregan, nunca se editan).

object

object

obligatorio

Valor permitido: stock_movement

id

obligatorio

string formato: uuid

product_id

obligatorio

string formato: uuid

variant_id

obligatorio

Cualquiera de:

string

string formato: uuid

null

null

warehouse_id

obligatorio

Cualquiera de:

string

Null si el movimiento llegó antes que su bodega.

string formato: uuid

null

null

type

obligatorio

Tipo de movimiento tal como lo registró la caja.

string

quantity

obligatorio

Cantidad en la unidad base del producto (puede ser fraccionaria).

number

reason

obligatorio

Cualquiera de:

string

string

null

null

reference

obligatorio

Cualquiera de:

string

Referencia libre del movimiento.

string

null

null

unit_cost

obligatorio

Cualquiera de:

number

Costo por unidad base al momento del movimiento.

number

null

null

origin_type

obligatorio

Cualquiera de:

string

Sale, purchase, adjustment, recipe_explosion, reversal.

string

null

null

sale_id

obligatorio

Cualquiera de:

string

La venta que causó el movimiento, si aplica.

string formato: uuid

null

null

created_at

obligatorio

string formato: date-time

updated_at

obligatorio

string formato: date-time

Ejemplo

{
  "object": "stock_movement"
}

400

Petición inválida (VALIDATION_ERROR, INVALID_JSON, INVALID_CURSOR).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

401

Sin API key válida (UNAUTHENTICATED, INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED, API_KEY_WRONG_ENVIRONMENT, ACCOUNT_INACTIVE).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

403

Sin permiso (PLAN_REQUIRED, INSUFFICIENT_SCOPE, BROWSER_REQUESTS_NOT_ALLOWED).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

409

Conflicto (CONFLICT, SKU_ALREADY_EXISTS, IDEMPOTENCY_IN_PROGRESS, NO_WAREHOUSE, DEVICES_OUTDATED).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

422

Regla de negocio o idempotencia (IDEMPOTENCY_KEY_REUSED, VARIANT_STOCK_UNSUPPORTED, COMPOSITE_STOCK_UNSUPPORTED).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

429

Límite de peticiones (RATE_LIMITED). Respeta Retry-After.

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

500

Error interno (INTERNAL_ERROR). Reintenta y comparte el request_id si persiste.

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}