openapi: 3.0.0 info: contact: name: Emporix url: https://emporix.com email: documentation@emporix.com title: Approval Service version: '' description: | The Emporix API Approval Service allows you to manage approval requests related to orders. The orders are referred to as resources. servers: - url: 'https://api.emporix.io' tags: - name: Approvals - name: Approval - name: Search paths: '/approval/{tenant}/approvals': parameters: - $ref: '#/components/parameters/path_tenant' post: summary: Creating a single approval responses: '201': description: | The resource has been successfully created. content: application/json: schema: $ref: '#/components/schemas/approvalId' examples: approvalId: value: id: 88b1779c-a8bf-4b94-b1be-b0edd149bba5 '400': $ref: '#/components/responses/approvals_response_BadRequest_400' '401': $ref: '#/components/responses/common_response_Unauthorized_401' '403': $ref: '#/components/responses/common_response_Forbidden_403' '409': $ref: '#/components/responses/approval_post_response_Conflict_409' description: | 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` operationId: POST-approval-create-approval requestBody: $ref: '#/components/requestBodies/approvalCreateBody' parameters: - $ref: '#/components/parameters/path_tenant' security: - CustomerAccessToken: [] tags: - Approvals get: summary: Retrieving a list of approvals operationId: GET-approval-list-approvals responses: '200': $ref: '#/components/responses/listOfApprovalsResponse_200' '401': $ref: '#/components/responses/common_response_Unauthorized_401' '403': $ref: '#/components/responses/common_response_Forbidden_403' tags: - Approvals description: | Retrieves a list of approval documents which is assigned to the user. The user needs to be a *Requestor* or an *Approver*. *** **Required scopes** * `approval.approval_read_own` parameters: - $ref: '#/components/parameters/x_total_count_header' - $ref: '#/components/parameters/page_size_query_param' - $ref: '#/components/parameters/page_number_query_param' - $ref: '#/components/parameters/sort_query_param' - $ref: '#/components/parameters/q_query_param' security: - CustomerAccessToken: [] '/approval/{tenant}/approvals/{approvalId}': parameters: - $ref: '#/components/parameters/path_tenant' - $ref: '#/components/parameters/approvalId' get: summary: Retrieving a single approval tags: - Approvals operationId: GET-approval-retrieve-approval description: | Retrieves a single approval document which is assigned to the user. The user needs to be a *Requestor* or an *Approver*. In case of any validation problems, the below `errorCodes` can be returned: - **APPROVAL-404001**: Approval does not exist *** **Required scopes** * `approval.approval_read_own` responses: '200': $ref: '#/components/responses/singleApprovalResponse_200' '401': $ref: '#/components/responses/common_response_Unauthorized_401' '403': $ref: '#/components/responses/common_response_Forbidden_403' '404': $ref: '#/components/responses/approvals_response_NotFound_404' security: - CustomerAccessToken: [] patch: summary: Updating a single approval operationId: PATCH-approval-update-approval responses: '204': description: No Content. '400': $ref: '#/components/responses/approvals_response_BadRequest_400' '401': $ref: '#/components/responses/common_response_Unauthorized_401' '403': $ref: '#/components/responses/common_response_Forbidden_403' '404': $ref: '#/components/responses/approvals_response_NotFound_404' tags: - Approvals description: | Partially updates a single approval document with given information. To update the approval, the user needs to be a *Requestor* or an *Approver*. 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` requestBody: $ref: '#/components/requestBodies/approvalUpdateBody' security: - CustomerAccessToken: [] delete: summary: Deleting a single approval operationId: DELETE-approval-remove-approval responses: '204': description: No Content '400': $ref: '#/components/responses/approvals_response_DeleteBadRequest_400' '401': $ref: '#/components/responses/common_response_Unauthorized_401' '403': $ref: '#/components/responses/common_response_Forbidden_403' '404': $ref: '#/components/responses/approvals_response_NotFound_404' tags: - Approvals description: |- 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` security: - CustomerAccessToken: [] '/approval/{tenant}/approval/permitted': parameters: - $ref: '#/components/parameters/path_tenant' post: summary: Checking the resource approval responses: '200': $ref: '#/components/responses/ApprovalPermittedResponse_200' '400': $ref: '#/components/responses/approvals_response_BadRequest_400' '401': $ref: '#/components/responses/common_response_Unauthorized_401' '403': $ref: '#/components/responses/common_response_Forbidden_403' description: | Checks the approval for given resource. The endpoint verifies whether a user is authorized to perform a specific action on a given resource within a tenant. 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` operationId: POST-approval-check-approval requestBody: $ref: '#/components/requestBodies/approvalPermittedRequestBody' parameters: - $ref: '#/components/parameters/path_tenant' security: - CustomerAccessToken: [] tags: - Approval '/approval/{tenant}/search/users': parameters: - $ref: '#/components/parameters/path_tenant' post: summary: Search for the users eligible to act as *Approvers*. responses: '200': $ref: '#/components/responses/ApprovalSearchUsersResponse_200' '400': $ref: '#/components/responses/approvals_response_BadRequest_400' '401': $ref: '#/components/responses/common_response_Unauthorized_401' '403': $ref: '#/components/responses/common_response_Forbidden_403' description: | 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` operationId: POST-approval-search-users requestBody: $ref: '#/components/requestBodies/approvalSearchUsersRequestBody' parameters: - $ref: '#/components/parameters/path_tenant' security: - CustomerAccessToken: [] tags: - Search components: responses: approvals_response_BadRequest_400: description: 'Bad request due to validation, incorrect parameters, etc.' content: application/json: schema: $ref: '#/components/schemas/coreErrorMessage' examples: Bad request: value: code: 400 status: Bad Request message: Problem with validation details: - message: 'resourceType: cannot be null' errorCode: APPROVAL-400001 approvals_response_NotFound_404: description: 'Resource cannot be found.' content: application/json: schema: $ref: '#/components/schemas/coreErrorMessage' examples: Bad request: value: code: 404 status: Not Found message: "Approval with id '123456789' does not exist." errorCode: APPROVAL-404001 common_response_Unauthorized_401: description: Unauthorized. content: application/json: schema: type: object properties: fault: type: object properties: faultstring: type: string detail: type: object properties: errorcode: type: string examples: Invalid access token: value: fault: faultstring: Invalid access token detail: errorcode: oauth.v2.InvalidAccessToken Access token expired: value: fault: faultstring: Access Token expired detail: errorcode: keymanagement.service.access_token_expired common_response_Forbidden_403: description: Access forbidden. The caller is not allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/coreErrorMessage' examples: Forbidden: value: code: 403 status: Forbidden message: The access to the requested resource has been forbidden by the server. approval_post_response_Conflict_409: description: | Resource with given code already exists. content: application/json: schema: $ref: '#/components/schemas/coreErrorMessage' examples: Conflict - an approval already exists.: value: code: 409 status: Conflict message: Approval with given id already exists. errorCode: APPROVAL-409001 approvals_response_DeleteBadRequest_400: description: Bad request - an approval cannot be deleted because it has an inappropriate status. content: application/json: schema: $ref: '#/components/schemas/coreErrorMessage' examples: Bad Request - an approval cannot be deleted.: value: code: 400 status: Bad Request message: Deleting this approval is not allowed since it doesn't match all preconditions. errorCode: APPROVAL-400001 singleApprovalResponse_200: description: '' content: application/json: schema: $ref: '#/components/schemas/getApprovalResponse' examples: an approval retrieved by a customer: value: id: 64e241ced632aa413a27a318 status: PENDING resourceType: CART resource: id: cartId items: - quantity: 1 itemPrice: currency: EUR amount: 10.0 itemYrn: urn:yaas:saasag:caasproduct:product:myshop;4474e3dfaee4c10def3d9b24 totalPrice: currency: EUR amount: 10.0 subTotalPrice: currency: EUR amount: 10.0 subtotalAggregate: currency: EUR netValue: 10.0 grossValue: 12.00 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.0 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 listOfApprovalsResponse_200: description: Example response. content: application/json: schema: items: $ref: '#/components/schemas/getApprovalResponse' type: array examples: All approvals: value: - id: 64e241ced632aa413a27a318 status: PENDING resourceType: CART resource: id: cartId items: - quantity: 1 itemPrice: currency: EUR amount: 10.0 itemYrn: urn:yaas:saasag:caasproduct:product:myshop;4474e3dfaee4c10def3d9b24 totalPrice: currency: EUR amount: 10.0 subTotalPrice: currency: EUR amount: 10.0 subtotalAggregate: currency: EUR netValue: 10.0 grossValue: 12.00 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.0 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 ApprovalPermittedResponse_200: description: Approval permitted response. content: application/json: schema: $ref: '#/components/schemas/approvalPermittedResponse' examples: Action permitted - approval exists: value: status: APPROVED action: CHECKOUT permitted: true approvalId: 64ef8d12b6385140afea1603 Action permitted for admin user - approval does not exist: value: action: CHECKOUT permitted: true Action denied - approval exists: value: status: PENDING action: CHECKOUT permitted: false approvalId: 64ef8d12b6385140afea1603 Action denied if approval is not defined: value: action: CHECKOUT permitted: false ApprovalSearchUsersResponse_200: description: Approval permitted response. content: application/json: schema: $ref: '#/components/schemas/approvalSearchUsersResponse' examples: List of approval users: value: - userId: aaa2f2b6-7dc8-45ff-9f20-4e6163c14ceb firstName: John lastName: Doe schemas: coreErrorMessage: type: object properties: code: type: integer description: HTTP Status Code. status: type: string description: HTTP Status. message: type: string description: Error message. errorCode: type: string description: code of the error. details: description: Details information. type: array items: type: object properties: field: type: string type: type: string message: type: string moreInfo: type: string basicApproval: title: basicApproval description: Base schema for an approval. type: object properties: resourceType: $ref: '#/components/schemas/resourceType' action: $ref: '#/components/schemas/approvalAction' approver: type: object description: User who can approve the approval request. properties: userId: type: string description: Identifier of the user. comment: type: string description: A comment from the requestor to the approver. details: type: object title: additional information description: additional information required for approval process. properties: shipping: $ref: '#/components/schemas/shipping' payment: $ref: '#/components/schemas/payment' paymentMethods: description: Methods chosen to process the payment for the order. type: array items: $ref: '#/components/schemas/paymentMethod' currency: type: string description: 'Three-letter currency code, compliant with the ISO 4217 standard.' addresses: type: array uniqueItems: true minItems: 1 description: List of addresses associated with the order. items: $ref: '#/components/schemas/address' required: - resourceType - action - approver address: type: object description: Information about the customer address. properties: contactName: type: string minLength: 0 companyName: type: string street: type: string minLength: 0 streetNumber: type: string streetAppendix: type: string zipCode: type: string maxLength: 11 minLength: 0 city: type: string minLength: 0 country: type: string minLength: 1 state: type: string contactPhone: type: string type: type: string description: Type of the address data, for example `BILLING` or `SHIPPING`. enum: - SHIPPING - BILLING shipping: type: object title: Shipping information description: Information about the shipping. additionalProperties: false properties: methodId: type: string description: Shipping method's unique identifier. minLength: 0 zoneId: type: string description: Shipping zone identifier. minLength: 0 methodName: type: string description: Shipping method chosen by the customer. minLength: 0 amount: type: number minimum: 0 description: Shipping net cost. shippingTaxCode: type: string description: The tax code of the shipping. payment: type: object description: Information about the payment. title: Payment information additionalProperties: false properties: paymentId: type: string minLength: 0 customAttributes: type: object paymentMethod: type: object additionalProperties: false properties: provider: type: string description: | Payment provider, possible values: * `payment-gateway` - When the Emporix Payment-Gateway service should be used to handle a payment. For details about custom attributes that are required for a particular payment mode, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments. * `custom` - When a custom provider is used. In this case the created order has the `IN_CHECKOUT` status. * `none` - For payment by cash or invoice. minLength: 0 customAttributes: type: object description: Additional information about the payment method. properties: token: type: string description: 'Payment token used for the tokenized credit card flows. The field is used when provider type is `payment-gateway`. For more details, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments' modeId: type: string description: 'Identifier of a payment mode. The payment mode has to be configured in the Emporix Payment Gateway service beforehand. For more details, check https://developer.emporix.io/user-guides/system-management/payment-gateway/payments' paymentType: type: string description: 'Payment type chosen by the customer, for example `paymentByCredit` or `paymentByDebit`.' method: type: string description: 'Payment method chosen by the customer, for example `invoice` or `cash-on-delivery`.' amount: type: number description: Amount to be paid by the customer. user: title: user schema type: object properties: userId: type: string description: An identifier of the user. firstName: type: string description: First name of the user. lastName: type: string description: Last name of the user. required: - userId - firstName - lastName resourceType: title: A type of a resource description: Base schema for an approval resource type. type: string enum: - CART approvalAction: title: An approval action description: Base schema for an approval action type. type: string enum: - CHECKOUT approvalStatus: title: A status of the approval description: Base schema for the approval status. type: string enum: - PENDING - APPROVED - CLOSED - EXPIRED - DECLINED expiryDate: title: An expiration date description: '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`' type: string getApprovalResponse: title: An approval response allOf: - $ref: '#/components/schemas/basicApproval' - type: object description: Base schema for an approval response. properties: id: type: string description: An identifier of the approval document. approverComment: type: string description: A comment from an approver user. resource: $ref: '#/components/schemas/resourceResponse' requestor: $ref: '#/components/schemas/user' approver: $ref: '#/components/schemas/user' status: $ref: '#/components/schemas/approvalStatus' expiryDate: $ref: '#/components/schemas/expiryDate' metadata: $ref: '#/components/schemas/metadata' approvalPermittedResponse: title: approval permitted response allOf: - type: object description: Base schema for approval permitted response. properties: action: $ref: '#/components/schemas/approvalAction' status: $ref: '#/components/schemas/approvalStatus' permitted: type: boolean description: Indicates if the operation is permitted. approvalId: type: string description: Identifier of the approval. required: - permitted - action resourceResponse: title: Resource description: Resource of the approval. type: object properties: id: type: string description: The identifier of the resource. items: type: array items: $ref: '#/components/schemas/resourceItem' totalPrice: $ref: '#/components/schemas/price' subTotalPrice: $ref: '#/components/schemas/price' subtotalAggregate: $ref: '#/components/schemas/taxablePrice' amount: type: number description: Value of the price. siteCode: type: string description: Name of the site. deliveryWindow: $ref: '#/components/schemas/deliveryWindow' resourceItem: title: Resource item description: Item of the resource. type: object properties: quantity: type: number description: Quantity of the given item. itemPrice: $ref: '#/components/schemas/price' itemYrn: type: string description: YRN which identifies the product. price: title: Price value description: Price value with the currency. type: object properties: currency: type: string description: Currency of the price. amount: type: number description: Value of the price. taxablePrice: title: Taxable price value description: Price value with the currency and tax information. type: object properties: currency: type: string description: Currency of the price. netValue: type: number description: Net value of the price. grossValue: type: number description: Gross value of the price. taxValue: type: number description: Tax value of the price. deliveryWindow: title: Delivery Window description: delivery window required for order. type: object properties: id: type: string description: Identifier of the delivery window. slotId: type: string description: Identifier of the slot. deliveryDate: type: string description: Delivery date. approvalSearchUsersResponse: title: Search approval users response description: Base schema search approval users response. type: array items: $ref: '#/components/schemas/user' createApprovalRequest: title: Create an approval allOf: - $ref: '#/components/schemas/basicApproval' - type: object description: Base schema for an approval creation. properties: id: type: string description: An identifier of the approval document. resourceId: type: string description: An identifier of the approval resource. updateApprovalRequest: type: array description: Approval partial update operation list. items: type: object properties: op: anyOf: - enum: - ADD - REMOVE - REPLACE type: string path: anyOf: - enum: - /status - /details* - /comment - /approverComment - /resource/deliveryWindow* type: string value: anyOf: - $ref: '#/components/schemas/approvalStatus' - type: string description: Value of the string type. - type: object description: Any part of the details object. - type: object description: Any part of the delivery window object. required: - op - path basicMetadata: type: object properties: version: minimum: 1 type: integer description: Version of the object. The version is required during the update operation because of the optimistic locking mechanism. required: - version metadata: allOf: - $ref: '#/components/schemas/basicMetadata' - type: object properties: createdAt: description: 'Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`' type: string modifiedAt: description: 'Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`' type: string required: - createdAt - modifiedAt - version approvalId: title: approvalId type: object properties: id: type: string description: Unique identifier of the created approval. approvalPermittedRequest: title: approval permitted request type: object properties: resourceType: $ref: '#/components/schemas/resourceType' resourceId: type: string description: An identifier of the resource for approval. action: $ref: '#/components/schemas/approvalAction' required: - resourceType - resourceId - action searchUsersRequest: title: Search approver users request type: object properties: resourceType: $ref: '#/components/schemas/resourceType' resourceId: type: string description: An identifier of the resource for approval. action: $ref: '#/components/schemas/approvalAction' required: - resourceType - resourceId - action requestBodies: approvalCreateBody: content: application/json: schema: $ref: '#/components/schemas/createApprovalRequest' examples: An approval request for cart checkout: value: 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.0 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' approvalUpdateBody: content: application/json: schema: $ref: '#/components/schemas/updateApprovalRequest' examples: Multiple update list: value: - op: REPLACE path: /comment value: new comment - op: REPLACE path: /status value: APPROVED Change status of the approval: value: - op: REPLACE path: /status value: APPROVED Change comment of the approval: value: - op: REPLACE path: /comment value: new comment Add comment by the approver: value: - op: ADD path: /approverComment value: new comment Change currency of the details: value: - op: REPLACE path: /details/currency value: EUR Change delivery window: value: - op: REPLACE path: /resource/deliveryWindow value: id: deliveryWindowId slotId: deliveryWindowSlotId deliveryDate: "2010-05-02T13:06:15.280Z" Change details of the approval: value: - op: REPLACE path: /details value: currency: EUR paymentMethods: - provider: stripe customAttributes: paymentType: invoice method: invoice amount: 3.0 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' approvalPermittedRequestBody: content: application/json: schema: $ref: '#/components/schemas/approvalPermittedRequest' examples: Check if action is permitted: value: resourceId: cartId resourceType: CART action: CHECKOUT approvalSearchUsersRequestBody: content: application/json: schema: $ref: '#/components/schemas/searchUsersRequest' examples: Search for approval users: value: resourceId: cartId resourceType: CART action: CHECKOUT parameters: path_tenant: name: tenant in: path required: true description: | Your Emporix tenant name. **Note**: The tenant name should always be written in lowercase. schema: pattern: '^[a-z][a-z0-9]+$' minLength: 3 maxLength: 16 type: string page_number_query_param: name: pageNumber in: query schema: type: integer default: 1 minimum: 1 description: '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.' page_size_query_param: name: pageSize in: query required: false schema: type: integer default: 60 minimum: 1 maximum: 60 description: The number of documents being retrieved on one page. sort_query_param: name: sort in: query required: false schema: type: string example: 'sort=name,metadata.createdAt:desc' description: '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.' q_query_param: name: q in: query required: false schema: type: string example: 'q=status:APPROVED' description: | A standard query parameter is used to search for the 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=mixins.mixinName:exists`, where the specific mixin named `mixinName` exists in the database. + 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. x_total_count_header: name: X-Total-Count in: header required: false schema: type: boolean description: '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.' approvalId: name: approvalId in: path required: true schema: type: string description: Unique identifier of an approval. securitySchemes: CustomerAccessToken: type: http scheme: bearer description: 'To generate a customer access token, go to the [Logging in a customer](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login) endpoint.'