API pubbliche di Visibilità inventario

Questo articolo descrive le API pubbliche fornite da Visibilità inventario.

L'API REST pubblica del componente aggiuntivo Visibilità magazzino presenta diversi endpoint specifici per l'integrazione. Supporta quattro tipi principali di interazione:

• Registrazione delle modifiche delle scorte disponibili nel componente aggiuntivo da un sistema esterno
• Impostazione o sovrascrittura delle quantità dell'inventario a disposizione nell'add-in da un sistema esterno
• Inviare eventi di prenotazione all'add-in da un sistema esterno
• Interrogazione delle quantità disponibili correnti da un sistema esterno

La seguente tabella elenca le API che sono attualmente disponibili:

Percorso	Metodo	Description
/api/environment/{environmentId}/onhand	Registra	Creare un evento di cambiamento a portata di mano
/api/environment/{environmentId}/onhand/bulk	Registra	Creare più eventi di cambiamento
/api/environment/{environmentId}/setonhand/{inventorySystem}/bulk	Registra	Impostare/sovrascrivere le quantità disponibili
/api/environment/{environmentId}/onhand/reserve	Registra	Creare un evento di prenotazione temporanea
/api/environment/{environmentId}/onhand/reserve/bulk	Registra	Creare più eventi di prenotazione temporanea
/api/environment/{environmentId}/onhand/unreserve	Registra	Invertire un evento di prenotazione temporanea
/api/environment/{environmentId}/onhand/unreserve/bulk	Registra	Invertire più eventi di prenotazione temporanea
/api/environment/{environmentId}/onhand/reserve/resyncjob	Registra	Pulire i dati di prenotazione
/api/environment/{environmentId}/onhand/changeschedule	Registra	Crea una modifica scorte disponibili programmata
/api/environment/{environmentId}/onhand/changeschedule/bulk	Registra	Crea più modifiche scorte disponibili con date
/api/environment/{environmentId}/onhand/indexquery	Registra	Query usando il metodo post (opzione consigliata)
/api/environment/{environmentId}/onhand	Ottieni	Query usando il metodo get
/api/environment/{environmentId}/onhand/exactquery	Registra	Query esatte usando il metodo post
/api/environment/{environmentId}/allocation/allocate	Registra	Creare un evento di allorazione
/api/environment/{environmentId}/allocation/unallocate	Registra	Creare un evento di annullamento dell'allorazione
/api/environment/{environmentId}/allocation/reallocate	Registra	Creare un evento di riallorazione
/api/environment/{environmentId}/allocation/consume	Registra	Creare un evento di consumo
/api/environment/{environmentId}/allocation/query	Registra	Risultato della query di allocazione
/api/environment/{environmentId}/onhand/productsearch/indexquery	Registra	Registra una query indice con la ricerca del prodotto
/api/environment/{environmentId}/onhand/productsearch/exactquery	Registra	Registra una query esatta con la ricerca del prodotto

Autenticazione

Il token di sicurezza della piattaforma è usato per chiamare l'API pubblica Visibilità inventario. Pertanto, devi generare un token Microsoft Entra usando l'applicazione Microsoft Entra. È quindi necessario utilizzare il token Microsoft Entra per ottenere il token di accesso dal servizio di sicurezza.

Per ottenere un token di servizio di sicurezza, seguite questi passi.

1. Accedi al portale Azure e usalo per trovare i valori clientId e clientSecret per la tua app Dynamics 365 Supply Chain Management.

2. Recupera un token Microsoft Entra (aadToken) inviando una richiesta HTTP che ha le seguenti proprietà:

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

   • Metodo:GET

   • Contenuto del corpo (dati del modulo):

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

   Dovresti ricevere un token Microsoft Entra (aadToken) in risposta. Il risultato sarà simile all'esempio seguente.

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

