Administration

The following services are included in this functional area:

Data Privacy

The following services are included in this functional area:

Data Privacy Download Service

Get Personally Identifiable Information

This section describes the Data Privacy Access service for Merchandising.

Business Overview

This query service provides access to data stored in Merchandising that contain personally identifiable information.

Service Type

GET

ReSTURL

https://<host:port>/RetailAppsDataPrivServicesRESTApp/rest/privatedata/getPersonalInfo?customer_id={entityName}::{entityType}::{entityId}::{fullName}::{phone}::{email}

Accept

application/json
application/xml

Query Parameters

customer_id (required): The customer ID string containing the parameters to be used in looking up data. The format of this string is as follows:
- entity name}::{entity type}::{entity id}::{full name}::{phone}::{email}

Path Parameters

Parameter	Description
Entity Name	The query group type for which data is to be retrieved. The available group types for Merchandising are: BUYER (Buyer) MERCHANT (Merchant) STORE (Store) WAREHOUSE (Warehouse) SUPPLIER (Supplier) PARTNER (Partner) OUTLOC (Outside Location) ORDER CUSTOMER (Merchandising Customer)
Entity Type	Used if the entity name is PARTNER or OUTLOC. The value here should indicate the type of partner or outside location being queried. Valid values for this input can be found on the Codes table for each type: Partner Types = PTNR Outside Location Types = LOCT
Entity ID	The ID of the entity being queried. For example, the supplier ID.
Full Name	The full name to be searched for the selected entity.
Phone	The phone number to be searched for the selected entity.
Email	The email to be searched for the selected entity.

Default Response

The response will return all instances of the data being searched that occur in the requested entity. For example, if the entity requested was BUYER, all instances where the buyer, name, and phone match the data sent will be returned. If any of these parameters are not sent (e.g. buyer), then it will not be used as part of the search. The following data is included in the response:

Parameter	Description
Entity Name	Valid values are: BUYER (Buyer) MERCHANT (Merchant) STORE (Store) WAREHOUSE (Warehouse) SUPPLIER (Supplier) PARTNER (Partner) OUTLOC (Outside Location) ORDER CUSTOMER (Merchandising Customer)
Entity Type	If the entity name is PARTNER or OUTLOC, the value here indicates the type of partner or outside location being queried. Valid values for this input can be found on the Codes table for each type: Partner Types = PTNR Outside Location Types = LOCT For other entity types, this will be null.
Entity ID	The ID of the entity where the data was found.
Full Name	The name associated with the entity.
Phone	The phone number associated with the entity.
Fax	The fax number associated with the entity.
Telex	The telex number associated with the entity.
Pager	The pager number associated with the entity.
Email	The email address associated with the entity.

Sample Response

{
  "Personal Information": {
    "list": [],
      "Get Personal Information": {
        "list": [      
           [
            {
              "ENTITY_NAME": "BUYER",
              "ENTITY_TYPE": "null",
              "ENTITY_ID": "1002",
              "FULL_NAME": "Matt Wilsman",
              "PHONE": "6125251034",
              "FAX": "6125259800",
              "TELEX": "null",
              "PAGER": "null",
              "EMAIL": "null"
            }
          ]
        ]
      }
    }
  }
}

Response Codes and Error Messages

200 - Success
400 - Bad Request - for the following situations:
- Customer ID does not match the required format
- Invalid input type
- Missing customer ID
- Invalid jsonFormat
500 - Internal Server Errors - for all other types of errors (for example, configuration errors, SQL errors, and so on)

Success Payloads

When Accept=application/json, this API will return data in JSON format
When Accept=application/xml, this API will return data formatted as an HTML page

Data Privacy Upload Service

Delete Personally Identifiable Information

This section describes the Data Privacy Forget service for Merchandising.

Business Overview

This service supports updating personal information stored in Merchandising. When the service is invoked with mask strings as inputs, it overwrites the fields with mask strings, which effectively removes the personal information from the system.

Service Type

DELETE

ReSTURL

https://<host:port>/RetailAppsDataPrivServicesRESTApp/rest/privatedata/updatePersonalInfo?customer_id={entityName}::{entityType}::{entityId}::{fullName}::{phone}::{fax}::{telex}::{pager}::{email}::{addr1}::{addr2}::{addr3}::{county}::{city}::{state}::{countryId}::{postalCode}

Accept

application/json
application/xml

Query Parameters

customer_id (required): The customer ID string containing the parameters to be used in updating data. The format of this string is as follows:
- {entityName}::{entityType}::{entityId}::{fullName}::{phone}::{fax}::{telex}::{pager}::{email}::{addr1}::{addr2}::{addr3}::{county}::{city}::{state}::{countryId}::{postalCode}

Path Parameters

Parameter	Description
Entity Name (required)	The group type for which data is to be updated. The available group types for Merchandising are: BUYER (Buyer) MERCHANT (Merchant) STORE (Store) WAREHOUSE (Warehouse) SUPPLIER (Supplier) PARTNER (Partner) OUTLOC (Outside Location) ORDER CUSTOMER (Merchandising Customer)
Entity Type	Required if the entity name is PARTNER or OUTLOC. The value here should indicate the type of partner or outside location. Valid values for this input can be found on the Codes table for each type: Partner Types = PTNR Outside Location Types = LOCT
Entity ID (required)	The ID of the entity to be updated. For example, the supplier ID.
Full Name	The value to update the full name with. If the value is null and this is a required field in the entity, 'XXXXX' will be used.
Phone	The value to update the phone number with. If the value is null and this is a required field in the entity, 'XXXXX' will be used.
Fax	The value to update the fax number with.
Telex	The value to update the telex number with.
Pager	The value to update the pager number with.
Email	The value to update the email address with.
Addr1	The value to update the address 1 with.
Addr2	The value to update the address 2 with.
Addr3	The value to update the address 3 with.
County	The value to update the county with.
City	The value to update the city with.
State	The value to update the state with.
Country	The value to update the country with.
Postal Code	The value to update the postal code with.

Default Response

This service only returns a response code to signify if the request is successful or not. If no record is updated, the service returns an error.

Response Codes and Error Messages

200 - Success
400 - Bad Request - for the following situations:
- Customer ID does not match the required format
- Invalid input type
- Missing customer ID
- Invalid jsonFormat
500 - Internal Server Errors - for all other types of errors (e.g. config errors, sql errors, etc).

Success Payloads

N/A

Operations

The following services are included in this functional area:

Background Job Configuration Upload Service

The following services are included in this functional area:

Get Batch Run Status Services

Endpoints

/MerchIntegrations/services/administration/operations/batchRunStatus

Functional Area

Administration - Operations

Business Overview

This service returns the current running status of the nightly batch. During the nightly batch window, certain REST services may be unavailable either for the entire duration or for a portion of the night, especially when inventory or costing batch flows are in progress. This API enables clients to monitor the status of batch processes, allowing them to optimize their service calls by pausing or resuming dependent REST services accordingly.

Service Type

GET

ReST URL

 /MerchIntegrations/services/administration/operations/batchRunStatus

Output

Name	Data Type	Description
batchRunningInd	String	This field indicates whether Nightly batch jobs are running. It is set to `Y` at the beginning of the Merchandising nightly batch cycle and set to `N` at the end of the cycle.
inventoryBatchRunningInd	String	This field indicates whether inventory batch jobs are running. Valid values are `Y` or `N`.
costingBatchRunningInd	String	This field indicates whether costing batch jobs are running. Valid values are `Y` or `N`.

Sample Response Message

{
  "batchRunningInd": "N",
  "inventoryBatchRunningInd": "N",
  "costingBatchRunningInd": "N"
}

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
RMS_BATCH_STATUS	Yes	No	No	No

Update Background Job Configuration

This section describes the Background Process Configuration.

Business Overview

This service is used to update the configuration for each background jobs in Merchandising.

Service Type

Post

ReST URL

processes/update/process_config/execution

Input Parameters

Parameter Name	Required	Description
JobName	Yes	Job Name
numThreads	No	Maximum number of threads the job will execute
numDataToProcess	No	Number of records a jobs will process each run.
commitMaxCtr	No	Max number of records processed before a commit is issued.
archiveInd	No	This field will be used to determine if associated tables for this job needs to be archived to history or not.

Output

N/A

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
B8D_PROCESS_CONFIG	No	No	Yes	No
JOB_AUDIT_LOGS	No	Yes	No	No
JOB_AUDIT_PAYLOAD	No	Yes	No	No

BI Publisher Report URL Download Service

The following services are included in this functional area:

Get BI Publisher Report URL

Get BI Publisher Report URL

Functional Area

Administration - Operations

Business Overview

This service is used by Oracle Retail Financial Integration (RFI) to retrieve the URL of a BI Publisher report from Merchandising or Sales Audit that can be invoked from the PeopleSoft Financials General Ledger based on a particular journal entry. The report URL that will be returned will be different based on the ID sent in the service call. Based on that ID, Merchandising will determine if it was a Merchandising, Sales Audit, or Invoice Matching ID and return a URL for the appropriate report.

The possible reports for Merchandising and Sales Audit are:

GL Fixed Deal Data Report
GL Item level Data Report
GL Item Rollup Daily Data Report
GL Item Rollup Monthly Data Report
GL Sales Audit Data Report

Also, for Invoice Matching, one of the following reports might be returned:

Merchandise Invoice Document Report
Non-Merchandise Invoice Document Report
Credit Note Document Report
Credit Memo Cost Document Report
Credit Memo Quantity Document Report
Debit Memo Cost Document Report
Debit Memo Quantity Document Report
Debit Memo VAT Document Report
Receipt Write Off Document Report

For cloud service implementations, this configuration should be done if you are working with PeopleSoft Financials. For on premise implementations, you may need to configure this in the RETAIL_SERVICE_REPORT_URL table. For cloud service implementations, this configuration can be done by the Oracle Cloud Operations team.

The report is similar functionality to the Drill Forward and Drill Back functionality available in the Merchandising Transaction Data and Fixed Deal pages and the Sales Audit General Ledger Transaction page. See also Get Drill Back Forward URL Service for more on the APIs that support this functionality.

Service Type

POST

ReST URL

MerchIntegrations/services/administration/operations/biPublisherReport/url/get

Input Payload Details

Table 5-2 Get - Object. See list of elements for detail

Element Name	Required	Data Type	Description
reportReferenceKey	Yes	String (32)	Holds the unique reference trace ID that is used to match to the report URL.

Sample Input Message

{
  "reportReferenceKey": "String"
}

Response Code: 200 (Success)

Table 5-3 GetResponse - Object. See list of elements for detail

Element Name	Required	Data Type	Description
reportReferenceKey	Yes	String (32)	Holds the unique reference trace ID that is used to match to the report URL.
reportUrl	Yes	String (256)	Contains the report URL with parameters for financial integration.

Sample Response Message

{
  "reportReferenceKey": "String",
  "reportUrl": "String"
}

Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element "validationErrors" will be present when input payload or input parameters are not as per the schema definition of this service. The element "businessError" will be present if the payload passes schema validation but exception is caught while processing business logic.

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ],
  "businessError": [
    "Error message"
  ]
}

Calendar Download Service

The following services are included in this functional area:

Get 4-5-4 Calendar

Get 4-5-4 Calendar

Endpoints

/MerchIntegrations/services/administration/operations/calendar

Functional Area

Administration – Operations

Business Overview

This service retrieves 4-5-4 calendar details. This service takes an optional query parameter of year to retrieve details for that year

Service Type

GET

ReST URL

/MerchIntegrations/services/administration/operations/calendar? year=[year]

Input Parameters

Parameter Name	Required	Data Type	Description
year	No	Number	Year. Retrieve calendar for a specific year

Output – Calendar

Name	Data Type	Description
year	String	Contains the year. The 4-5-4 year begins on the first day of the first 4-5-4 month regardless of when the calendar year begins.
month	String	Contains the number ranging from 1 to 12 which indicates the 4-5-4 month.
noOfWeeks	Number	Indicates whether there are 4 or 5 calendar weeks in the 4-5-4 month.
firstDay	Date	Contains the first day of the 4-5-4 month in YYYY-MM-DD format

Example JSON output:

[{
    "year": 2022,
    "month": 1,
    "noOfWeeks": 4,
    "firstDay": "2022-01-02"
  },
  {
    "year": 2022,
    "month": 2,
    "noOfWeeks": 4,
    "firstDay": "2022-01-30"
 }]

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
CALENDAR	Yes	No	No	No

Codes and Descriptions Download Service

The following services are included in this functional area:

Get Codes and Descriptions

Business Overview

Code Detail service allows user to retrieve code details for a selected code and code type.

Service Type

GET

ReST URL

CodeDetail/codeDetails?code={ }&codeType={ }

Input Parameters

Parameter Name	Required	Description	Valid values
Code	Yes	Code	NA
Code Type	Yes	Code Type	NA

Output

RestCodeDetailRecRDO

Parameter Name	Data Type
codeDesc	String
requiredInd	String
codeSeq	BigDecimal
codeType	String
codeTypeDesc	String
code	String

JSON Structure

{
  "codeDesc": null,
  "requiredInd": null,
  "codeSeq": null,
  "codeType": null,
  "codeTypeDesc": null,
  "code": null,
  "links": [],
  "hyperMediaContent": {
    "linkRDO": []
  }
}

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
CODE_HEAD	Yes	No	No	No
CODE_DETAIL	Yes	No	No	No
JOB_AUDIT_LOGS	No	Yes	No	No
JOB_AUDIT_PAYLOAD	No	Yes	No	No

Get Codes and Descriptions for All or Provided Code Type

Endpoints

/MerchIntegrations/services/administration/operations/codes

Functional Area

Administration – Operations

Business Overview

This service returns full dataset of code and code detail. This service supports pagination and the page size of each response is controlled by the query paramter 'limit'. This service optionally takes code type as input for returning the code details for a single code type.

Service Type

GET

ReST URL

/MerchIntegrations/services/administration/operations/codes? offsetkey={offsetkey}&limit={limit}&codeType=[codeType]

Input Payload Details

Table 5-4 Input Parameters for MerchIntegrations/services/administration/operations/codes

Parameter Name	Required	Data Type	Description
offsetkey	No	String	Offset Key. Valid Value is code type
limit	No	Number	Pagination limit. Default Value is 1000.
codeType	No	String	Code Type. Searches for a specific code type

Response Code: 200 (Success)

Table 5-5 Output – Code

Name	Data Type	Description
codeType	String	This field contains the code type which will serve as a grouping mechanism for the multiple codes.
description	String	This field will contain the description of the code type.
Details	Collection	Code details

Table 5-6 Output – Code Details

Name	Data Type	Description
code	String	This field contains the code used in the application.
codeDescription	String	This field contains the description associated with the code and code type.
sequence	Number	This is a number used to order the elements so that they appear consistently when using to populate a list or display in user interface.
usedInd	String	Indicate if the code is in use or not. Records set to N will not display as possible options for users. Valid value Y or N

Table 5-7 Elements in JSON Output

Elements	Description
items	The first element is named as items and contains a number of child elements. Each child element corresponds to a row in the result set generated by the query.
hasMore	This is dependent on limit value. If the total rows are more than then limit defined then hasMore will be set to true else false.
limit	This is used to limit the rows to control the paging of result data. Based on the limit, next and previous links are displayed. For example: If the limit is set to 25, internal it tries to fetch 26 rows. If 26th row exists then 25 rows are returned along with a "next" link else no links would be added to the JSON response.
links	“self” : This contains URI pointing to current page. “next”: This contains URI pointing to the next page of results.

Example JSON output:

{
  "items": [
    {
      "codeType": "LOC",
      "description": "Location",
      "details": [
        {
          "code": "W",
          "codeDescription": "Warehouse",
          "sequence": "2",
          "usedInd": "Y"
        },
        {
          "code": "S",
          "codeDescription": "Store",
          "sequence": "1",
          "usedInd": "Y"
        }
      ]
    }
  ],
  "hasMore": true,
  "limit": 1,
  "count": 1,
  "links": [
    {
      "href": "http://Server:port/MerchIntegrations/services/administration/operations/codes?offsetkey=LOB&limit=1",
      "rel": "self"
    },
    {
      "href": "http:// Server:port /MerchIntegrations/services/administration/operations/codes?offsetkey=LOC&limit=1",
      "rel": "next"
    }
  ]
}

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
CODE_HEAD	Yes	No	No	No
CODE_DETAIL	Yes	No	No	No

POM End of Week Signal Download Service

The following services are included in this functional area:

Get POM End of Week Signal Detail

Get POM End of Week Signal Detail

Business Overview

This service is used to determine whether the Vdate is an End of Week Date or Not.

If Vdate is at EOW, it returns 'Y', else 'N'.

Service Type

Get

ReST URL

EowRunSignal/EowRunSignalDetail

Input Parameters

N/A

Output

RestEowRDO

Parameter Name	Data Type
eow	Char('Y' or 'N')

JSON Structure

{
   "eow": "N",
   "links": [],
   "hyperMediaContent": {
      "linkRDO": []
   }
}

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
PERIOD	Yes	No	No	No
SYSTEM_VARIABLES	Yes	No	No	No

Virtual Date Download Service

The following services are included in this functional area:

Get Current Virtual Date in Date Format

Business Overview

Deprecated in v23.1.401.0: Scheduled for Removal in 2 Years. Use RmsReSTServices/services/private/Common/vDate

This service retrieves the Merchandising virtual business date (vdate).

Service Type

GET

ReST URL

Vdate/vdateDetail

Input Parameters

N/A

Output

Table 5-8 RestVdateRecRDO

Parameter Name	Data Type
vdate	Date

JSON Structure

[
  {
    "vdate": null,
    "links": [],
    "hyperMediaContent": {
      "linkRDO": []
    }
  }
]

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
PERIOD	Yes	No	No	No
JOB_AUDIT_LOGS	No	Yes	No	No
JOB_AUDIT_PAYLOAD	No	Yes	No	No

Get Current Virtual Date in Long and Date Format

Business Overview

Retrieve Merchandising Vdate.

Service Type

GET

ReST URL

/Common/vDate

Input Parameters

N/A

Output

Table 5-9 Vdate in Long and Date Format

Parameter Name	Data Type
Vdate	Long
Vdate	Date

JSON Structure

{
   "vdateDisplay": "01-Jul-2019",
   "vdate": 1561939200000,
   "links": [],
   "hyperMediaContent": {
      "linkRDO": []
   }
}

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
PERIOD	Yes	No	No	No
JOB_AUDIT_LOGS	No	Yes	No	No
JOB_AUDIT_PAYLOAD	No	Yes	No	No

Webhook Configuration

The following services are included in this functional area:

Webhook Configuration Download Service

Get Webhooks

Functional Area

Administration - Operations

Business Overview

This service retrieves all configured Webhooks Listeners. In addition to the configured webhook listeners, this service also retrieves records for unused, configured credentials.

Service Type

GET

ReST URL

MerchIntegrations/services/administration/operations/webhooks

Input Parameters

Parameter Name	Required	Data Type	Description
limit	No	Number (6)	Pagination limit. Default Value is 1000
offsetkey	No	String	Offset Key. Valid Value is combination of credential name and service
service	No	String (100)	Service Name to retrieve details for a particular service

Response Code: 200 (Success)

Element Name	Required	Data Type	Description
items	No	Collection of Object	References a collection of webhook listener details.

Table 5-10 Items - Object. See list of elements for detail

Element Name	Required	Data Type	Description
credentialName	Yes	String (100)	This field contains the Credential name.
credentialType	Yes	String (30)	This field contains the Credential type.
service	No	String (100)	This field contains the service name.
listenerUrl	No	String (255)	This field contains the listener URL.
enabled	No	String (1)	This field indicates if the service is enabled. Default is 'Y'. Valid values is 'Y' or 'N'.
intervalSeconds	No	Number (6,0)	This field contains the frequency in seconds webhook will poll for new events. Default is 900 seconds.
includePayload	No	String (1)	This field indicates if data should be included in the webhook call. Default is 'N'. Valid values is 'Y' or 'N'.
pageLimit	No	Number (6,0)	This field contains the number of records within a payload during pagination and is used to control the message size. Default is 1000.
heartbeatIntervalHours	No	Number (2,0)	This field frequency in hours on which heartbeat will be pinged to listener. Default is 6 hours.

Sample Response Message

{
  "items": [
    {
      "credentialName": "APP1",
      "credentialType": "OAUTH",
      "service": "foundation/item",
      "listenerUrl": "https://apigateway.myretailer.com/webhook/mfcs/item",
      "enabled": "N",
      "intervalSeconds": 900,
      "includePayload": "N",
      "pageLimit": 1000,
      "heartbeatIntervalHours": 6
    }  
  ],
  "hasMore": true,
  "limit": 1000,
  "count": 1,
  "links": [
    {
      "href": "https://<server>:<port>/Application/services/resources?limit=1000",
      "rel": "self"
    }
  ]
}

Webhook Configuration Upload Service

Manage Webhook Credential

Functional Area

Administration - Operations

Business Overview

This service maintains credentials for the Webhooks listener and allows for setting up new credentials, along with updating or deleting existing credentials. Credentials must be set up in advance of webhook listener setup. A credential cannot be deleted if it is attached to a listener.

The credentials are securely stored in OCI S3. The supported credentials are Basic Auth, oAuth2 (Client Credentials) and API key (Request Parameter - X-API-Key). Based on the type of credential, the corresponding field should be provided. In case of oAuth, the URL to retrieve the oAuth token should be allowlisted and should have a publicly trusted SSL/TLS certificate.

Service Type

PUT

ReST URL

MerchIntegrations/services/administration/operations/webhook/credential/manage

Input Payload Details

Table 5-11 Manage - Object. See list of elements for detail

Element Name	Required	Data Type	Description
credentialName	Yes	String (100)	Unique Credential name for storing credential details for webhook listener endpoint.
credentialType	No	String (30)	Type of credential supported by listener. Valid options are OAUTH, BASICAUTH or APIKEY
username	No	String (100)	Contains the username for basic auth credential
password	No	String (100)	Contains the password for basic auth credential
apikey	No	String (2000)	Contains apikey. API Key will be passed in Request Parameter X-API-Key
oauthClientId	No	String (255)	Contains the client id for Oauth - Client Credential authentication
oauthClientSecret	No	String (255)	Contains the client secret for Oauth - Client Credential authentication
oauthTokenUrl	No	String (255)	Contains the oAuth Token URL for Oauth - Client Credential authentication
oauthScope	No	String (255)	Contains the scope for Oauth - Client Credential authentication. Scope is optional.
heartbeatIntervalHours	No	Number (2)	Controls the frequency in which heartbeat will be published to the listener URL
deleteInd	No	String (1)	Pass a value of Y to delete the credential. To delete a credential, none of the listener should be using this credential. Supported values as Y or N. The default if left blank is N.

Sample Input Message

{
  "credentialName": "APP_DEV1",
  "credentialType": "OAUTH",
  "username": "",
  "password": "",
  "apikey": "",
  "oauthClientId": "oracle_mfcs_client_dev1",
  "oauthClientSecret": "6c2c0acb-88a1-4067-865b-5eb75b2989c3",
  "oauthTokenUrl": "https://iam-6c2c0acb.iamprovider.com:443/oauth2/v1/token",
  "oauthScope": "mfcs-webhook-dev1",
  "deleteInd": ""
}

Response Code: 200 (Success)

Sample Response Message

{
  "status": "SUCCESS",
  "message": "Create record was successful"
}

Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element validationErrors is present when the input payload or input parameters do not match the schema definition for this service.

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ]
}

Manage Webhooks

Functional Area

Administration - Operations

Business Overview

This service is used to register and manage webhook listeners. To register a listener, the credential for the listener should be set up first using the Manage Webhook Credential service.

Webhook Overview

The listener URL should be an allowlisted https ReST endpoint supporting THE POST method and having publicly trusted SSL/TLS certificate. a Webhook can be configured for THE Publish API and THE name of the service should match with the value in THE merchapi_name column from the merchapi_config table. Once a webhook is successfully registered, it is added to the server threadpool after a short interval and, thereafter, runs based on the configured interval.

Three types of publish are available:

HEARTBEAT - The frequency (in hours) of this can be defined using the field heartbeatIntervalHours. A ping call is made to the listener endpoint to validate the connectivity, credential, and to ensure that the webhook server is up and running. If the heartbeat call fails, the webhook call with the event or payload is put on hold until the heartbeat connectivity is established. Once the heartbeat connectivity is established, the event or payload publish starts.
EVENT - A webhook call of type Event indicates to the listener that there are one or more functional data packets that have been created or updated since the last webhook call, and the listener should poll the Publish API to publish the change. A webhook of type Event is the default webhook configuration and should be the preferred configuration to keep the data traffic through the webhook to a minimum. If the field includePayload is left blank or is set to N, this indicates that the webhook is configured for event publishing.
PAYLOAD - A webhook of type Payload includes the data as part of the webhook publish. The data is published in JSON format and is enclosed in the attribute named payload. To enable payload publish, set the value of includePayload to Y. The payload supports pagination to keep the individual message size in control. Use the field pageLimit to define the number of records included in the call. If pageLimit is not defined, it is set to 1000. For a payload publish, the server posts each subsequent page immediately upon receiving the success response from the client for the previous page.

