Share via

APIs públicas da aplicação Visibilidade do Inventário

  • Artigo

Nota

O Azure Active Directory é agora o Microsoft Entra ID. Saber mais

Este artigo descreve as APIs públicas que são fornecidas pela Visibilidade de Inventário.

A API REST pública do Suplemento de Visibilidade do Inventário apresenta vários pontos finais específicos para a integração. Suporta quatro tipos principais de interação:

  • Lançar alterações de inventário disponível no suplemento a partir de um sistema externo
  • Definir ou anular quantidades de inventário disponível no suplemento a partir de um sistema externo
  • Lançar eventos de reserva no suplemento a partir de um sistema externo
  • Consultar as quantidades atuais disponíveis a partir de um sistema externo

A tabela seguinte lista as APIs que estão disponíveis atualmente:

Caminho Método Descrição
/api/environment/{environmentId}/onhand Lançar Criar um evento de alteração de disponibilidade
/api/environment/{environmentId}/onhand/bulk Lançar Criar vários eventos de alteração
/api/environment/{environmentId}/setonhand/{inventorySystem}/bulk Lançar Definir/anular quantidades disponíveis
/api/environment/{environmentId}/onhand/reserve Lançar Criar um evento de reserva preliminar
/api/environment/{environmentId}/onhand/reserve/bulk Lançar Criar vários eventos de reserva preliminares
/api/environment/{environmentId}/onhand/unreserve Lançar Reverter um evento de reserva preliminar
/api/environment/{environmentId}/onhand/unreserve/bulk Lançar Reverter vários eventos de reserva preliminares
/api/environment/{environmentId}/onhand/reserve/resyncjob Lançar Limpeza de dados da reserva
/api/environment/{environmentId}/onhand/changeschedule Lançar Criar uma alteração de disponibilidade entrega imediata agendada
/api/environment/{environmentId}/onhand/changeschedule/bulk Lançar Criar várias alterações de disponibilidade com datas
/api/environment/{environmentId}/onhand/indexquery Lançar Consultar utilizando o método de publicação (recomendado)
/api/environment/{environmentId}/onhand Obter Consultar utilizando o método de obtenção
/api/environment/{environmentId}/onhand/exactquery Lançar Consulta exata utilizando o método de publicação
/api/environment/{environmentId}/allocation/allocate Lançar Criar um evento de alocação
/api/environment/{environmentId}/allocation/unallocate Lançar Criar um evento de anular alocação
/api/environment/{environmentId}/allocation/reallocate Lançar Criar um evento de realocação
/api/environment/{environmentId}/allocation/consume Lançar Criar um evento de consumo
/api/environment/{environmentId}/allocation/query Lançar Consultar resultado da alocação
/api/environment/{environmentId}/onhand/productsearch/indexquery Lançar Consulta de índice de publicação com pesquisa de produtos
/api/environment/{environmentId}/onhand/productsearch/exactquery Lançar Consulta exata de publicação com pesquisa de produtos

Nota

A parte {environmentId} do caminho é o ID do ambiente no Microsoft Dynamics Lifecycle Services.

A API em volume pode devolver um máximo de 512 registos para cada pedido.

Autenticação

O token de segurança da plataforma é utilizado para chamar a API pública de Visibilidade do Inventário. Portanto, tem de gerar um token do Microsoft Entra através da sua aplicação Microsoft Entra. Em seguida, deve usar o token do Microsoft Entra para obter o token de acesso a partir do serviço de segurança.

Para obter um token de serviço de segurança, siga estes passos.

  1. Inicie sessão no portal Azure e use-o para encontrar os valores clientId e clientSecret para a sua aplicação Dynamics 365 Supply Chain Management.

  2. Obter um token do Microsoft Entra (aadToken) submetendo um pedido HTTP que tenha as seguintes propriedades:

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

    • Método:GET

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

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

    Deve receber um token do Microsoft Entra (aadToken) em resposta. Deve assemelhar-se ao seguinte exemplo.

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

  3. Formular um pedido de JSON (JavaScript Object Notation) que se assemelha ao seguinte exemplo.

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

    Tenha em conta os seguintes pontos:

    • O valor client_assertion tem de ser o token do Microsoft Entra (aadToken) que recebeu no passo anterior.
    • O valor context tem de ser o ID do ambiente Lifecycle Services onde pretende implementar o suplemento.
    • Defina todos os outros valores, como mostrado no exemplo.

  4. Obter um token de acesso (access_token) submetendo um pedido HTTP que tenha 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 o pedido JSON que criou no passo anterior.

    Deve receber um token de acesso (access_token) em resposta. Tem de usar este token como um token de portador para chamar a API de Visibilidade do Inventário. Veja aqui um exemplo.

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

