Approvals

Retrieving a list of approvals

get

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.

Authorizations

AuthorizationstringRequired

To generate a customer access token, go to the Logging in a customer endpoint.

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant 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.

See: Standard Practices - Query parameter

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

Base schema for an approval response.

actionstring · enumRequired

Base schema for an approval action type.

Possible values:

commentstringOptional

A comment from the requestor to the approver.

resourceTypestring · enumRequired

Type of resource under approval.

Possible values:

idstringOptional

An identifier of the approval document.

approverCommentstringOptional

A comment from an approver user.

statusstring · enumOptional

Base schema for the approval status.

Possible values:

expiryDatestringOptional

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

401

Unauthorized.

application/json

403

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

application/json

get/approval/{tenant}/approvals

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
    }
  }
]

Creating a single approval

post

Creates a single approval document with information about the approver, resource type and resource identifier.

resourceType: CART: details is required (shipping, addresses, currency, payment methods, etc.).
resourceType: QUOTE: details must be omitted; the service loads quote data using resourceId.

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

Authorizations

AuthorizationstringRequired

To generate a customer access token, go to the Logging in a customer endpoint.

Path parameters

tenantstring · min: 3 · max: 16Required

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

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

Body

Responses

201

The resource has been successfully created.

application/json

idstringOptional

Unique identifier of the created approval.

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized.

application/json

403

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

application/json

409

Resource with given code already exists.

application/json

post/approval/{tenant}/approvals

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 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

Authorizations

AuthorizationstringRequired

To generate a customer access token, go to the Logging in a customer endpoint.

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant 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

Base schema for an approval response.

actionstring · enumRequired

Base schema for an approval action type.

Possible values:

commentstringOptional

A comment from the requestor to the approver.

resourceTypestring · enumRequired

Type of resource under approval.

Possible values:

idstringOptional

An identifier of the approval document.

approverCommentstringOptional

A comment from an approver user.

statusstring · enumOptional

Base schema for the approval status.

Possible values:

expiryDatestringOptional

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

401

Unauthorized.

application/json

403

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

application/json

404

Resource cannot be found.

application/json

get/approval/{tenant}/approvals/{approvalId}

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
  }
}

Deleting a single approval

delete

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.

Authorizations

AuthorizationstringRequired

To generate a customer access token, go to the Logging in a customer endpoint.

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant 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

No content

400

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

application/json

401

Unauthorized.

application/json

403

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

application/json

404

Resource cannot be found.

application/json

delete/approval/{tenant}/approvals/{approvalId}

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 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

Authorizations

AuthorizationstringRequired

To generate a customer access token, go to the Logging in a customer endpoint.

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant 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:

stringOptional

Value of the string type.

objectOptional

Any part of the details object.

objectOptional

Any part of the delivery window object.

Responses

204

No Content.

No content

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized.

application/json

403

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

application/json

404

Resource cannot be found.

application/json

patch/approval/{tenant}/approvals/{approvalId}

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

PreviousAPI Reference NextApproval

Last updated 2 months ago

Was this helpful?