Approval Service

Download OpenAPI specification:Download

Emporix: documentation@emporix.com URL: https://emporix.com

The Emporix API Approval Service allows you to manage approval requests related to orders. The orders are referred to as resources.

Key Features:

  • Creating new approvals for orders
  • Managing existing approvals

Key Benefits:

  • Optimised and digitalised ordering process for the entire organisation
  • Clear scopes that result in a better process transparency
  • Better collaboration among people within an organization
  • Cost control with the simplified process

Approvals

Creating a single approval

Creates a single approval document with information about the approver and order details.

In case of any validation problems, the below errorCodes can be returned:

  • APPROVAL-400003: Incorrect value of the approval status
  • APPROVAL-400004: Not matching combination of approval action and resource type
  • APPROVAL-400005: Approval has been already given
  • APPROVAL-400006: Provided approver cannot be assigned to the approval
  • APPROVAL-400008: Requested user has no permissions to the resource
  • APPROVAL-400011: Requested user is not assigned to any company
  • APPROVAL-404002: Provided resource does not exist
  • APPROVAL-404003: Requested user is not assigned to any legal entity
  • APPROVAL-409001: Approval already exists

Required scopes

  • approval.approval_manage_own
SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.

Request Body schema: application/json
resourceType
required
string (A type of a resource)

Base schema for an approval resource type

Value: "CART"
action
required
string (An approval action)

Base schema for an approval action type

Value: "CHECKOUT"
required
object

User which can approve the approval request

comment
string

A comment from the requestor to the approver

object (additional information)

additional information required for approval process

id
string

An identifier of the approval document

resourceId
string

An identifier of the approval resource

Responses
201

The resource has been successfully created.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

409

Resource with given code already exists.

post/{tenant}/approvals
Request samples
application/json
{
  • "id": "64e241ced632aa413a27a318",
  • "resourceType": "CART",
  • "resourceId": "cartId",
  • "action": "CHECKOUT",
  • "approver": {
    },
  • "comment": "Comment to the approval user",
  • "details": {
    }
}
Response samples
application/json
{
  • "id": "88b1779c-a8bf-4b94-b1be-b0edd149bba5"
}

Retrieving a list of approvals

Retrieves a list of approval documents which is assigned to the user. The user needs to be a requestor or the approval giver. Retrieves a list of approval documents which is assigned to the user. The user needs to be a requestor or an approval giver.

Required scopes

  • approval.approval_read_own
SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.

query Parameters
pageSize
integer [ 1 .. 60 ]
Default: 60

The number of documents being retrieved on one page.

pageNumber
integer >= 1
Default: 1

The page number to be retrieved, where the size of the pages is specified by the pageSize parameter. The number of the first page is 1.

sort
string

Fields to sort the response data by following the order of the parameters from left to right. Can contain multiple fields in the following format: field name:sort direction, separated by a comma. The colon preceding the sort direction parameter is optional, and the descending order is taken only if it is equal to desc or DESC. The ascending order is assumed in any other case.

Example: sort=sort=name,metadata.createdAt:desc
q
string

A standard query parameter is used to search for specific values.

  • Searching for an item by a string property: q=status:PENDING, where status is the name of the string field and PENDING is its required value.
  • Searching for items by a number-based property:
    • Searching for items with specific values: q=mixins.approvalCustomAttributes.orderQuantity:20
    • Searching for items with values greater than: q=mixins.approvalCustomAttributes.orderQuantity:>20
    • Searching for items with values lower than: q=mixins.approvalCustomAttributes.orderQuantity:<20
    • Searching for items with values greater than or equal to: q=mixins.approvalCustomAttributes.orderQuantity:>=20
    • Searching for items with values lower than or equal to: q=mixins.approvalCustomAttributes.orderQuantity:<=20
    • Searching for items within a range of values: q=mixins.approvalCustomAttributes.orderQuantity:(>=10 AND <=20), where mixins.approvalCustomAttributes.orderQuantity is the name of a number-based field, and 20 is its querying value.
  • Searching for items by a date property. All numer-based property queries are also valid for dates. In that case, the date should be placed within double quotes: q=metadataCreatedAt:(>="2021-05-18T07:27:27.455Z" AND <"2021-05-20T07:27:27.455Z")
  • Searching for items by a boolean value: q=received:true, where received is the name of a boolean field, and 'true' is its required value.
  • Searching for items with a non-existing or empty property: q=reason.description:null, where reason.description is the name of the field that has the null value.
  • Searching for items with an existing property: q=mixin:exists, where mixin is the name of the field that has the non null value.
  • Searching for items by multiple specific values: q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494), where id is the name of the field, and strings within a bracket are its required values.
  • Searching for items by multiple fields: q=id:5c3325baa9812100098ff48f code:A705121667, where id and 'code' are the names of fields. All documents that contain the specified values in these fields are approved. Multiple fields separated by spaces can be specified. Multiple values for each field can also be provided in the format presented above.
  • Searching for items with string fields conforming to a regex: q=orders._id:~EON107 or q=code:(~EON107 EON106) - in the case of searching for strings with a space, where order._id is the name of the field and EON107 or EON107 EON106 are its querying regular expressions.
Example: q=q=status:APPROVED
header Parameters
X-Total-Count
boolean

To get information how many entities meet the filtering requirements, the X-Total-Count header has been introduced. The header is optional and its default value is false. If the header is provided and it is set to true, then the total count is approved in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). This means that the information about the total count is approved only on demand, provided that the X-Total-Count header is present in a request.

Responses
200

Example response

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

get/{tenant}/approvals
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieving a single approval
Retrieves a single approval document which is assigned to the user. The user needs to be a requestor or an approval giver.


In case of any validation problems, the below errorCodes can be returned:


    

  • APPROVAL-404001: Approval does not exist
    • 





Required scopes


    

  • approval.approval_read_own
    • 



SecurityCustomerAccessToken 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.
Note: The tenant name should always be written in lowercase.


 
approvalId
required
string
Unique identifier of an approval.


 
Responses 
200
401
Unauthorized


403
Access forbidden. The caller is not allowed to access this resource.


404
Resource cannot be found


get/{tenant}/approvals/{approvalId}
Request samples 
Response samples 
application/json
{
  • "id": "64e241ced632aa413a27a318",
  • "status": "PENDING",
  • "resourceType": "CART",
  • "resource": {
    },
  • "action": "CHECKOUT",
  • "requestor": {
    },
  • "approver": {
    },
  • "comment": "Comment to the approval user",
  • "approverComment": "Important comment to the requestor user",
  • "expiryDate": "2023-04-31T13:18:02.379Z",
  • "details": {
    },
  • "metadata": {
    }
}
Updating a single approval
Partially updates a single approval document with given information. To update the approval, the user needs to be a requestor or an approval giver. 
Single update may contain multiple partial updates in the form of an array. It contains the allowed operations list:


    

  • add (adding an item to the items list)
    • 

  • remove (removing an item from the items list)
    • 

  • replace (replacing an item with given id with new definition)
Approval can be updated only when status is PENDING.
    • 



In case of any validation problems, the below errorCodes can be returned:


    

  • APPROVAL-400002: Approval status cannot be changed to the new value
    • 

  • APPROVAL-400003: Incorrect value of the approval status
    • 

  • APPROVAL-400004: Not matching combination of approval action and resource type 
    • 

  • APPROVAL-400005: Approval has been already permitted
    • 

  • APPROVAL-400007: Not supported patch operation
    • 

  • APPROVAL-400009: Approval process has been finished and cannot be updated
    • 

  • APPROVAL-400010: Incorrect patch operation
    • 

  • APPROVAL-404001: Approval does not exist
    • 





Required scopes


    

  • approval.approval_manage_own
    • 



SecurityCustomerAccessToken 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.
Note: The tenant name should always be written in lowercase.


 
approvalId
required
string
Unique identifier of an approval.


 
Request Body schema: application/json
 Array 
required
string
 
required
string
 
A status of the approval (string) or string or object or object
 
Responses 
204
No Content


400
Bad request due to validation, incorrect parameters, etc.


401
Unauthorized


403
Access forbidden. The caller is not allowed to access this resource.


404
Resource cannot be found


patch/{tenant}/approvals/{approvalId}
Request samples 
application/json
[
  • {
    },
  • {
    }
]
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Problem with validation",
  • "details": [
    ],
  • "errorCode": "APPROVAL-400001"
}
Deleting a single approval
Deletes a single approval document.
A customer, who has the approval.approval_manage_own scope granted and is assigned to the approval as a requestor, can delete an approval. The approval can only be deleted if its status is PENDING. The approval status is changed to CLOSED during deletion.


In case of any validation problems, the below errorCodes can be returned:


    

  • APPROVAL-404001: Approval does not exist
    • 





*Required scopes


    

  • approval.approval_manage_own
    • 



SecurityCustomerAccessToken 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.
Note: The tenant name should always be written in lowercase.


 
approvalId
required
string
Unique identifier of an approval.


 
Responses 
204
No Content


400
Bad request - an approval cannot be deleted because it has an inappropriate status.


401
Unauthorized


403
Access forbidden. The caller is not allowed to access this resource.


404
Resource cannot be found


delete/{tenant}/approvals/{approvalId}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Deleting this approval is not allowed since it doesn't match all preconditions.",
  • "errorCode": "APPROVAL-400001"
}
Approval
Checking the resource approval
Checks the approval for given resource


In case of any validation problems, the below errorCodes can be returned:


    

  • APPROVAL-400011: Requested user is not assigned to any company
    • 





Required scopes


    

  • approval.approval_read_own
    • 



SecurityCustomerAccessToken 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.
Note: The tenant name should always be written in lowercase.


 
Request Body schema: application/json
resourceType
required
string (A type of a resource) 
Base schema for an approval resource type


 Value: "CART"  
resourceId
required
string
An identifier of the resource for approval


 
action
required
string (An approval action) 
Base schema for an approval action type


 Value: "CHECKOUT"  
Responses 
200
Approval permitted response


400
Bad request due to validation, incorrect parameters, etc.


401
Unauthorized


403
Access forbidden. The caller is not allowed to access this resource.


post/{tenant}/approval/permitted
Request samples 
application/json
{
  • "resourceId": "cartId",
  • "resourceType": "CART",
  • "action": "CHECKOUT"
}
Response samples 
application/json
{
  • "status": "APPROVED",
  • "action": "CHECKOUT",
  • "permitted": true,
  • "approvalId": "64ef8d12b6385140afea1603"
}
Search
Search for the approver users
Search for the users who can be assigned to the approvals.


In case of any validation problem, the below errorCodes can be returned:


    

  • APPROVAL-400008: Requested user has no permissions to the resource
    • 

  • APPROVAL-400011: Requested user is not assigned to any company
    • 

  • APPROVAL-404002: Provided resource does not exist
    • 

  • APPROVAL-404003: Requested user is not assigned to any legal entity
    • 





Required scopes


    

  • approval.approval_read_own
    • 



SecurityCustomerAccessToken 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.
Note: The tenant name should always be written in lowercase.


 
Request Body schema: application/json
resourceType
required
string (A type of a resource) 
Base schema for an approval resource type


 Value: "CART"  
resourceId
required
string
An identifier of the resource for approval


 
action
required
string (An approval action) 
Base schema for an approval action type


 Value: "CHECKOUT"  
Responses 
200
Approval permitted response


400
Bad request due to validation, incorrect parameters, etc.


401
Unauthorized


403
Access forbidden. The caller is not allowed to access this resource.


post/{tenant}/search/users
Request samples 
application/json
{
  • "resourceId": "cartId",
  • "resourceType": "CART",
  • "action": "CHECKOUT"
}
Response samples 
application/json
[
  • {
    }
]