1. REST APIs for <Sales Audit>REST APIs for Sales Audit
  2. Quick Start

Quick Start

Step 1: Consider Before You Start

Review the basics. If you are new to REST APIs, make sure you understand the basics of REST and JSON. Review Roles and Privileges. You must have the necessary security roles and privileges to use the GET, POST, PUT, and DELETE methods on your resources. Choose a REST client. REST APIs connect software programs over the HTTP protocol. You need a software client to send the HTTP requests. In our examples, we use cURL. But, cURL is not the only tool you can use. To help you choose one, see Work with your REST Client.

Step 2: Get Your Oracle Retail Sales Audit Cloud Account Info

To make a REST HTTP request, you need to gather a few bits of information:

  • REST Server URL. Typically, the URL of your Oracle Cloud service. For example, https://cust-env-mfcs-mcs.oracleindustry.com

  • IDCS or OCI IAM OAuth Client ID and secret, Access Token URL and scope to obtain Oauth 2.0 Access Token

    OR

  • (Optionally, in case Basic authorization mode is to be used) User name and password. An Oracle Cloud service user with permissions to access the resources you are using.

Step 3: Configure Your Client

With the information gathered so far, you are ready to configure your client to send a REST HTTP request.

  1. Construct the request URL. The URL consists of the server name and the resource path:

    https://<server>/<resource-path>The <server> is the REST Server URL from Step 2, as in: https://cust-env-mfcs-mcs.oracleindustry.com

    The <resource-path> is the relative path or endpoint to the resource you are working with. You can pick any endpoint in All REST Endpoints. For example, we are interested in the a store day collection resource:

    /ResaReSTServices/services/private/Resa/getStoreDays?store=1000000003&pageSize=5&recordType=ALLCombine the REST Server URL and, in this example, the getStoreDays resource path and your request URL is complete.

    https://cust-env-mfcs-mcs.oracleindustry.com/ResaReSTServices/services/private/Resa/getStoreDays?store=1000000003&pageSize=5&recordType=ALL

  2. Choose the Authorization method

    1. Obtain Oauth Access Token using details obtained in Step 2. This is preferred way of authorization. 
      curl  -u <client id>:<client secret> -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<IDCS_BASE_URL>/oauth2/v1/token -d 'grant_type=client_credentials&scope=rgbu:merch:system'
      This will return a json payload containing access token like below 
      {"access_token":"<access token>","token_type":"Bearer","expires_in":3600}

      Include this access token in the 'Authorization' header of the request. If you are using curl, use--header or -H as follows:

      --header 'Authorization: Bearer <access token>'

      Note:

      This token is valid for one hour. After it expires repeat this step to obtain fresh access token.

      OR

    2. Provide your account information. Include your user name and password (from Step 2) in the client. For example, if you are using cURL, you can specify your account information using the -u cURL command as follows: 

      -u <username:password>

    3. In Clients like Postman both Basic Auth and Oauth token based authorization are simplified. For getting Oauth token, go to Authorization tab and select Oauth 2.0 from the drop down menu. Fill up the URL, Client Id, secret and scope and click on Get New Access Token. Subsequently click on Proceed and Use Token in the next dialog.


      Authorization Tab ??? Get New Access Token

      For Basic Auth, go to the Authorization tab and select Basic from the drop down menu. Fill in your username and password.


      Authorization Tab ??? Basic Auth, Username and Password

    4. Note:

      When using basic authorization, users should belong to groups that are authorized to access the service end points. For OAuth, oauth client needs to be created with the allowed scope. This needs to be done one time during provisioning the environment.

  3. Set other headers like Content-Type, Accept, Accept-Language to override default. In curl use --header 'Key: Value' (or -H 'Key:Value') to set these headers. For example: 
    --header 'Content-Type: application/json' --header 'Accept-Language: en-US'.

    Below are the acceptable values of commonly used headers:

    • Accept - application/json or application/xml

    • Content-Type - application/json or application/xml

    • Accept-Language - ISO code of one of the supported languages.

Step 4: Send an HTTP Request

You are almost done. Now that your authentication and authorization are set, you are ready to send a test HTTP request. Continuing with our example, you want to get all the information about the structure of the items details object in REST. You can do this using the describe action in cURL: 

curl --request GET 'https://cust-env-mfcs-mcs.oracleindustry.com/ResaReSTServices/services/private/Resa/getStoreDays?store=1000000003&pageSize=5&recordType=ALL' \
--header 'Accept: application/json' \
--header 'Accept-Language: en-US' \
--header 'Authorization: Bearer <access token>'

or

curl --request GET 'https://cust-env-mfcs-mcs.oracleindustry.com/ResaReSTServices/services/private/Resa/getStoreDays?store=1000000003&pageSize=5&recordType=ALL' \
--header 'Accept: application/json' \
--header 'Accept-Language: en-US' \
-u username:password

This is how the request looks in Postman:


GET Request

If your request for information about the store day is successful, you receive a response with a body similar to the following example.

