Los niveles de stock, artículos, ubicaciones, movimientos, recuentos y contenedores necesitan stock.read; crear o modificar artículos y ubicaciones, y registrar una corrección, necesitan stock.write. Las recepciones necesitan inbound.read e inbound.write. Los pedidos de compra necesitan purchasing.read y purchasing.write. Las listas de preparación necesitan fulfilment.read y las tareas de equipo tasks.read.

Una clave restringida nunca recibe las nuevas partes por sí sola. Marque Compras, Preparación o Tareas en Acceso a la API cuando la clave las necesite. Las líneas de recepción solo muestran unitPrice y currency si la clave también puede leer pedidos de compra.

Una clave de API que no está restringida tiene acceso total, así que puede usar la API de stock de inmediato.

Para limitar una clave, abra Settings > Business > Merchant Channels, abra el canal de venta, pestaña Settings, bloque Acceso a la API, y marque Leer niveles de stock, artículos, ubicaciones, movimientos, recuentos y contenedores y Ajustar stock y crear o modificar artículos y ubicaciones según necesite. Consulte "Restringir una clave de API (Acceso a la API)".

Su cuenta necesita tener activado el stock de almacén de QrX. Sin él, la API responde 403 ACCESS_DENIED.

reserved es todo lo que retienen los pedidos abiertos. available es sellable menos reserved.

lastSequence es el número del último movimiento de stock de ese artículo en ese almacén. Es el mismo número que sequence en el webhook stock/adjusted.

sku debe coincidir exactamente; se ignoran las mayúsculas y minúsculas y los espacios de los extremos.

Con locationId solo obtiene los artículos que tienen stock en esa ubicación, y locationQuantity contiene las unidades que hay allí.

Indique stockItemId o sku. Debe coincidir exactamente un artículo.

Indique locationId. Una cuenta sin ubicaciones puede indicar warehouseId en su lugar, o nada para el almacén por defecto.

delta es el cambio en unidades: positivo suma, negativo resta. No puede ser 0.

reasonCode es obligatorio: correction, found, damaged, expired, defective, lost, theft, sample u other.

Para un artículo con lotes, indique lotCode y, cuando el artículo lo necesite, expiryDate.

Recepciones: GET /api/v1/receipts (filtros state, warehouseId, q), GET /api/v1/receipts/{id}, POST /api/v1/receipts (con announce: true la recepción se anuncia), PATCH /api/v1/receipts/{id}, POST .../{id}/lines, POST .../{id}/complete y POST .../{id}/cancel.

Pedidos de compra: GET /api/v1/purchase-orders, GET /api/v1/purchase-orders/{id}, POST /api/v1/purchase-orders (un borrador), PATCH .../{id}, POST .../{id}/lines, POST .../{id}/send, POST .../{id}/close y POST .../{id}/cancel. El envío funciona exactamente como en PortalX: con email: true QrX envía el PDF al proveedor (o a to), como máximo 5 veces por pedido y 30 veces por cuenta y hora (429 RATE_LIMIT_EXCEEDED).

Artículos y ubicaciones: POST y PATCH /api/v1/stock/items y /api/v1/stock/locations. Las ubicaciones necesitan Full WMS con huecos. Las filas de GET items y GET locations ahora tienen version.

Lecturas: GET /api/v1/stock/movements, GET /api/v1/picklists, GET /api/v1/counts (con /{id} y /{id}/lines), GET /api/v1/containers y GET /api/v1/tasks (con /{id}). Las tareas de equipo son de solo lectura.

Un cambio en un registro existente necesita la version que leyó por última vez. Si alguien cambió el registro mientras tanto, recibe 409: vuelva a leerlo e inténtelo de nuevo.

Almacenes (scope stock.read, WMS completo): GET /api/v1/warehouses con código, nombre, predeterminado, zona horaria, dirección, contacto, instrucciones de recepción, muelles de carga y GLN; GET /api/v1/warehouses/{id}, .../{id}/hours (horario de recepción y de expedición por día de la semana) y .../{id}/closures (con from y cursor).

Traslados (scope stock.read, WMS completo con varios almacenes y traslados): GET /api/v1/transfers (filtros state, warehouseId, direction) y GET /api/v1/transfers/{id} con las líneas y los datos de shipping. Solo lectura.

Pedidos de compra: la creación y PATCH aceptan los campos de cabecera reference, supplierReference, buyerUserId, internalNote, incoterm, incotermPlace, paymentTermsDays, shippingCost, shippingVatRate, pricesIncludeVat, deliveryAddress y partialDeliveryAllowed, y las líneas aceptan discountPct, vatRate, note, confirmedQty y confirmedOn. Los pedidos devuelven los totales (neto, IVA por tipo, bruto) calculados por QrX. La lista filtra por reference, expectedFrom y expectedTo. Las condiciones quedan fijadas una vez enviado el pedido.

