Audit APIs

GreyMatter allows performing inventory audits in which manual count of selected inventory can be performed.

Audits can be created either from the Manager Dashboard or via API. But, they can be started only from the Manager Dashboard.

Audit Lifecycle

graph TD A[created] --> |Start Audit from MD| B[processing_start] B --> C[auditlines_created] C --> |Ongoing operations on<br/>selected inventory/slot| D[waiting_on_conflict] C --> E[queued] D --> E E --> F[started] F --> |Some discrepancy found| G[pending_approval] F --> |No discrepancy| H[completed] G --> I[approved] G --> J[rejected] J --> K[sent_for_reaudit] Any --> L[cancelled] B --> |No matching<br/>inventory found| M[aborted] A --> N[deleted] Any --> O[paused] class G node-failure class H node-success class I node-success class J node-failure class K node-success class L node-success class M node-failure class N node-success

Audit Object

Audits can be of two types: location audit or SKU audit:

  • In a location audit, a list of slots or MSUs are specified which have to be audited, and all inventory present in those slots are audited.
  • In an SKU audit, product parameters are given, and all products matching those parameters are audited. All slots which have those products are brought to the audit station for this purpose.
audit_id

A unique auto-generated string that identifies the audit

audit_param_name

required string, not unique

A string that will be displayed against the audit in manager dashboard

audit_param_type

Can be either location or sku.

audit_param_value
locations_list

In case of a location audit

A list of strings denoting locations (either slot ids or MSU ids)

Example

{
    "locations_list": [
        "014",
        "039",
        "001",
        "039.1.E.02",
        "014.1.E.05"
    ]
}
attributes_list

In case of SKU audit

A list of SKU selector objects. Each object has two properties: sku and attributes_sets.

Example

{
    "attributes_list": [{
        "attributes_sets": [{
            "product_color": [
                "Green"
            ]
        }],
        "sku": "3001"
    }]
}

Creating an Audit

POST /api-gateway/integration-service/wms-integration/butler/api/audit
Request Headers:
 
  • Content-Type – the request’s content-type has to be passed in this header
  • Accept – the response content type depends on Accept header
  • Authorization – OAuth token to authenticate
Status Codes:
Request JSON Object:
 
  • action (string) – create
  • audit_creator_name (string) – Optional string to denote who is creating the audit
  • audit_param_name (string) – Name of audit to be displayed on UI
  • audit_param_type (string) – Type of audit. location or sku.
  • audit_param_value – An object of type audit_param_value
  • kq (bool) – Should be true if keying in quantity is allowed during audit
Response JSON Object:
 
  • audit_id (string) – Unique auto-generated id of the created audit. This can be used for further requests related to the audit.
Example: Audit by Location

Request

POST /api-gateway/integration-service/wms-integration/butler/api/audit HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json, text/javascript

{
    "action": "create",
    "audit_creator_name": "Audit Creator Name",
    "audit_param_name": "Audit Name",
    "audit_param_type": "location",
    "audit_param_value": {
        "locations_list": [
            "014",
            "039",
            "001",
            "039.1.E.02",
            "014.1.E.05"
        ]
    },
    "kq": true
}

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "action": "create",
    "audit_id": "UQWHmJdsxL"
}
Example: Audit by SKU

Request

POST /api-gateway/integration-service/wms-integration/butler/api/audit HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json, text/javascript

{
    "action": "create",
    "audit_creator_name": "Audit Creator Name",
    "audit_param_name": "Audit Name",
    "audit_param_type": "sku",
    "audit_param_value": {
        "attributes_list": [{
            "attributes_sets": [{
                "product_color": [
                    "Green"
                ]
            }],
            "sku": "3001"
        }]
    },
    "kq": true
}

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "action": "create",
    "audit_id": "UQWHmJdsxL"
}

Delete an Audit

An audit can only be deleted before it is started.

DELETE /api-gateway/integration-service/wms-integration/butler/api/audit/delete/(audit_id)
Parameters:
  • audit_id – Id of the audit to be deleted.
Request Headers:
 
Status Codes:

Audit Notifications

Audit notifications are generated for most Audit Lifecycle events.

Audit Notifications Structure

All Audit notifications follow the generic notification format (see Event Notifications), and contain the relevant payload in the notification.notification_data attribute.

auditNotificationData
audit_id

A unique auto-generated string that identifies the audit

audit_param_name

required string, not unique

A string that will be displayed against the audit in manager dashboard

audit_param_type

New in version 4.1.

Can be either location or sku.

audit_status

This denotes the status of the whole audit. See Audit Lifecycle for possible audit statuses.

audit_data[]

This is a list of objects of type auditlineNotificationData.

auditlineNotificationData
audit_line_id

A unique auto-generated string that identifies this audit line.

status

This denotes the status of the audit line.

pdfa_values

This is an object containing the key value pairs denoting the product audited in this audit line.

location

This is a string representing the location id being audited in this audit line.