{
    "totalRecordCount": 48,
    "results": [
        {
            "store": 1000000003,
            "storeDaySeqNo": 11000005,
            "auditors": null,
            "businessDateDisplay": "14-May-2020 00:00:00",
            "businessDate": 1589414400000,
            "storeName": "Intermix Canada",
            "chain": 6489,
            "chainName": "CAD chain",
            "dataStatus": "P",
            "dataStatusDesc": "Partially Loaded",
            "auditStatus": "R",
            "auditStatusDesc": "Re-Totaling/Auditing Required",
            "auditChangedDatetimeDisplay": "01-Apr-2021 11:56:17",
            "auditChangedDatetime": 1617278177000,
            "fuelStatus": null,
            "fuelStatusDesc": null,
            "overShortAmount": 388.65,
            "currencyCode": "CAD",
            "errorCount": 0,
            "transactionCount": 4,
            "loadedFileCount": 3,
            "expectedFileCount": null,
            "links": [],
            "hyperMediaContent": {
                "linkRDO": []
            }
        },
        {
            "store": 1000000003,
            "storeDaySeqNo": 15000014,
            "auditors": null,
            "businessDateDisplay": "28-May-2020 00:00:00",
            "businessDate": 1590624000000,
            "storeName": "Intermix Canada",
            "chain": 6489,
            "chainName": "CAD chain",
            "dataStatus": "R",
            "dataStatusDesc": "Ready for Import",
            "auditStatus": "U",
            "auditStatusDesc": "Unaudited",
            "auditChangedDatetime": null,
            "fuelStatus": null,
            "fuelStatusDesc": null,
            "overShortAmount": 0,
            "currencyCode": "CAD",
            "errorCount": 0,
            "transactionCount": 0,
            "loadedFileCount": null,
            "expectedFileCount": null,
            "links": [],
            "hyperMediaContent": {
                "linkRDO": []
            }
        },
        {
            "store": 1000000003,
            "storeDaySeqNo": 17000014,
            "auditors": null,
            "businessDateDisplay": "01-Jun-2020 00:00:00",
            "businessDate": 1590969600000,
            "storeName": "Intermix Canada",
            "chain": 6489,
            "chainName": "CAD chain",
            "dataStatus": "R",
            "dataStatusDesc": "Ready for Import",
            "auditStatus": "U",
            "auditStatusDesc": "Unaudited",
            "auditChangedDatetime": null,
            "fuelStatus": null,
            "fuelStatusDesc": null,
            "overShortAmount": 0,
            "currencyCode": "CAD",
            "errorCount": 0,
            "transactionCount": 0,
            "loadedFileCount": null,
            "expectedFileCount": null,
            "links": [],
            "hyperMediaContent": {
                "linkRDO": []
            }
        },
        {
            "store": 1000000003,
            "storeDaySeqNo": 18000014,
            "auditors": null,
            "businessDateDisplay": "04-Jun-2020 00:00:00",
            "businessDate": 1591228800000,
            "storeName": "Intermix Canada",
            "chain": 6489,
            "chainName": "CAD chain",
            "dataStatus": "R",
            "dataStatusDesc": "Ready for Import",
            "auditStatus": "U",
            "auditStatusDesc": "Unaudited",
            "auditChangedDatetime": null,
            "fuelStatus": null,
            "fuelStatusDesc": null,
            "overShortAmount": 0,
            "currencyCode": "CAD",
            "errorCount": 0,
            "transactionCount": 0,
            "loadedFileCount": null,
            "expectedFileCount": null,
            "links": [],
            "hyperMediaContent": {
                "linkRDO": []
            }
        },
        {
            "store": 1000000003,
            "storeDaySeqNo": 19000014,
            "auditors": null,
            "businessDateDisplay": "05-Jun-2020 00:00:00",
            "businessDate": 1591315200000,
            "storeName": "Intermix Canada",
            "chain": 6489,
            "chainName": "CAD chain",
            "dataStatus": "R",
            "dataStatusDesc": "Ready for Import",
            "auditStatus": "U",
            "auditStatusDesc": "Unaudited",
            "auditChangedDatetime": null,
            "fuelStatus": null,
            "fuelStatusDesc": null,
            "overShortAmount": 0,
            "currencyCode": "CAD",
            "errorCount": 0,
            "transactionCount": 0,
            "loadedFileCount": null,
            "expectedFileCount": null,
            "links": [],
            "hyperMediaContent": {
                "linkRDO": []
            }
        }
    ],
    "links": [
        {
            "href": "https://cust-env-mfcs-mcs.oracleindustry.com/ResaReSTServices/services/private/Resa/getStoreDays?store=1000000003&pageSize=5&recordType=ALL",
            "rel": "self",
            "type": "GET",
            "methodType": null
        },
        {
            "href": "https://cust-env-mfcs-mcs.oracleindustry.com/ResaReSTServices/services/private/Resa/getStoreDays?pageNumber=2&recordType=ALL&pageSize=5&store=1000000003",
            "rel": "next",
            "type": "GET",
            "methodType": null
        }
    ],
    "hyperMediaContent": {
        "linkRDO": [
            {
                "href": "https://cust-env-mfcs-mcs.oracleindustry.com/ResaReSTServices/services/private/Resa/getStoreDays?store=1000000003&pageSize=5&recordType=ALL",
                "rel": "self",
                "type": "GET",
                "methodType": null
            },
            {
                "href": "https://cust-env-mfcs-mcs.oracleindustry.com/ResaReSTServices/services/private/Resa/getStoreDays?pageNumber=2&recordType=ALL&pageSize=5&store=1000000003",
                "rel": "next",
                "type": "GET",
                "methodType": null
            }
        ]
    }
}

Congratulations! Now you are ready to do more with your REST APIs.