Delen via

Openbare API's voor Inventory Visibility

  • Artikel

Opmerking

Azure Active Directory is nu Microsoft Entra ID. Meer informatie

In dit artikel worden de openbare API's beschreven die worden geleverd door Voorraadzichtbaarheid.

De openbare REST API van de invoegtoepassing Voorraadzichtbaarheid biedt verschillende specifieke eindpunten voor integratie. De API ondersteunt vier hoofdinteractietypen:

  • Wijzigingen in de voorhanden voorraad naar de invoegtoepassing boeken vanuit een extern systeem
  • Instellen of overschrijven van voorhanden voorraadhoeveelheden in de invoegtoepassing vanuit een extern systeem
  • Reserveringsgebeurtenissen boeken naar de invoegtoepassing vanuit een extern systeem
  • Huidige voorhanden hoeveelheden opvragen vanuit een extern systeem

De volgende tabel bevat de API's die momenteel beschikbaar zijn:

Pad methode Omschrijving
/api/environment/{environmentId}/onhand Plaatsen Eén wijzigingsgebeurtenis maken voor voorhanden voorraad
/api/environment/{environmentId}/onhand/bulk Plaatsen Meerdere wijzigingsgebeurtenissen maken voor voorhanden voorraad
/api/environment/{environmentId}/setonhand/{inventorySystem}/bulk Plaatsen Voorhanden hoeveelheden instellen/overschrijven
/api/environment/{environmentId}/onhand/reserve Plaatsen Eén zachte reserveringsgebeurtenis maken
/api/environment/{environmentId}/onhand/reserve/bulk Plaatsen Meerdere zachte reserveringsgebeurtenissen maken
/api/environment/{environmentId}/onhand/unreserve Plaatsen Eén zachte reserveringsgebeurtenis terugdraaien
/api/environment/{environmentId}/onhand/unreserve/bulk Plaatsen Meerdere zachte reserveringsgebeurtenissen terugdraaien
/api/environment/{environmentId}/onhand/reserve/resyncjob Plaatsen Reserveringsgegevens opschonen
/api/environment/{environmentId}/onhand/changeschedule Plaatsen Eén geplande wijziging in de voorhanden hoeveelheid maken
/api/environment/{environmentId}/onhand/changeschedule/bulk Plaatsen Meerdere wijzigingen in de voorhanden hoeveelheid maken met datums
/api/environment/{environmentId}/onhand/indexquery Plaatsen Een query uitvoeren met de post-methode (aanbevolen)
/api/environment/{environmentId}/onhand Ophalen Een query uitvoeren met de get-methode
/api/environment/{environmentId}/onhand/exactquery Plaatsen Een exacte query uitvoeren met de post-methode
/api/environment/{environmentId}/allocation/allocate Plaatsen Eén toewijzingsgebeurtenis maken
/api/environment/{environmentId}/allocation/unallocate Plaatsen Eén gebeurtenis voor ongedaan maken van toewijzing maken
/api/environment/{environmentId}/allocation/reallocate Plaatsen Eén gebeurtenis voor opnieuw toewijzen maken
/api/environment/{environmentId}/allocation/consume Plaatsen Eén verbruiksgebeurtenis maken
/api/environment/{environmentId}/allocation/query Plaatsen Querytoewijzingsresultaat
/api/environment/{environmentId}/onhand/productsearch/indexquery Plaatsen Indexquery met productzoekopdracht plaatsen
/api/environment/{environmentId}/onhand/productsearch/exactquery Plaatsen Exacte query met productzoekopdracht plaatsen

Opmerking

Het deel {environmentId} van het pad is de omgevings-id in Microsoft Dynamics Lifecycle Services.

De bulk-API kan maximaal 512 records voor elke aanvraag retourneren.

Verificatie

Het beveiligingstoken voor het platform wordt gebruikt om de openbare API Voorraadzichtbaarheid aan te roepen. U moet daarom een Microsoft Entra-token genereren met de Microsoft Entra-toepassing. Vervolgens moet u het Microsoft Entra-token gebruiken om het toegangstoken op te halen van de beveiligingsservice.

Ga als volgt te werk om een beveiligingstoken voor de service te krijgen.

  1. Meld u aan bij de Azure-portal en gebruik de portal om de waarden clientId en clientSecret voor uw Dynamics 365 Supply Chain Management-app te vinden.

  2. Haal een Microsoft Entra-token (aadToken) op door een HTTP-aanvraag met de volgende eigenschappen in te dienen:

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

    • Methode:GET

    • Inhoud hoofdtekst (formuliergegevens):

      Sleutel Waarde
      client_id ${aadAppId}
      client_secret ${aadAppSecret}
      grant_type client_credentials
      bereik 0cdb527f-a8d1-4bf8-9436-b352c68682b2/.default

    U moet een Microsoft Entra-token (aadToken) als reactie ontvangen. Het resultaat moet lijken op het volgende voorbeeld.

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

  3. Formuleer een JSON-aanvraag (JavaScript Object Notation) die op het volgende voorbeeld lijkt.

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

    Let op de volgende punten:

    • De waarde client_assertion moet het Microsoft Entra-token (aadToken) zijn dat u in de vorige stap hebt ontvangen.
    • De waarde context moet de omgevings-id van Lifecycle Services zijn waarin u de invoegtoepassing wilt implementeren.
    • Stel alle andere waarden in zoals in het voorbeeld wordt weergegeven.

  4. Haal een toegangstoken (access_token) op door een HTTP-aanvraag in te dienen met de volgende eigenschappen:

    • URL:https://securityservice.operations365.dynamics.com/token
    • Methode:POST
    • HTTP-header: neem de API-versie op. (De sleutel is Api-Version en de waarde is 1.0.)
    • Inhoud hoofdtekst: neem de JSON-aanvraag op die u in de vorige stap hebt gemaakt.

    U moet een toegangstoken (access_token) als reactie ontvangen. U moet dit token gebruiken als Bearer-token voor het aanroepen van de API Voorraadzichtbaarheid. Dit is een voorbeeld.

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

Notitie

De https://securityservice.operations365.dynamics.com/token-URL is een algemene URL voor de beveiligingsservice. Wanneer u de URL aanroept, is het eerste antwoord een http-omleidingsrespons met de statuscode 307 in de antwoordkopteksten en een vermelding met de sleutel Locatie die de doel-URL voor de beveiligingsservice bevat. Voor de URL wordt de volgende notatie gebruikt: https://gw.{$geo}-il101.gateway.prod.island.powerapps.com/securityservice/token. Als uw omgeving zich bijvoorbeeld in de geografische locatie VS bevindt, kan de URL https://gw.us-il101.gateway.prod.island.powerapps.com/securityservice/token zijn. Als de antwoordstatuscode 307 voor u niet acceptabel is, kunt u de werkelijke URL handmatig maken volgens uw FinOps-omgevingslocatie. De eenvoudigste manier is om https://gw.as-il101.gateway.prod.island.powerapps.com/securityservice/token met uw browser te openen en vervolgens het adres in de adresbalk te kopiëren.

Wijzigingsgebeurtenissen maken voor voorhanden voorraad

Er zijn twee API's voor het maken van wijzigingsgebeurtenissen voor voorhanden voorraad:

  • Eén record maken: /api/environment/{environmentId}/onhand
  • Meerdere records maken: /api/environment/{environmentId}/onhand/bulk

In de volgende tabel wordt de betekenis van elk veld in de JSON-tekst samengevat.

Veld-id Description
id Een unieke id voor de specifieke wijzigingsgebeurtenis. Als vanwege een servicefout de gegevens opnieuw worden ingediend, wordt deze id gebruikt om ervoor te zorgen dat dezelfde gebeurtenis niet twee keer in het systeem wordt geteld.
organizationId De id van de organisatie die aan de gebeurtenis is gekoppeld. Deze wordt toegewezen aan een organisatie of gegevensgebied-id in Supply Chain Management.
productId De identificatie van het product.
quantities De hoeveelheid waarmee de voorhanden hoeveelheid moet worden gewijzigd. Als er bijvoorbeeld 10 nieuwe boeken aan een plank worden toegevoegd, is deze waarde quantities:{ shelf:{ received: 10 }}. Als er drie boeken worden verwijderd van de plank of worden verkocht, is deze waarde quantities:{ shelf:{ sold: 3 }}.
dimensionDataSource De gegevensbron van de dimensies die worden gebruikt bij het boeken van de wijzigingsgebeurtenis en de query. Als u de gegevensbron opgeeft, kunt u de aangepaste dimensies gebruiken van de opgegeven gegevensbron. Voorraadzichtbaarheid kan de dimensieconfiguratie gebruiken om de aangepaste dimensies toe te wijzen aan de algemene standaarddimensies. Als er geen waarde voor dimensionDataSource is opgegeven, kunt u alleen de algemene basisdimensies in uw query's gebruiken.
dimensions Een dynamisch sleutelwaardepaar. De waarden worden aan enkele van de dimensies in Supply Chain Management toegewezen. U kunt echter ook aangepaste dimensies toevoegen (bijvoorbeeld Bron) om aan te geven of de gebeurtenis afkomstig is uit Supply Chain Management of uit een extern systeem.