The processing of a webhook is asynchronous. Using a background micro batch engine, the webhook server checks for new events in merchapi json tables for changes. The frequency at which the server polls the merchapi json table is configured using the field intervalSeconds. Every <interval> seconds, the server polls the table to check for new entries and, if there are updates, it makes a webhook call to the listener URL to publish the event or payload depending on the webhook configuration. If there are no new entries, it does not make an empty webhook call.

To keep track of the records that have been published, and have the subsequent webhook publish only include the newer records since the last call, the timestamp of the webhook pool is persisted by the server and is named the since timestamp. When the webhook is registered for the first time, the since timestamp is defaulted to Unix time zero (1970) unless a since timestamp was provided as part of the registration. The server polls the json table to check for newer entries having timestamp greater than since timestamp.

For a webhook of type Event, the since timestamp is included in the publish to inform the listener that there are records having a timestamp greater than the since timestamp and they should poll the Publish API using a query parameter of since timestamp.
For a webhook of type Payload, the server internally calls the Publish API with the since timestamp and using before as the current server time and the configured pagination limit. The server redirects the response from the Publish API to the webhook listener. Depending on the number of records and the pagination size, more than one call can be made to the listener URL. Once the last page is published, the server replaces the since timestamp with the server time when the first poll is performed. Subsequent polling uses the new since timestamp to check for newer entries.
If there are no new entries, the value of since timestamp is not changed and this value can be seen as a the timestamp when the last publish of type Event or Payload was made.

The since timestamp is available as part of webhook configuration and this can be updated for existing webhooks. This can be useful to request a full download or to replay all changes since, for example, last week for data corruption scenarios.

Enable/Disable The flag Enabled takes a value of Y or N, and can be used to activate or deactivate a webhook. If the webhook is disabled, it pauses all polls and even heartbeat calls to the listener. Once the webhook is enabled, it starts polling using the since timestamp of the last publish.

Update Webhook Configuration

To update the configuration of a webhook listener, include the fields that need to be updated and their values will be replaced. The fields left blank will not be changed. A configuration change can have an impact on the current publish process (multi-page payload publish).

Listener URL change will be applied immediately. A change of listener causes a heartbeat to be fired and, once the heartbeat is successful, subsequent calls are published to the new URL. If the change happened in between pagination publishes, the remaining pages are published to the new URL. A listener change is a major change and, if the intention for the new listener URL is to get the entire dataset or to start with a particular date and time, adjust the since timestamp accordingly to get the complete/required payload.
A change of credential takes effect immediately. A change of credential causes a heartbeat check to be fired before the next event or payload publish.
Since Timestamp change is applied immediately. This will terminate any in-progress pagination call and publish will restart with the new since timestamp.
Page limit change takes effect immediately for the subsequent page publish. In case of an in-progress pagination publish, the remaining pages publish happens with the new page limit.
Interval second change takes effect a few minutes after the webhook engine syncs up with update configuration.
Disable webhook - This takes effect immediately and may pause a pagination call in between. The remaining pagination pages are published when the webhook is enabled. Enabling of the webhook takes few minutes for the server engine to include this webhook in its thread pool.
A change of heartbeat interval hour takes effect after the next heartbeat is fired.
IncludePayload - This change takes effect immediately and stops any pagination call. It uses the currently active since timestamp to check for changes, unless the since timestamp was also updated as part of the update request.

Delete Webhook

To delete a registered webhook, set the flag deleteInd to Y. That immediately stops subsequent calls and purges all configurations for the webhook.

Service Type

PUT

ReST URL

MerchIntegrations/services/administration/operations/webhooks/manage

Input Payload Details

Table 5-12 Manage - Object. See list of elements for detail

Element Name	Required	Data Type	Description
collectionSize	Yes	Number (4)	Number of items in the collection.
items	Yes	Collection of Object	References a collection of webhook listeners

Table 5-13 Items - Object. See list of elements for detail

Element Name	Required	Data Type	Description
service	Yes	String (100)	Service name for which webhook listener has to be configured. The service name should match with merchapi_name in merchapi_config table. On the api's having the json_table column populated are eligible for webhook.
credentialName	No	String (100)	Registered credential name that was setup using the Manage Webhook Credential service. For update, this can be left blank.
listenerUrl	No	String (255)	A whitelisted listener endpoint which is running a post service to consume the webhook call and returns 200 for success.
includePayload	No	String (1)	Indicates if the webhook publish will contain the data or just the event. Takes a value of Y or N. A value of blank is defaulted to N during initail registration. In case of update of already registered webhook, leave it blank to keep the value unchanged.
intervalSeconds	No	Number (6)	Defines the polling seconds for the webhook server to poll to json table for new events. This value is in seconds.
pageLimit	No	Number (6)	If the webhook is registered to include payload, this defines the maximum number of records in one publish call. If the number of records to be published are greater than page limit, additional pagination call will be made to publish the entire data set. Default value is 1000.
sinceTimestamp	No	date-time	Allows the listener to define if the publish should include events that happens after a particular time. This also allows for replaying already published daata/event by setting this to a earlier time.
enabled	No	String (1)	Takes a value of Y (default if null) or N. If the webhook is disabled, it will pause polling and publish of webhook (inlcuding heartbeat)
heartbeatIntervalHours	No	Number (2)	Controls the frequency in which heartbeat will be published to the listener URL
deleteInd	No	String (1)	Use this to delete an existing listener by setting the value as Y. the default if left blank is N.

Table 5-14 ManageError - Object. See list of elements for detail

Element Name	Required	Data Type	Description
service	Yes	String (100)	Service name for which the registration failed
errorMessage	Yes	String (2000)	Error message

Sample Input Message

{
  "collectionSize": 1,
  "items": [
    {
      "service": "foundation/item",
      "credentialName": "APP_DEV1",
      "listenerUrl": "https://apigateway.myretailer.com/webhook/mfcs/item",
      "includePayload": null,
      "intervalSeconds": 900,
      "pageLimit": 1000,
      "sinceTimestamp": "2001-12-31T23:59:59.123Z",
      "enabled": null,
      "heartbeatIntervalHours": 6,
      "deleteInd": null
    }
  ]
}

Response Code: 200 (Success)

Response Code: 400 (Error)

In case of error, the following standard error response will be returned. The element validationErrors will be present when input payload or input parameters do not match the schema definition for this service. The element businessError will be present if the payload passes schema validation but an exception is caught while processing the business logic.

Table 5-15 ManageError - Object. See list of elements for detail

Element Name	Required	Data Type	Description
service	Yes	String (100)	Service name for which the registration failed
errorMessage	Yes	String (2000)	Error message

Sample Error Message

{
  "status": "ERROR",
  "message": "Error found in validation of input payload",
  "validationErrors": [
    {
      "error": "must be one of Y, N",
      "field": "createRecord.arg0.approveInd",
      "inputValue": "X"
    }
  ],
  "businessError": [
    {
      "service": "foundation/items/manage",
      "errorMessage": "Invalid API"
    }
  ]
}

System Options

The following services are included in this functional area:

System Options Download Service

System Options Download Service

The following services are included in this functional area:

Get Functional System Options

Business Overview

Retrieve Merchandising's Functional Config Options.

Service Type

GET

ReST URL

/Common/FuncSysOps

Input Parameters

N/A

Output

Table 5-16 FunctionalConfigRDO

Parameter Name	Data Type
importInd	String
orgUnitInd	String
supplierSitesInd	String
contractInd	String
elcInd	String

JSON Structure:

"{
    ""links"": [],
    ""importInd"": ""Y"",
    ""orgUnitInd"": ""Y"",
    ""supplierSitesInd"": ""Y"",
    ""contractInd"": ""Y"",
    ""elcInd"": ""Y"",
    ""hyperMediaContent"": {
        ""linkRDO"": []
    }

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
FUNCTIONAL_CONFIG_OPTIONS	Yes	No	No	No
JOB_AUDIT_LOGS	No	Yes	No	No
JOB_AUDIT_PAYLOAD	No	Yes	No	No

Get Inventory Movement System Options

Business Overview

Retrieve Merchandising's Inventory Movement Unit Options.

Service Type

GET

ReST URL

/Common/InvMovSysOps

Input Parameters

N/A

Output

Table 5-17 InvMoveUnitOptRDO

Parameter Name	Data Type
allocMethod	String
applyProfPresStock	String
autoRcvStore	String
closeOpenShipDays	BigDecimal
costMoney	BigDecimal
costOutStorage	BigDecimal
costOutStorageMeas	String
costOutStorageUom	String
costWhStorage	BigDecimal
costWhStorageMeas	String
costWhStorageUom	String
defaultAllocChrgInd	String
defaultOrderType	String
defaultSizeProfile	String
deptLevelTransfers	String
distributionRule	String
duplicateReceivingInd	String
increaseTsfQtyInd	String
intercompanyTransferBasis	String
invHistLevel	String
locActivityInd	String
locDlvryInd	String
lookAheadDays	BigDecimal
maxWeeksSupply	BigDecimal
ordWorksheetCleanUpDelay	BigDecimal
racRtvTsfInd	BigDecimal
rejectStoreOrdInd	String
replOrderDays	String
rtvNadLeadTime	BigDecimal
rtvUnitCostInd	BigDecimal
shipRcvStore	String
shipRcvWh	String
storageType	String
storePackCompRcvInd	String
wfDefaultWh	String
targetRoi	BigDecimal
tsfAutoCloseStore	BigDecimal
tsfAutoCloseWh	String
tsfCloseOverdue	String
simForceCloseInd	String
tsfForceCloseInd	String
tsfOverReceiptInd	String
tsfMdStoreToStoreSndRcv	String
tsfMdStoreToWhSndRcv	String
tsfMdWhToStoreSndRcv	String
tsfMdWhToWhSndRcv	String
tsfPriceExceedWacInd	String
ssAutoCloseDays	String
wsAutoCloseDays	BigDecimal
swAutoCloseDays	BigDecimal
wwAutoCloseDays	BigDecimal
wfOrderLeadDays	BigDecimal
whCrossLinkInd	BigDecimal
wrongStReceiptInd	String

JSON Structure:

{
    "links": [],
    "allocMethod": "P",
    "applyProfPresStock": "N",
    "autoRcvStore": "Y",
    "closeOpenShipDays": 3,
    "costMoney": 7.5,
    "costOutStorage": 1.5,
    "costOutStorageMeas": "P",
    "costOutStorageUom": null,
    "costWhStorage": 1.5,
    "costWhStorageMeas": "P",
    "costWhStorageUom": null,
    "defaultAllocChrgInd": "Y",
    "defaultOrderType": "WAVE",
    "defaultSizeProfile": "N",
    "deptLevelTransfers": "Y",
    "distributionRule": "PRORAT",
    "duplicateReceivingInd": "N",
    "increaseTsfQtyInd": "N",
    "intercompanyTransferBasis": "T",
    "invHistLevel": "A",
    "locActivityInd": "Y",
    "locDlvryInd": "Y",
    "lookAheadDays": 7,
    "maxScalingIterations": null,
    "maxWeeksSupply": 5,
    "ordWorksheetCleanUpDelay": 1,
    "racRtvTsfInd": "A",
    "rejectStoreOrdInd": "N",
    "replOrderDays": 3,
    "rtvNadLeadTime": 1,
    "rtvUnitCostInd": "A",
    "shipRcvStore": "Y",
    "shipRcvWh": "Y",
    "storageType": "W",
    "storePackCompRcvInd": "Y",
    "wfDefaultWh": 1212,
    "targetRoi": 7,
    "tsfAutoCloseStore": "Y",
    "tsfAutoCloseWh": "Y",
    "tsfCloseOverdue": "Y",
    "simForceCloseInd": "NL",
    "tsfForceCloseInd": "SL",
    "tsfOverReceiptInd": "NL",
    "tsfMdStoreToStoreSndRcv": "S",
    "tsfMdStoreToWhSndRcv": "S",
    "tsfMdWhToStoreSndRcv": "S",
    "tsfMdWhToWhSndRcv": "S",
    "tsfPriceExceedWacInd": "Y",
    "ssAutoCloseDays": 1,
    "wsAutoCloseDays": 1,
    "swAutoCloseDays": 1,
    "wwAutoCloseDays": 1,
    "wfOrderLeadDays": null,
    "whCrossLinkInd": "Y",
    "wrongStReceiptInd": "Y",
    "hyperMediaContent": {
        "linkRDO": []
    }
}

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
INV_MOVE_UNIT_OPTIONS	Yes	No	No	No
JOB_AUDIT_LOGS	No	Yes	No	No
JOB_AUDIT_PAYLOAD	No	Yes	No	No

Get Procurement System Options

Business Overview

Retrieve Merchandising's Procurement Unit Options.

Service Type

GET

ReST URL

/Common/POSysOps

Input Parameters

N/A

Output

ProcurementUnitOptionsRDO

Parameter Name	Data Type
backpostRcaRuaInd	String
calcNegativeIncome	String
copyPoCurrRate	String
costLevel	String
creditMemoLevel	String
dealAgePriority	String
dealLeadDays	BigDecimal
dealTypePriority	String
deptLevelOrders	String
ediCostOverrideInd	String
expiryDelayPreIssue	BigDecimal
genConsignmentInvcFreq	String
genConInvcItmSupLocInd	String
latestShipDays	BigDecimal
ordApprCloseDelay	BigDecimal
ordApprAmtCode	String
ordAutoClosePartRcvdInd	String
ordPartRcvdCloseDelay	BigDecimal
orderBeforeDays	BigDecimal
orderExchInd	String
otbSystemInd	String
rcvCostAdjType	String
reclassApprOrderInd	String
redistFactor	BigDecimal
softContractInd	String
wacRecalcAdjInd	String

JSON Structure:

{
    "links": [],
    "backpostRcaRuaInd": "N",
    "billToLoc": "1000",
    "calcNegativeIncome": "N",
    "copyPoCurrRate": null,
    "costLevel": "DNN",
    "creditMemoLevel": "D",
    "dealAgePriority": "O",
    "dealLeadDays": 1,
    "dealTypePriority": "P",
    "deptLevelOrders": "N",
    "ediCostOverrideInd": "Y",
    "expiryDelayPreIssue": 30,
    "genConsignmentInvcFreq": "M",
    "genConInvcItmSupLocInd": "I",
    "latestShipDays": 30,
    "ordApprCloseDelay": 1,
    "ordApprAmtCode": "C",
    "ordAutoClosePartRcvdInd": "N",
    "ordPartRcvdCloseDelay": 1,
    "orderBeforeDays": 5,
    "orderExchInd": "N",
    "otbSystemInd": "N",
    "rcvCostAdjType": "F",
    "reclassApprOrderInd": "Y",
    "redistFactor": 2,
    "softContractInd": "Y",
    "wacRecalcAdjInd": "N",
    "hyperMediaContent": {
        "linkRDO": []
    }
}

Table Impact

TABLE	SELECT	INSERT	UPDATE	DELETE
PROCUREMENT_UNIT_OPTIONS	Yes	No	No	No
JOB_AUDIT_LOGS	No	Yes	No	No
JOB_AUDIT_PAYLOAD	No	Yes	No	No