Compartilhar via

APIs públicas do Inventory Visibility

  • Artigo

Observação

O Azure Active Directory agora é Microsoft Entra ID. Saiba mais

Este artigo descreve as APIs públicas fornecidas pela visibilidade do Estoque.

A API REST pública do Suplemento Visibilidade de Estoque apresenta vários pontos de extremidade específicos para integração. Ela oferece suporte a quatro tipos de interação principais:

  • Lançar alterações de estoque disponíveis no suplemento a partir de um sistema externo
  • Configuração ou substituição de quantidades de estoque disponível no suplemento de um sistema externo
  • Lançamento de eventos de reserva no no suplemento desde um sistema externo
  • Consultar as quantidades disponíveis no momento a partir de um sistema externo

A tabela a seguir lista as APIs disponíveis no momento:

Caminho Método Descrição
/api/environment/{environmentId}/onhand Postar Criar um evento de alteração disponível
/api/environment/{environmentId}/onhand/bulk Postar Criar vários eventos de alteração
/api/environment/{environmentId}/setonhand/{inventorySystem}/bulk Postar Definir/substituir quantidades disponíveis
/api/environment/{environmentId}/onhand/reserve Postar Criar um evento de reserva flexível
/api/environment/{environmentId}/onhand/reserve/bulk Postar Criar vários eventos de reserva flexível
/api/environment/{environmentId}/onhand/unreserve Postar Reverter um evento de reserva flexível
/api/environment/{environmentId}/onhand/unreserve/bulk Postar Reverter vários eventos de reserva flexível
/api/environment/{environmentId}/onhand/reserve/resyncjob Postar Limpar dados da reserva
/api/environment/{environmentId}/onhand/changeschedule Postar Criar um alteração disponível programada
/api/environment/{environmentId}/onhand/changeschedule/bulk Postar Criar várias alterações disponíveis com datas
/api/environment/{environmentId}/onhand/indexquery Postar Fazer uma consulta usando o método POST (recomendado)
/api/environment/{environmentId}/onhand Obter Consultar usando o método get
/api/environment/{environmentId}/onhand/exactquery Postar Fazer uma consulta exata usando o método POST
/api/environment/{environmentId}/allocation/allocate Postar Criar um evento alocar
/api/environment/{environmentId}/allocation/unallocate Postar Criar um evento desalocar
/api/environment/{environmentId}/allocation/reallocate Postar Criar um evento realocar
/api/environment/{environmentId}/allocation/consume Postar Criar um evento consumir
/api/environment/{environmentId}/allocation/query Postar Resultado da alocação da consulta
/api/environment/{environmentId}/onhand/productsearch/indexquery Postar Publicar consulta de índice com pesquisa de produto
/api/environment/{environmentId}/onhand/productsearch/exactquery Postar Publicar consulta exata com pesquisa de produto

Observação

A parte {environmentId} do caminho é a ID do ambiente em Microsoft Dynamics Lifecycle Services.

A API em massa pode retornar um máximo de 512 registros para cada solicitação.

Autenticação

O token de segurança da plataforma é usado para chamar a API pública da Visibilidade de Estoque. Por isso, você deve gerar um token do Microsoft Entra usando o aplicativo Microsoft Entra. Você deve usar o token Microsoft Entra para obter o token de acesso do serviço de segurança.

Para obter um token de serviço de segurança, siga estas etapas.

  1. Entre no portal do Azure e use-o para localizar os valores de clientId e clientSecret para seu aplicativo Dynamics 365 Supply Chain Management.

  2. Busque um token do Microsoft Entra (aadToken) ao enviar uma solicitação HTTP com as seguintes propriedades:

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

    • Método:GET

    • Conteúdo do corpo (dados de formulário):

      Chave Alíquota
      client_id ${aadAppId}
      client_secret ${aadAppSecret}
      grant_type client_credentials
      escopo 0cdb527f-a8d1-4bf8-9436-b352c68682b2/.padrão

    Você deve receber um token do Microsoft Entra (aadToken) em resposta. Ela deve se assemelhar ao seguinte exemplo.

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

  3. Formula uma solicitação JSON (JavaScript Object Notation) semelhante ao exemplo a seguir.

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

    Observe os seguintes pontos:

    • O valor de client_assertion deverá ser o token do Microsoft Entra (aadToken) que você recebeu na etapa anterior.
    • O valor de context deve ser a ID do ambiente do Lifecycle Services em que você deseja implantar o suplemento.
    • Defina todos os demais valores conforme mostrado no exemplo.

  4. Busque um token de acesso (access_token) ao enviar uma solicitação HTTP com as seguintes propriedades:

    • URL:https://securityservice.operations365.dynamics.com/token
    • Método:POST
    • Cabeçalho HTTP: inclua a versão da API. (A chave é Api-Version, e o valor é 1.0.)
    • Conteúdo do corpo: inclua a solicitação JSON criada na etapa anterior.

    Você deverá receber um token de acesso (access_token) em resposta. Você deverá usar esse token como um token de portador para chamar a API da Visibilidade de Estoque. Este é um exemplo.

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

Observação

A URL https://securityservice.operations365.dynamics.com/token é uma URL geral para o serviço de segurança. Quando você chama a URL, a primeira resposta é uma resposta de redirecionamento http com o código de status 307 nos cabeçalhos de resposta e uma entrada com a chave "Localização" que contém a URL de destino do serviço de segurança. A URL está no formato https://gw.{$geo}-il101.gateway.prod.island.powerapps.com/securityservice/token. Por exemplo, se o seu ambiente está localizado na área geográfica EUA, a URL poderia ser https://gw.us-il101.gateway.prod.island.powerapps.com/securityservice/token. Se o código de status de resposta 307 não for aceitável, você poderá criar manualmente a URL real de acordo com a localização do ambiente do FinOps. A forma mais simples é abrir https://gw.as-il101.gateway.prod.island.powerapps.com/securityservice/token com o navegador e copiar o endereço na barra de endereços.

Criar eventos de alteração disponíveis

Há duas APIs para a criação de eventos de alteração disponíveis:

  • Criar um registro: /api/environment/{environmentId}/onhand
  • Criar vários registros: /api/environment/{environmentId}/onhand/bulk

A tabela a seguir resume o significado de cada campo no corpo do JSON.

ID do campo Descrição
id Uma ID exclusiva para o evento de alteração específico. Se ocorrer um reenvio devido a uma falha de serviço, essa ID será usada para garantir que o mesmo evento não seja contado duas vezes no sistema.
organizationId O identificador da organização vinculado ao evento. Esse valor é mapeado para uma ID da organização ou da área de dados no Supply Chain Management.
productId O identificador do produto.
quantities A quantidade pela qual a quantidade disponível deve ser alterada. Por exemplo, se 10 novos livros forem adicionados a uma prateleira, esse valor será quantities:{ shelf:{ received: 10 }}. Se três livros forem removidos da prateleira ou se forem vendidos, esse valor será quantities:{ shelf:{ sold: 3 }}.
dimensionDataSource A fonte de dados das dimensões usadas no evento e na consulta de alteração de lançamento. Se você especificar a fonte de dados, poderá usar as dimensões personalizadas da fonte de dados especificada. A Visibilidade de Estoque pode usar a configuração da dimensão para mapear as dimensões personalizadas para as dimensões padrão gerais. Se nenhum valor de dimensionDataSource for especificado, você só poderá usar as dimensões base gerais em suas consultas.
dimensions Um par de chave-valor dinâmico. Os valores são mapeados para algumas das dimensões no Supply Chain Management. No entanto, você também pode adicionar dimensões personalizadas (por exemplo, Origem) para indicar se o evento provém do Supply Chain Management ou de um sistema externo.

Observação

Se a regra de partição de dados estiver definida como Por ID do produto, siteId e locationId serão dimensões opcionais. Caso contrário, serão dimensões necessárias. Essa regra também se aplica às APIs de alocação, reserva flexível e agenda de alterações.

As subseções a seguir fornecem exemplos que mostram como usar essas APIs.

Criar um evento de alteração disponível

Essa API cria um único evento de alteração disponível.

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,
            },
        },
    }

O exemplo a seguir mostra o conteúdo do corpo de exemplo. Neste exemplo, a empresa possui um sistema de ponto de venda (POS) que processa as transações na loja e, portanto, as alterações de estoque. O cliente devolveu uma camiseta vermelha à sua loja. Para refletir a alteração, você publica um único evento de alteração para o produto Camiseta. Esse evento aumentará a quantidade do produto Camiseta em 1.

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

O exemplo a seguir mostra o conteúdo do corpo de exemplo sem dimensionDataSource. Nesse caso, dimensions será as dimensões básicas. Se dimensionDataSource for definido, dimensions poderá ser as dimensões da fonte de dados ou as dimensões básicas.

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

Criar vários eventos de alteração

Essa API pode criar eventos de alteração, assim como a API de evento único. A única diferença é que esta API pode criar vários registros ao mesmo tempo. Portanto, os valores Path e Body diferem. Para essa API, Body fornece uma matriz de registros. O número máximo de registros é 512. Portanto, a API em massa de alteração disponível pode suportar até 512 eventos de alteração por vez.

Por exemplo, uma máquina PDV de uma loja de varejo processou as duas transações a seguir:

  • Um pedido de devolução de uma camiseta vermelha
  • Uma transação de venda de três camisetas pretas

Nesse caso, você pode incluir ambas as atualizações de estoque em uma chamada de 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,
                },
            },
        },
        ...
    ]

O exemplo a seguir mostra o conteúdo do corpo de exemplo.

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

Definir/substituir quantidades disponíveis

A API Definir disponível substitui os dados atuais do produto especificado. Essa funcionalidade é normalmente usada para fazer atualizações de contagem de estoque. Por exemplo, durante sua contagem diária de estoque, uma loja pode descobrir que o estoque disponível real de uma camiseta vermelha é 100. Portanto, a quantidade de entrada do PDV deve ser atualizada para 100, independentemente de qual era a quantidade anterior. Você pode usar esta API para substituir o 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,
        },
        ...
    ]

O exemplo a seguir mostra o conteúdo do corpo de exemplo. O comportamento dessa API difere do comportamento das APIs descritas na seção Criar eventos de alteração disponíveis, anteriormente neste artigo. Neste exemplo, a quantidade do produto Camiseta será definida como 1.

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

Criar eventos de reserva

Para usar a API Reservar, você deverá ativar o recurso de reserva e concluir a configuração da reserva. Para obter mais informações (incluindo um fluxo de dados e um cenário de exemplo), consulte Reservas de Visibilidade de Estoque.

Criar um evento de reserva

Uma reserva pode ser feita com diferentes configurações da fonte de dados. Para configurar esse tipo de reserva, especifique primeiro a fonte de dados no parâmetro dimensionDataSource. Depois disso, no parâmetro dimensions, especifique as dimensões de acordo com as configurações de dimensão na fonte de dados de destino.

Ao chamar a API de reserva, você pode controlar a validação da reserva especificando o parâmetro booliano ifCheckAvailForReserv no corpo da solicitação. Um valor True significa que a validação é necessária, enquanto um valor False significa que a validação não é necessária. O valor padrão é True.

Se você desejar reverter uma reserva ou cancelar a reserva de quantidades de estoque especificadas, defina a quantidade como um valor negativo e o parâmetro ifCheckAvailForReserv como False para ignorar a validação. Há também uma API de cancelamento de reserva dedicada para fazer o mesmo. A diferença só ocorre no modo como as duas APIs são chamadas. É mais fácil reverter um evento de reserva específico usando reservationId com a API cancelar reserva. Para obter mais informações, consulte a seção Cancelar a reserva de um evento de 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,
    }

O exemplo a seguir mostra o conteúdo do corpo de exemplo.

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

O exemplo a seguir mostra uma resposta bem-sucedida.

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

Criar vários eventos de reserva

Essa API é uma versão em massa da 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,
        },
        ...
    ]

Reverter eventos de reserva

A API Cancelar reserva funciona como a operação reversa para eventos de Reserva. Ela oferece uma forma de reverter um evento de reserva especificado por reservationId ou de diminuir a quantidade de reserva.

Reverter um evento de reserva

