CommunitySupport PortalYouTubeStart a free trial

Approvals

Retrieving a list of approvals

get

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
Query parameters
pageSizeinteger · min: 1 · max: 60Optional

The number of documents being retrieved on one page.

Default: 60
pageNumberinteger · min: 1Optional

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.

Default: 1
sortstringOptional

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=name,metadata.createdAt:desc
qstringOptional

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 number-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=status:APPROVED
Header parameters
X-Total-CountbooleanOptional

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
application/json
get
GET /approval/{tenant}/approvals HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "64e241ced632aa413a27a318",
    "status": "PENDING",
    "resourceType": "CART",
    "resource": {
      "id": "cartId",
      "items": [
        {
          "quantity": 1,
          "itemPrice": {
            "currency": "EUR",
            "amount": 10
          },
          "itemYrn": "urn:yaas:saasag:caasproduct:product:myshop;4474e3dfaee4c10def3d9b24"
        }
      ],
      "totalPrice": {
        "currency": "EUR",
        "amount": 10
      },
      "subTotalPrice": {
        "currency": "EUR",
        "amount": 10
      },
      "subtotalAggregate": {
        "currency": "EUR",
        "netValue": 10,
        "grossValue": 12,
        "taxValue": 20
      },
      "siteCode": "main",
      "deliveryWindow": {
        "id": "deliveryWindowId",
        "slotId": "deliveryWindowSlotId",
        "deliveryDate": "2023-04-30T13:18:02.379Z"
      }
    },
    "action": "CHECKOUT",
    "requestor": {
      "userId": "aaa2f2b6-7dc8-45ff-9f20-4e6163c14ceb",
      "firstName": "John",
      "lastName": "Doe"
    },
    "approver": {
      "userId": "aaa2f2b6-7dc8-45ff-9f20-4e6163c14cbb",
      "firstName": "John",
      "lastName": "Doe"
    },
    "comment": "Comment to the approval user",
    "approverComment": "Important comment to the requestor user",
    "expiryDate": "2023-04-31T13:18:02.379Z",
    "details": {
      "currency": "EUR",
      "paymentMethods": [
        {
          "provider": "stripe",
          "customAttributes": {
            "paymentType": "invoice"
          },
          "method": "invoice",
          "amount": 3
        }
      ],
      "shipping": {
        "zoneId": "deliveryarea",
        "methodId": "4-more_hours_timeframe",
        "amount": 10,
        "methodName": "Delivery method name",
        "shippingTaxCode": "STANDARD"
      },
      "payment": {
        "paymentId": "636cc738-f0cd-11ed-a05b-0242ac120003",
        "customAttributes": {
          "attribute1": "value of the attribute1",
          "attribute2": "value of the attribute2"
        }
      },
      "addresses": [
        {
          "contactName": "John Doe",
          "street": "Fritz-Elsas-Straße",
          "streetNumber": "20",
          "streetAppendix": "",
          "zipCode": "70173",
          "city": "Stuttgart",
          "country": "DE",
          "type": "SHIPPING",
          "contactPhone": "123456789"
        },
        {
          "contactName": "John Doe",
          "street": "Fritz-Elsas-Straße",
          "streetNumber": "20",
          "streetAppendix": "",
          "zipCode": "70173",
          "city": "Stuttgart",
          "country": "DE",
          "type": "BILLING",
          "contactPhone": "123456789"
        }
      ]
    },
    "metadata": {
      "createdAt": "2023-04-31T13:18:02.379Z",
      "modifiedAt": "2023-04-31T13:18:02.379Z",
      "version": 1
    }
  }
]

Creating a single approval

post

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
Body
all ofOptional

Base schema for an approval creation.

Responses
201
The resource has been successfully created.
application/json
post
POST /approval/{tenant}/approvals HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1059

{
  "id": "64e241ced632aa413a27a318",
  "resourceType": "CART",
  "resourceId": "cartId",
  "action": "CHECKOUT",
  "approver": {
    "userId": "aaa2f2b6-7dc8-45ff-9f20-4e6163c14cbb"
  },
  "comment": "Comment to the approval user",
  "details": {
    "currency": "EUR",
    "paymentMethods": [
      {
        "provider": "stripe",
        "customAttributes": {
          "paymentType": "invoice"
        },
        "method": "invoice",
        "amount": 3
      }
    ],
    "shipping": {
      "zoneId": "deliveryarea",
      "methodId": "4-more_hours_timeframe",
      "amount": 10,
      "methodName": "Delivery method name",
      "shippingTaxCode": "STANDARD"
    },
    "payment": {
      "paymentId": "636cc738-f0cd-11ed-a05b-0242ac120003",
      "customAttributes": {
        "attribute1": "value of the attribute1",
        "attribute2": "value of the attribute2"
      }
    },
    "addresses": [
      {
        "contactName": "John Doe",
        "street": "Fritz-Elsas-Straße",
        "streetNumber": "20",
        "streetAppendix": "",
        "zipCode": "70173",
        "city": "Stuttgart",
        "country": "DE",
        "type": "SHIPPING",
        "contactPhone": "123456789"
      },
      {
        "contactName": "John Doe",
        "street": "Fritz-Elsas-Straße",
        "streetNumber": "20",
        "streetAppendix": "",
        "zipCode": "70173",
        "city": "Stuttgart",
        "country": "DE",
        "type": "BILLING",
        "contactPhone": "123456789"
      }
    ]
  }
}
{
  "id": "88b1779c-a8bf-4b94-b1be-b0edd149bba5"
}