3. Formulare una richiesta JSON (JavaScript Object Notation) che assomigli al seguente esempio.

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

   Notare i punti seguenti:

   • Il valore client_assertion deve essere il token Microsoft Entra (aadToken) che avete ricevuto nel passo precedente.
   • Il valore context deve essere l'ID dell'ambiente Lifecycle Services in cui si desidera distribuire il componente aggiuntivo.
   • Impostare tutti gli altri valori come mostrato nell'esempio.

4. Recuperare un token di accesso (access_token) inviando una richiesta HTTP che ha le seguenti proprietà:

   • URL:https://securityservice.operations365.dynamics.com/token
   • Metodo:POST
   • Intestazione HTTP: Includere la versione dell'API. (La chiave è Api-Version, e il valore è 1.0.)
   • Contenuto del corpo: Includete la richiesta JSON che avete creato nel passo precedente.

   Dovresti ricevere un token di accesso (access_token) in risposta. È necessario utilizzare questo token come token portatore per chiamare l'API di visibilità dell'inventario. Ecco un esempio.

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

Creare eventi di cambiamento a portata di mano

Ci sono due API per la creazione di eventi di cambiamento on-hand:

• Creare un record: /api/environment/{environmentId}/onhand
• Creare record multipli: /api/environment/{environmentId}/onhand/bulk

La tabella seguente riassume il significato di ogni campo nel corpo JSON.

ID campo	Description
id	Un ID univoco per l'evento di modifica specifico. Se si verifica un nuovo invio a causa di un errore del servizio, questo ID è usato per assicurare che lo stesso evento non sarà contato due volte nel sistema se viene ripresentato.
organizationId	L'identificatore dell'organizzazione che è collegata all'evento. Questo valore è mappato a un'organizzazione o a un ID dell'area dati in Supply Chain Management.
productId	Identificatore del prodotto.
quantities	La quantità di cui deve essere cambiata la quantità a disposizione. Per esempio, se 10 nuovi libri vengono aggiunti a uno scaffale, questo valore sarà quantities:{ shelf:{ received: 10 }}. Se tre libri vengono rimossi dallo scaffale o venduti, questo valore sarà quantities:{ shelf:{ sold: 3 }}.
dimensionDataSource	L'origine dei dati delle dimensioni che sono utilizzate nell'evento di modifica del distacco e nella query. Se si specifica l'origine dati, è possibile utilizzare le dimensioni personalizzate dell'origine dati specificata. Visibilità inventario può utilizzare la configurazione delle dimensioni per mappare le dimensioni personalizzate alle dimensioni generali predefinite. Se nessun valore dimensionDataSource è specificato, puoi usare solo le dimensioni di base generali nelle tue query.
dimensions	Una coppia chiave-valore dinamica. I valori sono mappati ad alcune delle dimensioni del Supply Chain Management. Tuttavia, puoi anche aggiungere dimensioni personalizzate (per esempio, Source) per indicare se l'evento proviene da Supply Chain Management o da un sistema esterno.

Le seguenti sottosezioni forniscono esempi che mostrano come utilizzare queste API.

Creare un evento di cambiamento a portata di mano

Questa API crea un singolo evento di cambiamento on-hand.

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

L'esempio seguente mostra un esempio di contenuto del corpo. In questo esempio, l'azienda dispone di un sistema POS (point of sale) che elabora le transazioni in negozio e quindi le variazioni di inventario. Il cliente ha restituito una maglietta rossa al tuo negozio. Per riflettere la modifica, pubblichi un singolo evento di cambiamento per il prodotto T-shirt . Questo evento aumenterà la quantità del prodotto T-shirt di 1.

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

Il seguente esempio mostra un esempio di contenuto del corpo senza dimensionDataSource. In questo caso, le dimensions saranno le dimensioni di base. Se dimensionDataSource è impostato, le dimensions possono essere le dimensioni dell'origine dati o le dimensioni di base.

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

Creare più eventi di cambiamento

Questa API può creare eventi di modifica, proprio come l'API a evento singolo. L'unica differenza è che questa API può creare più record allo stesso tempo. Quindi, i valori Path e Body differiscono. Per questa API, Body fornisce un array di record. Il numero massimo di record è 512. Pertanto, l'API della programmazione delle modifiche delle scorte disponibili può supportare fino a 512 eventi di modifica alla volta.