Quando uma reserva for criada, uma reservationId será incluída no corpo da resposta. Você deve fornecer a mesma reservationId para cancelar a reserva e incluir as mesmas organizationId, productId e dimensions usadas na chamada à API de reserva. Finalmente, especifique um valor OffsetQty que represente o número de itens a serem liberados da reserva anterior. Uma reserva pode ser total ou parcialmente revertida dependendo do OffsetQty especificado. Por exemplo, se 100 unidades de itens foram reservadas, você poderá especificar OffsetQty: 10 para cancelar a reserva 10 do valor inicial reservado.

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
    }

O código a seguir mostra um exemplo do conteúdo do corpo.

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

O código a seguir mostra um exemplo do corpo de uma resposta bem-sucedida.

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

Observação

No corpo da resposta, quando OffsetQty for menor ou igual à quantidade de reserva, processingStatus será "êxito" e totalInvalidOffsetQtyByReservId será 0.

Se OffsetQty for maior que o valor reservado, processingStatus será "partialSuccess" e totalInvalidOffsetQtyByReservId será a diferença entre OffsetQty e o valor reservado.

Por exemplo, se a reserva tiver uma quantidade de 10 e OffsetQty tiver um valor de 12, totalInvalidOffsetQtyByReservId será 2.

Reverter vários eventos de reserva

Essa API é uma versão em massa da 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
        }
        ...
    ]

Limpar dados da reserva

A API limpar dados da reserva é usada para limpar dados históricos de reservas. O corpo deve ser uma lista de fontes de dados. Se a lista estiver vazia, todas as fontes de dados serão limpas.

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

Consultar disponíveis

Use a API Consultar disponíveis para buscar dados de estoque disponível atuais para seus produtos. Você pode usar essa API sempre que precisar saber o estoque, por exemplo, quando quiser revisar os níveis de estoque do produto em seu site de comércio eletrônico ou quando quiser verificar a disponibilidade do produto em várias regiões ou em lojas e armazéns próximos. No momento, a API oferece suporte à consulta de até 5000 itens individuais por valor de productID. Diversos valores siteID e locationID também podem ser especificados em cada consulta. Quando a regra de partição de dados é definida como Por local, o limite máximo é definido pela seguinte equação:

NumOf(SiteID) × NumOf(LocationID) <= 10.000.

Consultar usando o método post

A API de consulta por post está disponível em duas versões. A tabela a seguir descreve as diferenças.

API versão 1.0 API versão 2.0
Só pode consultar uma ID de organização. Pode consultar várias IDs da organização.
Pode consultar até 10.000 combinações de sites e depósitos. Pode consultar mais de 10.000 combinações de IDs de organização, sites e depósitos. Pode retornar resultados em várias páginas.

As subseções a seguir mostram como usar cada versão da API.

Consulta por post API versão 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,
    }

Na parte do corpo desta solicitação, dimensionDataSource é um parâmetro opcional. Se não estiver definido, filters será tratado como dimensões básicas.

O parâmetro returnNegative controla se os resultados contêm entradas negativas.

Consultar dados armazenados por local

Esta seção se aplica quando a regra de partição de dados é definida como Por local.

  • organizationId deve ser uma matriz contendo exatamente um valor.
  • productId pode conter um ou mais valores. Se for uma matriz vazia, o sistema retornará todos os produtos dos sites e locais específicos. Nesse caso, siteId e locationId não devem estar vazias.
  • siteId e locationId são usados para particionamento. Você pode especificar mais de um valor siteId e locationId em uma solicitação Consulta de disponíveis. Se ambas as matrizes estiverem vazias, o sistema retornará todos os sites e locais dos produtos especificados. Nesse caso, productId não deve estar vazia.

É recomendável usar o parâmetro groupByValues de maneira consistente com a configuração do seu índice. Para obter mais informações, consulte Configuração de índice disponível.

Consultar dados armazenados por ID do produto (product ID)

Esta seção se aplica quando a regra de partição de dados é definida como Por ID do produto (product ID). Nesse caso, dois campos filters são necessários: organizationId, productId.

  • organizationId deve ser uma matriz contendo exatamente um valor.
  • productId deve ser uma matriz com, pelo menos, um valor.

Diferentemente do armazenamento de dados por local, se você não especificar valores para siteId e locationId, as informações de estoque para cada ID de produto (product ID) serão agregadas em todos os sites e/ou locais.