Opmerking

Als uw gegevenspartitieregel is ingesteld op Op product-id, zijn siteId en locationId optionele dimensies. Anders zijn het vereiste dimensies. Deze regel geldt ook voor API's voor toewijzing, zachte reservering en planning wijzigen.

De volgende subsecties geven voorbeelden die laten zien hoe u deze API's gebruikt.

Eén wijzigingsgebeurtenis maken voor voorhanden voorraad

Met deze API wordt ëén wijzigingsgebeurtenis gemaakt voor voorhanden voorraad.

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

In het volgende voorbeeld wordt een voorbeeld van de inhoud van de hoofdtekst weergegeven. In dit voorbeeld heeft het bedrijf een POS-systeem (point-of-sale) dat winkeltransacties verwerkt en dus voorraadwijzigingen. De klant heeft een rood y-shirt naar uw winkel geretourneerd. Om de wijziging aan te geven boekt u één wijzigingsgebeurtenis voor het product T-shirt. Met deze gebeurtenis wordt de hoeveelheid van het product T-shirt verhoogd met 1.

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

In het volgende voorbeeld wordt een voorbeeld gegeven van de inhoud van de hoofdtekst zonder dimensionDataSource. In dit geval zijn dimensions de basisdimensies. Als dimensionDataSource is ingesteld, kunnen dimensions de gegevensbrondimensies of de basisdimensies zijn.

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

Meerdere wijzigingsgebeurtenissen maken voor voorhanden voorraad

Met deze API kunnen wijzigingsgebeurtenissen worden gemaakt, net als bij de API voor één gebeurtenis. Het enige verschil is dat met deze API meerdere records tegelijkertijd kunnen worden gemaakt. Daarom verschillen de waarden van Path en Body. Voor deze API biedt Body een matrix van records. Het maximum aantal records is 512. Daarom kan de bulk-API voor wijzigingen in de voorhanden hoeveelheid maximaal 512 wijzigingsgebeurtenissen per keer ondersteunen.

Een POS-apparaat voor de detailhandel verwerkt bijvoorbeeld de volgende twee transacties:

  • Eén retourorder van één rood t-shirt
  • Eén verkooptransactie van drie zwarte t-shirts

In dit geval kunt u beide voorraadupdates opnemen in één API-aanroep.

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

In het volgende voorbeeld wordt een voorbeeld van de inhoud van de hoofdtekst weergegeven.

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

Voorhanden hoeveelheden instellen/overschrijven

Met de API Voorhanden set worden de huidige gegevens voor het opgegeven product overschreven. Deze functionaliteit wordt meestal gebruikt om voorraadtellingsupdates uit te voeren. Tijdens de dagelijkse voorraadtelling van een winkel wordt bijvoorbeeld vastgesteld dat de werkelijke voorraad voor een rood t-shirt 100 is. Daarom moet de inkomende POS-hoeveelheid worden bijgewerkt naar 100, ongeacht wat de vorige hoeveelheid was. Gebruik deze API om de bestaande waarde te overschrijven.

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

In het volgende voorbeeld wordt een voorbeeld van de inhoud van de hoofdtekst weergegeven. Het gedrag van deze API verschilt van het gedrag van de API's dat wordt beschreven in de sectie Wijzigingsgebeurtenissen maken voor voorhanden voorraad eerder in dit artikel. In dit voorbeeld wordt de hoeveelheid van het product T-shirt ingesteld op 1.

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

Reserveringsgebeurtenissen maken