Ad esempio, un computer POS di un punto vendita al dettaglio ha elaborato le seguenti due transazioni:

• Un ordine di reso di una maglietta rossa
• Una transazione di vendita di tre magliette nere

In questo caso, puoi includere entrambi gli aggiornamenti dell'inventario in una chiamata 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,
                },
            },
        },
        ...
    ]

L'esempio seguente mostra un esempio di contenuto del 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 }
        }
    }
]

Impostare/sovrascrivere le quantità disponibili

L'API Set on-hand sovrascrive i dati attuali per il prodotto specificato. Questa funzionalità viene in genere utilizzata per eseguire gli aggiornamenti del conteggio dell'inventario. Ad esempio, durante il conteggio giornaliero dell'inventario, un punto vendita potrebbe scoprire che l'inventario effettivamente disponibile per una maglietta rossa è 100. Pertanto, la quantità in entrata POS deve essere aggiornata a 100, indipendentemente da quale fosse la quantità precedente. Puoi utilizzare questa API per sovrascrivere il valore esistente.

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

L'esempio seguente mostra un esempio di contenuto del corpo. Il comportamento di questa API differisce da quello delle API che sono descritte nella sezione Creare eventi di modifica on-hand in precedenza in questo articolo. In questo esempio, la quantità del prodotto T-shirt sarà impostata a 1.

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

Creare eventi di prenotazione

Per utilizzare l'API di riserva , è necessario attivare la funzione di prenotazione e completare la configurazione della prenotazione. Per ulteriori informazioni (incluso un flusso di dati e uno scenario di esempio), vedere Prenotazioni di visibilità dell'inventario.

Creare un evento di prenotazione

È possibile effettuare una prenotazione su impostazioni dell'origine dati diverse. Per configurare questo tipo di prenotazione, specificare prima l'origine dati nel parametro dimensionDataSource. Quindi, nel parametro dimensions, specificare le dimensioni in base alle impostazioni delle dimensioni nell'origine dati di destinazione.

Quando si chiama l'API di prenotazione, è possibile controllare la convalida della prenotazione specificando il parametro booleano ifCheckAvailForReserv nel corpo della richiesta. Un valore di True significa che è richiesta la convalida, mentre un valore di False significa che la convalida non è richiesta. Il valore predefinito è True.

Se si desidera annullare una prenotazione o annullare la prenotazione di quantità delle scorte specificate, impostare la quantità su un valore negativo e impostare il parametro ifCheckAvailForReserv su False per saltare la convalida. Esiste anche un'API per annullare la prenotazione dedicata per fare lo stesso. La differenza è solo nel modo in cui vengono chiamate le due API. È più facile annullare un evento di prenotazione specifico utilizzando reservationId con l'API di annullamento della prenotazione. Per ulteriori informazioni, vedere Annullare la prenotazione di un evento di prenotazione.

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

L'esempio seguente mostra un esempio di contenuto del 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"
    }
}

L'esempio seguente mostra una risposta riuscita.

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

Creare più eventi di prenotazione

Questa API è una versione in blocco dell' API a evento singolo.

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

Annullare gli eventi di prenotazione

L'API Annulla prenotazione funge da operazione di annullamento per gli eventi Prenotazione. Fornisce un modo per annullare un evento di prenotazione specificato da reservationId o per diminuire la quantità di prenotazione.

Annullare la prenotazione di un evento

Quando viene creata una prenotazione, un reservationId sarà incluso nel corpo di risposta. Devi fornire lo stesso reservationId per annullare la prenotazione, e includere gli stessi organizationId, productId e dimensions utilizzati per la chiamata API di prenotazione. Infine, specificare un valore OffsetQty che rappresenta il numero di elementi da liberare dalla prenotazione precedente. Una prenotazione può essere completamente o parzialmente annullata a seconda del valore OffsetQty specificato. Ad esempio, se 100 unità di articoli sono state prenotate, è possibile specificare OffsetQty: 10 per annullare la prenotazione di 10 dell'importo iniziale riservato.

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
    }

Il codice seguente mostra un esempio di contenuto del 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
}

Il codice seguente mostra un esempio del corpo della risposta riuscita.

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

Annullare più eventi di prenotazione

Questa API è una versione in blocco dell' API a evento singolo.

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
        }
        ...
    ]

Pulire i dati di prenotazione

L'API per pulire i dati di prenotazione viene utilizzata per ripulire i dati storici delle prenotazioni. Il corpo dovrebbe essere un elenco di origini dati. Se l'elenco è vuoto, tutte le origini dati verranno pulite.

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

Query disponibilità

Usa l'API Query disponibilità per recuperare i dati di inventario correnti per i tuoi prodotti. Puoi utilizzare questa API ogni volta che devi conoscere lo stock, ad esempio quando desideri esaminare i livelli di stock dei prodotti sul tuo sito Web di e-commerce o quando desideri verificare la disponibilità dei prodotti nelle aree geografiche o nei punti vendita e magazzini vicini. L'API attualmente supporta l'esecuzion di query di fino a 5000 singoli elementi con il valore productID. Più valori siteID e locationID possono anche essere specificati in ogni query. Quando la regola di partizione dei dati è impostata su Per posizione, il limite massimo è definito dalla seguente equazione:

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

Query usando il metodo post

La query tramite API post è disponibile in due versioni. La tabella seguente illustra le differenze.

Versione API 1.0	Versione dell'API 2.0
È possibile eseguire query su un solo ID organizzazione.	Può eseguire query su più ID organizzazione.
Può interrogare fino a 10.000 combinazioni di siti e magazzini.	Può interrogare più di 10.000 combinazioni di ID organizzazione, siti e magazzini. Può restituire risultati su più pagine.

Le sottosezioni seguenti mostrano come utilizzare ciascuna versione dell'API.

Query per posta API versione 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,
    }

Nella parte del corpo di questa richiesta, dimensionDataSource è un parametro facoltativo. Se non è impostato, i filters saranno considerati come dimensioni di base.

Il parametro returnNegative controlla se i risultati contengono voci negative.

Eseguire query sui dati memorizzati in base alla posizione

Questa sezione si applica quando la regola di partizione dei dati è impostata su Per posizione.

• organizationId dovrebbe essere un array contenente esattamente un valore.
• productId può contenere uno o più valori. Se si tratta di un array vuoto, il sistema restituirà tutti i prodotti dei siti e delle ubicazioni specifici. In questo caso siteId e locationId non devono essere vuoti.
• siteId e locationId sono usati per il partizionamento. È possibile specificare più di un valore siteId e locationId in una richiesta Query disponibilità. Se entrambi gli array sono vuoti, il sistema restituirà tutti i siti e le posizioni dei prodotti specifici. In questo caso productId non deve essere vuoto.

Ti consigliamo di utilizzare il parametro groupByValues in modo coerente con la configurazione dell'indice. Per maggiori informazioni, vedi Configurazione dell'indice di scorte disponibili.

Eseguire query per i dati memorizzati per ID prodotto

Questa sezione si applica quando la regola di partizione dei dati è impostata su Per ID prodotto. In questo caso sono obbligatori due campi filters: organizationId, productId.

• organizationId dovrebbe essere un array contenente esattamente un valore.
• productId dovrebbe essere un array con almeno un valore.

A differenza dell'archiviazione dei dati in base alla posizione, se non specifichi valori per siteId e locationId, le informazioni sull'inventario per ciascun ID prodotto verranno aggregate in tutti i siti e/o posizioni.

L'esempio seguente mostra un esempio di contenuto del corpo. Mostra che è possibile eseguire query sull'inventario disponibile da più posizioni (magazzini).

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

L'esempio seguente mostra come eseguire query su tutti i prodotti in un sito e in una posizione specifici.

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

Query per posta API versione 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

