Approvals
Retrieves a list of approval documents assigned to the user. The user must be a Requestor or an Approver to have the required approval.approval_read_own scope.
To generate a customer access token, go to the Logging in a customer endpoint.
Your Emporix tenant name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$The number of documents being retrieved on one page.
60The 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.
1Fields 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.
sort=name,metadata.createdAt:descA standard query parameter is used to search for specific values.
q=status:APPROVEDTo 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.
Example response.
Base schema for an approval response.
Base schema for an approval action type.
A comment from the requestor to the approver.
Type of resource under approval.
An identifier of the approval document.
A comment from an approver user.
Base schema for the approval status.
An expiration date which defines when the approval will expire. The value is approved as an ISO-8601 representation of an Instant. For example: 2022-04-31T13:18:02.379Z
Unauthorized.
Access forbidden. The caller is not allowed to access this resource.
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,
"itemId": "507f1f77bcf86cd799439011",
"itemPrice": {
"currency": "EUR",
"amount": 10,
"unitPrice": 10,
"calculatedPrice": {
"price": {
"netValue": 10,
"grossValue": 12,
"taxValue": 2
}
}
}
}
],
"totalPrice": {
"currency": "EUR",
"amount": 10,
"netValue": 10,
"grossValue": 12,
"taxValue": 2
},
"subTotalPrice": {
"currency": "EUR",
"amount": 10,
"netValue": 10,
"grossValue": 12,
"taxValue": 2
},
"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"
}
]
},
"legalEntity": {
"id": "legalEntityId"
},
"createdResource": {
"id": "64ef8d12b6385140afea1603"
},
"metadata": {
"createdAt": "2023-04-31T13:18:02.379Z",
"modifiedAt": "2023-04-31T13:18:02.379Z",
"version": 1
}
}
]Creates a single approval document with information about the approver, resource type and resource identifier.
resourceType: CART:detailsis required (shipping, addresses, currency, payment methods, etc.).resourceType: QUOTE:detailsmust be omitted; the service loads quote data usingresourceId.
The user must be a Requestor or an Approver to have the required approval.approval_manage_own scope.
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
To generate a customer access token, go to the Logging in a customer endpoint.
Your Emporix tenant name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$The resource has been successfully created.
Unique identifier of the created approval.
Bad request due to validation, incorrect parameters, etc.
Unauthorized.
Access forbidden. The caller is not allowed to access this resource.
Resource with given code already exists.
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"
}Retrieves a single approval document which is assigned to the user. The user must be a Requestor or an Approver to have the required approval.approval_read_own scope.
In case of any validation problems, the below errorCodes can be returned:
APPROVAL-404001: Approval does not exist
To generate a customer access token, go to the Logging in a customer endpoint.
Your Emporix tenant name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$Unique identifier of an approval.
Base schema for an approval response.
Base schema for an approval action type.
A comment from the requestor to the approver.
Type of resource under approval.
An identifier of the approval document.
A comment from an approver user.
Base schema for the approval status.
An expiration date which defines when the approval will expire. The value is approved as an ISO-8601 representation of an Instant. For example: 2022-04-31T13:18:02.379Z
Unauthorized.
Access forbidden. The caller is not allowed to access this resource.
Resource cannot be found.
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,
"itemId": "507f1f77bcf86cd799439011",
"itemPrice": {
"currency": "EUR",
"amount": 10,
"unitPrice": 10,
"calculatedPrice": {
"price": {
"netValue": 10,
"grossValue": 12,
"taxValue": 2
}
}
}
}
],
"totalPrice": {
"currency": "EUR",
"amount": 10,
"netValue": 10,
"grossValue": 12,
"taxValue": 2
},
"subTotalPrice": {
"currency": "EUR",
"amount": 10,
"netValue": 10,
"grossValue": 12,
"taxValue": 2
},
"subtotalAggregate": {
"currency": "EUR",
"netValue": 10,
"grossValue": 12,
"taxValue": 2
},
"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"
}
]
},
"legalEntity": {
"id": "legalEntityId"
},
"createdResource": {
"id": "64ef8d12b6385140afea1603"
},
"metadata": {
"createdAt": "2023-04-31T13:18:02.379Z",
"modifiedAt": "2023-04-31T13:18:02.379Z",
"version": 1
}
}Deletes a single approval document. To delete an approval, a customer must be a Requestor or an Approver to have the required approval.approval_manage_own scope. 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.
To generate a customer access token, go to the Logging in a customer endpoint.
Your Emporix tenant name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$Unique identifier of an approval.
No Content
No content
Bad request - an approval cannot be deleted because it has an inappropriate status.
Unauthorized.
Access forbidden. The caller is not allowed to access this resource.
Resource cannot be found.
DELETE /approval/{tenant}/approvals/{approvalId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Partially updates a single approval document with given information. To update the approval, the user must be a Requestor or an Approver to have the required approval.approval_manage_own scope.
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
To generate a customer access token, go to the Logging in a customer endpoint.
Your Emporix tenant name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$Unique identifier of an approval.
Approval partial update operation list.
Base schema for the approval status.
Value of the string type.
Any part of the details object.
Any part of the delivery window object.
No Content.
No content
Bad request due to validation, incorrect parameters, etc.
Unauthorized.
Access forbidden. The caller is not allowed to access this resource.
Resource cannot be found.
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
Last updated
Was this helpful?