Retrieving a single approval

get

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
approvalIdstringRequired

Unique identifier of an approval.

Responses
200Success
application/json
Responseall of

Base schema for an approval response.

get
GET /approval/{tenant}/approvals/{approvalId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "64e241ced632aa413a27a318",
  "status": "PENDING",
  "resourceType": "CART",
  "resource": {
    "id": "cartId",
    "items": [
      {
        "quantity": 1,
        "itemPrice": {
          "currency": "EUR",
          "amount": 10
        },
        "itemYrn": "urn:yaas:saasag:caasproduct:product:myshop;4474e3dfaee4c10def3d9b24"
      }
    ],
    "totalPrice": {
      "currency": "EUR",
      "amount": 10
    },
    "subTotalPrice": {
      "currency": "EUR",
      "amount": 10
    },
    "subtotalAggregate": {
      "currency": "EUR",
      "netValue": 10,
      "grossValue": 12,
      "taxValue": 20
    },
    "siteCode": "main",
    "deliveryWindow": {
      "id": "deliveryWindowId",
      "slotId": "deliveryWindowSlotId",
      "deliveryDate": "2023-04-30T13:18:02.379Z"
    }
  },
  "action": "CHECKOUT",
  "requestor": {
    "userId": "aaa2f2b6-7dc8-45ff-9f20-4e6163c14ceb",
    "firstName": "John",
    "lastName": "Doe"
  },
  "approver": {
    "userId": "aaa2f2b6-7dc8-45ff-9f20-4e6163c14cbb",
    "firstName": "John",
    "lastName": "Doe"
  },
  "comment": "Comment to the approval user",
  "approverComment": "Important comment to the requestor user",
  "expiryDate": "2023-04-31T13:18:02.379Z",
  "details": {
    "currency": "EUR",
    "paymentMethods": [
      {
        "provider": "stripe",
        "customAttributes": {
          "paymentType": "invoice"
        },
        "method": "invoice",
        "amount": 3
      }
    ],
    "shipping": {
      "zoneId": "deliveryarea",
      "methodId": "4-more_hours_timeframe",
      "amount": 10,
      "methodName": "Delivery method name",
      "shippingTaxCode": "STANDARD"
    },
    "payment": {
      "paymentId": "636cc738-f0cd-11ed-a05b-0242ac120003",
      "customAttributes": {
        "attribute1": "value of the attribute1",
        "attribute2": "value of the attribute2"
      }
    },
    "addresses": [
      {
        "contactName": "John Doe",
        "street": "Fritz-Elsas-Straße",
        "streetNumber": "20",
        "streetAppendix": "",
        "zipCode": "70173",
        "city": "Stuttgart",
        "country": "DE",
        "type": "SHIPPING",
        "contactPhone": "123456789"
      },
      {
        "contactName": "John Doe",
        "street": "Fritz-Elsas-Straße",
        "streetNumber": "20",
        "streetAppendix": "",
        "zipCode": "70173",
        "city": "Stuttgart",
        "country": "DE",
        "type": "BILLING",
        "contactPhone": "123456789"
      }
    ]
  },
  "metadata": {
    "createdAt": "2023-04-31T13:18:02.379Z",
    "modifiedAt": "2023-04-31T13:18:02.379Z",
    "version": 1
  }
}

Deleting a single approval

delete

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
approvalIdstringRequired

Unique identifier of an approval.

Responses
204
No Content
delete
DELETE /approval/{tenant}/approvals/{approvalId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Updating a single approval

patch

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
approvalIdstringRequired

Unique identifier of an approval.

Bodyobject[]

Approval partial update operation list.

opany ofRequired
undefined · enumOptionalPossible values:
pathany ofRequired
undefined · enumOptionalPossible values:
valueany ofOptional
string · enumOptional

Base schema for the approval status

Possible values:
or
stringOptional

Value of the string type

or
objectOptional

Any part of the details object

or
objectOptional

Any part of the delivery window object

Responses
204
No Content
patch
PATCH /approval/{tenant}/approvals/{approvalId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111

[
  {
    "op": "REPLACE",
    "path": "/comment",
    "value": "new comment"
  },
  {
    "op": "REPLACE",
    "path": "/status",
    "value": "APPROVED"
  }
]
No content
PreviousApprovalNextSearch

Was this helpful?