Als u de Reserve-API wilt gebruiken, moet u de reserveringsfunctie inschakelen en de reserveringsconfiguratie voltooien. Zie Reserveringen voor voorraadzichtbaarheid voor meer informatie (inclusief een gegevensstroom en voorbeeldscenario).

Eén reserveringsgebeurtenis maken

Er kan een reservering worden gemaakt met verschillende instellingen voor de gegevensbron. Als u dit type reservering wilt configureren, geeft u eerst de gegevensbron op in de parameter dimensionDataSource. Geef vervolgens in de parameter dimensions de dimensies op aan de hand van de dimensie-instellingen in de doelgegevensbron.

Wanneer u de reserverings-API aanroept, kunt u de reserveringsvalidatie beheren door de booleaanse parameter ifCheckAvailForReserv op te geven in de aanvraagbody. De waarde True betekent dat de validatie is vereist, terwijl de waarde False betekent dat de validatie niet is vereist. De standaardwaarde is True.

Als u een reservering wilt terugdraaien of de reservering van opgegeven voorraadhoeveelheden wilt verwijderen, stelt u de hoeveelheid in op een negatieve waarde en stelt u de parameter ifCheckAvailForReserv in op False om de validatie over te slaan. U kunt dit ook doen met een speciale API voor het opheffen van de reservering. Het verschil is alleen de manier waarop de twee API's worden aangeroepen. U kunt een specifieke reserveringsgebeurtenis eenvoudiger terugdraaien door gebruik te maken van reservationId met de unreserve API. Raadpleeg het gedeelte Eén reserveringsgebeurtenis terugdraaien voor meer informatie.

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

In het volgende voorbeeld wordt een voorbeeld van de inhoud van de hoofdtekst weergegeven.

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

In het volgende voorbeeld is een geslaagd antwoord gegeven.

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

Meerdere reserveringsgebeurtenissen maken

Deze API is een bulkversie van de API voor één gebeurtenis.

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

Reserveringsgebeurtenissen terugdraaien

De Unreserve API wordt gebruikt als de omgekeerde bewerking voor reserveringsgebeurtenissen. Het is een manier om een reserveringsgebeurtenis terug te draaien die is opgegeven met reservationId of om de reserveringshoeveelheid te verlagen.

Eén reserveringsgebeurtenis terugdraaien

Wanneer u een reservering maakt, wordt een reservationId opgenomen in de antwoordtekst. Geef dezelfde reservationId op om de reservering te annuleren en neem dezelfde organizationId, productId en dimensions op die voor de API-aanroep van de reservering worden gebruikt. Geef ten slotte een OffsetQty-waarde op voor het aantal items dat moet worden vrij gemaakt uit de vorige reservering. Een reservering kan volledig of gedeeltelijk worden teruggedraaid, afhankelijk van de opgegeven OffsetQty-reservering. Als er bijvoorbeeld 100 eenheden zijn gereserveerd, geeft u OffsetQty: 10 op om 10 van de oorspronkelijke gereserveerde hoeveelheid terug te draaien.

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
    }

In de volgende code ziet u een voorbeeld van de inhoud van de hoofdtekst.

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

In de volgende code ziet u een voorbeeld van een geslaagd antwoord.

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

Notitie

Wanneer in de antwoordtekst OffsetQty kleiner is dan of gelijk is aan de reserveringshoeveelheid, is de processingStatus geslaagd en is totalInvalidOffsetQtyByReservId 0.

Als OffsetQty groter is dan de gereserveerde hoeveelheid, is processingStatus partialSuccess en geeft totalInvalidOffsetQtyByReservId het verschil aan tussen OffsetQty en de gereserveerde hoeveelheid.

Als de reservering bijvoorbeeld een hoeveelheid van 10 heeft en OffsetQty een waarden van 12, is totalInvalidOffsetQtyByReservId 2.

Meerdere reserveringsgebeurtenissen terugdraaien

Deze API is een bulkversie van de API voor één gebeurtenis.

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

Reserveringsgegevens opschonen

De APO reserveringsgegevens opschonen wordt gebruikt om historische reserveringsgegevens op te schonen. De hoofdtekst moet een lijst met gegevensbronnen zijn. Als de lijst leeg is, worden alle gegevensbronnen opgeschoond.

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

Voorhanden query