Observação

Se você tiver habilitado o plano de alteração disponível e os recursos disponíveis para a promessa (ATP), a consulta também poderá incluir o parâmetro QueryATP booliano, que controla se os resultados da consulta incluirão informações de ATP. Para obter mais informações e exemplos, consulte Agenda de alterações disponíveis e disponível para promessa de Visibilidade de Estoque.

O exemplo a seguir mostra o conteúdo do corpo de exemplo. Isso mostra que você pode consultar o estoque disponível de vários locais (armazéns).

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

O exemplo a seguir mostra como consultar todos os produtos em um site e local específicos.

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

Consulta por post API versão 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

O formato de solicitação para a versão 2.0 da API é semelhante ao da versão 1.0, mas também oferece suporte a dois parâmetros opcionais: pageNumber e pageSize, que permitem que o sistema divida um único resultado grande em vários documentos menores. Os resultados são classificados por depósito (locationId) e os parâmetros são usados da seguinte maneira para dividir os resultados em páginas:

  • pageSize Estabelece o número de depósitos (locationId valores) retornados em cada página.
  • pageNumber Estabelece o número da página que é retornado.

Uma solicitação desse formato retorna dados de estoque disponíveis a partir do número do depósito ({pageNumber} − 1) × {pageSize} e inclui dados para os próximos {pageSize} depósitos.

A API versão 2.0 responde com um documento que usa a seguinte estrutura:

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

Quando a solicitação chega ao último depósito (locationId), o nextLink valor é uma cadeia de caracteres vazia.

A versão 2.0 da API também permite especificar mais de uma ID de organização em sua solicitação. Para fazer isso, inclua uma lista separada por vírgulas de IDs da organização no organizationId filtro do documento da solicitação. Por exemplo, "organizationId": ["org1", "org2", "org3"].

Consultar usando o 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 é um exemplo de obtenção de URL. Essa solicitação get é exatamente igual ao exemplo de lançamento fornecido 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

O sistema não oferece suporte à consulta de estoque em várias IDs da organização com o método GET.

Consulta exata de estoque disponível

As consultas exatas sobre disponibilidade se assemelham às consultas sobre disponibilidade regulares, mas permitem especificar uma hierarquia de mapeamento entre um site e um local. Por exemplo, se você tiver os seguintes dois sites:

  • Site 1, que é mapeado para o local A
  • Site 2, que é mapeado para o local B

Para uma consulta de disponíveis regular, se você especificar "siteId": ["1","2"] e "locationId": ["A","B"], o Visibilidade de estoque consultará automaticamente o resultado para os seguintes sites e locais:

  • Site 1, local A
  • Site 1, local B
  • Site 2, local A
  • Site 2, local B

Como você pode ver, a consulta disponível regular não reconhece que o local A existe apenas no site 1 e o local B existe apenas no site 2. Portanto, ela faz consultas redundantes. Para acomodar esse mapeamento hierárquico, você pode usar uma consulta exata disponível e especificar os mapeamentos de localização no corpo da consulta. Nesse caso, você consultará e receberá resultados apenas para o site 1, local A, e para o site 2, local B.

Consulta de consulta exata disponível usando o método POST

A consulta exata disponível por API de postagem está disponível em duas versões. A tabela a seguir descreve as diferenças.

API versão 1.0 API versão 2.0
Só pode consultar uma ID de organização. Pode consultar várias IDs da organização.

Consulta exata disponível por API pós versão 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,
    }

Na parte do corpo desta solicitação, dimensionDataSource é um parâmetro opcional. Se não estiver definido, dimensions em filters será tratado como dimensões básicas. Há quatro campos obrigatórios para filters: organizationId, productId, dimensions e values.

  • organizationId deve conter apenas um valor, mas ainda é uma matriz.
  • productId pode conter um ou mais valores. Se for uma matriz vazia, todos os produtos serão retornados.
  • Na matriz dimensions, siteId e locationId são necessárias se e somente se a regra de partição de dados estiver definida como Por local. Nesse caso, elas podem aparecer com outros elementos em qualquer ordem.
  • O campo values pode conter uma ou mais tuplas de valores correspondendo a dimensions.

O campo dimensions em filters será adicionado automaticamente a groupByValues.

O parâmetro returnNegative controla se os resultados contêm entradas negativas.

O exemplo a seguir mostra o conteúdo do corpo de exemplo.

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

O exemplo a seguir mostra como consultar todos os produtos em vários sites e locais.

{
    "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 exata disponível por API pós versão 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,
    }

A versão 2.0 da API difere da versão 1.0 das seguintes maneiras:

  • A filters seção agora tem um keys campo em vez de um dimensions campo. O keys campo funciona como o dimensions campo na versão 1.0, mas agora também pode incluir organizationId. Você pode especificar as chaves em qualquer ordem.
  • A filters seção não dá mais suporte ao organizationId campo. Em vez disso, você pode incluir organizationId entre as dimensões no keys campo (por exemplo, keys: ["organizationId", "siteId", "locationId"]) e definir valores de ID da organização na posição correspondente no values campo (por exemplo, values: ["SCM_IV", "iv_contoso_site_1", "iv_contoso_location_1"]).

Outros campos são idênticos à API versão 1.0.

Consulta com pesquisa de produto

As seguintes APIs de consulta disponíveis foram aprimoradas para dar suporte à pesquisa de produto:

Anotação

Ao postar uma consulta de visibilidade de estoque que usa pesquisa de produto, use o parâmetro de solicitação productSearch (com um objeto ProductAttributeQuery dentro) para encontrar ou filtrar por ID do produto. As APIs mais recentes não dão mais suporte ao parâmetro de solicitação productid anterior no corpo da solicitação.

Pré-requisitos

Para começar a usar as APIs de pesquisa do produto, o sistema deve atender aos seguintes requisitos:

Contrato da pesquisa de produto

O contrato da pesquisa de produto define as regras de comunicação com as APIs de pesquisa de produto. Ele oferece uma maneira padronizada de descrever os recursos e o comportamento dos recursos de pesquisa de produto. Por isso, os usuários podem compreender, criar e interagir mais facilmente com aplicativos que consomem as APIs da Visibilidade de Estoque.

O exemplo a seguir mostra um contrato de amostra.

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

A tabela a seguir descreve os campos usados no contrato.

ID do Campo Descrição
logicalOperator Os valores possíveis são And e Or. Use esse campo para conectar várias condições ou condições e subfiltros. Na verdade, subFilters é um objeto productFilter ou attributeFilter. Por isso, você pode ter subFilters dentro de subFilters.
conditionOperator Os valores possíveis são IsExactly, IsNot, Contains, DoesNotContain, BeginsWith, IsOneOf, GreaterEqual, LessEqual e Between.
ProductFilter Use esse campo para filtrar produtos por informações relacionadas ao produto. Por exemplo, você pode alterar productName no contrato para Company, itemNumber, productSearchName, productType, productName, productDescription, inventoryUnitSymbol, salesUnitSymbol ou purchaseUnitSymbol para atender às necessidades comerciais.
AttributeFilter Use esse campo para filtrar produtos por informações relacionadas ao atributo.
attributeArea Os valores possíveis são ProductAttribute, DimensionAttribute e 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,
    }

O exemplo a seguir mostra o conteúdo do corpo de exemplo.

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

O exemplo a seguir mostra uma resposta bem-sucedida.

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

O exemplo a seguir mostra o conteúdo do corpo de exemplo.

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

O exemplo a seguir mostra uma resposta bem-sucedida.

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

Disponível para promessa

É possível configurar a Visibilidade do Estoque para permitir que você agende alterações futuras disponíveis e calcule as quantidades do ATP. ATP é a quantidade de um item que está disponível e pode ser prometida a um cliente no próximo período. O uso do cálculo do ATP pode aumentar bastante o recurso de preenchimento de seu pedido. Para obter informações sobre como habilitar esse recurso e como interagir com a Visibilidade do Estoque por meio de sua API após a habilitação do recurso, consulte Agenda de alterações disponíveis e disponível para promessa de Visibilidade de Estoque.

Alocação

As APIs relacionadas à alocação estão localizadas em Alocação da Visibilidade de estoque.