expected_qty

This is the expected quantity of the product above in the location above.

actual_qty

This is the actual quantity of the product kept in the location at the time the audit line finished.

Note that if extra items were found at a location, and only some of it was allowed back into the location, then this quantity will contain the count of inventory finally kept in the slot.

extra_qty

This is the quantity of extra products removed from the slot either due to some exceptions like damaged or unscannable, or due to COG/algo restrictions, etc.. The removed items are kept in IRT bin.

quantity_details

New in version 4.1.

This is an object representing the breakup of found quantity and exceptions.

good_qty

This is the total good quantity (non-exceptional) found in the location.

missing_qty

This is the quantity calculated as missing from the slot.

damaged_qty

This is the number of items removed from the slot because they were reported as damaged.

unscannable_qty

This is the number of items removed from the slot because they were reported as unscannable.

system_removed_qty

This is the number of good (non-exceptional) extra items which were removed from the slot due to system limitations like COG, etc..

Audit Created Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [],
        "pps_id": null,
        "pps_seat_name": null,
        "complete_time": null,
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": null,
        "audit_status": "created",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Auditlines Created Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_queued",
            "expected_qty": 0,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_queued",
            "expected_qty": 0,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": null,
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": null,
        "audit_status": "auditlines_created",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Waiting on Conflict Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_queued",
            "expected_qty": 0,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_queued",
            "expected_qty": 0,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": null,
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": null,
        "audit_status": "waiting_on_conflict",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Queued Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_queued",
            "expected_qty": 0,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_queued",
            "expected_qty": 0,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": null,
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": null,
        "audit_status": "queued",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Started Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_started",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }, {
            "status": "auditline_started",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": null,
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": null,
        "audit_status": "started",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Completed Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_completed",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 1,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_completed",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 1,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": "2017-11-22T12:18:32.553543+05:30",
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": "admin",
        "audit_status": "completed",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Pending Approval Notification

Example with 1 auditline started and 1 pending approval
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_pending_approval",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_started",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 1,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": null,
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": "admin",
        "audit_status": "pending_approval",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}
Example with 1 auditline completed and 1 pending approval
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_pending_approval",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_completed",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 1,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": "2017-11-22T12:18:32.553543+05:30",
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": "admin",
        "audit_status": "pending_approval",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Rejected Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_rejected",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_completed",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 1,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": "2017-11-22T12:18:32.553543+05:30",
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": "admin",
        "audit_status": "rejected",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Approved Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_approved",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_completed",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 1,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": "2017-11-22T12:18:32.553543+05:30",
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": "admin",
        "audit_status": "approved",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Sent for Re-audit Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_sent_for_reaudit",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 0,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_completed",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 1,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": "2017-11-22T12:18:32.553543+05:30",
        "audit_id": "ZFQkUnN6cj",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": "admin",
        "audit_status": "sent_for_reaudit",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Cancelled Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [{
            "status": "auditline_cancelled",
            "expected_qty": 1,
            "location": "003.1.A.03-04",
            "item_id": "3fcb566d-c777-4910-a667-afd7e83b4d43",
            "audit_line_id": "da6af053-9efc-4bee-9bcc-4cefed7c71c6",
            "actual_qty": 1,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "3001",
                "colour": "yellow",
                "smell": "foul"
            }
        }, {
            "status": "auditline_completed",
            "expected_qty": 1,
            "location": "002.1.A.03-04",
            "item_id": "9e0832dc-523a-416f-ad32-aba2e0e580ab",
            "audit_line_id": "e57d5718-7155-447f-b447-017732413ce2",
            "actual_qty": 1,
            "extra_qty": 0,
            "pdfa_values": {
                "product_sku": "2024"
            }
        }],
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": "2017-11-22T12:18:32.553543+05:30",
        "audit_id": "ASEkUnN8dk",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": "admin",
        "audit_status": "cancelled",
        "creation_time": "2017-11-22T12:16:08.025296+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Deleted Notification

Show/Hide
{
    "notification_data": {
        "audit_data": [],
        "pps_id": null,
        "pps_seat_name": null,
        "complete_time": null,
        "audit_id": "StkuKtBAFh",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "creation_time": "2017-04-27T13:34:17.610550+05:30",
        "audit_status": "deleted",
        "user_name": null
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}

Aborted Notification

Show/Hide
{
    "notification_data": {
        "pps_id": 1,
        "pps_seat_name": "front_1",
        "complete_time": "2017-11-23T11:12:32.252420+05:30",
        "audit_id": "FEPYqepAem",
        "audit_param_name": "Audit Name",
        "audit_param_type": "location",
        "user_name": "admin",
        "audit_status": "aborted",
        "creation_time": "2017-11-23T11:12:27.640083+05:30",
        "timestamp": "2017-11-28T10:58:54.855768+05:30"
    },
    "notification_id": "e7828e10",
    "notification_type": "audit_information",
    "version_number": "1.5.0"
}