Gebruik de API Voorhanden query om huidige voorhanden voorraadgegevens voor uw producten op te halen. U kunt deze API gebruiken wanneer u op de hoogte moet zijn van de voorraad, bijvoorbeeld wanneer u de productvoorraadniveaus op uw e-commercewebsite wilt bekijken, of wanneer u de beschikbaarheid van producten in regio's of in winkels en magazijnen in de buurt wilt controleren. De API ondersteunt momenteel query's met maximaal 5000 afzonderlijke artikelen per productID-waarde. Ook kunnen in elke query meerdere siteID- en locationID-waarden worden opgegeven. Wanneer uw gegevenspartitieregel is ingesteld op Op locatie wordt de maximumlimiet bepaald door de volgende vergelijking.

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

Een query uitvoeren met de post-methode

De API voor query's is beschikbaar in twee versies. De volgende tabel bevat de verschillen.

API versie 1.0 API versie 2.0
Kan slechts een organisatie-ID opvragen. Meerdere organisatie-IDs opvragen.
Er kunnen tot 10.000 combinaties van locaties en magazijnen worden opgevraagd. Er kunnen meer dan 10.000 combinaties van organisatie-ID's, locaties en magazijnen worden opgevraagd. Kan resultaten op meerdere pagina's retourneren.

In de volgende subsecties wordt elke API-versie gebruikt.

Query op bericht API versie 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,
    }

In de hoofdtekst van deze aanvraag is dimensionDataSource een optionele parameter. Als deze parameter niet is ingesteld, worden filters als basisdimensies beschouwd.

De parameter returnNegative bepaalt of de resultaten negatieve vermeldingen bevatten.

Querygegevens opgeslagen op locatie

Deze sectie is van toepassing wanneer uw gegevenspartitieregel is ingesteld op Op locatie.

  • organizationId mag een matrix zijn die precies één waarde bevat.
  • productId kan een of meer waarden bevatten. Als het een lege matrix is, retourneert het systeem alle producten voor de opgegeven sites en locaties. In dit geval mogen siteId en locationId niet leeg zijn.
  • siteId en locationId worden gebruikt voor partitionering. U kunt meer dan één waarde voor siteId en locationId opgeven in een aanvraag voor een Voorhanden query. Als beide matrixen leeg zijn, retourneert het systeem alle sites en locaties voor de opgegeven producten. In dit geval mag productId niet leeg zijn.

Wij adviseren u de parameter groupByValues te gebruiken op een manier die consistent is met uw indexconfiguratie. Zie Voorhanden indexconfiguratie voor meer informatie.

Querygegevens opgeslagen op product-id

Deze sectie is van toepassing wanneer uw gegevenspartitieregel is ingesteld op Op product-id. In dit geval zijn twee filters-velden vereist: organizationId, productId.

  • organizationId mag een matrix zijn die precies één waarde bevat.
  • productId mag een matrix zijn met ten minste één waarde.

In tegenstelling tot wanneer u gegevens opslaat op locatie, worden voorraadgegevens voor elke product-id als u geen waarden voor siteId en locationId opgeeft geaggregeerd binnen alle sites en/of locaties.

Opmerking

Als u de functies voor planning van wijzigingen in voorhanden voorraad en available to promise (ATP) hebt ingeschakeld, kan uw query ook de booleaanse parameter QueryATP bevatten, waarmee wordt bepaald of de queryresultaten ATP-informatie bevatten. Zie Planningen van wijzigingen in voorhanden hoeveelheid en available to promise in Voorraadzichtbaarheid voor meer informatie en voorbeelden.

In het volgende voorbeeld wordt een voorbeeld van de inhoud van de hoofdtekst weergegeven. Hier ziet u dat u een query kunt uitvoeren op de voorhanden voorraad vanuit meerdere locaties (magazijnen).

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

Het volgende voorbeeld laat zien hoe u een query uitvoert op een specifieke site en locatie.

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

Query op bericht API versie 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

De aanvraagindeling voor API versie 2.0 is vergelijkbaar met die van versie 1.0, maar ondersteunt ook twee optionele parameters: pageNumber pageSize waardoor het systeem één groot resultaat kan opsplitsen in verschillende kleinere documenten. De resultaten worden gesorteerd op magazijn (locationId) en de parameters worden als volgt gebruikt om resultaten op te splitsen in pagina's:

  • pageSize legt het aantal magazijnen (locationId waarden) vast dat op elke pagina wordt geretourneerd.
  • pageNumber legt het paginanummer vast dat wordt geretourneerd.

