Skip to main content

Actions

The ballerinax/sap.s4hana.api_material_stock_srv package exposes the following clients:

ClientPurpose
ClientProvides read-only access to SAP S/4HANA material stock, stock in the account model and material serial numbers via the API_MATERIAL_STOCK_SRV OData API.

Client​

Provides read-only access to SAP S/4HANA material stock, stock in the account model and material serial numbers via the API_MATERIAL_STOCK_SRV OData API.

Configuration​

The client is initialized with a ConnectionConfig record, the SAP S/4HANA hostname and an optional port (default 443). The client builds the service URL https://<hostname>:<port>/sap/opu/odata/sap/API_MATERIAL_STOCK_SRV from these values.

FieldTypeDefaultDescription
authhttp:BearerTokenConfig|OAuth2RefreshTokenGrantConfig|http:CredentialsConfigRequiredAuthentication configuration; use http:CredentialsConfig (username/password) for Basic Auth with the communication user.
httpVersionhttp:HttpVersionhttp:HTTP_2_0HTTP protocol version understood by the client.
http1Settingshttp:ClientHttp1Settings{}HTTP/1.x protocol settings.
http2Settingshttp:ClientHttp2Settings{}HTTP/2 protocol settings.
timeoutdecimal60Maximum time (in seconds) to wait for a response before closing the connection.
forwardedstring"disable"Choice of setting the forwarded/x-forwarded header.
followRedirectshttp:FollowRedirects()Redirection settings.
poolConfighttp:PoolConfiguration()Request pooling settings.
cachehttp:CacheConfig{}HTTP caching settings.
compressionhttp:Compressionhttp:COMPRESSION_AUTOHow the accept-encoding header is handled.
circuitBreakerhttp:CircuitBreakerConfig()Circuit breaker settings.
retryConfighttp:RetryConfig()Retry settings.
cookieConfighttp:CookieConfig()Cookie settings.
responseLimitshttp:ResponseLimitConfigs{}Inbound response size limits.
secureSockethttp:ClientSecureSocket()SSL/TLS configuration for secure connections.
proxyhttp:ProxyConfig()Proxy server configuration.
socketConfighttp:ClientSocketConfig{}Client socket settings.
validationbooleantrueEnables inbound payload validation using the constraint package.
laxDataBindingbooleantrueEnables relaxed data binding, treating nil values as optional and absent fields as nilable.

Initializing the client​

import ballerinax/sap.s4hana.api_material_stock_srv as materialstock;

configurable string hostname = ?;
configurable string username = ?;
configurable string password = ?;

materialstock:Client materialStockClient = check new (
    {
        auth: {
            username: username,
            password: password
        }
    },
    hostname
);

Operations​

All entity operations of this API are read-only. Stock records in the account model (A_MatlStkInAcctMod) are identified by eleven key fields: Material, Plant, StorageLocation, Batch, Supplier, Customer, WBSElementInternalID, SDDocument, SDDocumentItem, InventorySpecialStockType and InventoryStockType. Key fields that do not apply to a stock record (for example, Supplier for own stock) are passed with the initial values returned by the API, such as an empty string.

In the query records, $select, $expand and $orderby take arrays of the allowed property names, and $top and $skip take integers.

Material stock​

listA_MaterialStocks

Retrieves a collection of materials with their base unit of measure. Expand to_MatlStkInAcctMod to include the stock records of each material.

Parameters:

NameTypeRequiredDescription
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesListA_MaterialStocksQueriesNoOData query parameters: $filter, $select, $expand, $orderby, $top, $skip, $inlinecount.

Returns: CollectionOfA_MaterialStockWrapper|error

Sample code:

materialstock:CollectionOfA_MaterialStockWrapper result = check materialStockClient->listA_MaterialStocks(
    queries = {
        \$filter: "startswith(Material,'TG')",
        \$top: 3,
        \$orderby: ["Material"]
    }
);

Sample response:

{
  "d": {
    "results": [
      {
        "Material": "TG10",
        "MaterialBaseUnit": "PC"
      },
      {
        "Material": "TG11",
        "MaterialBaseUnit": "PC"
      },
      {
        "Material": "TG12",
        "MaterialBaseUnit": "KG"
      }
    ]
  }
}
getA_MaterialStock

Retrieves the material ID and base unit of measure for a specific material.

Parameters:

NameTypeRequiredDescription
MaterialstringYesMaterial number (e.g., "TG11").
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesGetA_MaterialStockQueriesNoOData query parameters: $select, $expand.

Returns: A_MaterialStockWrapper|error

Sample code:

materialstock:A_MaterialStockWrapper material = check materialStockClient->getA_MaterialStock(
    "TG11",
    queries = {
        \$expand: ["to_MatlStkInAcctMod"]
    }
);

Sample response:

{
  "d": {
    "Material": "TG11",
    "MaterialBaseUnit": "PC",
    "to_MatlStkInAcctMod": {
      "results": [
        {
          "Material": "TG11",
          "Plant": "1010",
          "StorageLocation": "101A",
          "Batch": "",
          "Supplier": "",
          "Customer": "",
          "WBSElementInternalID": "00000000",
          "SDDocument": "",
          "SDDocumentItem": "000000",
          "InventorySpecialStockType": "",
          "InventoryStockType": "01",
          "WBSElementExternalID": "",
          "MaterialBaseUnit": "PC",
          "MatlWrhsStkQtyInMatlBaseUnit": "250.000"
        }
      ]
    }
  }
}
listMatlStkInAcctModsOfA_MaterialStock

Retrieves the stock records in the account model for a specific material, one record per combination of plant, storage location, batch, stock type and special stock.

Parameters:

NameTypeRequiredDescription
MaterialstringYesMaterial number (e.g., "TG11").
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesListMatlStkInAcctModsOfA_MaterialStockQueriesNoOData query parameters: $filter, $select, $expand, $orderby, $top, $skip, $inlinecount.

Returns: CollectionOfA_MatlStkInAcctModWrapper|error

Sample code:

materialstock:CollectionOfA_MatlStkInAcctModWrapper stock = check materialStockClient->listMatlStkInAcctModsOfA_MaterialStock(
    "TG11",
    queries = {
        \$filter: "Plant eq '1010'",
        \$select: ["Plant", "StorageLocation", "InventoryStockType", "MatlWrhsStkQtyInMatlBaseUnit", "MaterialBaseUnit"]
    }
);

Sample response:

{
  "d": {
    "results": [
      {
        "Plant": "1010",
        "StorageLocation": "101A",
        "InventoryStockType": "01",
        "MaterialBaseUnit": "PC",
        "MatlWrhsStkQtyInMatlBaseUnit": "250.000"
      },
      {
        "Plant": "1010",
        "StorageLocation": "101A",
        "InventoryStockType": "02",
        "MaterialBaseUnit": "PC",
        "MatlWrhsStkQtyInMatlBaseUnit": "12.000"
      }
    ]
  }
}

Stock in account model​

listA_MatlStkInAcctMods

Retrieves a collection of material stock records in the account model, with the warehouse stock quantity in the base unit of measure for each stock identifier combination.

Parameters:

NameTypeRequiredDescription
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesListA_MatlStkInAcctModsQueriesNoOData query parameters: $filter, $select, $expand, $orderby, $top, $skip, $inlinecount.

Returns: CollectionOfA_MatlStkInAcctModWrapper|error

Sample code:

materialstock:CollectionOfA_MatlStkInAcctModWrapper result = check materialStockClient->listA_MatlStkInAcctMods(
    queries = {
        \$filter: "Plant eq '1010' and InventoryStockType eq '01'",
        \$top: 2,
        \$inlinecount: "allpages"
    }
);

Sample response:

{
  "d": {
    "__count": "148",
    "results": [
      {
        "Material": "TG10",
        "Plant": "1010",
        "StorageLocation": "101A",
        "Batch": "",
        "Supplier": "",
        "Customer": "",
        "WBSElementInternalID": "00000000",
        "SDDocument": "",
        "SDDocumentItem": "000000",
        "InventorySpecialStockType": "",
        "InventoryStockType": "01",
        "WBSElementExternalID": "",
        "MaterialBaseUnit": "PC",
        "MatlWrhsStkQtyInMatlBaseUnit": "80.000"
      },
      {
        "Material": "TG11",
        "Plant": "1010",
        "StorageLocation": "101A",
        "Batch": "",
        "Supplier": "",
        "Customer": "",
        "WBSElementInternalID": "00000000",
        "SDDocument": "",
        "SDDocumentItem": "000000",
        "InventorySpecialStockType": "",
        "InventoryStockType": "01",
        "WBSElementExternalID": "",
        "MaterialBaseUnit": "PC",
        "MatlWrhsStkQtyInMatlBaseUnit": "250.000"
      }
    ]
  }
}
getA_MatlStkInAcctMod

Retrieves a single material stock record in the account model identified by its full set of stock identifiers.

Parameters:

NameTypeRequiredDescription
MaterialstringYesMaterial in respect of which stock is managed (e.g., "TG11").
PlantstringYesPlant (e.g., "1010").
StorageLocationstringYesStorage location (e.g., "101A").
BatchstringYesBatch number (stock identifier); empty string when the material is not batch managed.
SupplierstringYesSupplier for special stock; empty string for own stock.
CustomerstringYesCustomer for special stock; empty string for own stock.
WBSElementInternalIDstringYesValuated sales order stock WBS element (e.g., "00000000" when not applicable).
SDDocumentstringYesSales order number of valuated sales order stock; empty string when not applicable.
SDDocumentItemstringYesSales order item of valuated sales order stock (e.g., "000000" when not applicable).
InventorySpecialStockTypestringYesSpecial stock type; empty string for own stock.
InventoryStockTypestringYesStock type of goods movement (e.g., "01" for unrestricted-use stock).
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesGetA_MatlStkInAcctModQueriesNoOData query parameters: $select, $expand.

Returns: A_MatlStkInAcctModWrapper|error

Sample code:

materialstock:A_MatlStkInAcctModWrapper stockRecord = check materialStockClient->getA_MatlStkInAcctMod(
    "TG11",
    "1010",
    "101A",
    "",
    "",
    "",
    "00000000",
    "",
    "000000",
    "",
    "01"
);

Sample response:

{
  "d": {
    "Material": "TG11",
    "Plant": "1010",
    "StorageLocation": "101A",
    "Batch": "",
    "Supplier": "",
    "Customer": "",
    "WBSElementInternalID": "00000000",
    "SDDocument": "",
    "SDDocumentItem": "000000",
    "InventorySpecialStockType": "",
    "InventoryStockType": "01",
    "WBSElementExternalID": "",
    "MaterialBaseUnit": "PC",
    "MatlWrhsStkQtyInMatlBaseUnit": "250.000"
  }
}
getMaterialStockOfA_MatlStkInAcctMod

Retrieves the material (material ID and base unit of measure) that a specific stock record in the account model belongs to.

Parameters:

NameTypeRequiredDescription
MaterialstringYesMaterial in respect of which stock is managed (e.g., "TG11").
PlantstringYesPlant (e.g., "1010").
StorageLocationstringYesStorage location (e.g., "101A").
BatchstringYesBatch number (stock identifier); empty string when the material is not batch managed.
SupplierstringYesSupplier for special stock; empty string for own stock.
CustomerstringYesCustomer for special stock; empty string for own stock.
WBSElementInternalIDstringYesValuated sales order stock WBS element (e.g., "00000000" when not applicable).
SDDocumentstringYesSales order number of valuated sales order stock; empty string when not applicable.
SDDocumentItemstringYesSales order item of valuated sales order stock (e.g., "000000" when not applicable).
InventorySpecialStockTypestringYesSpecial stock type; empty string for own stock.
InventoryStockTypestringYesStock type of goods movement (e.g., "01" for unrestricted-use stock).
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesGetMaterialStockOfA_MatlStkInAcctModQueriesNoOData query parameters: $select, $expand.

Returns: A_MaterialStockWrapper|error

Sample code:

materialstock:A_MaterialStockWrapper material = check materialStockClient->getMaterialStockOfA_MatlStkInAcctMod(
    "TG11",
    "1010",
    "101A",
    "",
    "",
    "",
    "00000000",
    "",
    "000000",
    "",
    "01"
);

Sample response:

{
  "d": {
    "Material": "TG11",
    "MaterialBaseUnit": "PC"
  }
}
listMaterialSerialNumbersOfA_MatlStkInAcctMod

Retrieves the serial numbers of the serialized items held in a specific stock record in the account model.

Parameters:

NameTypeRequiredDescription
MaterialstringYesMaterial in respect of which stock is managed (e.g., "TG11").
PlantstringYesPlant (e.g., "1010").
StorageLocationstringYesStorage location (e.g., "101A").
BatchstringYesBatch number (stock identifier); empty string when the material is not batch managed.
SupplierstringYesSupplier for special stock; empty string for own stock.
CustomerstringYesCustomer for special stock; empty string for own stock.
WBSElementInternalIDstringYesValuated sales order stock WBS element (e.g., "00000000" when not applicable).
SDDocumentstringYesSales order number of valuated sales order stock; empty string when not applicable.
SDDocumentItemstringYesSales order item of valuated sales order stock (e.g., "000000" when not applicable).
InventorySpecialStockTypestringYesSpecial stock type; empty string for own stock.
InventoryStockTypestringYesStock type of goods movement (e.g., "01" for unrestricted-use stock).
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesListMaterialSerialNumbersOfA_MatlStkInAcctModQueriesNoOData query parameters: $filter, $select, $expand, $orderby, $top, $skip, $inlinecount.

Returns: CollectionOfA_MaterialSerialNumberWrapper|error

Sample code:

materialstock:CollectionOfA_MaterialSerialNumberWrapper serials = check materialStockClient->listMaterialSerialNumbersOfA_MatlStkInAcctMod(
    "TG11",
    "1010",
    "101A",
    "",
    "",
    "",
    "00000000",
    "",
    "000000",
    "",
    "01",
    queries = {
        \$select: ["SerialNumber", "Equipment"]
    }
);

Sample response:

{
  "d": {
    "results": [
      {
        "SerialNumber": "100000000001",
        "Equipment": "10000041"
      },
      {
        "SerialNumber": "100000000002",
        "Equipment": "10000042"
      }
    ]
  }
}

Material serial numbers​

listA_MaterialSerialNumbers

Retrieves a collection of material serial numbers with the stock location, stock type and equipment of each serialized item.

Parameters:

NameTypeRequiredDescription
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesListA_MaterialSerialNumbersQueriesNoOData query parameters: $filter, $select, $expand, $orderby, $top, $skip, $inlinecount.

Returns: CollectionOfA_MaterialSerialNumberWrapper|error

Sample code:

materialstock:CollectionOfA_MaterialSerialNumberWrapper result = check materialStockClient->listA_MaterialSerialNumbers(
    queries = {
        \$filter: "Material eq 'TG11' and Plant eq '1010'",
        \$top: 2,
        \$select: ["Material", "SerialNumber", "Plant", "StorageLocation", "Equipment"]
    }
);

Sample response:

{
  "d": {
    "results": [
      {
        "Material": "TG11",
        "SerialNumber": "100000000001",
        "Plant": "1010",
        "StorageLocation": "101A",
        "Equipment": "10000041"
      },
      {
        "Material": "TG11",
        "SerialNumber": "100000000002",
        "Plant": "1010",
        "StorageLocation": "101A",
        "Equipment": "10000042"
      }
    ]
  }
}
getA_MaterialSerialNumber

Retrieves a single material serial number by material and serial number.

Parameters:

NameTypeRequiredDescription
MaterialstringYesMaterial number (e.g., "TG11").
SerialNumberstringYesSerial number (e.g., "100000000001").
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesGetA_MaterialSerialNumberQueriesNoOData query parameters: $select, $expand.

Returns: A_MaterialSerialNumberWrapper|error

Sample code:

materialstock:A_MaterialSerialNumberWrapper serial = check materialStockClient->getA_MaterialSerialNumber(
    "TG11",
    "100000000001"
);

Sample response:

{
  "d": {
    "Material": "TG11",
    "SerialNumber": "100000000001",
    "Plant": "1010",
    "StorageLocation": "101A",
    "InventorySpecialStockType": "",
    "Batch": "",
    "InventoryStockType": "01",
    "Equipment": "10000041",
    "Customer": "",
    "Supplier": "",
    "SDDocument": "",
    "SDDocumentItem": "000000",
    "WBSElementInternalID": "00000000",
    "WBSElementExternalID": ""
  }
}
listMatlStkInAcctModsOfA_MaterialSerialNumber

Retrieves the stock records in the account model that hold a specific serialized item.

Parameters:

NameTypeRequiredDescription
MaterialstringYesMaterial number (e.g., "TG11").
SerialNumberstringYesSerial number (e.g., "100000000001").
headersmap<string|string[]>NoAdditional HTTP request headers.
queriesListMatlStkInAcctModsOfA_MaterialSerialNumberQueriesNoOData query parameters: $filter, $select, $expand, $orderby, $top, $skip, $inlinecount.

Returns: CollectionOfA_MatlStkInAcctModWrapper|error

Sample code:

materialstock:CollectionOfA_MatlStkInAcctModWrapper stock = check materialStockClient->listMatlStkInAcctModsOfA_MaterialSerialNumber(
    "TG11",
    "100000000001"
);

Sample response:

{
  "d": {
    "results": [
      {
        "Material": "TG11",
        "Plant": "1010",
        "StorageLocation": "101A",
        "Batch": "",
        "Supplier": "",
        "Customer": "",
        "WBSElementInternalID": "00000000",
        "SDDocument": "",
        "SDDocumentItem": "000000",
        "InventorySpecialStockType": "",
        "InventoryStockType": "01",
        "WBSElementExternalID": "",
        "MaterialBaseUnit": "PC",
        "MatlWrhsStkQtyInMatlBaseUnit": "250.000"
      }
    ]
  }
}

Batch operations​

performBatchOperation

Sends multiple OData read requests as a single HTTP $batch call, reducing round trips to the SAP server.

Parameters:

NameTypeRequiredDescription
requesthttp:RequestYesAn http:Request object containing the multipart/mixed batch payload with individual OData request parts.
headersmap<string|string[]>NoAdditional HTTP request headers.

Returns: http:Response|error

Sample code:

http:Request batchRequest = new;
string boundary = "batch_ms001";
batchRequest.setHeader("Content-Type", "multipart/mixed; boundary=" + boundary);
batchRequest.setTextPayload(
    "--" + boundary + "\r\n" +
    "Content-Type: application/http\r\n" +
    "Content-Transfer-Encoding: binary\r\n\r\n" +
    "GET A_MaterialStock('TG11') HTTP/1.1\r\n" +
    "Accept: application/json\r\n\r\n" +
    "--" + boundary + "\r\n" +
    "Content-Type: application/http\r\n" +
    "Content-Transfer-Encoding: binary\r\n\r\n" +
    "GET A_MaterialStock('TG11')/to_MatlStkInAcctMod HTTP/1.1\r\n" +
    "Accept: application/json\r\n\r\n" +
    "--" + boundary + "--"
);
http:Response batchResponse = check materialStockClient->performBatchOperation(batchRequest);

Returns the raw http:Response from the $batch endpoint. On success the status code is 202 Accepted and the body is a multipart/mixed payload containing one part per request in the batch, each with its own HTTP status line, headers and JSON body. Read it with batchResponse.getTextPayload() and parse each part as needed.

Last updated on
On this page
Was this page helpful?
Report an issue