APIs públicas da aplicação Visibilidade do Inventário
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.
Inicie sessão no portal Azure e use-o para encontrar os valores
clientId
eclientSecret
para a sua aplicação Dynamics 365 Supply Chain Management.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" }
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.
- O valor
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 }
-
URL:
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
elocationId
não devem estar vazios. -
siteId
elocationId
são utilizados para a criação de partições. Pode especificar mais do que um valorsiteId
elocationId
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.
Uma solicitação deste formato retorna dados de estoque em depósito a partir do número do depósito ({pageNumber} - 1) × {pageSize} e inclui dados para os próximos {pageSize} depósitos.
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
elocationId
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 adimensions
.
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 campokeys
em vez de um campodimensions
. O campokeys
funciona como o campodimensions
na versão 1.0, mas agora também pode incluirorganizationId
. Pode especificar as chaves por qualquer ordem. - A secção
filters
já não suporta o campoorganizationId
. Em vez disso, é possível incluirorganizationId
entre as dimensões no campokeys
(por exemplo,keys: ["organizationId", "siteId", "locationId"]
) e definir valores de ID da organização na posição correspondente no campovalues
(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:
- Deverá estar a executar o Dynamics 365 Supply Chain Management 10.0.36 ou posterior.
- A versão 1.2.2.54 ou posterior da Visibilidade do Inventário tem de estar instalada e configurada conforme descrito em Instalar e configurar a Visibilidade do Inventário.
- O serviço de pesquisa da Visibilidade do Inventário tem de estar instalado e configurado, conforme descrito em Configurar a pesquisa de produtos da Visibilidade do Inventário.
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 . |
Consulta com pesquisa de produtos
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
}
}
}
]
Consulta exata com pesquisa de produtos
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.