Document Properties
Kbid29V604
Last Modified02-Nov-2020
Added to KB03-Sep-2020
Public AccessEveryone
StatusOnline
Doc TypeReferences
ProductICM 7.10

Reference - ICM REST API - B2B Front End - Requisition Approval 1.0.0


Product Version

7.10

Product To Version


Status

final

Download Specification 

This API specification is available for download as an Open API 3.0 YAML file: 

API Specification

Introduction

OpenAPI Version: 3.0.1
Requisition Approval Version: 1.0.0-beta

This is Intershop ICM REST API documentation.

This reference lists the REST API for storefront development. The REST API covers features of both, the B2C (SMB - Small and Medium-sized businesses) and the B2B storefront development.
This reference is intended for developers who want to make use of an easy-to-use API when developing frontend solutions.
You can find more information at Intershop Communications. Contact our Intershop experts at Support - Intershop Communications

Introduction

This API is documented in OpenAPI format.

Budget API

/customers/{CustomerKey}/users/{CustomerItemUserKey}/budgets
GET: [BETA] Returns the budgets for the user.

Description

The budget information consists of threshold amount for single orders, budget and corresponding budget period (weekly, monthly etc.) as well as the calculated values spent budget and remaining budget.

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.b2b.approval.capi.resource.budget.UserBudgetResource.getUserBudgets()

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

200 - OK

The user budgets.
UserBudgetsRO application/json

401 - Unauthorized

If the user couldn't be authenticated.

403 - Forbidden

If the user isn't allowed to access this resource.
PUT: [BETA] Updates the budgets for the user.

Description

The budget information consists of threshold amount for single orders, budget and corresponding budget period (weekly, monthly etc.) as well as the calculated values spent budget and remaining budget.

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.b2b.approval.capi.resource.budget.UserBudgetResource.setUserBudgets(com.intershop.sellside.rest.b2b.approval.capi.resourceobject.budget.UserBudgetsRO)

Request Body

UserBudgetsRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

200 - OK

The udpated user budget.
UserBudgetsRO application/json

401 - Unauthorized

If the user couldn't be authenticated.

403 - Forbidden

If the user isn't allowed to access this resource.

Requisition API

/customers/{CustomerKey}/users/{CustomerItemUserKey}/requisitions
GET: [BETA] Returns the list requisitions for the user

Description

Depending on the attribute 'view' the list of requisitions either consists of purchases the used did (buyer view) or consists of purchases the user (with role 'approver') has to approve. The requisition information consists of creation date, amount of line items and the total overall line items.

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.b2b.approval.capi.resource.requisition.RequisitionListResource.getRequisitions(java.lang.String,java.lang.String,java.lang.String,java.lang.String)

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in querystatusstringThe optional approval status to filter. Possible values: 'pending', 'approved', 'rejected', 'all'. If parameter is missing or empty option 'all' is returned.
in querytypestringThe optional requisition type to filter. Possible values: 'one-time', 'recurring', 'all'. If parameter is missing or empty option 'all' is returned.
in queryviewstringThe optional view attribute defines if the buyer view (purchases of the user) or approver view (purchases the user has to approve) is applied. Possible values: 'buyer', 'approver'. If parameter is missing or empty option 'buyer' is returned.
in queryincludestringRelated objects (as a comma separated list) which are to be included with the response.

Response

200 - OK

The list of requisitions container for the user (buyer, approver). If the list is requested with approver view and the given user is not an approver and empty list will be returned.
ContainerRO_v1 application/json

400 - Bad Request

If a query parameter contains an invalid value.

401 - Unauthorized

If the user couldn't be authenticated.

403 - Forbidden

If the user isn't allowed to access this resource.
/customers/{CustomerKey}/users/{CustomerItemUserKey}/requisitions/{RequisitionKey}
GET: [BETA] Returns the requisition with the given ID.

Description

...

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.b2b.approval.capi.resource.requisition.RequisitionItemResource.getRequisition(java.lang.String)

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathRequisitionKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in queryincludestringRelated objects (as a comma separated list) which are to be included with the response.

Response

200 - OK

The requisition container with the given ID.
ContainerRO_v1 application/json

401 - Unauthorized

If the user could not be authenticated.

403 - Forbidden

If the user does not have the required access privileges.

404 - Not Found

If no requisition is found.
FeedbackRO_v1 application/json
PATCH: [BETA] Does the approval status change of a requisition.

Description

--

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.b2b.approval.capi.resource.requisition.RequisitionItemResource.changeStatus(com.intershop.sellside.rest.b2b.approval.capi.resourceobject.approval.ApprovalStatusChangeRO,java.lang.String)

Request Body

ApprovalStatusChangeRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathRequisitionKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in queryincludestringRelated objects (as a comma separated list) which are to be included with the response.

Response

202 - Accepted

The updated requisition container.
ContainerRO_v1 application/json