Il formato di richiesta per la versione API 2.0 è simile a quello della versione 1.0, ma supporta anche due parametri opzionali: pageNumber e pageSize, che consentono al sistema di dividere un unico grande risultato in più documenti più piccoli. I risultati vengono ordinati per magazzino (locationId) e i parametri vengono utilizzati come segue per suddividere i risultati in pagine:

• pageSize stabilisce il numero di magazzini (locationId valori) che vengono restituiti in ogni pagina.
• pageNumber stabilisce il numero di pagina restituito.

Una richiesta di questo formato restituisce i dati delle scorte disponibili a partire dal numero di magazzino ({pageNumber} − 1) × {pageSize} e include i dati per il successivo {pageSize} magazzini.

La versione API 2.0 risponde con un documento che utilizza la seguente struttura:

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

Quando la richiesta raggiunge l'ultimo magazzino (locationId), il valore nextLink è una stringa vuota.

La versione API 2.0 ti consente inoltre di specificare più di un ID organizzazione nella tua richiesta. A tale scopo, includi un elenco di ID organizzazione separati da virgole nel organizationId filtro del documento di richiesta. Ad esempio, "organizationId": ["org1", "org2", "org3"].

Query usando il metodo 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]

Ecco un esempio di URL. Questa richiesta di get è esattamente la stessa dell'esempio di post che è stato fornito prima.

/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

Il sistema non supporta l'esecuzione di query sull'inventario su più ID organizzazione con il metodo GET.

Query sulla disponibilità esatta

Le query sulla disponibilità esatta assomigliano alle normali query disponibili, ma consentono di specificare una gerarchia di mapping tra un sito e una posizione. Per esempio, hai i seguenti due siti:

• Sito 1, mappato alla posizione A
• Sito 2, mappato alla posizione B

Per una normale richiesta di disponibilità, se specifichi "siteId": ["1","2"] e "locationId": ["A","B"], Visibilità inventario eseguirà automaticamente query sul risultato per i seguenti siti e località:

• Sito 1, posizione A
• Sito 1, posizione B
• Sito 2, posizione A
• Sito 2, posizione B

Come vedi, la normale query sulla disponibilità non riconosce che la posizione A esiste solo nel sito 1 e la posizione B esiste solo nel sito 2. Pertanto, effettua query ridondanti. Per soddisfare questo mapping gerarchico, è possibile utilizzare una query esatta disponibile e specificare i mapping della posizione nel corpo della query. In questo caso, eseguirai la query e riceverai i risultati solo per il sito 1, posizione A e per il sito 2, posizione B.

Query di query esatta disponibile utilizzando il metodo post

La query esatta disponibile tramite API post è disponibile in due versioni. La tabella seguente illustra le differenze.

Versione API 1.0	Versione dell'API 2.0
È possibile eseguire query su un solo ID organizzazione.	Può eseguire query su più ID organizzazione.

Query esatta disponibile tramite API post versione 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,
    }

Nella parte del corpo di questa richiesta, dimensionDataSource è un parametro facoltativo. Se non è impostato, dimensions in filters saranno considerati come dimensioni di base. Sono presenti quattro campi obbligatori per filters: organizationId, productId, dimensions e values.

• organizationId deve contenere un solo valore, ma è ancora una matrice.
• productId potrebbe contenere uno o più valori. Se è una matrice vuota, verranno restituiti tutti i prodotti.
• Nell'array dimensions, siteId e locationId sono obbligatori se e solo se la regola di partizione dei dati è impostata per Per posizione. In questo caso, potrebbero apparire con altri elementi in qualsiasi ordine.
• values potrebbe contenere una o più distinte tuple di valori corrispondenti a dimensions.

I valori dimensions in filters verranno automaticamente aggiunti a groupByValues.

Il parametro returnNegative controlla se i risultati contengono voci negative.

L'esempio seguente mostra un esempio di contenuto del 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
}

L'esempio seguente mostra come eseguire query su tutti i prodotti in più siti e ubicazioni.

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

Query esatta disponibile tramite la versione API post 2.0

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

La versione API 2.0 differisce dalla versione 1.0 nei seguenti modi:

• La sezione filters ora ha un campo keys invece di un campo dimensions . Il campo keys funziona come il campo dimensions nella versione 1.0, ma ora può includere anche organizationId. È possibile specificare le chiavi in ​​qualsiasi ordine.
• La sezione filters non supporta più il campo organizationId . Puoi invece includere organizationId tra le dimensioni nel campo keys (ad esempio, keys: ["organizationId", "siteId", "locationId"]) e definire i valori dell'ID organizzazione nella posizione corrispondente nel values campo (ad esempio, values: ["SCM_IV", "iv_contoso_site_1", "iv_contoso_location_1"]).

Gli altri campi sono identici alla versione API 1.0.

Query con la ricerca del prodotto

Le seguenti API di query disponibili sono state migliorate per supportare la ricerca di prodotti:

• Query usando il metodo post
• Query esatte usando il metodo post

Prerequisiti

Prima di poter iniziare a usare le API di ricerca dei prodotti, il tuo sistema deve soddisfare i seguenti requisiti:

• Devi usare Dynamics 365 Supply Chain Management versione 10.0.36 o successiva.
• Devi aver installato e configurato Visibilità inventario versione 1.2.2.54 o successiva, come descritto in Installare e configurare Visibilità inventario.
• Devi aver installato il servizio di ricerca Visibilità inventario come descritto in Configurare la Impostare la ricerca di prodotti per Visibilità inventario.

Contratto per la ricerca di prodotti

Il contratto per la ricerca di prodotti definisce le regole per la comunicazione con le API di ricerca di prodotti. Fornisce un modo standardizzato per descrivere le funzionalità e il comportamento delle funzionalità di ricerca di prodotti. Pertanto, gli utenti possono comprendere, interagire e creare più facilmente applicazioni che utilizzano le API di Visibilità inventario.

L'esempio seguente mostra un esempio di contratto.

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

Nella tabella seguente sono descritti i campi usati nel contratto.

ID campo	Descrizione
logicalOperator	I valori possibili sono And e Or. Utilizza questo campo per connettere più condizioni o condizioni e filtri secondari. Nota che subFilters è in realtà un oggetto productFilter o attributeFilter. Pertanto, puoi avere subFilters in subFilters.
conditionOperator	I valori possibili sono IsExactly, IsNot, Contains, DoesNotContain, BeginsWith, IsOneOf, GreaterEqual, LessEqual e Between.
ProductFilter	Utilizza questo campo per filtrare i prodotti in base alle informazioni relative al prodotto. Ad esempio, puoi cambiare productName nel contratto in Company, itemNumber, productSearchName, productType, productName, productDescription, inventoryUnitSymbol, salesUnitSymbol o purchaseUnitSymbol per soddisfare le tue esigenze aziendali.
AttributeFilter	Utilizza questo campo per filtrare i prodotti in base alle informazioni relative all'attributo.
attributeArea	I valori possibili sono ProductAttribute, DimensionAttribute e BatchAttribute.

Query con la ricerca del prodotto

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

L'esempio seguente mostra un esempio di contenuto del corpo.

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

L'esempio seguente mostra una risposta riuscita.

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

Query esatta con la ricerca del prodotto

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

L'esempio seguente mostra un esempio di contenuto del corpo.

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

L'esempio seguente mostra una risposta riuscita.

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

Available-to-promise

È possibile impostare la visibilità inventario per pianificare le modifiche future disponibili e calcolare le quantità ATP. ATP è la quantità di un articolo disponibile e che può essere promessa a un cliente nel prossimo periodo. L'uso del calcolo ATP può aumentare notevolmente la capacità di evasione degli ordini. Per informazioni su come abilitare questa funzione e su come interagire con la visibilità inventario tramite la relativa API dopo che la funzione è stata abilitata, vedi Visibilità dell'inventario con programmazioni di modifiche scorte disponibili e available-to-promise.

Allocazione

Le API relative all'allocazione si trovano in Allocazione di Inventory Visibility.