Version: draft
The Field Supply Web API for the NHLMIS exists to enable integration with external stock reporting and tendering systems like ONE network.
PSM 3PLs need to be able to read LMD orders from Field Supply once they're finalised, so that they can be fulfilled. These orders will be dispatched to the relevant 3PL managing the necessary warehouse and transport legs. 3PLs can update inventory levels in NHLMIS for certain warehouses.
This documentation is intended to aid technical audiences to implement an integration of an external system carrying stock levels with the NHLMIS by sending a stock report to the system to update the stock levels of one or more products in a location.
The /orders endpoint allows for sequential polling and updating of deployment
orders. Implementers can look up information about accepted orders in Field Supply,
and then complete or cancel these orders by sending information about the shipment
or a cancellation request. In case an order is completed, Field Supply will also
create a shipment record matching the deployment order.
| Operation | Description |
|---|---|
| GET /orders | Retrieve a list of accepted orders |
| GET /orders/{suborderId} | Retrieve a single deployment order |
| PATCH /orders/{suborderId} | Update a deployment order |
The /stock-counts API allows implementers to look up the latest recorded
stock levels at locations, and to perform updates on these levels in batch.
It also allows the retrieval of batched inventory stock for the last reporting cycle.
| Operation | Description |
|---|---|
| POST /stock-counts | Submit a batched list of inventory levels |
| GET /stock-counts | Retrieves a list of stock counts including batch information within the last 12 months. |
The /locations API provides read-only access to information about service
locations by PSM Warehouse Code.
| Operation | Description |
|---|---|
| GET /locations | Retrieve a filterable list of locations |
| GET /locations/{identifier} | Retrieve a location document |
The /products endpoint provides read-only access to information about
products.
| Operation | Description |
|---|---|
| GET /products | Retrieve a filterable list of products |
| GET /products/{productId} | Retrieve a single product |
The /batches endpoint provides access to information about existing product batches
as well as the possibility to add new or update batches for an existing product.
| Operation | Description |
|---|---|
| GET /batches | Retrieve a list of product batches. |
| POST /batches | Create new or update product batch |
The /services endpoint provides read-only access to information about
services.
| Operation | Description |
|---|---|
| GET /services | Retrieve a list of available services. |
| GET /services/{serviceId} | Retrieve a service by service id |
x-api-key
header
Authentication is done using an API key tied to your application’s security
scope which is expected to be sent in the request's x-api-key header. This key
is tied to a location, program(s) and optionally funder(s). Here is an example
key you can use to test the API on the development server at https://dev.api.nscip.field.supply/v1:
LXXmQYQZdi2zHVhxjF3XG35URVuJr2ph4PLAU8P1
Note this API Key is tied to the national location, so the returned datasets might be very big.
You can test if your API key is working by doing a simple GET request for a product:
curl -X GET \
https://dev.api.nscip.field.supply/v1/products/product:100000DGA04S04K \
-H 'x-api-key: <api_key_value>'
In case filtering is applied, all three parameters are needed in order to yield a successful response. This response will then contain a single batch document only.
| productId | id of the product to look up |
query | string | |
| manufacturer | id of the manufacturer to look up |
query | string | |
| batchNo | batch number to look up |
query | string | |
| alias | If set to |
query | string , x ∈ { one , none } |
application/json
Return a list of batches
| apiKeyAuth | read |
Send information about a new batch for a product that already exists in the database.
In case the sent information matches a batch that already exists, the existing batch will be updated and returned.
The product batch to create or update
| alias | If set to |
query | string , x ∈ { one (default) , none } | |
| updatedAliasId | If set, the endpoint would update the batch alias with this value |
query | string |
application/json
Return a newly created or an updated batch
Sent payload could not be processed successfully
| apiKeyAuth | read , write |
Get a list of locations, filtered by the given query parameters.
| serviceId | id of the service to filter against |
query | string |
application/json
Return a list of locations
| apiKeyAuth | read |
Look up information about a location.
| identifier | PSM warehouse code of the location to look up |
path | string | |
| useWarehouseCodes | If set to |
query | string , x ∈ { true (default) , false } |
application/json
Return location document
No such location
| apiKeyAuth | read |
On default, this endpoint returns a list of all suborder whose parent orders
are of status accepted. The suborder can have a closedStatus of packed,
in-transit, received or failed in case it has already been completed.
If the status parameter is set to "new", orders instead will be of status "new",
and other statuses will be filtered out.
Each response will contain a sequence identifier that can be used by implementers
to periodically poll for updated orders. In case the returned sequence
number is passed to a later request using the since parameter, the response
will only include orders that have been created or transitioned state since.
A response will contain at most 50 suborders. In case there are more entities
currently available (which is signalled by the value of pending being true),
the returned sequence identifier will immediately yield more suborders when
passed to a subsequent call.
| since | A sequence identifier defining a previously polled state from which to include updates. |
query | string | |
| limit | If given, limits the response to contain at most n items. Defaults to 50. |
query | number | |
| alias | If set to |
query | string , x ∈ { one (default) , none } | |
| status | If set to |
query | string , x ∈ { accepted (default) , new } | |
| programId | If set, orders will be filtered to only those on the given NHLMIS program ID |
query | string , x ∈ { program:hiv-aids , program:family-planning , program:malaria } | |
| funderId | If set, orders will be filtered by funder ID |
query | string , x ∈ { funder:global-fund } | |
| geolocationId | If set, |
query | string , x ∈ { zone:north-central:state:benue , zone:north-central:state:fct , zone:north-central:state:kogi , zone:north-central:state:kwara , zone:north-central:state:nasarawa , zone:north-central:state:niger , zone:north-central:state:plateau , zone:north-east:state:adamawa , zone:north-east:state:bauchi , zone:north-east:state:borno , zone:north-east:state:gombe , zone:north-east:state:taraba , zone:north-east:state:yobe , zone:north-west:state:jigawa , zone:north-west:state:kaduna , zone:north-west:state:kano , zone:north-west:state:katsina , zone:north-west:state:kebbi , zone:north-west:state:sokoto , zone:north-west:state:zamfara , zone:south-east:state:abia , zone:south-east:state:anambra , zone:south-east:state:ebonyi , zone:south-east:state:enugu , zone:south-east:state:imo , zone:south-south:state:akwa-ibom , zone:south-south:state:bayelsa , zone:south-south:state:cross-river , zone:south-south:state:delta , zone:south-south:state:edo , zone:south-south:state:rivers , zone:south-west:state:ekiti , zone:south-west:state:lagos , zone:south-west:state:ogun , zone:south-west:state:ondo , zone:south-west:state:osun , zone:south-west:state:oyo } | |
| closedStatus | When not set, defaults to filtering out orders with any |
query | string , x ∈ { in-transit , packed , received , failed } | |
| useGenericParent | If set to true, will return the products at the generic parent level, and the quantities will be converted to the generic parent level. |
query | boolean |
application/json
Returns a list of orders
| apiKeyAuth | read |
Get the document for the deployment order specified by the given suborderId
| suborderId | path | string | ||
| alias | path | string one | ||
| useGenericParent | If set to true, will return the products at the generic parent level, and the quantities will be converted to the generic parent level. |
path | boolean |
application/json
Returns a deployment order
Requested deployment order was not found
| apiKeyAuth | read |
Complete or cancel a deployment order by suborderId, adding the given information and updating product counts. When an order is completed, Field Supply will also create a matching shipment record from the order's origin to the order's destination, containing the deployed products.
application/json
| suborderId | path | string | ||
| alias | path | string one | ||
| useGenericParent | If set to true, will return the products at the generic parent level, and the quantities will be converted to the generic parent level. |
path | boolean |
application/json
Successfully updated order and return the updated model
In case the update successfully closed the suborder, this field will contain the matching Field Supply shipment id.
Could not update shipment as given payload was invalid
| apiKeyAuth | read , write |
This endpoint is used to find a set of products that matches a service or all products that Field Supply is currently tracking.
| serviceId | id of the service to filter against |
query | string | |
| expanded | if set to true, will return additional data for each product: |
query | boolean |
application/json
Return a list of products
| apiKeyAuth | read |
This endpoint enables implementers to look up information about a single product in the Field Supply database.
| productId | id of the requested product |
path | string |
application/json
Return a single products
| apiKeyAuth | read |
Implementers can use this endpoint to retrieve information about which services are available in Field Supply.
application/json
Return a list of services
| apiKeyAuth | read |
Implementers can use this endpoint to retrieve information about a specific service and the products that are associated with it.
application/json
Return a services
Service not found
| apiKeyAuth | read |
Retrieves a list of inventory updates.
This API endpoint returns the latest inventory stock on a given location and service within the last 12 months.
| location | This is the warehouse ID. You can get this by querying the "/locations" endpoint and copying the warehouse ID. |
query | string | |
| service | This is the service we are retrieving inventory stock quantity |
query | string |
Returns a batched inventory stock quantity in the specified warehouse
Location or Service not found
| apiKeyAuth | read |
Submit a list of inventory updates. In case these updates contain product
batches that do not exist in the database yet, the implementer needs to
create these batches using the /batches endpoint beforehand.
The update will be tied to the given funderId and programId.
application/json text/csv
A list of stock counts to be created or updated
| alias | If set to |
query | string , x ∈ { one (default) , none } | |
| useWarehouseCodes | If set to |
query | string , x ∈ { true (default) , false } |
application/json
Stock count data successfully submitted
Submitted data was invalid
| apiKeyAuth | read , write |
{
"expiry": "2025-01-01T00:00:00.000Z",
"id": "product:100019AAA08A02B:manufacturer:micro-labs:batchNo:037G5022",
"manufacturer": "Micro Labs",
"productId": "product:100019AAA08A02B"
}
{
"batchNo": "1222333/45",
"expiry": "2021-05-22T12:32:28.123Z",
"manufacturer": "Aurobindo",
"productId": "product:100002AAA07G04K"
}
Add updatedAliasId as queryparams while updating alias using the API. Example, /batches?updatedAliasId=GGG-MAL4444. Without updatedAliasId, alias update will not work.
{
"errors": [
{
"dataPath": ".receiptData.closedStatus",
"keyword": "enum",
"message": "should be equal to one of the allowed values",
"params": {
"allowedValues": [
"received",
"failed",
"in-transit"
]
},
"schemaPath": "#/properties/receiptData/properties/closedStatus/enum"
}
],
"message": "Validating the payload against the defined schema failed."
}
A message explaining the error that prevented the request from being successfully processed.
An optional array of objects giving further information about the error. This will likely contain information about payloads that failed schema validation.
{
"id": "zone:north-central:state:plateau:lga:wase:sdp:cottage-hospital-wase",
"level": "sdp",
"location": {
"country": "ng",
"id": "country:ng:zone:north-central:state:plateau:lga:wase",
"lga": "wase",
"sdp": "cottage-hospital-wase",
"state": "plateau",
"zone": "north-central"
},
"name": "Wase - Cottage Hospital Wase",
"services": [
"program:family-planning:service:family-planning",
"program:tb:service:dstb",
"program:tb:service:laboratory-microscopy"
],
"tracksBatches": false,
"warehouseCode": "PSM/PLT/17/002"
}
{
"additionalData": {
"remark": "all went well",
"updatedAt": "2018-12-20T14:01:03.462Z"
},
"closedStatus": "received",
"createdAt": "2018-11-01T00:00:00.000Z",
"destinationId": "zone:south-south:state:akwa-ibom:lga:abak:sdp:general-hospital-ukpom-abak",
"destinationWarehouseCode": "PSM/AKB/01/004",
"funderId": "funder:usaid",
"orderId": "-OfCX3EhVwhn",
"productQuantities": {
"product:100000DGA04S04K": 3883,
"product:100000DGA04S09G": 4054
},
"programId": "program:hiv-aids",
"route": "sampleRouteName",
"routeId": "route:0192ed1b-6d86-4f79-8989-d253e4c3a551",
"status": "accepted",
"suborderId": "VlmNxW0Yee",
"supplierId": "zone:north-central:name:abuja-mds",
"supplierWarehouseCode": "DC-301 :: MDS Abuja",
"updatedAt": "2019-03-01T00:00:00.000Z",
"version": "1.0.0"
}
The destination of the suborder, represented as a Field Supply location id.
The destination of the suborder, represented as a PSM Warehouse Code.
The supplier of the suborder, represented as a Field Supply location id.
The supplier of the suborder, represented as a PSM Warehouse Code.
The API version that created this response.
The Field Supply program id of the program associated with the suborder.
This is the status of the parent order, which might be split into cold-chain
and non-cold-chain suborders with different suborderIds.
This is the delivery status of this suborder. In case the suborder has not yet been shipped, the value will be the empty string.
This is the id of the parent order.
This is the id of the suborder which contains all products that are delivered from the given supplier to the given target.
The time when this suborder has been created, i.e. when its parent order got accepted.
The time when this suborder has last changed.
An object containg a key/value mapping of product ids and quantities.
The Field Supply funder id of the funder associated with the suborder.
This contains arbitrary data attached when closing an order via API
This contains the name of the route the suborder is assigned to
This contains the routeId the suborder is assigned to
{
"productQuantities": {
"product:100002AAA07G04K": {
"batches": {
"product:100002AAA07G04K:manufacturer:cipla:batchNo:1234567": {
"amount": 5000
},
"product:100002AAA07G04K:manufacturer:cipla:batchNo:AB34568": {
"amount": 400
}
}
},
"product:100004AAK0A210B": {
"batches": {
"product:100004AAK0A210B:manufacturer:medopharm:batchNo:35C12": {
"amount": 7000
}
}
},
"product:100010KARMYXX006": {
"batches": {
"product:100010KARMYXX006:manufacturer:karex:batchNo:7UJJZ": {
"amount": 1000
},
"product:100010KARMYXX006:manufacturer:karex:batchNo:KU1JA": {
"amount": 6500
}
}
}
},
"receiptData": {
"closedStatus": "received",
"remark": "all went well",
"updatedAt": "2018-12-20T14:01:03.462Z"
},
"shipmentNumber": "ONE#S-1080"
}
The delivered product quantities by product id. For a failed shipment
this key can be omitted.
The current status of the suborder which has either been moved into transit, fulfilled or failed.
Optional remarks about the shipment.
A timestamp defining the point in time when the suborder has transitioned state.
The ONE shipment number. Field Supply will associate this value with the document that represents the shipment internally.
{
"basicUnit": "25x3 tabs",
"fullName": "Artesunate/Amodiaquine 25/67.5 mg Tablet, 25 Blisters of 3 Tablets [Sanofi]",
"id": "product:06930381AA2293Z",
"name": "Artesunate/Amodiaquine 25/67.5 mg Tablet",
"storageType": "non-cold-chain",
"tracer": false,
"tracksBatches": true
}
{
"id": "program:hiv-aids:service:pmtct",
"name": "PMTCT",
"products": [
{
"basicUnit": "240ml",
"fullName": "Abacavir 20 mg/mL Solution, 240 mL [Aurobindo]",
"id": "product:100000DGA04S04K",
"name": "Abacavir 20 mg/mL Solution",
"storageType": "cold-chain",
"tracer": false,
"tracksBatches": true
}
],
"program": {
"id": "program:hiv-aids",
"name": "HIV/AIDS"
}
}
{
"productQuantities": {
"product:ghsc-mal0009": {
"batches": {
"product:ghsc-mal0009:manufacturer:chemonics:batchNo:4000028716": {
"amount": 300
}
}
}
},
"receiptData": {
"closedStatus": "packed"
},
"shipmentNumber": 4010,
"suborderId": "EsbLC_E2iTon"
}
An object contianing key/value pairs of products and their batch quantities/amount.
An object containing details about the shipment status to be created via the closedStatus property
The id of the suborderId whose shipment we want to advance to the next status
The number of the external shipment to be created, must be unique across existing suborder created shipments
{
"changes": [
],
"comments": [
],
"counts": {
"product:ghsc-aid0146:manufacturer:chemonics:batchNo:219100830LPZA": {
"checked": false,
"paymentType": "pay_as_you_sell",
"quantity": 7,
"skuMarket": "originSKU"
},
"product:ghsc-mal0031:manufacturer:chemonics:batchNo:I-STK": {
"checked": false,
"paymentType": "pay_as_you_sell",
"quantity": 38,
"skuMarket": "originSKU"
}
},
"createdAt": "2024-08-29T06:10:37.153Z",
"createdBy": {
"agent": "",
"user": "psm-api-user"
},
"date": "2024-08-29",
"destination": {
"id": "zone:north-central:state:fct:lga:abaji:sdp:ni-ima-clinic",
"lga": "abaji",
"sdp": "ni-ima-clinic",
"state": "fct",
"zone": "north-central"
},
"externalShipmentId": "ONE-9899",
"funder": "funder:global-fund",
"funderId": "funder:global-fund",
"history": {
"origin:zone-north-central-name-abuja-global-fund:destination:zone-north-central-state-fct-lga-abaji-sdp-ni-ima-clinic:date:2024-08-29:shipmentNo:1322:status:packed:agent:": {
"counts": {
"product:ghsc-aid0146:manufacturer:chemonics:batchNo:219100830LPZA": {
"quantity": 7
},
"product:ghsc-mal0031:manufacturer:chemonics:batchNo:I-STK": {
"quantity": 38
}
},
"createdAt": "2024-08-29T06:10:37.153Z",
"createdBy": {
"agent": "",
"user": "psm-api-user"
}
}
},
"id": "origin:zone-north-central-name-abuja-global-fund:destination:zone-north-central-state-fct-lga-abaji-sdp-ni-ima-clinic:date:2024-08-29:shipmentNo:1322",
"orderId": "type:orderSnapshot:groupId:1SO0OKVYI:orderId:mo3Gcmx_BFm:suborderId:0H2lOD6Ezbl",
"origin": {
"id": "zone:north-central:name:abuja-global-fund",
"name": "abuja-global-fund",
"zone": "north-central"
},
"planningType": "routine",
"shipmentNo": "1322",
"shipmentType": {
"abbreviation": "FUNDER",
"id": "allocated:funder:global-fund",
"name": "funder:global-fund"
},
"snapshotDates": {
"packed": "2024-08-29T06:10:37.153Z"
},
"snapshotId": "origin:zone-north-central-name-abuja-global-fund:destination:zone-north-central-state-fct-lga-abaji-sdp-ni-ima-clinic:date:2024-08-29:shipmentNo:1322:status:packed:agent:",
"status": "packed",
"statusType": "arrival",
"updatedAt": "2024-08-29T06:10:37.153Z",
"updatedBy": {
"agent": "",
"user": "psm-api-user"
}
}
The shipments internal tagged number
Contains information about the origin of the shipment i.e the source
Contains information about the destination of the shipment i.e the receiver
The current status of the shipment
The semantic definition of the shipment current status
The id of the order shipment was created from
The shipment ID defined by the integrating party on shipment creation
The id of the funder for given shipment
The type of plan shipment falls under. Typically will be defined as routine
Date shipment was created at
User who created the shipment
Last updated at timestamp of the shipment
Last user who updated the shipment
Name of the funder
Object containing information of products and quantities packed in the shipment
The date shipment is scheduled to be delivered
Id of the most recent shipment snapshot indicating the current status of the shipment
The unique id of the shipment
Contains historical information of the shipment snapshots created through its life cycle
Contains information of all changes made on the shipment
Array of comment entries made during the shipment lifecyle
details of the shipment type
An object containing each shipment status as keys and the corresponding date they were created
{
"error": "Shipment not found"
}
Shipment not found for given shipmentNumber parameter
{
"error": "packed snapshot already exists for suborder EsbLC_E2iTon"
}
A message describing the validation error that prevented the request from being processed
{
"error": "No uncompleted suborder with id \"EsbLC_E2iTonss\" was found. Cannot continue."
}
Not found error message returned if suborder for given shipment doesn't exist
{
"id": "origin:zone-north-central-name-abuja-global-fund:destination:zone-north-central-state-niger-lga-agaie-sdp-basic-health-centre-etsugaie:date:2024-07-17:shipmentNo:6474:status:packed:agent:"
}
Id of the newly created shipment with its status information embedded in id
{
"stockCounts": [
{
"date": "2018-05-28",
"funderId": "funder:usaid",
"id": "zone:north-central:state:akwa-ibom:2018-W05:lga:itu:sdp:model-health-centre-ntak-inyang:funder:usaid",
"serviceId": "program:hiv-aids:service:warehouse",
"stock": {
"product:100002AAA07G04K": {
"batches": {
"product:100002AAA07G04K:manufacturer:cipla:batchNo:1234567": {
"amount": 12000
},
"product:100002AAA07G04K:manufacturer:mylan:batchNo:AB34568": {
"amount": 4000
}
}
},
"product:100010KARMYXX006": {
"batches": {
"product:100010KARMYXX006:manufacturer:karex:batchNo:7UJJZ": {
"amount": 1000
},
"product:100010KARMYXX006:manufacturer:suretex:batchNo:KU1JA": {
"amount": 8500
}
}
}
},
"version": "2.0.0",
"warehouseCode": "PSM/AKB/16/013"
}
]
}
{
"_id": "zone:south-west:name:lagos-global-fund:bimonth:2021-M05:program:malaria:service:warehouse",
"_rev": "2-fb7e7169261ae90a5af831c16c63fca5",
"createdAt": "2021-06-10T12:10:55.619Z",
"createdBy": "psm-api-user",
"date": {
"month": 5,
"period": {
"effectiveEnd": "2021-06-30T00:00:00.000Z",
"effectiveStart": "2021-05-01T00:00:00.000Z"
},
"reportingPeriod": "2021-M05",
"year": 2021
},
"idVersion": 1,
"location": {
"id": "zone:south-west:name:lagos-global-fund",
"level": "zone",
"name": "lagos-global-fund",
"zone": "south-west"
},
"partialCount": false,
"serviceId": "program:malaria:service:warehouse",
"stock": {
"product:ghsc-mal0004": {
"amount": 8000,
"available": 8000,
"availableTotal": 8000,
"batches": {
"product:ghsc-mal0004:manufacturer:chemonics:batchNo:PA05090": {
"fields": {
"field:standard-physical-count": {
"amount": 5000
}
}
},
"product:ghsc-mal0004:manufacturer:chemonics:batchNo:PA05091": {
"fields": {
"field:standard-physical-count": {
"amount": 3000
}
}
}
}
}
},
"submittedAt": "2021-06-17T08:56:14.321Z",
"type": "stockCount",
"updatedAt": "2021-06-17T08:56:14.814Z",
"updatedBy": "psm-api-user",
"version": "2.0.0"
}
The id of the warehouse, the stock is retrieved from
"zone:south-west:name:lagos-global-fund"
The id of the service, the stock is retrieved for.
"program:malaria:service:warehouse"
{
"message": "Could not find stock count for zone:south-west:name:lagos-global-fund, program:family-planning:service:family-planning between now and period 2021-M05."
}
A message explaining the error that prevented the request from being successfully processed.
{
"stockCounts": [
{
"funderId": "funder:usaid",
"programId": "program:hiv-aids",
"stock": {
"product:100002AAA07G04K": {
"batches": {
"product:100002AAA07G04K:manufacturer:cipla:batchNo:1234567": {
"amount": 5000
},
"product:100002AAA07G04K:manufacturer:mylan:batchNo:AB34568": {
"amount": 3777
}
}
},
"product:100010KARMYXX006": {
"batches": {
"product:100010KARMYXX006:manufacturer:karex:batchNo:7UJJZ": {
"amount": 1000
},
"product:100010KARMYXX006:manufacturer:suretex:batchNo:KU1JA": {
"amount": 6500
}
}
}
},
"warehouseCode": "NDC-202 :: Lagos Premier Medical Warehouse"
}
]
}
The id of the funder the sent stock should be associated with.
The id of the program the sent stock is being used for.
"program:hiv-aids"
The batched stock levels. In case alias is used (which is the default
behavior, this expects ONE ItemIds to be used in the product ids as
well as batch ids.
The PSM warehouse code of the target destination. Either this or locationId
needs to be sepcified.
"NDC-202 :: Lagos Premier Medical Warehouse"
The location id of the target destination. Either this or warehouseCode
needs to be sepcified.
"zone:lagos:name:lagos"
route, i.e the name of the delivery route suborder falls under.POST /shipments api endpoint now supported to allow integrators to create shipments for their suborder.PATCH /shipments/{shipmentNumber} api endpoint now supported to allow integrators to incrementally update the status
and product quantites of their created shipments for suborders.GET /shipments/{shipmentNumber} endpoints allows integrators to get shipment information using their own specific shipment ids used in the creation of the shipment.Note: The /shipment endpoints are currently disabled on production. This is a feature that is currently undergoing testing and will be released sometime in the future.
Order payloads will now omit the requestedDeliveryDate value as ONE Network does not use the value in any way.
In order to support FEFO deployment orders, the NHLMIS API has been updated with the following:
When a Field Supply suborder is being finalized using a PATCH /orders/{suborderId} request, the endpoint now expects batch level product information. This means that instead of echoing the ARTMIS ItemId level information contained in an accepted order without a closedStatus like
{
// ...additional keys
"productQuantities": {
"product:100004AAK0A210B": 5000
}
}the counts of the stock delivered will need to include batch level information like this:
{
// ...additional keys
"productQuantities": {
"product:100004AAK0A210B": {
"batches": {
"product:100004AAK0A210B:manufacturer:cipla:batchNo:4512": {
"amount": 3550
},
"product:100004AAK0A210B:manufacturer:cipla:batchNo:1983": {
"amount": 1450
}
}
}
}
} This aligns with the way inventory levels are being submitted using POST /stock-counts, and is a breaking change.
We added an additional value for closedStatus of a suborder, which is in-transit, signifying that a DO has been shipped out of the warehouse. This means that in order to mark a suborder as "in transit" you can send the following payload to PATCH /orders/{suborderId}:
{
"receiptData": {
"closedStatus": "in-transit",
"updatedAt": "2018-12-20T14:01:03.462Z"
}
} which extends the list of possible values to in-transit, received, failed.
An OrderUpdate with an in-transit status can include batch level inventory in order to let the NHLMIS know exactly what was shipped.
When sending product meta information alongside an inventory update or an order
update, the itemName and basicUnit parameters at product level are now optional.
This means if they will not be sent, the ARTMIS ItemId will be enough to match
the product against our catalog.
{
// ...additional keys
"productQuantities": {
"product:100004AAK0A210B": {
"itemName": "Amoxicillin 250 mg Dispersible Tablet", // this is now optional as it contains redundant information
"basicUnit": "100 tabs", // this is now optional as it contains redundant information
"batches": {
"product:100004AAK0A210B:manufacturer:cipla:batchNo:4512": {
"amount": 3550
}
}
}
}
}