Document Properties
KbidA29773
Last Modified23-Feb-2021
Added to KB26-Jan-2021
Public AccessEveryone
StatusOnline
Doc TypeReferences
ProductICM 7.10

Reference - Punchout API 1.1.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
Punchout Version: 1.0.0

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.

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

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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp
in pathPunchoutKeystringRequired | The type of the Punchout | Example: oci

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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp
in pathPunchoutKeystringRequired | The type of the Punchout | Example: oci

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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp

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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp
in pathPunchoutKeystringRequired | The type of the Punchout | Example: oci
in querybasketIdstringReturns the basket line item data according to Punchout configuration
in querysearchTermstringReturns data of products that match the search term | Example: Sony

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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp
in pathPunchoutKeystringRequired | The type of the Punchout | Example: oci

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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp
in pathPunchoutKeystringRequired | The type of the Punchout | Example: oci

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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp
in pathPunchoutKeystringRequired | The type of the Punchout | Example: oci

Response

201 - Created

- The Punchout user were 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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp
in pathPunchoutKeystringRequired | The type of the Punchout | Example: oci
in pathPunchoutUserKeystringRequired | The ID of the Punchout user | Example: ociuser@test.intershop.de

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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp
in pathPunchoutKeystringRequired | The type of the Punchout | Example: oci
in pathPunchoutUserKeystringRequired | The ID of the Punchout user | Example: ociuser@test.intershop.de

Response

200 - OK

- The Punchout user data were 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 Punchout specific 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

LocationNameFormatDescription
in pathCustomerKeystringRequired | The customer ID | Example: OilCorp
in pathPunchoutKeystringRequired | The type of the Punchout | Example: oci
in pathPunchoutUserKeystringRequired | The ID of the Punchout user | Example: ociuser@test.intershop.de

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 object. This is normally a constant that can be used to differentiate objects 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 object. This is normally a constant that can be used to differentiate objects 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 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 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: This resource holds 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.
  • "items":
    array
    An array of PunchoutConfigurationItemRO objects. The configuration items as collection of PunchoutConfigurationItemROs
    [
    PunchoutConfigurationItemRO: This resource holds 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.
    • "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 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.
  • "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 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: This resource holds the Punchout data as a 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 a collection of PunchoutDataItemFieldROs
        [
        PunchoutDataItemFieldRO:
        {
        • "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: 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 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 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 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 a collection of PunchoutDataItemFieldROs
        [
        PunchoutDataItemFieldRO:
        {
        • "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: 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 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
    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.

Customer Support
Knowledge Base
Product Resources
Tickets