Recepciones: la creación y PATCH aceptan supplierId para vincular una recepción a un proveedor; las filas lo devuelven.

Artículos de stock y ubicaciones: las escrituras de ubicaciones aceptan zone o zoneId y los campos de tamaño y capacidad; las escrituras de artículos aceptan storage, dangerousGoods, imageUrl y abcClassOverride. POST /api/v1/stock/adjust acepta sus propios códigos de motivo.

Envíe su propio texto único por corrección. Si repite la misma petición con la misma clave, recibe de nuevo la primera respuesta con replayed: true y nada se registra dos veces.

La misma clave con otro cuerpo se rechaza con 409 DUPLICATE_IDEMPOTENCY_KEY.

Una clave no puede empezar por un prefijo de sistema de QrX como mcp- ni terminar en dos puntos seguidos de dígitos (422).

Cada POST y PATCH de los recursos del almacén necesita la cabecera Idempotency-Key (1 a 140 caracteres). La misma clave con el mismo cuerpo en la misma ruta devuelve la primera respuesta, con la cabecera Idempotent-Replayed: true. Una creación repetida de una recepción o un pedido de compra devuelve el registro tal como está ahora.

Las respuestas se guardan 30 días. Una llamada fallida (4xx o 5xx) no se guarda, así que puede enviar la misma clave de nuevo.

Mientras la primera llamada con una clave sigue en curso, recibe 409 CONCURRENCY_CONFLICT con Retry-After. Una llamada que se detuvo a medias libera su clave a los 15 minutos.

Enviar un pedido de compra con email: true manda el correo al proveedor como máximo una vez por clave. Si una llamada falla después de enviar el pedido pero antes del correo, no se envía ningún correo para esa clave: revise el historial de correos del pedido en PortalX y vuelva a enviarlo con una clave nueva.

Cada lista devuelve items y nextCursor. Envíe nextCursor como cursor para la página siguiente. Null significa el final. No hay total.

Trate un cursor como un valor opaco.

Con updatedSince solo obtiene las filas modificadas en ese momento o después. El servidor examina hasta 1.000 filas por llamada, así que una página puede tener menos filas que limit, incluso ninguna, mientras nextCursor tiene valor. Siga llamando hasta que nextCursor sea null.

Cada fila tiene partnerCustomerId (el almacén del socio) y su propio id en ownerCustomerId.

Use partnerCustomerId en la query para quedarse con un socio, y warehouseId para uno de sus almacenes.

Las ubicaciones nunca se devuelven: locationId, GET locations y POST adjust responden 422 en este scope.

Necesita al menos un socio con acceso activo; su propia cuenta no necesita tener activado el stock de almacén.

401 UNAUTHORIZED: no hay un token de acceso válido.

403 STOCK_SCOPE_MISSING: la clave está restringida y no tiene stock.read o stock.write.

403 ACCESS_DENIED: el stock de almacén no está activado para la cuenta o, con scope=partner, ningún socio tiene acceso activo.

404 STOCK_NOT_FOUND: el artículo, el almacén o la ubicación no es suyo.

400 IDEMPOTENCY_KEY_REQUIRED: un POST sin la cabecera.

422 VALIDATION_FAILED: datos no válidos, por ejemplo delta 0, un código de motivo desconocido, un cursor no válido, o más de 50 artículos con el mismo SKU o EAN (filtre por stockItemId).

409 DUPLICATE_IDEMPOTENCY_KEY: la misma clave con otro cuerpo.

409 STOCK_CONFLICT: no hay stock suficiente, stock asignado a una lista de preparación, un SKU que coincide con varios artículos, o un artículo inactivo.

409 CONCURRENCY_CONFLICT: envíe de nuevo la misma petición con la misma clave.

429: demasiadas peticiones; espere Retry-After.

403 INBOUND_SCOPE_MISSING, PURCHASING_SCOPE_MISSING, FULFILMENT_SCOPE_MISSING o TASKS_SCOPE_MISSING: la clave está restringida y le falta esa parte.

404 INBOUND_NOT_FOUND, PURCHASE_ORDER_NOT_FOUND o NOT_FOUND: el registro no es suyo.

409 INBOUND_CONFLICT o PURCHASING_CONFLICT: la versión o el estado no permiten el cambio.

429 RATE_LIMIT_EXCEEDED: demasiados correos al proveedor para un pedido de compra.

400 ZONE_UNKNOWN: la zona no es una zona activa de ese almacén. 400 DG_CLASS_UNKNOWN: la clase de mercancías peligrosas no es una clase visible de su cuenta. Un motivo que necesita fotos no se puede usar a través de la API.