Personal Library

Kbid	E29601
Last Modified	23-Mar-2021
Added to KB	03-Sep-2020
Public Access	Everyone
Status	Online
Doc Type	References
Product	ICM 7.10

Reference - Punchout API 1.0.0

https://support.intershop.com/kb/E29601

Share this document

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:

icm-b2b-punchout-1x0x0.yaml

References

Reference - ICM 7.10 - REST API Version Matrix

API Specification

Introduction

OpenAPI Version: 3.0.1

Punchout Version: 1.0.0

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.

Punchout API

/customers/{CustomerKey}/punchouts

GET: Returns all supported Punchout standards

Description

The Returned Resource Collection contains objets of type LinkRO

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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

200 - OK

Object application/json

401 - Unauthorized

403 - Forbidden

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

GET: Returns details for the selected Punchout standard

Description

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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in query	basketId	string
in query	searchTerm	string

Response

200 - OK

PunchoutItemRO application/json

401 - Unauthorized

403 - Forbidden

OPTIONS: shows all available configuration options for the selected Punchout standard

Description

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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

200 - OK

PunchoutConfigurationOptionsRO application/json

401 - Unauthorized

403 - Forbidden

Punchout Configuration API

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

GET: Returns the Punchout related customer specific configurations

Description

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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

200 - OK

PunchoutConfigurationRO application/json

401 - Unauthorized

403 - Forbidden

PUT: Update the existing Punchout configuration

Description

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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

200 - OK

PunchoutConfigurationRO application/json

401 - Unauthorized

403 - Forbidden

Punchout User API

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

GET: Get punchout users

Description

response ResourceCollectionRO 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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

200 - OK

Object application/json

401 - Unauthorized

403 - Forbidden

404 - Not Found

POST: Create a Punchout user

Description

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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

201 - Created

LinkRO application/json

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

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

Description

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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutUserKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

200 - OK

PunchoutUserRO application/json

401 - Unauthorized

403 - Forbidden

404 - Not Found

PUT: Update Punchout user data

Description

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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutUserKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

200 - OK

PunchoutUserRO application/json

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

DELETE: Delete a Punchout specific user of a customer

Description

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	Description
in path	CustomerKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`
in path	PunchoutUserKey	string	Required \| The key or UUID to resolve a single item \| Example: `ExampleKey`

Response

204 - No Content

401 - Unauthorized

403 - Forbidden

404 - Not 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.
}

}

PunchoutConfigurationOptionsRO 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: PunchoutConfigurationOptions
"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 Collection of PunchoutAvailableFormatterROs
[
PunchoutAvailableFormatterRO: The available formatters for the Configuration as Collection of PunchoutAvailableFormatterROs
{
- "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: PunchoutAvailableFormatter
- "id":
  string
  The id of the formatter | Example: Trim
}
]
"availablePlaceholders":
array
An array of PunchoutAvailablePlaceholderRO objects. The available placeholders for the Configuration as Collection of PunchoutAvailablePlaceholderROs
[
PunchoutAvailablePlaceholderRO: The available placeholders for the Configuration as Collection of PunchoutAvailablePlaceholderROs
{
- "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: 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 object. This is normally a constant that can be used to differentiate objects by their type. | Example: PunchoutConfiguration
"items":
array
An array of PunchoutConfigurationItemRO objects. The configuration Items as Collection of PunchoutConfigurationItemROs
[
PunchoutConfigurationItemRO: The configuration Items as Collection of PunchoutConfigurationItemROs
{
- "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: PunchoutConfigurationItem
- "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: The configuration Item Mappings as Collection of PunchoutConfigurationItemMappingROs
  {
  "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: 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 object. This is normally a constant that can be used to differentiate objects by their type. | Example: PunchoutItem
"punchoutType":
string
Required | The punchout type | Example: oci
"version":
string
Required | The punchout version | Example: ver5
"punchoutData":
object
A PunchoutDataRO object. The Punchout Data as PunchoutDataRO
{
- "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: PunchoutData
- "punchoutDataItems":
  array
  An array of PunchoutDataItemRO objects.
  [
  PunchoutDataItemRO: The Punchout Data as Collection of PunchoutDataItemROs
  {
  "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: PunchoutDataItem
  "dataItemFields":
  array
  An array of PunchoutDataItemFieldRO objects. The Data Item Fields as Collection of PunchoutDataItemFieldROs
  [
  PunchoutDataItemFieldRO:
  {
  "name":
  string
  The name of an element. | Example: NEW_ITEM-PRICE
  "type":
  string
  The type of the object. This is normally a constant that can be used to differentiate objects 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. | Example: NEW_ITEM-PRICE
  "type":
  string
  The type of the object. This is normally a constant that can be used to differentiate objects 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 Collection of PunchoutDataItemROs
  [
  PunchoutDataItemRO: The Punchout Data as Collection of PunchoutDataItemROs
  {
  "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: PunchoutDataItem
  "dataItemFields":
  array
  An array of PunchoutDataItemFieldRO objects. The Data Item Fields as Collection of PunchoutDataItemFieldROs
  [
  PunchoutDataItemFieldRO:
  {
  "name":
  string
  The name of an element. | Example: NEW_ITEM-PRICE
  "type":
  string
  The type of the object. This is normally a constant that can be used to differentiate objects 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. | Example: NEW_ITEM-PRICE
  "type":
  string
  The type of the object. This is normally a constant that can be used to differentiate objects 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 object. This is normally a constant that can be used to differentiate objects by their type. | Example: PunchoutUser
"id":
string
The id of the user | Example: oci1
"login":
string
The login of the user | Example: ociuser1
"email":
string
The mail of the user | Example: ocitester@test.intershop.de
"password":
string
The password of the user | Example: !InterShop00!
"active":
boolean
Is the user active? | Example: true

}

Object application/json

{

"links":
array
An array of object literals.
[
{
- "uri":
  string
  Format: uri
- "title":
  string
- "uriBuilder":
  object
- "rel":
  string
- "rels":
  array
  An array of string literals.
- "params":
  object
- "type":
  string
}
]
"statusInfo":
object
{
- "reasonPhrase":
  string
- "statusCode":
  integer
  Format: int32
- "family":
  string
  Possible Values: INFORMATIONALSUCCESSFULREDIRECTIONCLIENT_ERRORSERVER_ERROROTHER
}
"allowedMethods":
array
An array of string literals.
"stringHeaders":
object
{
- "empty":
  boolean
}
"mediaType":
object
{
- "type":
  string
- "subtype":
  string
- "parameters":
  object
- "wildcardType":
  boolean
- "wildcardSubtype":
  boolean
}
"entityTag":
object
{
- "value":
  string
- "weak":
  boolean
}
"metadata":
object
{
- "empty":
  boolean
}
"entity":
object
"lastModified":
string
Format: date-time
"date":
string
Format: date-time
"headers":
object
{
- "empty":
  boolean
}
"cookies":
object
"status":
integer
Format: int32
"length":
integer
Format: int32
"language":
object
{
- "language":
  string
- "script":
  string
- "country":
  string
- "variant":
  string
- "extensionKeys":
  array
  An array of string literals.
- "unicodeLocaleAttributes":
  array
  An array of string literals.
- "unicodeLocaleKeys":
  array
  An array of string literals.
- "iso3Language":
  string
- "iso3Country":
  string
- "displayLanguage":
  string
- "displayScript":
  string
- "displayCountry":
  string
- "displayVariant":
  string
- "displayName":
  string
}
"location":
string
Format: uri

}

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.