Nota

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

Criar eventos de alteração de disponibilidade

Existem duas APIs para criar eventos de alteração de disponibilidade:

  • Criar um registo: /api/environment/{environmentId}/onhand
  • Criar vários registos: /api/environment/{environmentId}/onhand/bulk

A tabela seguinte resume o significado de cada campo no corpo JSON.

ID do Campo Descrição
id Uma identificação exclusiva para o evento de alteração específico. Se ocorrer nova submissão devido a falha do serviço, este ID é utilizado para garantir que o mesmo evento não será contado duas vezes no sistema.
organizationId O identificador da organização que está ligada ao evento. Este valor é mapeado para uma organização ou ID 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, este valor será quantities:{ shelf:{ received: 10 }}. Se três livros forem removidos da prateleira ou vendidos, este valor será quantities:{ shelf:{ sold: 3 }}.
dimensionDataSource A origem de dados das dimensões que são utilizadas no lançamento do evento e consulta da alteração. Se especificar a origem de dados, pode utilizar as dimensões personalizadas a partir da origem de dados especificada. A Visibilidade do Inventário pode usar a configuração da dimensão para mapear as dimensões personalizadas para as dimensões predefinidas gerais. Se não for especificado qualquer valor dimensionDataSource, pode utilizar apenas as dimensões de base gerais nas suas consultas.
dimensions Um par dinâmico valor-chave. Os valores são mapeados para algumas das dimensões no Supply Chain Management. No entanto, também pode adicionar dimensões personalizadas (por exemplo, Origem) para indicar se o evento vem do Supply Chain Management ou de um sistema externo.

Nota

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

As subsecções que se seguem fornecem exemplos que mostram como utilizar estas APIs.

Criar um evento de alteração de disponibilidade

Esta API cria um único evento de alteração de disponibilidade.

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 de amostra do corpo. Neste exemplo, a empresa tem um sistema de ponto de venda (POS) que processa transações na loja e, portanto, alterações de inventário. O cliente devolveu uma T-shirt vermelha à sua loja. Para refletir a alteração, publica um único evento de alteração para o produto T-shirt. Este evento irá aumentar a quantidade do produto T-shirt 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 de amostra do corpo sem dimensionDataSource. Neste caso, dimensions serão as dimensões de base. Se dimensionDataSource estiver definido, dimensions podem ser as dimensões da origem de dados ou as dimensões de base.

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

Esta API pode criar eventos de alteração, tal como a API de evento único. A única diferença é que esta API pode criar vários registos ao mesmo tempo. Por conseguinte, os valores Path e Body diferem. Para esta API, Body fornece uma série de registos. O número máximo de registos é 512. Por conseguinte, a API de alteração de disponibilidade em massa pode suportar até 512 eventos de modificação de cada vez.

Por exemplo, uma máquina de POS de uma loja de retalho processou as duas transações seguintes:

  • Uma ordem de devolução de uma T-shirt vermelha
  • Uma transação de venda de três T-shirts pretas

Neste caso, pode incluir ambas as atualizações de inventário numa chamada à 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 de amostra do corpo.

[
    {
        "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/anular quantidades disponíveis

A API Definir disponibilidade sobrepõe-se aos dados atuais do produto especificado. Esta funcionalidade é, normalmente, utilizada para fazer atualizações de contagem de inventário. Por exemplo, durante a contagem diária do inventário, uma loja pode descobrir que o inventário real disponível para uma T-shirt vermelha é 100. Portanto, a quantidade de entrada do POS tem de ser atualizada para 100, independentemente da quantidade anterior. Pode utilizar 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 de amostra do corpo. O comportamento desta API difere do comportamento das APIs que são descritas na secção Criar eventos de alteração de disponibilidade mais atrás neste artigo. Nesta amostra, a quantidade do produto T-shirt será definida para 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 utilizar a API Reserva, tem de ativar a caraterística de reserva e completar a configuração da reserva. Para mais informações (incluindo um fluxo de dados e um cenário de amostra), consulte Reservas de Visibilidade do Inventário.

Criar um evento de reserva

Uma reserva pode ser feita com base em diferentes configurações de origem de dados. Para configurar este tipo de reserva, primeiro especifique a origem de dados no parâmetro dimensionDataSource. Em seguida, no parâmetro dimensions, especifique as dimensões de acordo com as definições de dimensão na origem de dados de destino.

Quando chama a API de reserva, pode controlar a validação da reserva especificando o parâmetro booleano ifCheckAvailForReserv no corpo de pedido. Um valor de True significa que a validação é necessária, enquanto um valor de False significa que a validação não é necessária. O valor predefinido é True.

Se pretender reverter uma reserva ou cancelar a reserva de quantidades de inventário especificadas, defina a quantidade como um valor negativo e defina o parâmetro ifCheckAvailForReserv como False para ignorar a validação. Existe também uma API dedicada de anular reserva para fazer o mesmo. A diferença está apenas na forma como as duas APIs são chamadas. É mais fácil reverter um evento de reserva específico utilizando reservationId com a API anular reserva. Para mais informações, consulte a secção Anular reserva 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 de amostra do corpo.

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

Esta API é uma versão em volume 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 Anular reserva funciona como a operação inversa dos eventos Reserva. Permite anular um evento de reserva especificado por reservationId ou diminuir a quantidade da reserva.

Reverter um evento de reserva

Quando uma reserva é criada, um reservationId será incluído no corpo da resposta. É necessário fornecer o mesmo reservationId para cancelar a reserva e incluir os mesmos organizationId, productId e dimensions utilizados para a chamada à API da reserva. Por fim, especifique um valor OffsetQty que represente o número de itens a libertar da reserva anterior. Uma reserva pode ser total ou parcialmente anulada, consoante o OffsetQty especificado. Por exemplo, se 100 unidades de itens foram reservadas, pode especificar OffsetQty: 10 para anular a reserva de 10 da quantidade inicialmente 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
    }

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 de um corpo de resposta bem-sucedido.

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

Nota

No corpo da resposta, quando OffsetQty for inferior ou igual à quantidade da reserva, processingStatus será "success" e totalInvalidOffsetQtyByReservId será 0.

Se OffsetQty for superior ao montante reservado, processingStatus será "partialSuccess" e totalInvalidOffsetQtyByReservId será a diferença entre OffsetQty e o montante 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

Esta API é uma versão em volume 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
        }
        ...
    ]

Limpeza de dados da reserva

A API Limpar dados da reserva é utilizada para limpar os dados históricos das reservas. O corpo deve ser uma lista de origens de dados. Se a lista estiver vazia, todas as origens 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 a disponibilidade

Utilize a API Consultar a disponibilidade para obter dados de inventário atuais sobre a disponibilidade dos seus produtos. Pode utilizar esta API sempre que precisar de conhecer o inventário, por exemplo, quando quiser rever os níveis de inventário de produtos no seu site de comércio eletrónico ou quando quiser verificar a disponibilidade de produtos em várias regiões ou em lojas e armazéns próximos. A API suporta atualmente a consulta até 5,000 itens individuais por valor productID. Vários valores siteID e locationID também podem ser especificados em cada consulta. Quando a sua regra de partição de dados está definida como Por localização, o limite máximo é definido pela seguinte equação:

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

Consultar utilizando o método de publicação

A API de consulta por correio está disponível em duas versões. O quadro seguinte apresenta as diferenças.

API versão 1.0 API versão 2.0
Só é possível consultar um ID da organização. Pode consultar vários IDs de organização.
Pode consultar até 10.000 combinações de locais e armazéns. Pode consultar mais de 10.000 combinações de IDs de organizações, locais e armazéns. Pode devolver resultados em várias páginas.

As subsecções seguintes mostram como utilizar cada versão da API.

Consulta por correio 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 deste pedido, dimensionDataSource é um parâmetro opcional. Se não estiver definido, filters será tratado como dimensões de base.

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

Consulta de dados armazenados por localização

Esta secção aplica-se quando a sua regra de partição de dados está definida como Por localização.

  • organizationId deve ser uma matriz que contenha exatamente um valor.
  • productId pode conter um ou mais valores. Se for uma matriz vazia, o sistema devolverá todos os produtos para sites e localizações especificados. Neste caso, siteId e locationId não devem estar vazios.
  • siteId e locationId são utilizados para a criação de partições. Pode especificar mais do que um valor siteId e locationId num pedido para Consultar a disponibilidade. Se ambas as matrizes estiverem vazias, o sistema devolverá todos os sites e localizações para os produtos especificados. Neste caso, productId não deve estar vazio.

Recomendamos que utilize o parâmetro groupByValues de uma forma que seja consistente com a sua configuração de índice. Para mais informações, consulte Configuração do índice de disponibilidade.

Consulta de dados armazenados por ID de produto

Esta secção aplica-se quando a sua regra de partição de dados está definida como Por ID de produto. Neste caso, são necessários dois campos filters: organizationId, productId.

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

Ao contrário do que acontece com o armazenamento de dados por localização, se não especificar valores para siteId e locationId, as informações de inventário para cada ID de produto serão agregadas em todos os locais e/ou localizações.

Nota

Se tiver ativado as caraterísticas de agenda de alterações de disponibilidade e disponível para promessa (ATP), a sua consulta também pode incluir o parâmetro booleano QueryATP, que controla se os resultados da consulta incluem informações ATP. Para mais informações e exemplos, consulte Agendamentos de alterações de disponíveis para entrega imediata da Visibilidade do Inventário e disponível para promessa.

O exemplo a seguir mostra o conteúdo de amostra do corpo. Mostra que pode consultar o inventário disponível a partir de várias localizações (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 mostram como consultar todos os produtos num local e localização específicos.

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

Consulta por correio 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 pedido para a versão 2.0 da API é semelhante ao da versão 1.0, mas também suporta dois parâmetros opcionais: pageNumber e pageSize, que permitem ao sistema dividir um único resultado grande em vários documentos mais pequenos. Os resultados são ordenados por armazém (locationId), e os parâmetros são utilizados da seguinte forma para dividir os resultados em páginas:

  • pageSize estabelece o número de armazéns (valores emlocationId ) que são devolvidos em cada página.
  • pageNumber estabelece o número de página que é devolvido.

Um pedido deste formato devolve dados de inventário em curso a partir do número de armazém ({pageNumber} - 1) × {pageSize} e inclui dados para os próximos {pageSize} armazéns.

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

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

Quando o pedido chega ao último armazém (locationId), o valor nextLink é uma cadeia vazia.

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

Consultar utilizando o método de obtenção

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]

Eis uma amostra do URL de obtenção. Este pedido de obtenção é exatamente o mesmo que a amostra de lançamento que foi fornecida 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 suporta a consulta de inventário em vários IDs de organização com o método GET.

Consulta exata de disponibilidade

As consultas exatas manuais assemelham-se às consultas de disponibilidade normais, mas permitem especificar uma hierarquia de mapeamento entre um site e uma localização. Por exemplo, tem os seguintes dois sites:

  • Site 1, que está mapeado para a localização A
  • Site 2, que está mapeado para a localização B

Para uma consulta normal de disponibilidade, se especificar "siteId": ["1","2"] e "locationId": ["A","B"], a Visibilidade do Inventário consultará automaticamente o resultado para os seguintes sites e localizações:

  • Site 1, localização A
  • Site 1, localização B
  • Site 2, localização A
  • Site 2, localização B

Como se pode ver, a consulta de disponibilidade normal não reconhece que a localização A existe apenas no site 1 e que a localização B existe apenas no site 2. Por conseguinte, realiza consultas redundantes. Para acomodar este mapeamento hierárquico, pode utilizar uma consulta exata de disponibilidade e especificar os mapeamentos de localização no corpo da consulta. Neste caso, irá consultar e receber resultados apenas para o site 1, localização A e site 2, localização B.

Consulta exacta disponível utilizando o método de lançamento

A API de consulta exacta disponível por correio está disponível em duas versões. O quadro seguinte apresenta as diferenças.

API versão 1.0 API versão 2.0
Só é possível consultar um ID da organização. Pode consultar vários IDs de organização.

Consulta exacta disponível por correio API 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 deste pedido, dimensionDataSource é um parâmetro opcional. Se não estiver definido, dimensions em filters será tratado como dimensões de base. Existem quatro campos obrigatórios para filters: organizationId, productId, dimensions e values.

  • organizationId deve conter apenas um valor, mas ainda é uma matriz.
  • productId poderia conter um ou mais valores. Se for uma matriz vazia, todos os produtos serão devolvidos.
  • Na matriz dimensions, siteId e locationId são necessários se e apenas se a regra de partição de dados estiver definida como Por localização. Neste caso, podem aparecer com outros elementos em qualquer ordem.
  • values poderia conter uma ou mais cadeias de identificação distintas de valores correspondentes a dimensions.

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 de amostra do corpo.

{
    "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 mostram como consultar todos os produtos em vários sites e localizações.

{
    "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 disponível por correio API 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 nos seguintes aspectos:

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

Os outros campos são idênticos aos da versão 1.0 da API.

Consulta com pesquisa de produtos

As seguintes APIs de consulta de disponibilidades foram melhoradas para suportar a pesquisa de produtos:

Nota

Ao publicar uma consulta de Visibilidade do Inventário que usa a pesquisa de produtos, use o parâmetro de pedido productSearch (com um objeto ProductAttributeQuery dentro) para localizar ou filtrar por ID do produto. As APIs mais recentes já não suportam o parâmetro de pedido productid mais antigo no corpo do pedido.

Pré-requisitos

Antes de poder começar a utilizar as APIs de pesquisa de produtos, o sistema tem de cumprir os seguintes requisitos:

Contrato da pesquisa de produtos

O contrato da pesquisa de produtos define as regras de comunicação com as APIs de pesquisa de produtos. Fornece uma forma padronizada de descrever as capacidades e o comportamento das capacidades de pesquisa de produtos. Assim, os utilizadores podem, mais facilmente, compreender, interagir e criar aplicações que consumam as APIs da Visibilidade do Inventário.

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 seguinte descreve os campos utilizados no contrato.

ID do Campo Descrição
logicalOperator Os valores possíveis são And e Or. Utilize este campo para ligar várias condições ou condições e subfiltros. Note que subFilters é, na realidade, um objeto productFilter ou attributeFilter. Por conseguinte, pode ter subFilters dentro de subFilters.
conditionOperator Os valores possíveis são IsExactly, IsNot, Contains, DoesNotContain, BeginsWith, IsOneOf, GreaterEqual, LessEqual e Between.
ProductFilter Utilize este campo para filtrar produtos por informações relacionadas com o produto. Por exemplo, pode alterar productName no contrato para Company, itemNumber, productSearchName, productType, productName, productDescription, inventoryUnitSymbol, salesUnitSymbol ou purchaseUnitSymbol para satisfazer as suas necessidades comerciais.
AttributeFilter Utilize este campo para filtrar produtos por informações relacionadas com o 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 de amostra do corpo.

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

O exemplo seguinte 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 de amostra do corpo.

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

O exemplo seguinte 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

Pode configurar a Visibilidade do Inventário para permitir o agendamento de alterações futuras de disponibilidade e calcular quantidades ATP. ATP é a quantidade de um item que está disponível e pode ser prometida a um cliente no período seguinte. O uso do cálculo de ATP pode aumentar muito a sua capacidade de cumprimento de pedidos. Para informações sobre como ativar esta caraterística e como interagir com a Visibilidade do Inventário através da respetiva API depois de a caraterística ser ativada, consulte Agendas de alteração de disponibilidade e disponível para promessa da Visibilidade do Inventário.

Alocação

As APIs relacionadas com a alocação estão localizadas em Alocação da Visibilidade do Inventário.