19.09. mSupply REST API

{
    "username": "Admin",
    "password": "Admin",
    "loginType": "invoice"
} 

Response:

// success (HTTP status 200)
{
    "status": "success",
    "authenticated": true,
    "username": "Admin",
    "userFirstName": "Minnie",
    "userLastName": "Streator",
    "userJobTitle": "Boss",
    "userType": "contact",
    "service": "invoice",
    "storeName": "General Warehouse"
}
// failure (HTTP status 400)
{
    "status": "error",
    "error": "Username/password/login type missing"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "Failed to authenticate/No store found for user"
}

// success (HTTP status 200)
[
    {
        "itemCode": "ABC012",
        "itemName": "Amoxycillin 250mg tab",
        "batchName": "SD34567",
        "expiryDate": "2021-05-05T12:00:00.000Z",
        "unit": "Tab",
        "barcode": "0123456778899",
        "packSize": 100,
        "quantity": 23, // in packs
        "storeName": "General Warehouse"
    },
    ...
]
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

The stock levels will be those of the supplying store for the logged in customer, with separate lines for different batches, expiry dates or pack sizes. By default, the items included will be those in the customer's master list(s), unless overridden by the optional item name/code parameters, in which case the results will be filtered by items with a name/code starting with the specified value(s).

{
    "orderReference": "VS2345",
    "comment": "Test order",
    "lines":[
        {
            "itemCode": "ABC012",
            "itemName": "Amoxycillin 250mg tab",
            "packSize": 100,
            "quantity": 3, // in packs
            "comment": "something about this line"
        },
        {
            "itemCode": "CYZ456",
            "itemName": "Paracetamol 500mg tab",
            "packSize": 100,
            "quantity": 5, // in packs
            "comment": ""
        },
        ...  
    ]
}

Response:

// success (HTTP status 200)
{
    "status": "success",
    "numberOfRecordsUpdated": 1,
    "orderNumber": 23425
}
// failure (HTTP status 404)
{
    "status": "error",
    "error": "Item code not found"
}
// failure (HTTP status 409)
{
    "status": "error",
    "error": "Duplicate line for item"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Order already exists"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Item is not available to order"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Invalid pack size/quantity"
}
// failure (HTTP status 400)
{
    "status": "error",
    "error": "Order reference/order lines/item code/item name/quantity missing"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

The customer order (response requisition) will be created in the logged in customer's supplying store, set to confirmed with the current date, and the new (automatically assigned) customer order number returned

// success (HTTP status 200)
{
    "ID": "UID23425",
    "confirmedDate": "2020-12-27T17:51:00.000Z",
    "orderNumber": 23425,
    "orderReference": "VS2345",
    "comment": "Test order",
    "storeName": "General Warehouse",
    "lines":[
        {
            "itemCode": "ABC012",
            "itemName": "Amoxycillin 250mg tab",
            "packSize": 100,
            "quantity": 2, // in packs
            "comment": "Reduced quantity supplied"
        },
        {
            "itemCode": "CYZ456",
            "itemName": "Paracetamol 500mg tab",
            "packSize": 100,
            "quantity": 5, // in packs
            "comment": ""
        },
        ...  
    ]
}
// failure (HTTP status 404)
{
    "status": "error",
    "error": "Order not found"
}
// failure (HTTP status 409)
{
    "status": "error",
    "error": "More than one order found"
}
// failure (HTTP status 400)
{
    "status": "error",
    "error": "Order number missing"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

Returns the specified customer order in the logged in customer's supplying store

// success (HTTP status 200)
[
    {
        "ID": "UID8567546AS",
        "invoiceNumber": 8567546,
        "confirmedDate": "2020-12-29T12:45:00.000Z",
        "receivedDate": "",
        "cancelledDate": "", // blank unless the invoice has been manually cancelled after it has been confirmed
        "invoiceReference": "REF222",
        "comment": "From order reference VS2345",
        "orderNumber": 23425, // original order number (can have multiple invoices from a single order)
        "storeName": "General Warehouse",
        "invoiceTotal": 135.55, // sum of all lines plus any extras e.g. shipping
        "lines": [
            {
                "itemCode": "ABC012",
                "itemName": "Amoxycillin 250mg tab",
                "batchName": "SD34567",
                "expiryDate": "2021-05-05T12:00:00.000Z",
                "unit": "Tab",
                "barcode": "0123456778899",
                "packPrice": 3.65,
                "packSize": 100,
                "quantity": 2, // in packs
                "comment": "Reduced quantity supplied; Requested pack size 100",
                "lineTotal": 7.3 // pack price x quantity
            },
            ...
        ]
    },
  ...
]
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

Returns all customer invoices for the logged in customer in their supplying store and confirmed, but which haven't yet been received or cancelled. Note that a single customer order can be split into multiple customer invoices

{
    "receivedDate": "2020-12-31T09:23:00.000Z"
}

Response:

// success (HTTP status 200)
{
    "status": "success",
    "numberOfRecordsUpdated": 1
}
// failure (HTTP status 404)
{
    "status": "error",
    "error": "Invoice not found"
}
// failure (HTTP status 409)
{
    "status": "error",
    "error": "More than one invoice found"
}
// failure (HTTP status 503)
{
    "status": "error",
    "error": "Unable to update invoice"
}
// failure (HTTP status 503)
{
    "status": "error",
    "error": "receivedDate is invalid"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Invoice is not yet ready for dispatch"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Invoice has been already been received/cancelled"
}
// failure (HTTP status 400)
{
    "status": "error",
    "error": "Invoice number/received date missing"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

Updates the received date for the specified customer invoice → it will no longer appear in the GET response above

// success (HTTP status 200)
{
    "ID": "UID8567546AS",
    "invoiceNumber": 8567546,
    "confirmedDate": "2020-12-29T12:45:00.000Z",
    "receivedDate": "2020-12-31T09:23:00.000Z",
    "cancelledDate": "", // blank unless the invoice has been manually cancelled after it has been confirmed
    "invoiceReference": "REF222",
    "comment": "From order reference VS2345",
    "orderNumber": 23425, // original order number
    "storeName": "General Warehouse",
    "invoiceTotal": 135.55, // sum of all lines plus any extras e.g. shipping
    "lines": [
        {
            "itemCode": "ABC012",
            "itemName": "Amoxycillin 250mg tab",
            "batchName": "SD34567",
            "expiryDate": "2021-05-05T12:00:00.000Z",
            "unit": "Tab",
            "barcode": "0123456778899",
            "packPrice": 3.65,
            "packSize": 100,
            "quantity": 2, // in packs
            "comment": "Requested pack size 100",
            "lineTotal": 7.3 // pack price x quantity
        },
        ...
    ]
}
// failure (HTTP status 404)
{
    "status": "error",
    "error": "Invoice not found"
}
// failure (HTTP status 409)
{
    "status": "error",
    "error": "More than one invoice found"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

Returns the specified customer invoice for the logged in customer in their supplying store