> For the complete documentation index, see [llms.txt](https://docs.eu-pactum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eu-pactum.com/procurement-product/integration/configuring-ariba-integration-for-requisitions.md).

# Ariba integration

## Introduction

This document serves as a technical overview of SAP Ariba Buying for integration with Pactum’s Autonomous Negotiation platform for the negotiation of Purchase Orders with suppliers.

Setting up the integration is guided in the Pactum platform under **Settings → Ariba Integration**. The platform walks you through each step and gives you the exact values to enter in Ariba.

## Prerequisites

Integration between SAP Ariba Buying and Pactum’s Autonomous Negotiation platform has a specific set of minimal requirements to work. These requirements will be covered in more depth in the following pages.

* Ariba location information:
  * Datacenter
  * Realm name
* User and groups for Pactum capabilities in Ariba
* Approval workflow which assigns Pactum as approver
* Exporting of Payment Terms that will be sent to Pactum
* Credentials for Document Approval API and Master Data Retrieval API for Procurement:
  * Application Key
  * OAuth Client Id
  * OAuth Client Secret
* Import Requisition(s) web service configured with basic auth:
  * Web service URL
  * Username
  * Password

## Integration overview

### Importing requisitions

Pactum regularly monitors requisitions assigned to the Pactum approver in the Ariba approval workflow. When a new requisition is assigned, Pactum gathers the required data using both REST APIs and screen scraping. If the data is valid and the requisition is eligible for negotiation, a new negotiation event is created, and negotiation links are sent to suppliers. Otherwise, the requisition is approved immediately, bypassing the negotiation process.

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-5012809725259e3b475f7a1e7d8b01c0244ecd67%2FPactum%20Ariba%20Integration%20-%20Import.svg?alt=media" alt=""><figcaption><p>Figure 1. Import process</p></figcaption></figure>

#### Mandatory data

There is a set of mandatory values which are necessary to initiate a negotiation. Requisition data will be validated against these requirements when Pactum platform retrieves the data from Ariba API.

Mandatory data:

* Requisition:
  * PR number
  * Delivery location
  * Expected delivery date
  * Line item:
    * Name
    * Type
    * Description
    * Quantity
    * Unit of measure
    * Unit price
* Supplier:
  * Name
  * Email

#### Requirements for negotiability

A requisition may not be negotiable for the following reasons:

| Configuration parameter        | Reason for not negotiating                                           |
| ------------------------------ | -------------------------------------------------------------------- |
| Attachments extraction options | Requisition has already been invoiced                                |
| Supplier ignore list           | Supplier is on the ignore list                                       |
| Contract detector filter       | An annual contract was detected based on the line item description   |
| Supplier frequency filter      | Supplier has already received `X` negotiations in the past `Y` hours |
| Spend range filter             | Total amount falls outside the specified spend range                 |
| Payment term options           | Payment term with given ID is not configured                         |
| Payment term filters           | Payment terms are not listed for the given purchasing unit           |
| Negotiation deadline           | Need-by date cannot be closer than `X` business days                 |
| Allow multiple suppliers       | Multiple suppliers not supported                                     |
| -                              | Multiple currencies not supported                                    |
| -                              | Number of line items must be <= 40                                   |
| -                              | The price unit quantity for a line item cannot be more than 1        |
| -                              | Invalid delivery address (must contain at least street or city)      |

### Concluding negotiations

Before the negotiation results can be sent back to Ariba, the negotiation process with the suppliers must be completed. The negotiation process itself is not specific to the Ariba integration, and therefore, is not covered in detail here. What is presented in this document is a high-level state diagram, focusing on the handling of quote uploads.

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-dfd319be078942c5d655209bf7ed42a754c7e32c%2FPactum%20Ariba%20Integration%20-%20Negotiate.svg?alt=media" alt=""><figcaption><p>Figure 2a. Negotiation process</p></figcaption></figure>

Depending on the workspace configuration, quote uploads may be either optional or mandatory. It is important to note that if quote uploads are optional, the supplier is given 60 minutes to upload the updated quote. If the supplier either uploads the quote or skips the upload, the negotiation is considered concluded at that point. However, if the supplier leaves the chat without taking any action, the negotiation will be concluded after a 60-minute timeout.

### Updating requisitions with results

Once the negotiations are concluded, Pactum updates the following details in Ariba for each line item:

* Unit prices
* Payment terms

Since the update via [RequisitionImportPull](#updating-requisition-data) has a side effect of restarting the approvable workflow, Pactum must first wait until it becomes the first approver in the list again. Only then can Pactum proceed with uploading any optionally provided updated quotes and approve the requisition, adding a comment to indicate that the requisition has been updated.

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-5413fbdf4f17e797bf1332726911f04e6bed6443%2FPactum%20Ariba%20Integration%20-%20Update.svg?alt=media" alt=""><figcaption><p>Figure 2b. Update process</p></figcaption></figure>

### Requisition withdrawals

Pactum regularly verifies during the negotiation process whether the requisition is still assigned to the Pactum approver. If it is no longer assigned, the negotiations are withdrawn, and a relevant comment is added to the Ariba requisition.

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-438b6686e89f658de5bc761b4357677cafbe60ab%2FPactum%20Ariba%20Integration%20-%20Withdraw.svg?alt=media" alt=""><figcaption><p>Figure 3. Withdrawal process</p></figcaption></figure>

## Configuration

Most of the configuration is done in the Pactum platform under **Settings → Ariba Integration**. Add your Ariba realm there and the platform guides you through creating the Pactum user, adding Pactum to your approval flow, configuring the Import Requisition(s) web service, and entering the API credentials. It also gives you the exact values to enter in Ariba.

### Approval workflow

Approval workflow used for purchase requisitions that need to be negotiated needs to include a step where the requisitions end up in approval step where approver is a group for the Pactum capability.

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-9ef9056a5c20e495e0b48920c69f7d7a3d6fc01f%2Fariba-approval-workflow.png?alt=media" alt=""><figcaption><p>Figure 4. Example approval workflow diagram with negotiation step</p></figcaption></figure>

Updating requisition data causes it to go back to the start of approval workflow. Therefore, the approval workflow needs to be configured in a way that it again reaches the point where Pactum is the approver. The self-service under **Settings → Ariba Integration** guides through the process of adding rules to the approval process so that Pactum’s updates do not reset the approval flow.

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-2e4ad8b8dcff30cb0bba0f08a0094634abe2f0c0%2Fariba-approvable-edit-rule.png?alt=media" alt=""><figcaption><p>Figure 5. Example edit rule to avoid sending requisition through approval process when it’s updated by Pactum platform</p></figcaption></figure>

### Payment Terms

#### Enable changing payment terms during requisition creation

A member of the Customer Administrator group needs to enable this feature in the Intelligent Configuration Manager workspace:

* Change Payment Terms during Requisition creation (PR-420)

The feature can be found under `Manage -> Core Administration -> Intelligent Configuration Manager -> Manage Configurations`. If you don’t see this feature, open an SAP support case to confirm the feature is on.

#### Sending Payment Terms to Pactum

Pactum’s system needs to know the IDs of the Payment Terms that are used in Ariba. These can be exported from `Manage -> Core Administration -> Procure-to-Pay Manager -> Payment Terms`

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-c4f801966261a78108f5403027d169293f2636ed%2Fariba-payment-terms-export.png?alt=media" alt=""><figcaption><p>Figure 6. Example payment terms export view</p></figcaption></figure>

Please send us this export containing only the Payment Terms that are relevant for the suppliers we will negotiate with.

## APIs

Pactum uses two Ariba REST APIs to read requisition and supplier data and to approve requisitions, and one SOAP web service to write the negotiated results back. Below is an overview of each API, why it is needed, and the necessary HTTP requests and responses (with irrelevant data omitted).

### Activating the REST APIs

Both REST APIs are enabled through the [SAP Ariba Developer Portal](https://developer.ariba.com/). SAP has to activate each API before Pactum can use it, and this may take up to 24 hours. It is worth requesting access early, since the integration cannot be tested until both APIs are active. This is also the one part of the setup you can prepare before you have access to the Pactum platform.

#### Prerequisites

* User with Developer or Organization Admin role in Ariba developer portal for parent and child realms.

Note: Getting Developer Portal access configured for a user needs service request to be made in Ariba support portal

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-331607357041c88664101804ffd00a83091f23d2%2Fariba-developer-portal-sign-in.png?alt=media" alt=""><figcaption><p>Figure 7. Developer Portal Sign-in</p></figcaption></figure>

#### Configuring REST API in Developer Portal

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-35f30dcf8291dd05cde44240ded706512c7d98a1%2Fariba-developer-portal-api-access-steps.png?alt=media" alt=""><figcaption><p>Figure 8. REST API credentials creation process in Developer Portal</p></figcaption></figure>

REST APIs that are required to be configured in Ariba Developer Portal:

* Document Approval API
* Master Data Retrieval API

#### Creating OAuth credentials for REST API

Repeat these steps for each of the two APIs, creating one application per API.

1. Login to [SAP Ariba Developer Portal](https://developer.ariba.com/)
2. Navigate to Manage tab in developer portal
3. Navigate to Applications
4. Click + button next to the search input (or Create a New Application button if there are no pre-existing applications)
5. Fill in the name and description for the application. For example: “Document Approval API for Pactum”
6. Click Actions → Request API Access

   <figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-73178bde370c8fd370045c1e949076fa942b6087%2Fariba-developer-portal-request-api-access.png?alt=media" alt=""><figcaption></figcaption></figure>
7. Choose the API you are activating from the list of APIs

   <figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-ca76c78eb6253d3bba3707fd9380e9ad69d3ca6c%2Fariba-developer-portal-choose-api.png?alt=media" alt=""><figcaption></figcaption></figure>
8. Click Procurement and choose child realm

   <figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-d1d2d2a1b259ee80be7a97fda5c35a4719893847%2Fariba-developer-portal-choose-child-realm.png?alt=media" alt=""><figcaption></figcaption></figure>
9. Click Submit to submit the request
10. Allow 24 hours for the API to be enabled
11. Click Actions → Generate OAuth Secret

    <figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-09fbbf2c4785d6f2a7a6090c631cf6d032aa8eb8%2Fariba-developer-portal-generate-oauth-secret.png?alt=media" alt=""><figcaption></figcaption></figure>
12. Copy secrets and store securely as you will need them later

    <figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fgit-blob-311909a9538e4c196ead1b8f61b74b83dba88932%2Fariba-developer-portal-oauth-secret.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Authentication

Ariba REST API uses OAuth 2.0 client credentials authentication flow. To call either REST API, Pactum needs the realm name, the OAuth server URL prefix, and the Application key, OAuth Client ID and OAuth Client Secret of that API.

**GET request to OAuth token endpoint**

```bash
curl -X POST
 https://{{oauth_server_url_prefix}}/v2/oauth/token \
 -H 'Authorization: Basic {{Base64EncodedClientAndSecret}}' \
 -H 'Content-Type:application/x-www-form-urlencoded' \
 -d 'grant_type=client_credentials'
```

**Response from token endpoint**

```
 "timeUpdated": 1462815524141,
 "access_token": "********-****-****-****-********",
 "refresh_token": "********-****-****-****-********",
 "token_type": "Bearer",
 "expires_in": 1440,
 "scope": null
```

### Document Approval API

Pactum uses this API to find the requisitions that are waiting for its approval, to read the requisition data needed for the negotiation, and to approve or deny the requisition so it can move forward in the approval flow.

#### Retrieving requisitions waiting for approval

**GET request to Document Approval API endpoint**

```bash
curl -X GET {{baseUrl}}/pendingApprovables?realm={{realm}}&$count=true&$filter=approvableType eq 'requisitions' and user eq 'pactum' \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer {{bearerToken}}' \
 -H 'apikey: {{applicationKey}}'
```

**Response with pending approvables**

```json
{
 {
  "approvableId": "UFJya0FYMUNZdWtISTc",
   "approvableUniqueName": "PR53",
   "approvableType": "requisitions",
   "approver": "pactum",
   ...
 }
 ...
}
```

#### Retrieving requisition data

**GET request to Document Approval API endpoint**

```bash
curl -X GET {{baseUrl}}/requisitions/{{approvableId}}?realm={{realm}}
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer {{bearerToken}}' \
 -H 'apikey: {{applicationKey}}'
```

**Response with requisition data**

```json
{
 "approvableId": "UFJya0FYMUNZdWtISTc",
 "uniqueName": "PR53", // PR number
 "lineItems": [
   {
     "numberInCollection": 1,
     "supplier": {
       "commonSupplier": {
         "name": "BigBox Retail (Email)"
       },
       "name": "BigBox Retail (Email)", // Supplier name
       "uniqueName": "1000003725"
     },
     "shipTo": {
       "name": "ABC Test Enterprise", // Delivery location
        ...
     },
     "deliverTo": "Chad Noll", // Needs to be fed back to RequisitionImportPull
     "description": {
       "shortName": "Pens", // Line item name
       "price": {
         "amount": 2.0000000000, // Line item unit price
         ...
       },
       "unitOfMeasure": "each", // Line item unit of measure
       "description": "Blue gel pens" // Line item description
       ...
     },
     "needBy": 1616828400000, // Expected delivery date
     "quantity": 500.0000000000, // Line item quantity
     "commonCommodityCode": "Published Products", // Line item type
     ...
   }
 ],
 ...
}
```

#### Approving requisition

Approving requisition through Document Approval API, so it can move forward in approval flow.

**PATCH request to Document Approval API endpoint**

```bash
curl -X PATCH {{baseUrl}}/{{approvableType}}/{{approvableId}}?user=pactum&passwordAdapter=PasswordAdapter1&realm={{realm}}
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer {{bearerToken}}' \
 -H 'apikey: {{applicationKey}}' \
 -d '{
   "state": "approve",
   "comment": {
     "text": "Price improvement: 3.7%",
     "visibleToSupplier": false
   }
 }'
```

**Response with approved requisition data**

```json
{
 ...
 "approvableId": "UFJya0FYMUNZWTdqb0Y",
 "uniqueName": "PR41",
 "comments": [
   {
     ...
     "requisitionId": "PR41",
     "text": "Price improvement: 3.7%",
     "user": {
       ...
       "name": "Pactum",
       "uniqueName": "pactum",
       "passwordAdapter": "PasswordAdapter1",
       ...
     }
     ...
   }
 ],
 "records": [
   {
     ...
     "summary": "PR41 approved.",
     "requisitionId": "PR41",
     "realUser": "Pactum",
     "action": "Approved",
     "user": {
       ...
       "name": "Pactum",
       "uniqueName": "pactum",
       "passwordAdapter": "PasswordAdapter1",
       ...
     }
     ...
   }
 ]
 ...
}
```

### Master Data Retrieval API for Procurement

This API gives read-only access to reference data. Pactum uses it to look up the supplier contact email, which is needed to send the negotiation link but is not returned by the Document Approval API.

#### Retrieving supplier contact data

**GET request to Master Data Retrieval API for procurement endpoint**

```bash
curl -X GET {{baseUrl}}/entities/commonsuppliers?$filter=SystemID eq '{{commonSupplierId}}'
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer {{bearerToken}}' \
 -H 'X-Realm: {{realm}}' \
 -H 'apikey: {{applicationKey}}'
```

**Response with supplier data**

```json
[
 {
   ...
   "Name_en": "BigBox Retail (Email)",
   "SystemID": "1000003725",
   "CorporateEmailAddress": "corporate@bigbox.com", // Supplier email address
   ...
 }
]
```

### Import Requisition(s) web service (RequisitionImportPull)

Pactum uses this SOAP web service to write the negotiation results back to the requisition, updating the unit prices and payment terms of each line item.

The Pactum platform guides you through creating the inbound End Point in Ariba and pointing the Import Requisition(s) task at it. More information about [configuring SOAP web services](https://help.sap.com/docs/ARIBA_SOURCING/eb12a8256a244b86be23c9b4e4e751da/7cae31dd71ea10149abff4fec0eb02d6.html)

#### Prerequisites

You must be a member of the Customer Administrator or Integration Admin group, or a group with the Administrator or Integration Admin role.

#### Keep line-level attachments and comments

Unless this parameter is enabled, Ariba deletes line-level attachments and comments from a requisition every time Pactum writes back negotiation results.

A member of the Customer Administrator group needs to enable this parameter in the Intelligent Configuration Manager workspace:

* Application.Purchasing.RetainReqLineCommentsAndAttachmentsOptionForWSImport

The parameter can be found under `Manage -> Core Administration -> Intelligent Configuration Manager -> Manage Configurations`. If you don’t see this parameter, open an SAP support case to have it enabled.

#### Authentication

Basic Authentication and/or Web Service Security configured in Ariba End Point settings.

#### Updating requisition data

Sending data to previously configured web service End Point.

**POST request to RequisitionImportPull web service**

```bash
curl -X POST {{baseUrl}}/Buyer/soap/{{realmName}}/RequisitionImportPull
 -H 'Content-Type: application/xop+xml; charset=UTF-8; type="text/xml"'
 -H 'Authorization: Basic {{base64EncodedCredentials}}'
 -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:Ariba:Buyer:vrealm_400458">
  <soapenv:Body>
    <urn:RequisitionImportPullRequest>
      <urn:Requisition_RequisitionImportPull_Item>
        <urn:item>
          <urn:LineItems>
            <urn:item>
              <urn:Description>
                <urn:Price>
                  <urn:Amount>105.00</urn:Amount>
                  <urn:Currency>
                    <urn:UniqueName>EUR</urn:UniqueName>
                  </urn:Currency>
                </urn:Price>
              </urn:Description>
              <urn:Supplier>
                <urn:UniqueName>1000003725</urn:UniqueName>
              </urn:Supplier>
              <urn:ImportedDeliverToStaging/>
              <urn:ImportedNeedByStaging>2025-03-31T10:30:00.000Z</urn:ImportedNeedByStaging>
              <urn:ImportedPaymentTermsStaging>
                <urn:UniqueName>N60</urn:UniqueName>
              </urn:ImportedPaymentTermsStaging>
              <urn:NumberInCollection>1</urn:NumberInCollection>
            </urn:item>
          </urn:LineItems>
          <urn:OriginatingSystem>pactum</urn:OriginatingSystem>
          <urn:Name/>
          <urn:UniqueName>PR59</urn:UniqueName>
        </urn:item>
      </urn:Requisition_RequisitionImportPull_Item>
    </urn:RequisitionImportPullRequest>
  </soapenv:Body>
</soapenv:Envelope>'
```

**Response from Import Requisition(s) web service**

```xml
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Header>
    <Headers xmlns="urn:Ariba:Buyer:vrealm_400458">
      <variant>vrealm_400458</variant>
      <partition>prealm_400458</partition>
    </Headers>
  </soap:Header>
  <soap:Body>
    <RequisitionImportPullReply xmlns="urn:Ariba:Buyer:vrealm_400458" variant="vrealm_400458" partition="prealm_400458">
      <Requisition_RequisitionIdExport_Item>
        <item>
          <OriginatingSystem>pactum</OriginatingSystem>
          <StatusString>Submitted</StatusString>
          <UniqueName>PR59</UniqueName>
        </item>
      </Requisition_RequisitionIdExport_Item>
    </RequisitionImportPullReply>
  </soap:Body>
</soap:Envelope>
```

## Comment

This document describes the most simple way of implementing SAP Ariba Buying for integration with Pactum’s Autonomous Negotiation platform for the negotiation of Purchase Orders with suppliers. Every company has different processes, data availability and technical needs. Therefore, this document should be considered as a starting point for integration discussions and not a recipe for final implementation. Any differences and additions to the previous description are welcome to be discussed with the Pactum integration team.
