Compartir a través de

API públicas de Visibilidad de inventario

  • Artículo

Nota

Azure Active Directory ahora es Microsoft Entra ID. Más información

Este artículo describe las API públicas que proporciona Visibilidad de inventario.

La API de REST pública del complemento de visibilidad de inventario presenta varios puntos finales específicos para integración. Admite cuatro tipos principales de interacción:

  • Publicar cambios de inventario disponible en el complemento desde un sistema externo
  • Establecer o anular las cantidades de inventario disponibles en el complemento desde un sistema externo
  • Registrar eventos de reserva en el complemento desde un sistema externo
  • Consultar cantidades actuales disponibles desde un sistema externo

En la tabla siguiente se muestran las API actualmente disponibles:

Ruta de acceso Método Description
/api/environment/{environmentId}/onhand Publicar Crear un evento de cambio de inventario disponible
/api/environment/{environmentId}/onhand/bulk Publicar Crear varios eventos de cambio
/api/environment/{environmentId}/setonhand/{inventorySystem}/bulk Publicar Establecer/reemplazar cantidades disponibles
/api/environment/{environmentId}/onhand/reserve Publicar Crear un evento de reserva no en firme
/api/environment/{environmentId}/onhand/reserve/bulk Publicar Crear varios eventos de reserva no en firme
/api/environment/{environmentId}/onhand/unreserve Publicar Revertir un evento de reserva no en firme
/api/environment/{environmentId}/onhand/unreserve/bulk Publicar Revertir varios eventos de reserva no en firme
/api/environment/{environmentId}/onhand/reserve/resyncjob Publicar Limpieza de datos de reserva
/api/environment/{environmentId}/onhand/changeschedule Publicar Crear un cambio de inventario disponible programado
/api/environment/{environmentId}/onhand/changeschedule/bulk Publicar Crear múltiples cambios de inventario disponible con fechas
/api/environment/{environmentId}/onhand/indexquery Publicar Consulta mediante el método POST (recomendado)
/api/environment/{environmentId}/onhand Obtener Consulta mediante el método GET
/api/environment/{environmentId}/onhand/exactquery Publicar Consulta exacta mediante el método POST
/api/environment/{environmentId}/allocation/allocate Publicar Crear un evento de asignación
/api/environment/{environmentId}/allocation/unallocate Publicar Crear un evento de desasignación
/api/environment/{environmentId}/allocation/reallocate Publicar Crear un evento de reasignación
/api/environment/{environmentId}/allocation/consume Publicar Crear un evento de consumo
/api/environment/{environmentId}/allocation/query Publicar Resultado de asignación de consulta
/api/environment/{environmentId}/onhand/productsearch/indexquery Publicar Consulta de índice de publicaciones con búsqueda de productos
/api/environment/{environmentId}/onhand/productsearch/exactquery Publicar Consulta exacta de publicaciones con búsqueda de productos

Nota

La parte {environmentId} de la ruta es el id. de entorno en Microsoft Dynamics Lifecycle Services

La API masiva puede devolver un máximo de 512 registros para cada solicitud.

Autenticación

El token de seguridad de la plataforma se utiliza para llamar a la API pública de Visibilidad de inventario. Por lo tanto, debe generar un token de Microsoft Entra usando su aploicación de Microsoft Entra. A continuación, debe utilizar el token de Microsoft Entra para obtener el token de acceso del servicio de seguridad.

Para obtener un token de servicio de seguridad, siga estos pasos:

  1. Inicie sesión en Azure Portal y utilícelo para buscar los valores de clientId y clientSecret para su aplicación de Dynamics 365 Supply Chain Management.

  2. Recupere un token de Microsoft Entra (aadToken) enviando una solicitud HTTP con las siguientes propiedades:

    • URL:https://login.microsoftonline.com/${aadTenantId}/oauth2/v2.0/token

    • Método:GET

    • Contenido del cuerpo (datos del formulario):

      Clave Valor
      client_id ${aadAppId}
      client_secret ${aadAppSecret}
      grant_type client_credentials
      scope 0cdb527f-a8d1-4bf8-9436-b352c68682b2/.default

    Debería recibir un token de Microsoft Entra (aadToken) en respuesta. El resultado se parecerá al ejemplo siguiente.

    {
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "3599",
    "access_token": "eyJ0eX...8WQ"
}

  3. Formule una solicitud de notación de objetos JavaScript (JSON) que se parezca al siguiente ejemplo.

    {
    "grant_type": "client_credentials",
    "client_assertion_type": "aad_app",
    "client_assertion": "{Your_Microsoft EntraToken}",
    "scope": "https://inventoryservice.operations365.dynamics.com/.default",
    "context": "{$LCS_environment_id}",
    "context_type": "finops-env"
}

    Tenga en cuenta los aspectos siguientes:

    • El valor de client_assertion debe ser el token de Microsoft Entra (aadToken) que recibió en el paso anterior.
    • El valor context debe ser el ID de entorno de Lifecycle Services en el que desea implementar el complemento.
    • Configure todos los demás valores como se muestra en el ejemplo.

  4. Recupere un token de acceso (access_token) enviando una solicitud HTTP con las siguientes propiedades:

    • URL:https://securityservice.operations365.dynamics.com/token
    • Método:POST
    • Encabezado HTTP: Incluya la versión de API. (La clave es Api-Version y el valor es 1.0.)
    • Contenido del cuerpo: Incluya la solicitud JSON que creó en el paso anterior.

    Debería recibir un token de acceso (access_token) en respuesta. Debe usar este token como token de portador para llamar a la API de Visibilidad de inventario. Este es un ejemplo.

    {
    "access_token": "{Returned_Token}",
    "token_type": "bearer",
    "expires_in": 3600
}