404 - Not Found

If a requisition with the given ID is not found.
FeedbackRO_v1 application/json

422 - Unprocessable Entity

If the requisition could not be updated.
FeedbackRO_v1 application/json

Role API

/customers/{CustomerKey}/roles
GET: [BETA] Get the complete list of user roles for the customer.

Description

Returns the complete list of user roles (assignable & implicit)for the customer. Thie list contains implicitly assigneed roles as well roles that can be explicitly assigned.The role information consists of the role ID, the localized display name and a list of localized names of the included permissions. The flag 'fixed' indicates that the role is implicitly assigned and can't be removed.

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.b2b.approval.capi.resource.role.CustomerRoleResource.getCustomeRoles()

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

200 - OK

The list of user roles.
UserRolesRO application/json

401 - Unauthorized

If the user couldn't be authenticated.

403 - Forbidden

If the user isn't allowed to access this resource.
/customers/{CustomerKey}/users/{CustomerItemUserKey}/roles
GET: [BETA] Get the list of assigned user roles.

Description

Returns the list of roles that are assigned to the user. The role information consists of the role ID, the localized display name and a list of localized names of the included permissions. The flag 'fixed' indicates that the role is implicitly assigned and can't be removed.

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.b2b.approval.capi.resource.role.UserRoleResource.getUserRoles()

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

200 - OK

The list of user roles.
UserRolesRO application/json

401 - Unauthorized

If the user couldn't be authenticated.

403 - Forbidden

If the user isn't allowed to access this resource.
PUT: [BETA] Updates the list of assigned user roles.

Description

Updates the list of roles that are asigned to the user. Some roles might be implicitly assigned and cannot be removed. An empty list will remove all roles despite the ones that can't be removed. The updated list of user roles is returned.

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.b2b.approval.capi.resource.role.UserRoleResource.setUserRoles(com.intershop.sellside.rest.b2b.approval.capi.resourceobject.role.UserRolesInputRO)

Request Body

UserRolesInputRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

200 - OK

The list of user roles.
UserRolesRO application/json

401 - Unauthorized

If the user couldn't be authenticated.

403 - Forbidden

If the user isn't allowed to access this resource.

Request and Response Object Schemata

ApprovalStatusChangeRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: ApprovalStatusChange
  • "status":
    string
    The status to be changed. | Example: approved
  • "approvalComment":
    string
    The approval comment for rejection.
}
ContainerRO_v1 application/json{
  • "data":
    object
    The core data of the response object.
  • "errors":
    array
    Readonly | An array of FeedbackRO_v1 objects. List of errors that occurred in relation to the request.
    [
    FeedbackRO_v1: An error or information representation regarding the current request.
    {
    • "causes":
      array
      An array of FeedbackCauseRO_v1 objects. A collection of errors/infos that caused this feedback.
      [
      FeedbackCauseRO_v1: A representation for the common feedback informations.
      {
      • "code":
        string
        Required | An unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: invoiceToAddress.address.postalcode.invalid
      • "message":
        string
        Required | A human readable message in request's locale (server falls back to lead locale if requested local is not supported). | Example: The specified postal code is invalid. Valid values are numbers 10000 to 99999.
      • "parameters":
        object
        A map of several parameters that are used to assemble the message.
      • "paths":
        array
        An array of string literals. A collection of JSON paths to the associated entities. If not otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath
      }
      ]
    • "code":
      string
      An unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: invoiceToAddress.address.postalcode.invalid
    • "message":
      string
      A human readable message in request's locale (server falls back to lead locale if requested local is not supported). | Example: The specified postal code is invalid. Valid values are numbers 10000 to 99999.
    • "parameters":
      object
      A map of several parameters that are used to assemble the message.
    • "paths":
      array
      An array of string literals. A collection of JSON paths to the associated entities. If not otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath
    • "status":
      string
      The HTTP status code, that is applicable to this problem. | Example: 400
    }
    ]
  • "included":
    object
    Optionally included related data objects.
  • "infos":
    array
    Readonly | An array of FeedbackRO_v1 objects. List of informations regarding to the request (e.g. value adjustments).
    [
    FeedbackRO_v1: An error or information representation regarding the current request.
    {
    • "causes":
      array
      An array of FeedbackCauseRO_v1 objects. A collection of errors/infos that caused this feedback.
      [
      FeedbackCauseRO_v1: A representation for the common feedback informations.
      {
      • "code":
        string
        Required | An unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: invoiceToAddress.address.postalcode.invalid
      • "message":
        string
        Required | A human readable message in request's locale (server falls back to lead locale if requested local is not supported). | Example: The specified postal code is invalid. Valid values are numbers 10000 to 99999.
      • "parameters":
        object
        A map of several parameters that are used to assemble the message.
      • "paths":
        array
        An array of string literals. A collection of JSON paths to the associated entities. If not otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath
      }
      ]
    • "code":
      string
      An unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: invoiceToAddress.address.postalcode.invalid
    • "message":
      string
      A human readable message in request's locale (server falls back to lead locale if requested local is not supported). | Example: The specified postal code is invalid. Valid values are numbers 10000 to 99999.
    • "parameters":
      object
      A map of several parameters that are used to assemble the message.
    • "paths":
      array
      An array of string literals. A collection of JSON paths to the associated entities. If not otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath
    • "status":
      string
      The HTTP status code, that is applicable to this problem. | Example: 400
    }
    ]
  • "links":
    object
    Readonly | Map of links to this and the optionally included related data objects. The object in the "data" property is always referenced by identifier "self". Note that this identifier may also contain a list of URIs, if the data block contains multiple elements.
}
FeedbackRO_v1 application/json{
  • "causes":
    array
    An array of FeedbackCauseRO_v1 objects. A collection of errors/infos that caused this feedback.
    [
    FeedbackCauseRO_v1: A representation for the common feedback informations.
    {
    • "code":
      string
      Required | An unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: invoiceToAddress.address.postalcode.invalid
    • "message":
      string
      Required | A human readable message in request's locale (server falls back to lead locale if requested local is not supported). | Example: The specified postal code is invalid. Valid values are numbers 10000 to 99999.
    • "parameters":
      object
      A map of several parameters that are used to assemble the message.
    • "paths":
      array
      An array of string literals. A collection of JSON paths to the associated entities. If not otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath
    }
    ]
  • "code":
    string
    An unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: invoiceToAddress.address.postalcode.invalid
  • "message":
    string
    A human readable message in request's locale (server falls back to lead locale if requested local is not supported). | Example: The specified postal code is invalid. Valid values are numbers 10000 to 99999.
  • "parameters":
    object
    A map of several parameters that are used to assemble the message.
  • "paths":
    array
    An array of string literals. A collection of JSON paths to the associated entities. If not otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath
  • "status":
    string
    The HTTP status code, that is applicable to this problem. | Example: 400
}
UserBudgetsRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: UserBudgets
  • "orderSpentLimit":
    object
    A MoneyRO_v1 object. Describes a money object.
    {
    • "currency":
      string
      Readonly | Three-letter currency code (ISO 4217) of the monetary value. | Example: USD
    • "value":
      number
      Readonly | The monetary value. | Example: 10.99
    }
  • "remainingBudget":
    object
    A MoneyRO_v1 object. Describes a money object.
    {
    • "currency":
      string
      Readonly | Three-letter currency code (ISO 4217) of the monetary value. | Example: USD
    • "value":
      number
      Readonly | The monetary value. | Example: 10.99
    }
  • "spentBudget":
    object
    A MoneyRO_v1 object. Describes a money object.
    {
    • "currency":
      string
      Readonly | Three-letter currency code (ISO 4217) of the monetary value. | Example: USD
    • "value":
      number
      Readonly | The monetary value. | Example: 10.99
    }
  • "budget":
    object
    A MoneyRO_v1 object. Describes a money object.
    {
    • "currency":
      string
      Readonly | Three-letter currency code (ISO 4217) of the monetary value. | Example: USD
    • "value":
      number
      Readonly | The monetary value. | Example: 10.99
    }
  • "budgetPeriod":
    string
    The user budget period. | Example: monthly
}
UserRolesInputRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: UserRoles
  • "userRoles":
    array
    An array of string literals. The assigned user roles. | Example: APP_B2B_APPROVER, APP_B2B_ACCOUNT_OWNER
}
UserRolesRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: UserRoles
  • "userRoles":
    array
    An array of UserRoleRO objects. The assigned user roles.
    [
    UserRoleRO: The assigned user roles.
    {
    • "name":
      string
      The name of an element.
    • "type":
      string
      The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: UserRole
    • "roleID":
      string
      The id of the role | Example: APP_B2B_APPROVER
    • "roleDisplayName":
      string
      The localized name of the role | Example: Approver
    • "roleDescription":
      string
      The localized description of the role | Example: The approver is responsible for the order approval...
    • "fixed":
      boolean
      Flag that indicates if the role fixed (implicitly assigned) and cannot be deselected | Example: true
    • "permissions":
      array
      An array of RolePermissionRO objects. The list of permissions assigned to the role containing id and localized display name
      [
      RolePermissionRO: The list of permissions assigned to the role containing id and localized display name
      {
      • "name":
        string
        The name of an element.
      • "type":
        string
        The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: RolePermission
      • "permissionID":
        string
        The id of the permission | Example: APP_B2B_ASSIGN_COSTOBJECT_TO_BASKET
      • "permissionDisplayName":
        string
        The localized name of the permission | Example: Assign a cost object to a basket
      }
      ]
    }
    ]
}

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets