Reference - Punchout REST API 1.0.0

Document View

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

icm-b2b-punchout-1x0x0.yaml

References

The following page lists available REST APIs for ICM 7.10 and their version dependencies:

Reference - Intershop Commerce Management 7.10 REST API

API Specification

Introduction

OpenAPI Version: 3.0.1

Punchout Version: 1.0.0

This version is deprecated. Please use the newer version which covers all supported operations from this version and also additional functionality.

The Intershop Punchout REST API contains resources for managing supported Punchout standards, Punchout configurations and Punchout users.
This includes updating configurations, creating, changing or deleting users or user data as well as retrieving information on available standards and options.

Configuration API

This section covers operations for managing Punchout configurations. This includes retrieving customer-specific configurations as well as updating an existing configuration.

/customers/{CustomerKey}/punchouts/{PunchoutKey}/configurations

GET: Returns customer-specific Punchout configurations Deprecated.

Description

This operation returns the customer-specific configuration for the selected Punchout standard. The authenticated user must have the permission APP_B2B_MANAGE_PUNCHOUT.

Java Method

public javax.ws.rs.core.Response com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutConfigurationListResource.getPunchoutConfiguration()

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	CustomerKey	string		`OilCorp`	Required \| The customer ID
in path	PunchoutKey	string		`oci`	Required \| The type of the Punchout

Response

200 - OK - The customer-specific configurations for the Punchout standard were successfully retrieved.

PunchoutConfigurationRO application/json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer or Punchout with the given ID could not be found.

PUT: Update the existing Punchout configuration Deprecated.

Description

This operation updates existing Punchout configurations. The configuration can be updated entirely or partially. The fields that are not provided remain untouched, e.g.: NEW_ITEM-CONTRACT. The authenticated user requires the permission APP_B2B_MANAGE_PUNCHOUT.

Java Method

public javax.ws.rs.core.Response com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutConfigurationListResource.updatePunchoutConfiguration(com.intershop.application.storefront.rest.b2b.capi.punchout.resourceobject.PunchoutConfigurationRO)

Request Body

PunchoutConfigurationRO application/json

Request Parameters

Location	Name	Format	Default	Example	Description
in path	CustomerKey	string		`OilCorp`	Required \| The customer ID
in path	PunchoutKey	string		`oci`	Required \| The type of the Punchout

Response

200 - OK - The customer-specific configurations for the Punchout standard were successfully updated.

PunchoutConfigurationRO application/json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer or Punchout with the given ID could not be found.

General API

This section covers operations for managing Punchout standards. This includes retrieving a list of available standards, details for a specific standard or available options for a chosen standard.

/customers/{CustomerKey}/punchouts

GET: Returns supported Punchout standards Deprecated.

Description

This operation returns details on supported Punchout standards. Punchout standards are defined in the punchoutconfiguration.properties. The authenticated user requires the permission APP_B2B_VIEW_PUNCHOUT or APP_B2B_SEND_OCI_BASKET. The returned resource collection contains objects of type LinkRO with all available Punchout standards.

Java Method

public javax.ws.rs.core.Response com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutListResource.getAvailablePunchouts()

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	CustomerKey	string		`OilCorp`	Required \| The customer ID

Response

200 - OK - The punchout standards were successfully retrieved.

LinkROResourceCollectionRO application/json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer with the given ID could not be found.

/customers/{CustomerKey}/punchouts/{PunchoutKey}

GET: Returns details for the selected Punchout standard Deprecated.

Description

This operation returns details of the selected Punchout standard. The authenticated user requires the permission APP_B2B_VIEW_PUNCHOUT or APP_B2B_SEND_OCI_BASKET. Either basketId or searchTerm is allowed.

Java Method

public javax.ws.rs.core.Response com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutItemResource.getPunchoutItemDetails(java.lang.String,java.lang.String)

Request Body

Request Parameters

Location	Name	Format	Example	Description
in path	CustomerKey	string	`OilCorp`	Required \| The customer ID
in path	PunchoutKey	string	`oci`	Required \| The type of the Punchout
in query	basketId	string		Returns the basket line item data according to Punchout configuration
in query	searchTerm	string	`Sony`	Returns data of products that match the search term

Response

200 - OK - The details for the Punchout standard were successfully retrieved.

PunchoutItemRO application/json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer or Punchout with the given ID could not be found.

OPTIONS: Shows configuration options for the selected Punchout standard Deprecated.

Description

This operation returns all available configuration options for the selected Punchout standard. The authenticated user requires the permission APP_B2B_VIEW_PUNCHOUT or the permission APP_B2B_SEND_OCI_BASKET.

Java Method

public javax.ws.rs.core.Response com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutItemResource.getPunchoutConfigurationOptions()

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	CustomerKey	string		`OilCorp`	Required \| The customer ID
in path	PunchoutKey	string		`oci`	Required \| The type of the Punchout

Response

200 - OK - The configuration options for the Punchout standard were successfully retrieved.

PunchoutConfigurationOptionsRO application/json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer or Punchout with the given ID could not be found.

User Management API

This section covers operations for managing Punchout users. This includes retrieving information on users, creating a new user, updating user data as well as deleting specific users.

/customers/{CustomerKey}/punchouts/{PunchoutKey}/users

GET: Get Punchout users Deprecated.

Description

This operation returns all users for the selected Punchout standard. The authenticated user requires the permission APP_B2B_MANAGE_PUNCHOUT. The response is of type ResourceCollectionRO and contains objects of type LinkRO.

Java Method

public javax.ws.rs.core.Response com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutUserListResource.getPunchoutUsers()

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	CustomerKey	string		`OilCorp`	Required \| The customer ID
in path	PunchoutKey	string		`oci`	Required \| The type of the Punchout

Response

200 - OK - The Punchout users were successfully retrieved.

LinkROResourceCollectionRO application/json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer or punchout with the given ID could not be found.

POST: Create a Punchout user Deprecated.

Description

This operation creates a new Punchout user. The ID property of PunchoutUser will be created automatically. The authenticated user must have the permission APP_B2B_MANAGE_PUNCHOUT.

Java Method

public javax.ws.rs.core.Response com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutUserListResource.createPunchoutUser(com.intershop.application.storefront.rest.b2b.capi.punchout.resourceobject.PunchoutUserRO)

Request Body

PunchoutUserRO application/json

Request Parameters

Location	Name	Format	Default	Example	Description
in path	CustomerKey	string		`OilCorp`	Required \| The customer ID
in path	PunchoutKey	string		`oci`	Required \| The type of the Punchout

Response

201 - Created - The Punchout user was successfully created.

LinkRO application/json

400 - Bad Request - At least one attribute is missing in the request body or the credentials are not valid regarding internal policies.

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer or Punchout with the given ID could not be found.

409 - Conflict - The Punchout user already exists.
Possible values for header 'error-key':
- punchout.login_already_exists.error

/customers/{CustomerKey}/punchouts/{PunchoutKey}/users/{PunchoutUserKey}

GET: Returns information on the given Punchout user Deprecated.

Description

This operation returns information on the given Punchout user. The authenticated user requires the permissionAPP_B2B_MANAGE_PUNCHOUT.

Java Method

public com.intershop.application.storefront.rest.b2b.capi.punchout.resourceobject.PunchoutUserRO com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutUserItemResource.getUserDetails()

Request Body

Request Parameters

Location	Name	Format	Example	Description
in path	CustomerKey	string	`OilCorp`	Required \| The customer ID
in path	PunchoutKey	string	`oci`	Required \| The type of the Punchout
in path	PunchoutUserKey	string	`ociuser@test.intershop.de`	Required \| The ID of the Punchout user

Response

200 - OK - The details for the Punchout user were successfully retrieved.

PunchoutUserRO application/json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer, Punchout or Punchout user with the given ID could not be found.

PUT: Updates Punchout user data Deprecated.

Description

This operation updates the information of a Punchout user. The authenticated user requires the permission APP_B2B_MANAGE_PUNCHOUT.

The following user attributes can be updated:

email - notifications for the Punchout user are send to this email address
password - the configured password for the Punchout user
active - flag to enable/disable the Punchout user

All attributes are optional, see request code examples below.

Java Method

public com.intershop.application.storefront.rest.b2b.capi.punchout.resourceobject.PunchoutUserRO com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutUserItemResource.updatePunchoutUser(com.intershop.application.storefront.rest.b2b.capi.punchout.resourceobject.PunchoutUserRO)

Request Body

PunchoutUserRO application/json

Request Parameters

Location	Name	Format	Example	Description
in path	CustomerKey	string	`OilCorp`	Required \| The customer ID
in path	PunchoutKey	string	`oci`	Required \| The type of the Punchout
in path	PunchoutUserKey	string	`ociuser@test.intershop.de`	Required \| The ID of the Punchout user

Response

200 - OK - The Punchout user data was successfully updated.

PunchoutUserRO application/json

400 - Bad Request - If the credentials to update are not valid regarding internal policies.

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer, Punchout or Punchout user with the given ID could not be found.

DELETE: Deletes a specific Punchout user of a customer Deprecated.

Description

This operation deletes a Punchout-specific user of a customer. The executing user must be authenticated and requires the permission APP_B2B_MANAGE_PUNCHOUT.

Java Method

public javax.ws.rs.core.Response com.intershop.application.storefront.rest.b2b.capi.punchout.resource.PunchoutUserItemResource.deletePunchoutUser()

Request Body

Request Parameters

Location	Name	Format	Example	Description
in path	CustomerKey	string	`OilCorp`	Required \| The customer ID
in path	PunchoutKey	string	`oci`	Required \| The type of the Punchout
in path	PunchoutUserKey	string	`ociuser@test.intershop.de`	Required \| The ID of the Punchout user

Response

204 - No Content - The Punchout user was successfully deleted.

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user does not have the required permissions.

404 - Not Found - The customer, Punchout or Punchout user with the given ID could not be found.

Request and Response Object Schemata

LinkRO application/json

{

"name":
string
The name of the returned element
"type":
string
Readonly | This is a constant: Link | Example: Link
"attributes":
array
An array of ResourceAttribute objects. The list of attributes
[
ResourceAttribute: An attribute
{
- "name":
  string
  The attribute's name
- "type":
  string
  This is a constant: ResourceAttribute | Example: ResourceAttribute
- "value":
  object
  The attribute's value.
}
]
"uri":
string
The URI
"relation":
string
The relation of the link | Documentation: Link Relations (www.iana.org) | Possible Values: aboutalternateappendixarchivesauthorbookmarkcanonicalchaptercollectioncontentscopyrightcreate-formcurrentdescribedbydescribesdisclosureduplicateeditedit-formedit-mediaenclosurefirstglossaryhelphostshubiconindexitemlastlatest-versionlicenselrddmonitormonitor-groupnextnext-archivenofollownoreferrerpaymentpredecessor-versionprefetchprevpreviewpreviousprev-archiveprivacy-policyprofilerelatedrepliessearchsectionselfservicestartstylesheetsubsectionsuccessor-versiontagterms-of-servicetypeupversion-historyviaworking-copyworking-copy-of
"title":
string
The title of the link
"description":
string
The description of the link
"itemId":
string
The ID of the linked item
"attribute":
object
A ResourceAttribute object. An attribute
{
- "name":
  string
  The attribute's name
- "type":
  string
  This is a constant: ResourceAttribute | Example: ResourceAttribute
- "value":
  object
  The attribute's value.
}

}

LinkROResourceCollectionRO application/json

{

"pageable":
string
The pageable ID
"total":
integer
The pageable amount total | Format: int32
"offset":
integer
The pageable offset | Format: int32
"amount":
integer
The pageable amount | Format: int32
"elements":
array
An array of LinkRO objects. The list of elements
[
LinkRO: A Link pointing to a resource
{
- "name":
  string
  The name of the returned element
- "type":
  string
  Readonly | This is a constant: Link | Example: Link
- "attributes":
  array
  An array of ResourceAttribute objects. The list of attributes
  [
  ResourceAttribute: An attribute
  {
  "name":
  string
  The attribute's name
  "type":
  string
  This is a constant: ResourceAttribute | Example: ResourceAttribute
  "value":
  object
  The attribute's value.
  }
  ]
- "uri":
  string
  The URI
- "relation":
  string
  The relation of the link | Documentation: Link Relations (www.iana.org) | Possible Values: aboutalternateappendixarchivesauthorbookmarkcanonicalchaptercollectioncontentscopyrightcreate-formcurrentdescribedbydescribesdisclosureduplicateeditedit-formedit-mediaenclosurefirstglossaryhelphostshubiconindexitemlastlatest-versionlicenselrddmonitormonitor-groupnextnext-archivenofollownoreferrerpaymentpredecessor-versionprefetchprevpreviewpreviousprev-archiveprivacy-policyprofilerelatedrepliessearchsectionselfservicestartstylesheetsubsectionsuccessor-versiontagterms-of-servicetypeupversion-historyviaworking-copyworking-copy-of
- "title":
  string
  The title of the link
- "description":
  string
  The description of the link
- "itemId":
  string
  The ID of the linked item
- "attribute":
  object
  A ResourceAttribute object. An attribute
  {
  "name":
  string
  The attribute's name
  "type":
  string
  This is a constant: ResourceAttribute | Example: ResourceAttribute
  "value":
  object
  The attribute's value.
  }
}
]
"type":
string
The type of the element. This is normally a constant that can be used to differentiate elements by their type.
"sortKeys":
array
An array of string literals. The keys to sort for
"name":
string
The name of an element

}

PunchoutConfigurationOptionsRO application/json

{

"name":
string
The name of an element
"type":
string
The type of the element. This is normally a constant that can be used to differentiate elements by their type.
"description":
string
The description of the configuration | Example: Show available configurations for OCI Punchout
"availableFormatters":
array
An array of PunchoutAvailableFormatterRO objects. The available formatters for the configuration as a collection of PunchoutAvailableFormatterROs
[
PunchoutAvailableFormatterRO: This resource holds the available formatters for the configuration as a collection of PunchoutAvailableFormatterROs.
{
- "name":
  string
  The name of an element
- "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutAvailableFormatter
- "id":
  string
  The ID of the formatter | Example: Trim
}
]
"availablePlaceholders":
array
An array of PunchoutAvailablePlaceholderRO objects. The available placeholders for the configuration as a collection of PunchoutAvailablePlaceholderROs
[
PunchoutAvailablePlaceholderRO: This resource holds the available placeholders for the configuration as a collection of PunchoutAvailablePlaceholderROs.
{
- "name":
  string
  The name of an element
- "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutAvailablePlaceholder
- "id":
  string
  The ID of the placeholder | Example: Currency
}
]

}

PunchoutConfigurationRO application/json

{

"name":
string
The name of an element
"type":
string
The type of the element. This is normally a constant that can be used to differentiate elements by their type.
"items":
array
An array of PunchoutConfigurationItemRO objects. The configuration items as a collection of PunchoutConfigurationItemROs
[
PunchoutConfigurationItemRO: This resource holds the configuration items as a collection of PunchoutConfigurationItemROs.
{
- "name":
  string
  The name of an element
- "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type.
- "field":
  string
  The field of the configuration item | Example: NEW_ITEM-MATGROUP
- "transform":
  string
  The transform of the configuration Item | Example: {ManufacturerName}
- "formatter":
  string
  The formatter for the configuration item | Example: UpperCase
- "mappings":
  array
  An array of PunchoutConfigurationItemMappingRO objects. The configuration item mappings as collection of PunchoutConfigurationItemMappingROs
  [
  PunchoutConfigurationItemMappingRO: This resource holds the configuration item mappings as a collection of PunchoutConfigurationItemMappingROs.
  {
  "name":
  string
  The name of an element
  "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutConfigurationItemMapping
  "mapFromValue":
  string
  The 'from' value for the configuration of the item mapping | Example: meter
  "mapToValue":
  string
  The 'to' value for the configuration of the item mapping | Example: m
  }
  ]
}
]

}

PunchoutItemRO application/json

{

"name":
string
The name of an element
"type":
string
The type of the element. This is normally a constant that can be used to differentiate elements by their type.
"punchoutType":
string
Required | The Punchout type | Example: oci
"version":
string
Required | The Punchout version | Example: ver5
"punchoutData":
object
A PunchoutDataRO object. This resource holds the Punchout data as PunchoutDataRO.
{
- "name":
  string
  The name of an element
- "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutData
- "punchoutDataItems":
  array
  An array of PunchoutDataItemRO objects.
  [
  PunchoutDataItemRO: This resource holds the Punchout data as a collection of PunchoutDataItemROs.
  {
  "name":
  string
  The name of an element
  "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutDataItem
  "dataItemFields":
  array
  An array of PunchoutDataItemFieldRO objects. The data item fields as a collection of PunchoutDataItemFieldROs
  [
  PunchoutDataItemFieldRO
  {
  "name":
  string
  The name of an element
  "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutDataItemField
  "value":
  string
  The value of the Data Item Field | Example: 0.0
  }
  ]
  "punchoutDataItemFields":
  array
  An array of PunchoutDataItemFieldRO objects.
  [
  PunchoutDataItemFieldRO
  {
  "name":
  string
  The name of an element
  "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutDataItemField
  "value":
  string
  The value of the Data Item Field | Example: 0.0
  }
  ]
  }
  ]
- "dataItems":
  array
  An array of PunchoutDataItemRO objects. The Punchout data as a collection of PunchoutDataItemROs
  [
  PunchoutDataItemRO: This resource holds the Punchout data as a collection of PunchoutDataItemROs.
  {
  "name":
  string
  The name of an element
  "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutDataItem
  "dataItemFields":
  array
  An array of PunchoutDataItemFieldRO objects. The data item fields as a collection of PunchoutDataItemFieldROs
  [
  PunchoutDataItemFieldRO
  {
  "name":
  string
  The name of an element
  "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutDataItemField
  "value":
  string
  The value of the Data Item Field | Example: 0.0
  }
  ]
  "punchoutDataItemFields":
  array
  An array of PunchoutDataItemFieldRO objects.
  [
  PunchoutDataItemFieldRO
  {
  "name":
  string
  The name of an element
  "type":
  string
  The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutDataItemField
  "value":
  string
  The value of the Data Item Field | Example: 0.0
  }
  ]
  }
  ]
}

}

PunchoutUserRO application/json

{

"name":
string
The name of an element
"type":
string
The type of the element. This is normally a constant that can be used to differentiate elements by their type. | Example: PunchoutUser
"id":
string
Readonly | The ID of the user | Example: oci1
"login":
string
The login of the user | Example: ociuser1
"email":
string
The e-mail adress of the user | Example: ocitester@test.intershop.de
"password":
string
The password of the user | Example: !InterShop00!
"active":
boolean
Indicates whether the user is active | Example: true

}

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.