Billete

La URL https://securityservice.operations365.dynamics.com/token es una URL general para el servicio de seguridad. Cuando llama a la URL, la primera respuesta es una respuesta de redireccionamiento http con el código de estado 307 en los encabezados de respuesta y una entrada con la clave "Ubicación" que contiene la URL de destino para el servicio de seguridad. La URL está en este formato: https://gw.{$geo}-il101.gateway.prod.island.powerapps.com/securityservice/token. Por ejemplo, si su entorno se ubica en la ubicación geográfica de EE. UU., la URL podría ser https://gw.us-il101.gateway.prod.island.powerapps.com/securityservice/token. Si el código de estado de respuesta 307 no es aceptable para usted, puede construir manualmente la URL real de acuerdo con la ubicación de su entorno FinOps. La forma más sencilla es abrir https://gw.as-il101.gateway.prod.island.powerapps.com/securityservice/token con su navegador y luego copie la dirección en la barra de direcciones.

Crear eventos de cambio de inventario disponible

Hay dos API para crear eventos de cambio de inventario disponible:

  • Crear un registro: /api/environment/{environmentId}/onhand
  • Crea varios registros: /api/environment/{environmentId}/onhand/bulk

La siguiente tabla resume el significado de cada campo en el cuerpo JSON.

Id. del campo Description
id Un ID único para el evento de cambio específico. Si se produce un reenvío por un error de servicio, este ID se utiliza para garantizar que el mismo evento no se contará dos veces en el sistema.
organizationId El identificador de la organización vinculada al evento. Este valor se asigna a una organización o Id. de área de datos en Supply Chain Management.
productId El identificador del producto.
quantities La cantidad por la que se debe cambiar la cantidad de inventario disponible. Por ejemplo, si se agregan 10 libros nuevos a un estante, este valor será quantities:{ shelf:{ received: 10 }}. Si se sacan tres libros del estante o se venden, este valor será quantities:{ shelf:{ sold: 3 }}.
dimensionDataSource El origen de datos de las dimensiones utilizadas en la consulta y el evento de cambio de registro. Si especifica el origen de datos, puede utilizar las dimensiones personalizadas del origen de datos especificada. Visibilidad de inventario puede asignar la configuración de dimensiones para asignar las dimensiones personalizadas a las dimensiones predeterminadas generales. Si no se especifica ningún valor de dimensionDataSource, solo puede utilizar las dimensiones base generales en sus consultas.
dimensions Una par de clave-valor dinámico. Los valores se asignan a algunas de las dimensiones en Supply Chain Management. Sin embargo, también puede agregar dimensiones personalizadas (por ejemplo, Origen) para indicar si el evento proviene de Supply Chain Management o de un sistema externo.

Nota

Si su regla de partición de datos está configurada en Por ID de producto, siteId y locationId son dimensiones opcionales. De lo contrario, son dimensiones requeridas. Esta regla también se aplica a las API de asignación, reserva flexible y programación de cambios.

Las siguientes subsecciones proporcionan ejemplos que muestran cómo usar estas API.

Crear un evento de cambio de inventario disponible

Esta API crea un único evento de cambio de inventario disponible.

Path:
    /api/environment/{environmentId}/onhand
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        id: string,
        organizationId: string,
        productId: string,
        dimensionDataSource: string, # Optional
        dimensions: {
            [key:string]: string,
        },
        quantities: {
            [dataSourceName:string]: {
                [key:string]: number,
            },
        },
    }

El siguiente ejemplo muestra el contenido del cuerpo de muestra. En este ejemplo, la empresa tiene un sistema de punto de venta (POS) que procesa las transacciones en la tienda y, por lo tanto, los cambios de inventario. El cliente ha devuelto una camiseta roja a tu tienda. Para reflejar el cambio, publica un único evento de cambio para el producto Camiseta de manga corta. Este evento aumentará la cantidad del producto Camiseta de manga corta en 1.

{
    "id": "Test201",
    "organizationId": "usmf",
    "productId": "T-shirt",
    "dimensionDataSource": "pos",
    "dimensions": {
        "siteId": "1",
        "locationId": "11",
        "posMachineId": "0001",
        "colorId": "red"
    },
    "quantities": {
        "pos": {
            "inbound": 1
        }
    }
}

El siguiente ejemplo muestra el contenido del cuerpo de muestra sin dimensionDataSource. En este caso, dimensions serán las dimensiones base. Si dimensionDataSource está establecido, dimensions puede ser las dimensiones del origen de datos o las dimensiones base.

{
    "id": "Test202",
    "organizationId": "usmf",
    "productId": "T-shirt",
    "dimensions": {
        "siteId": "1",
        "locationId": "11",
        "colorId": "red"
    },
    "quantities": {
        "pos": {
            "inbound": 1
        }
    }
}

Crear varios eventos de cambio

Esta API puede crear eventos de cambio, al igual que la API de evento único. La única diferencia es que esta API puede crear varios registros al mismo tiempo. Por lo tanto, los valores de Path y Body difieren. Para esta API, Body proporciona una matriz de registros. El número máximo de registros es de 512. Por lo tanto, la API masiva de cambios de disponible puede admitir hasta 512 eventos de cambios a la vez.

Por ejemplo, una máquina POS de una tienda minorista procesó las siguientes dos transacciones:

  • Un pedido de devolución de una camiseta roja
  • Una transacción de venta de tres camisetas negras

En este caso, puede incluir ambas actualizaciones de inventario en una llamada a la API.

Path:
    /api/environment/{environmentId}/onhand/bulk
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [
        {
            id: string,
            organizationId: string,
            productId: string,
            dimensionDataSource: string, # Optional
            dimensions: {
                [key:string]: string,
            },
            quantities: {
                [dataSourceName:string]: {
                    [key:string]: number,
                },
            },
        },
        ...
    ]

El siguiente ejemplo muestra el contenido del cuerpo de muestra.

[
    {
        "id": "Test203",
        "organizationId": "usmf",
        "productId": "T-shirt",
        "dimensionDataSource": "pos",
        "dimensions": {
            "SiteId": "Site1",
            "LocationId": "11",
            "posMachineId": "0001"
            "colorId": "red"
        },
        "quantities": {
            "pos": { "inbound": 1 }
        }
    },
    {
        "id": "Test204",
        "organizationId": "usmf",
        "productId": "T-shirt",
        "dimensions": {
            "siteId": "1",
            "locationId": "11",
            "colorId": "black"
        },
        "quantities": {
            "pos": { "outbound": 3 }
        }
    }
]

Establecer/reemplazar cantidades disponibles

La API Establecer valor disponible reemplaza los datos actuales del producto especificado. Esta funcionalidad se utiliza normalmente para realizar actualizaciones de recuento de inventario. Por ejemplo, durante el recuento de inventario diario, una tienda puede descubrir que el inventario disponible real para una camiseta roja es 100. Por lo tanto, la cantidad de entrada a POS debe actualizarse a 100, independientemente de cuál era la cantidad anterior. Puede usar esta API para anular el valor existente.

Path:
    /api/environment/{environmentId}/setonhand/{inventorySystem}/bulk
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [
        {
            id: string,
            organizationId: string,
            productId: string,
            dimensionDataSource: string, # Optional
            dimensions: {
                [key:string]: string,
            },
            quantities: {
                [dataSourceName:string]: {
                    [key:string]: number,
                },
            },
            modifiedDateTimeUTC: datetime,
        },
        ...
    ]

El siguiente ejemplo muestra el contenido del cuerpo de muestra. El comportamiento de esta API difiere del comportamiento de las API que se describen en la sección Crear eventos de cambio de inventario disponible anterior en este artículo. En esta muestra, la cantidad del producto Camiseta de manga corta se establecerá en 1.

[
    {
        "id": "Test204",
        "organizationId": "usmf",
        "productId": "T-shirt",
        "dimensionDataSource": "pos",
        "dimensions": {
            "SiteId": "1",
            "LocationId": "11",
            "posMachineId": "0001"
            "colorId": "red"
        },
        "quantities": {
            "pos": {
                "inbound": 100
            }
        }
    }
]

Crear eventos de reserva

Para usar la API de Reserva, debe activar la función de reserva y completar la configuración de la reserva. Para obtener más información (incluido un flujo de datos y un escenario de muestra), consulte Reservas de Visibilidad de inventario.

Crear un evento de reserva

Se puede hacer una reserva con diferentes configuraciones de origen de datos. Para configurar este tipo de reserva, primero especifique el origen de datos en el parámetro dimensionDataSource. Entonces, en el parámetro dimensions, especifique las dimensiones de acuerdo con la configuración de dimensión en el origen de datos de destino.

Cuando llama a la API de reserva, puede controlar la validación de la reserva especificando el parámetro booleano ifCheckAvailForReserv en el cuerpo de la solicitud. Un valor True significa que se requiere la validación, mientras que un valor False significa que la validación no es necesaria. El valor predeterminado es True.

Si desea revertir una reserva o anular la reserva de cantidades de inventario especificadas, establezca la cantidad en un valor negativo y establezca el parámetro ifCheckAvailForReserv en False para omitir la validación. También hay una API de anulación de reserva dedicada para hacer lo mismo. La diferencia está solo en la forma en que se llama a las dos API. Es más fácil revertir un evento de reserva específico usando reservationId con la API unreserve. Para obtener más información, consulte la sección evento Cancelar una reserva.

Path:
    /api/environment/{environmentId}/onhand/reserve
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        id: string,
        organizationId: string,
        productId: string,
        dimensionDataSource: string,
        dimensions: {
            [key:string]: string,
        },
        quantityDataSource: string, # optional
        quantities: {
            [dataSourceName:string]: {
                [key:string]: number,
            },
        },
        modifier: string,
        quantity: number,
        ifCheckAvailForReserv: boolean,
    }

El siguiente ejemplo muestra el contenido del cuerpo de muestra.

{
    "id": "reserve-0",
    "organizationId": "SCM_IV",
    "productId": "iv_contoso_product",
    "quantity": 1,
    "quantityDataSource": "iv",
    "modifier": "softReservOrdered",
    "ifCheckAvailForReserv": true,
    "dimensions": {
        "siteId": "iv_contoso_site",
        "locationId": "iv_contoso_location",
        "colorId": "red",
        "sizeId": "small"
    }
}

El siguiente ejemplo muestra una respuesta correcta.

{
    "reservationId": "RESERVATION_ID",
    "id": "ohre~id-822-232959-524",
    "processingStatus": "success",
    "message": "",
    "statusCode": 200
}

Crear varios eventos de reserva

Esta API es una versión masiva de la API de evento único.

Path:
    /api/environment/{environmentId}/onhand/reserve/bulk
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [
        {
            id: string,
            organizationId: string,
            productId: string,
            dimensionDataSource: string,
            dimensions: {
                [key:string]: string,
            },
            quantityDataSource: string, # optional
            quantities: {
                [dataSourceName:string]: {
                    [key:string]: number,
                },
            },
            modifier: string,
            quantity: number,
            ifCheckAvailForReserv: boolean,
        },
        ...
    ]

Revertir eventos de reserva

La API Unreserve sirve como operación inversa para eventos Reserva. Proporciona una forma de revertir un evento de reserva especificado por reservationId o para disminuir la cantidad de reserva.

Revertir un evento de reserva

Cuando se crea una reserva, se incluirá un reservationId en el cuerpo de la respuesta. Debe proporcionar el mismo reservationId para cancelar la reserva, e incluir los mismos organizationId, productId y dimensions utilizados para la llamada a la API de reserva. Finalmente, especifique un valor de OffsetQty que represente el número de artículos a liberar de la reserva anterior. Una reserva puede revertirse total o parcialmente dependiendo de la especificación de OffsetQty. Por ejemplo, si se reservaron 100 unidades de artículos, puede especificar OffsetQty: 10 para anular la reserva 10 de la cantidad inicial reservada.

Path:
    /api/environment/{environmentId}/onhand/unreserve
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        id: string,
        organizationId: string,
        productId: string,
        reservationId: string,
        dimensions: {
            [key:string]: string,
        },
        OffsetQty: number
    }

El siguiente código muestra un ejemplo de contenido del cuerpo.

{
    "id": "unreserve-0",
    "organizationId": "SCM_IV",
    "productId": "iv_contoso_product",
    "reservationId": "RESERVATION_ID",
    "dimensions": {
        "siteid":"iv_contoso_site",
        "locationid":"iv_contoso_location",
        "ColorId": "red",
        "SizeId": "small"
    },
    "OffsetQty": 1
}

El siguiente código muestra un ejemplo de cuerpo de respuesta correcto.

{
    "reservationId": "RESERVATION_ID",
    "totalInvalidOffsetQtyByReservId": 0,
    "id": "ohoe~id-823-11744-883",
    "processingStatus": "success",
    "message": "",
    "statusCode": 200
}

Nota

En el cuerpo de la respuesta, cuando OffsetQty es menor o igual que la cantidad de reserva, processingStatus será "success" y totalInvalidOffsetQtyByReservId será 0.

Si OffsetQty es mayor que la cantidad reservada, processingStatus será "partialSuccess" y totalInvalidOffsetQtyByReservId será la diferencia entre OffsetQty y la cantidad reservada.

Por ejemplo, si la reserva tiene una cantidad de 10 y OffsetQty tiene un valor de 12, totalInvalidOffsetQtyByReservId sería 2.

Revertir varios eventos de reserva

Esta API es una versión masiva de la API de evento único.

Path:
    /api/environment/{environmentId}/onhand/unreserve/bulk
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [      
        {
            id: string,
            organizationId: string,
            productId: string,
            reservationId: string,
            dimensions: {
                [key:string]: string,
            },
            OffsetQty: number
        }
        ...
    ]

Limpieza de datos de reserva

La API de limpieza de datos de reserva se utiliza para limpiar los datos históricos de reservas. El cuerpo debe ser una lista de fuentes de datos. Si la lista está vacía, se limpiarán todas las fuentes de datos.

Path:
    /api/environment/{environmentId}/onhand/reserve/resyncjob
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [      
        "iv",
        "pos"
    ]

Consulta de inventario disponible

Use la API de Consulta de inventario disponible se utiliza para obtener datos del inventario disponible actual para sus productos. Puede usar esta API siempre que deba conocer el stock, como cuando desee revisar los niveles de stock del producto en su sitio web de comercio electrónico, o cuando desee verificar la disponibilidad del producto en todas las regiones o en tiendas y almacenes cercanos. La API actualmente admite la consulta de hasta 5000 elementos individuales por el valor productID. También se pueden especificar varios valores siteID y locationID en cada consulta. Cuando su regla de partición de datos está establecida en Por ubicación, el límite máximo se define mediante la siguiente ecuación:

NumOf(ID del sitio) × NumOf(ID de ubicación) <= 10 000.

Consulta mediante el método POST

La API de consulta por publicación está disponible en dos versiones. La siguiente tabla describe las diferencias.

API versión 1.0 API versión 2.0
Solo se puede consultar un ID de organización. Puede consultar varios ID de organización.
Puede consultar hasta 10.000 combinaciones de sitios y almacenes. Puede consultar más de 10.000 combinaciones de ID de organización, sitios y almacenes. Puede devolver resultados en varias páginas.

Las siguientes subsecciones muestran cómo utilizar cada versión de API.

Consulta por publicación API versión 1.0

Path:
    /api/environment/{environmentId}/onhand/indexquery
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        dimensionDataSource: string, # Optional
        filters: {
            organizationId: string[],
            productId: string[],
            siteId: string[],
            locationId: string[],
            [dimensionKey:string]: string[],
        },
        groupByValues: string[],
        returnNegative: boolean,
    }

En la parte del cuerpo de esta solicitud, dimensionDataSource es un parámetro opcional. Si no está configurado, filters se tratará como dimensiones base.

El parámetro returnNegative controla si los resultados contienen entradas negativas.

Consultar datos almacenados por ubicación

Esta sección se aplica cuando su regla de partición de datos está configurada en Por ubicación.

  • organizationId debe ser una matriz que contenga exactamente un valor.
  • productId puede contener uno o más valores. Si es una matriz vacía, el sistema devolverá todos los productos de los sitios y ubicaciones específicos. En este caso, siteId y locationId no deben estar vacíos.
  • siteId y locationId se utilizan para particionar. Puede especificar más de un valor siteId y locationId en una solicitud Consulta disponible. Si ambas matrices están vacías, el sistema devolverá todos los sitios y ubicaciones de los productos específicos. En este caso, productId no debe estar vacío.

Le recomendamos que utilice el parámetro groupByValues de forma coherente con la configuración de su índice. Para obtener más información, consulte Configuración de índice de disponibilidad.

Consultar datos almacenados por id. del producto

Esta sección se aplica cuando su regla de partición de datos está configurada en Por id. del producto. En este caso, se requieren dos campos filters: organizationId, productId.

  • organizationId debe ser una matriz que contenga exactamente un valor.
  • productId debe ser una matriz que contenga al menos un valor.

A diferencia de cuando se almacenan datos por ubicación, si no especifica valores para siteId y locationId, la información de inventario para cada id. de producto se agregará en todos los sitios y/o ubicaciones.

Nota

Si ha habilitado las características del programa de cambios de inventario disponible y neto no comprometido (NNC), su consulta también puede incluir el parámetro booleano QueryATP, que controla si los resultados de la consulta incluyen información de NNC. Para obtener más información y ver ejemplos, consulte Planes de cambio de visibilidad de inventario disponible y neto no comprometido.

El siguiente ejemplo muestra el contenido del cuerpo de muestra. Muestra que puede consultar el inventario disponible desde varias ubicaciones (almacenes).

{
    "dimensionDataSource": "pos",
    "filters": {
        "organizationId": ["usmf"],
        "productId": ["T-shirt"],
        "siteId": ["1"],
        "locationId": ["11","12","13"],
        "colorId": ["red"]
    },
    "groupByValues": ["colorId", "sizeId"],
    "returnNegative": true
}

El siguiente ejemplo muestra cómo consultar todos los productos en un sitio y una ubicación específicos.

{
    "filters": {
        "organizationId": ["usmf"],
        "productId": [],
        "siteId": ["1"],
        "locationId": ["11"],
    },
    "groupByValues": ["colorId", "sizeId"],
    "returnNegative": true
}

Consulta por publicación API versión 2.0

Path:
    /api/environment/{environmentId}/onhand/indexquery?pageNumber={pageNumber}&pageSize={pageSize}
Method:
    Post
Headers:
    Api-Version="2.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    # Same as version 1.0

El formato de solicitud para la versión 2.0 de API es similar al de la versión 1.0, pero también admite dos parámetros opcionales: pageNumber y pageSize, que permiten al sistema dividir un único resultado grande en varios documentos más pequeños. Los resultados se ordenan por almacén (locationId) y los parámetros se utilizan de la siguiente manera para dividir los resultados en páginas:

  • pageSize establece el número de almacenes (locationId valores) que se devuelven en cada página.
  • pageNumber establece el número de página que se devuelve.

Una solicitud de este formato devuelve datos de inventario disponibles a partir del número de almacén ({pageNumber} − 1) × {pageSize} e incluye datos para el siguiente {pageSize} . almacenes.

La versión 2.0 de API responde con un documento que utiliza la siguiente estructura:

{
    Value: { # Response same as Api-Version=1.0 }
    nextLink: onhand/indexquery?pageNumber={pageNumber+1}&pageSize={pageSize}
}

Cuando la solicitud llega al último almacén (locationId), el valor nextLink es una cadena vacía.

La versión 2.0 de API también le permite especificar más de un ID de organización en su solicitud. Para hacerlo, incluya una lista de ID de organización separados por comas en el filtro organizationId de su documento de solicitud. Por ejemplo, "organizationId": ["org1", "org2", "org3"].

Consulta mediante el método GET

Path:
    /api/environment/{environmentId}/onhand
Method:
    Get
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Query(Url Parameters):
    groupBy
    returnNegative
    [Filters]

Este es un ejemplo de URL de GET. Esta solicitud GET es exactamente la misma que la muestra de POST que se proporcionó anteriormente.

/api/environment/{environmentId}/onhand?organizationId=SCM_IV&productId=iv_contoso_product&siteId=iv_contoso_site&locationId=iv_contoso_location&colorId=red&groupBy=colorId,sizeId&returnNegative=true

El sistema no admite la consulta de inventario a través de múltiples ID de organización con el método GET.

Consulta exacta de inventario disponible

Las consultas exactas disponibles se parecen a las consultas disponibles regulares, pero le permiten especificar una jerarquía de mapeo entre un sitio y una ubicación. Por ejemplo, tiene los dos sitios siguientes:

  • Sitio 1, que está asignado a la ubicación A
  • Sitio 2, que está asignado a la ubicación B

Para una consulta disponible regular, si especifica "siteId": ["1","2"] y "locationId": ["A","B"], Visibilidad de inventario consultará automáticamente el resultado de los siguientes sitios y ubicaciones:

  • Sitio 1, ubicación A
  • Sitio 1, ubicación B
  • Sitio 2, ubicación A
  • Sitio 2, ubicación B

Como puede ver, la consulta disponible normal no reconoce que la ubicación A existe solo en el sitio 1 y la ubicación B solo existe en el sitio 2. Por lo tanto, hace consultas redundantes. Para adaptarse a esta asignación jerárquica, puede usar una consulta exacta disponible y especificar las asignaciones de ubicación en el cuerpo de la consulta. En este caso, consultará y recibirá resultados solo para el sitio 1, ubicación A y el sitio 2, ubicación B.

Consulta de consulta exacta disponible mediante el método de publicación

La consulta exacta disponible por API de publicación está disponible en dos versiones. La siguiente tabla describe las diferencias.

API versión 1.0 API versión 2.0
Solo se puede consultar un ID de organización. Puede consultar varios ID de organización.

Consulta exacta disponible mediante publicación API versión 1.0

Path:
    /api/environment/{environmentId}/onhand/exactquery
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        dimensionDataSource: string, # Optional
        filters: {
            organizationId: string[],
            productId: string[],
            dimensions: string[],
            values: string[][],
        },
        groupByValues: string[],
        returnNegative: boolean,
    }

En la parte del cuerpo de esta solicitud, dimensionDataSource es un parámetro opcional. Si no está configurado, dimensions en filters se tratará como dimensiones base. Hay cuatro campos obligatorios para filters: organizationId, productId, dimensions y values.

  • organizationId debería contener solo un valor, pero sigue siendo una matriz.
  • productId puede contener uno o más valores. Si es una matriz vacía, se devolverán todos los productos.
  • En la matriz dimensions, siteId y locationId son requeridos si y solo si su regla de partición de datos se establece en Por ubicación. En este caso, pueden aparecer con otros elementos en cualquier orden.
  • values podría contener una o más tuplas distintas de valores correspondientes a dimensions.

dimensions en filters se agregará automáticamente groupByValues.

El parámetro returnNegative controla si los resultados contienen entradas negativas.

El siguiente ejemplo muestra el contenido del cuerpo de muestra.

{
    "dimensionDataSource": "pos",
    "filters": {
        "organizationId": ["SCM_IV"],
        "productId": ["iv_contoso_product"],
        "dimensions": ["siteId", "locationId", "colorId"],
        "values" : [
            ["iv_contoso_site", "iv_contoso_location", "red"],
            ["iv_contoso_site", "iv_contoso_location", "blue"],
        ]
    },
    "groupByValues": ["colorId", "sizeId"],
    "returnNegative": true
}

El siguiente ejemplo muestra cómo consultar todos los productos en varios sitios y ubicaciones.

{
    "filters": {
        "organizationId": ["SCM_IV"],
        "productId": [],
        "dimensions": ["siteId", "locationId"],
        "values" : [
            ["iv_contoso_site_1", "iv_contoso_location_1"],
            ["iv_contoso_site_2", "iv_contoso_location_2"],
        ]
    },
    "groupByValues": ["colorId", "sizeId"],
    "returnNegative": true
}

Consulta exacta disponible mediante publicación API versión 2.0

Path:
    /api/environment/{environmentId}/onhand/exactquery
Method:
    Post
Headers:
    Api-Version="2.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        dimensionDataSource: string, # Optional
        filters: {
            productId: string[],
            keys: string[],
            values: string[][],
        },
        groupByValues: string[],
        returnNegative: boolean,
    }

La versión 2.0 de API se diferencia de la versión 1.0 en los siguientes aspectos:

  • La sección filters ahora tiene un campo keys en lugar de un campo dimensions . El campo keys funciona como el campo dimensions en la versión 1.0, pero ahora también puede incluir organizationId. Puede especificar las claves en cualquier orden.
  • La sección filters ya no admite el campo organizationId . En su lugar, puede incluir organizationId entre las dimensiones en el campo keys (por ejemplo, keys: ["organizationId", "siteId", "locationId"]) y definir valores de ID de organización en la posición coincidente en el values campo (por ejemplo, values: ["SCM_IV", "iv_contoso_site_1", "iv_contoso_location_1"]).

Otros campos son idénticos a la versión API 1.0.

Consulta con búsqueda de productos

Las siguientes API de consulta disponibles se han mejorado para admitir la búsqueda de productos:

Billete

Cuando publica una consulta de visibilidad de inventario que utiliza la búsqueda de productos, utilice el productSearchparámetro de solicitud (con un objeto ProductAttributeQuery dentro) para buscar o filtrar por ID de producto. Las API más nuevas ya no son compatibles con el parámetro de solicitud productid más antiguo en el cuerpo de la solicitud.

Requisitos previos

Antes de poder empezar a utilizar las API de búsqueda de productos, su sistema debe cumplir los siguientes requisitos:

Contrato de búsqueda de productos

El contrato de búsqueda de productos define las reglas para comunicarse con las API de búsqueda de productos. Proporciona una forma estandarizada de describir las capacidades y el comportamiento de las capacidades de búsqueda de productos. Por lo tanto, los usuarios pueden comprender, interactuar y crear aplicaciones que consuman las API de visibilidad de inventario más fácilmente.

El siguiente ejemplo muestra un contrato de ejemplo.

{
    "productFilter": {
        "logicalOperator": "And",
        "conditions": [
            {
                "conditionOperator": "Contains",
                "productName": [
                    "Deluxe"
                ],
            },
        ],
        "subFilters": [
            {
                "conditions": [
                    {
                        "conditionOperator": "IsExactly",
                        "productType": [
                            "Item"
                        ]
                    }
                ]
            }
        ]
    },
    "attributeFilter": {
        "logicalOperator": "Or",
        "conditions": [
            {
                "attributeName": "Weight Limit",
                "attributeTypeName":"PoundDomain",
                "attributeArea": " ProductAttribute",
                "attributeValues": [
                    "370"
                ],
                "conditionOperator": "GreaterEqual"
            }
        ],
        "subFilters": [
            {
                "conditions": [
                    {
                        "attributeName": "Weight Limit",
                        "attributeTypeName":"PoundDomain",
                        "attributeArea": " ProductAttribute",
                        "attributeValues": [
                            "330"
                        ],
                        "conditionOperator": "LessEqual"
                    }
                ]
            }
        ]
    },
}

En la tabla siguiente se describen los campos que se usan en el contrato.

Id. de campo Description
logicalOperator Los valores posibles son And y Or. Utilice este campo para conectar múltiples condiciones o condiciones y subfiltros. Tenga en cuenta que subFilters es en realidad un objeto productFilter o attributeFilter. Por lo tanto, puede tener subFilters dentro de subFilters.
conditionOperator Los valores posibles son IsExactly, IsNot, Contains, DoesNotContain, BeginsWith, IsOneOf, GreaterEqual, LessEqual y Between.
ProductFilter Utilice este campo para filtrar productos por información relacionada con el producto. Por ejemplo, puede cambiar productName en el contrato para Company, itemNumber, productSearchName, productType, productName, productDescription, inventoryUnitSymbol, salesUnitSymbol o purchaseUnitSymbol para adaptarse a las necesidades de su negocio.
AttributeFilter Utilice este campo para filtrar productos por información relacionada con el atributo.
attributeArea Los valores posibles son ProductAttribute, DimensionAttribute y BatchAttribute. 
Path:
    /api/environment/{environmentId}/onhand/productsearch/indexquery
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        productSearch: {ProductAttributeQuery contract object inherited from Product Search}
            dimensionDataSource: string, # Optional
            filters: {
                organizationId: string[],
                siteId: string[],
                locationId: string[],
                [dimensionKey:string]: string[],
            },
            groupByValues: string[],
            returnNegative: boolean,
    }

