Exact for Manufacturing REST API 101: Making shop order receipts

Exact for Manufacturing comes with a great set of REST APIs to build connections with your MES apps, machines or supply chain. At a first glance, the number of available APIs seems overwhelming and chances are that we waste time picking the right ones. In this REST API 101 we look at making receipts from shop orders.

The big picture In Exact Online we have entities related to Master data, which is loosely defined as everything that we set up once and leave unchanged until it requires maintenance. Master data serves as a template for our day-to-day operations. Example of master data are Items (properties of products and materials), and the Bill of materials (the standard recipe of how to produce a product out of materials and operations). In our day-to-day operations we create so-called Shop orders which describe which products we are going to make, in which quantity and when. The Shop order also contains all materials to be used and all the required operations. As we don’t want to reinvent the wheel, our starting point will often be the Bill of materials. However, in an environment that requires customization, we may have tweaked the Shop order in a manner that reflects the customization, and we should therefore not rely on the underlying Bill of materials to understand the current requirements for materials and operations! The Shop order serves as our production planning record. Lastly, once we start producing we will track our actual product receipts, material issue and time used on operations to get an adequate picture of progress and cost made. These are the production transactions. We could broadly divide our APIs into those that create and maintain master data, those that support production planning and the ones that are used to create transactions.   APIs that create or reverse transactions frequently do more than making an inventory transaction. The underlying business components create financial transactions reflecting the value received or consumed, affect the status of the shop order and measure progress in quantities and time.   (Click to enlarge)   Shop order receipts In the list of APIs (https://start.exactonline.nl/docs/HlpRestAPIResources.aspx?SourceAction=10) we find a particular one that is called ShopOrderReceipts. To some developers this sounds like BINGO! Unfortunately, there are eight, yes 8, APIs supporting various shop order receipt purposes. Let’s walk you through.   (Click to enlarge)   ShopOrderReceipts and ShopOrderReversals These APIs have been developed to support the disposition Receive to stock (That’s what we call it on the screens of Exact Online). If we receive a product to stock, the process pretty much ends there. We would do this for shop orders that are meant to produce to stock, such as the ones generated from processes like Demand planning and MRP. The ShopOrderReceipts API puts a quantity of product into stock. The API specifies no unit of measure, it is implied that we use the stock unit of measure of the product (item). Dependent on the subscription (Standard, Advanced or Premium), products may use a serial or batch number and/or a storage location. Only in an Advanced or Premium subscription we can use serial or batch numbers, and then only if the item has been classified as a serial or batch item. Only in a Premium subscription we can use storage locations, and then only if the item is stored in a warehouse that set to use storage locations. Putting serial or batch numbers into stock requires you, as a developer, to test Item.IsBatchItem=1 or Item.IsSerialItem=1 as you will have to reserve a serial or batch number with the StockBatchNumbers or StockSerialNumbers API with the StockTransactionType of '140' prior to making a POST with ShopOrderReceipts. Lastly, if we want to make a (downward) correction to a shop order receipt we have to use the API ShopOrderReversals.   If a shop order is created off a sales order (the make to order environment), then we are not supposed to put the received product in stock, but we should rather do an effort to deliver to the customer. Technically, we do have the disposition Receive to stock available, and we can therefore also use the ShopOrderReceipts API. However, we would miss out on a number of niceties that are under the hood of the APIs discussed next.   StageForDeliveryReceipts and StageForDeliveryReversals If we have a shop order that is linked to a sales order (see ShopOrders.SalesOrderLineCount) and we are working within the screens of Exact Online we could choose for the disposition Deliver, which would amongst many other things produce a delivery note and send it to the customer. As this mechanism is not supported in the manufacturing APIs today, we do not support this disposition. The alternative, also available on the screens, is the disposition Stage for delivery. With Stage for delivery we notify the regular Exact for Manufacturing user that the product has been finished and is ready to ship. This user can then continue with delivering on the sales order. The Stage for deliver disposition (using the StageForDeliveryReceipts API)is strongly recommended for all shop orders linked to sales orders! The nice thing of Deliver and Stage for delivery is that we update our financials with the actual costs made in this shop order. If we would Receive to stock, we would use the cost price (or average cost price) of the product item and our job costing will become inaccurate. However, there is a scenario where we will have to make a Receive in stock, and that is when the total quantity received exceeds the planned quantity of the shop order. We cannot overdeliver to the customer and any excess received should be put into stock using the ShopOrderReceipts API. Lastly, if we want to make a (downward) correction to a shop order stage for delivery receipt we have to use the API StageForDeliveryReversals.   SubOrderReceipts and SubOrderReversals When we have a layered bill of materials (multi-level bill of materials), we will have to deal with suborders (to the parent shop orders). The idea is that we do not receive components into stock, but pass them on to the parent order (where it appears as a material issued). We recognize this scenario by testing ShopOrders.ShopOrderParent. Only when we have reported an excess quantity (i.e. more than planned) of components we may put them into stock using the ShopOrderReceipts API.   ByProductReceipts and ByProductReversals A special category of shop order receipts are the By-product receipts. The by-products are optional to any shop order and may represent rest materials to receive (metal scrap), co-products (like the  processing of fresh milk would produce cream and skim), outputs of a recycling process (like the processing of used tires would yield rubber, metal and nylon scrap) or rejects (like the manufacture of widgets would also produce rejected widgets). It is important to understand that only planned by-products can be received, i.e. if a by-product is not named in the shop order (even when the planned quantity is zero), it cannot be received.   (Click to enlarge)   By-products are received with the ByProductReceipts API and corrected with the ByProductReversals API. All by-products are of the Receive to stock type, i.e. may require a serial or batch number and may require a storage location, just like with ShopOrderReceipts. By-product receipts are always valued with the item cost price (or the average item cost price) as defined in the Item record at the time of receipt. It is not possible to receive a by-product for a Stage for delivery or an Issue to Parent.   In a next installment we will discuss material issues and time transactions.