Een aanvraag van deze indeling retourneert de gegevens van de beschikbare voorraad vanaf het magazijnnummer({pageNumber} − 1 × {pageSize} ) en bevat gegevens voor de volgende {pageSize} magazijnen.

API versie 2.0 reageert met een document dat de volgende structuur gebruikt:

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

Wanneer de aanvraag het laatste magazijn bereikt (locationId), is de nextLink waarde een lege tekenreeks.

Met API versie 2.0 kunt u ook meer dan één organisatie-ID opgeven in uw aanvraag. U doet dit door een door komma's gescheiden lijst met organisatie-IDs op te nemen in het organizationId filter van het aanvraagdocument. Bijvoorbeeld: "organizationId": ["org1", "org2", "org3"]

Een query uitvoeren met de get-methode

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]

Hier is een voorbeeld van een get-URL. Deze get-aanvraag is exact hetzelfde als het post-voorbeeld dat eerder is opgegeven.

/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

Het systeem biedt geen ondersteuning voor het opvragen van voorraad op meerdere organisatie-ID's met de GET-methode.

Query voor exacte voorhanden voorraad

Query's voor de exacte voorhanden voorraad lijkt op de normale query's voor voorhand voorraad, maar u kunt hiermee een toewijzingshiërarchie opgeven tussen een site en een locatie. Stel dat u de volgende twee sites hebt:

  • Site 1, die is gekoppeld aan locatie A
  • Site 2, die is gekoppeld aan locatie B

Als u voor een normale query voor de voorraad "siteId": ["1","2"] en "locationId": ["A","B"] opgeeft, wordt bij de volgende sites en locaties automatisch een query uitgevoerd door Voorraadzichtbaarheid:

  • Site 1, locatie A
  • Site 1, locatie B
  • Site 2, locatie A
  • Site 2, locatie B

Zoals u ziet, herkent de reguliere query niet dat locatie A alleen in site 1 bestaat en locatie B alleen in site 2. Daarom worden overbodige query's gemaakt. Voor deze hiërarchische toewijzing kunt u een exacte query voor voorhanden voorraad gebruiken en de locatietoewijzingen opgeven in de querytekst. In dit geval ontvangt u alleen resultaten voor site 1, locatie A en site 2, locatie B.

Query op de exacte query die op die manier wordt uitgevoerd met behulp van de methode voor het plaatsen van gegevens

De VOORHANDEN query per API voor bericht is in twee versies beschikbaar. De volgende tabel bevat de verschillen.

API versie 1.0 API versie 2.0
Kan slechts een organisatie-ID opvragen. Meerdere organisatie-IDs opvragen.

Exacte query voor de hand door API versie 1.0 te plaatsen

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

In de hoofdtekst van deze aanvraag is dimensionDataSource een optionele parameter. Als deze parameter niet is ingesteld, worden dimensions in filters als basisdimensies beschouwd. Er zijn vier velden vereist voor filters: organizationId, productId, dimensions en values.

  • organizationId mag slechts één waarde bevatten, maar is nog steeds een matrix.
  • productId kan een of meer waarden bevatten. Als het een lege matrix is, worden alle producten geretourneerd.
  • In de matrix dimensions, zijn siteId en locationId vereist als en alleen als uw gegevenspartitieregel is ingesteld op Op locatie. In dit geval kunnen ze in elke volgorde met andere elementen worden weergegeven.
  • values kan een of meer verschillende tuples van waarden bevatten die corresponderen met dimensions.

dimensions in filters worden automatisch toegevoegd aan groupByValues.

De parameter returnNegative bepaalt of de resultaten negatieve vermeldingen bevatten.

In het volgende voorbeeld wordt een voorbeeld van de inhoud van de hoofdtekst weergegeven.

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

Het volgende voorbeeld laat zien hoe u een query uitvoert op een meerdere sites en locaties.

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

Exacte query voor de hand door API versie 2.0 te plaatsen

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

API versie 2.0 verschilt van versie 1.0 op de volgende manieren:

  • De filters sectie heeft nu een veld keys in plaats van een dimensions veld. Het keys veld werkt zoals het veld dimensions in versie 1.0, maar kan nu ook worden gebruikt organizationId. U kunt de sleutels in elke volgorde opgeven.
  • Dit filters veld wordt niet meer ondersteund in de organizationId sectie. In plaats daarvan kunt u in plaats organizationId daarvan de dimensies in keys het veld ( keys: ["organizationId", "siteId", "locationId"]bijvoorbeeld) opnemen en organisatie-ID-waarden definiëren op de overeenkomende positie in values het veld (bijvoorbeeld). values: ["SCM_IV", "iv_contoso_site_1", "iv_contoso_location_1"]

Andere velden zijn identiek aan API versie 1.0.

Zoeken met productzoekopdrachten

De volgende API's voor het zoeken naar voorhanden voorraad zijn verbeterd om het zoeken naar producten te ondersteunen:

Notitie

Wanneer u een zoekopdracht voor voorraadzichtbaarheid plaatst waarbij u naar producten zoekt, gebruikt u de aanvraagparameter productSearch (met een ProductAttributeQuery-object) om op product-id te zoeken of te filteren. De nieuwere API's ondersteunen niet langer de oudere productid-aanvraagparameter in de aanvraagbody.

Vereisten

Voordat u de API's voor het zoeken van producten kunt gebruiken, moet uw systeem aan de volgende vereisten voldoen:

Contract voor het zoeken van producten

Het contract voor het zoeken van producten definieert de regels voor communicatie met de productzoek-API's. Het biedt een gestandaardiseerde manier om de mogelijkheden en het gedrag van de mogelijkheden voor het zoeken van producten te beschrijven. Daarom kunnen gebruikers gemakkelijker toepassingen begrijpen, ermee communiceren en toepassingen bouwen die de Voorraadzichtbaarheid-API's gebruiken.

In het volgende voorbeeld wordt een voorbeeldcontract weergegeven.

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

In de volgende tabel worden de velden beschreven die in het contract worden gebruikt.

Veld-id Description
logicalOperator De mogelijke waarden zijn And en Or. Gebruik dit veld om meerdere voorwaarden of voorwaarden en subfilters te verbinden. subFilters is eigenlijk een productFilter- of attributeFilter-object. Daarom kunt u subFilters in subFilters hebben.
conditionOperator De mogelijke waarden zijn IsExactly, IsNot, Contains, DoesNotContain, BeginsWith, IsOneOf, GreaterEqual, LessEqual en Between.
ProductFilter Gebruik dit veld om producten te filteren op productgerelateerde informatie. U kunt bijvoorbeeld productName in het contract wijzigen in Company, itemNumber, productSearchName, productType, productName, productDescription, inventoryUnitSymbol, salesUnitSymbol of purchaseUnitSymbol om aan uw zakelijke behoeften te voldoen.
AttributeFilter Gebruik dit veld om producten te filteren op kenmerkgerelateerde informatie.
attributeArea De mogelijke waarden zijn ProductAttribute, DimensionAttribute en 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,
    }

In het volgende voorbeeld wordt een voorbeeld van de inhoud van de hoofdtekst weergegeven.

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

In het volgende voorbeeld is een geslaagd antwoord gegeven.

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

In het volgende voorbeeld wordt een voorbeeld van de inhoud van de hoofdtekst weergegeven.

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

In het volgende voorbeeld is een geslaagd antwoord gegeven.

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

U kunt Voorraadzichtbaarheid zo instellen dat u toekomstige wijzigingen in de voorhanden voorraad kunt plannen en ATP-hoeveelheden kunt berekenen. ATP is de hoeveelheid van een artikel, die beschikbaar is en die aan een klant kan worden beloofd in de volgende periode. Het gebruik van de ATP-berekening kan uw capaciteit voor het afhandelen van orders veel groter maken. Zie Planningen van wijzigingen in voorhanden hoeveelheid en available to promise in Voorraadzichtbaarheid voor informatie over hoe u deze functie kunt inschakelen en hoe u kunt communiceren met Voorraadzichtbaarheid via de bijbehorende API nadat de functie is ingeschakeld.

Toewijzing

Toewijzingsgerelateerde API's bevinden zich in de toewijzing Voorraadzichtbaarheid.