El siguiente ejemplo muestra el contenido del cuerpo de muestra.

{
    "productSearch": {
        "productFilter": {
            "conditions": [
                {
                    "conditionOperator": "contains",
                    "productName": [
                        "speaker cable"
                    ],
                },
            ],
        },
    },
    "returnNegative": true, 
    "filters": 
    {
        "organizationId": ["usmf"], 
        "siteId": ["1"], 
        "locationId": ["13"],
    },
    "groupByValues": ["colorid"],
}

El siguiente ejemplo muestra una respuesta correcta.

[
    {
        "productId": "M0030",
        "dimensions": {
            "ColorId": "White",
            "siteid": "1",
            "locationid": "13"
        },
        "quantities": {
            "fno": {
                "arrived": 0,
                "availordered": 20,
                "onorder": 5,
                "ordered": 20,
                "physicalinvent": 0,
                "reservordered": 0,
                "reservphysical": 0,
                "orderedsum": 20,
                "softreserved": 0
            },
            "iv": {
                "ordered": 0,
                "softreserved": 0,
                "softreservphysical": 0,
                "softreservordered": 0,
                "total ordered": 20,
                "total on order": 5,
                "availabletoreserve": 20,
                "totalavailable": 20,
                "totalordered": 20,
                "totalonorder": 5
            },
            "pos": {
                "inbound": 0,
                "outbound": 0
            },
            "@iv": {
                "@allocated": 0
            }
        }
    },
    {
        "productId": "M0030",
        "dimensions": {
            "ColorId": "Black",
            "siteid": "1",
            "locationid": "13"
        },
        "quantities": {
            "fno": {
                "arrived": 0,
                "availordered": 3,
                "ordered": 3,
                "physicalinvent": 0,
                "reservordered": 0,
                "reservphysical": 0,
                "orderedsum": 3,
                "softreserved": 0
            },
            "iv": {
                "ordered": 0,
                "softreserved": 0,
                "softreservphysical": 0,
                "softreservordered": 0,
                "total ordered": 3,
                "availabletoreserve": 3,
                "totalavailable": 3,
                "totalordered": 3
            },
            "pos": {
                "inbound": 0,
                "outbound": 0
            },
            "@iv": {
                "@allocated": 0
            }
        }
    }
]

Path:
    /api/environment/{environmentId}/onhand/productsearch/exactquery
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        productSearch: {ProductAttributeQuery contract object inherited from Product Search}
            dimensionDataSource: string, # Optional
            filters: {
                organizationId: string[],
                dimensions: string[],
                values: string[][],
            },
            groupByValues: string[],
            returnNegative: boolean,
    }

El siguiente ejemplo muestra el contenido del cuerpo de muestra.

{
    "productSearch": {
        "productFilter": {
            "conditions": [
                {
                    "conditionOperator": "contains",
                    "productName": [
                        "speaker cable"
                    ],
                },
            ],
        },
    },
    "filters": {
        "organizationId": ["usmf"],
        "dimensions": ["siteId", "locationId", "colorid"],
        "values" : [
            ["1", "13", "Black"],
        ]
    },
    "groupByValues": [],
    "returnNegative": true
}

El siguiente ejemplo muestra una respuesta correcta.

[
    {
        "productId": "M0030",
        "dimensions": {
            "ColorId": "Black",
            "siteid": "1",
            "locationid": "13"
        },
        "quantities": {
            "fno": {
                "arrived": 0,
                "availordered": 3,
                "ordered": 3,
                "physicalinvent": 0,
                "reservordered": 0,
                "reservphysical": 0,
                "orderedsum": 3,
                "softreserved": 0
            },
            "iv": {
                "ordered": 0,
                "softreserved": 0,
                "softreservphysical": 0,
                "softreservordered": 0,
                "total ordered": 3,
                "availabletoreserve": 3,
                "totalavailable": 3,
                "totalordered": 3
            },
            "pos": {
                "inbound": 0,
                "outbound": 0
            },
            "@iv": {
                "@allocated": 0
            }
        }
    }
]

Neto no comprometido

Puede configurar la visibilidad del inventario para que le permita programar futuros cambios de inventario disponible y calcular las cantidades de NNC. El NNC es la cantidad de un artículo que esté disponible y se pueda prometer a un cliente en el siguiente periodo. El uso del cálculo del NNC puede aumentar considerablemente la capacidad de entrega de su pedido. Para obtener información sobre cómo habilitar esta función y cómo interactuar con la visibilidad de inventario a través de su API después de habilitar la característica, consulte Planes de cambio de visibilidad de inventario disponible y neto no comprometido.

Asignación

Las API relacionadas con la asignación se encuentran en Asignación de visibilidad de inventario.