Calling the Business Documents API

Calls to the Business Documents API must be authorized. Before making an API request, make sure you have received the authorization token. For more information, see Getting API Authorization Data.

• Authorizing in the Business Documents API
• Calling the Business Documents API:
• Calling the API at the Account Level
• Calling the API at the Business Unit Level

Authorizing in the Business Documents API

To get authorized in the Business Documents API:

1. Go to the Business Documents API:
   https://api-docs.petrosoft.cloud/?service=aws_integration_service
2. Click the Authorize button.

   

3. In the Available authorizations window, enter the authorization token. Take the value from the access_token parameter. For more information, see Getting the Authorization Token.
4. Click Authorize.

   

5. Make sure all authorize icons are locked. It means that you have been successfully authorized in the API.

   

Calling the Business Documents API

Depending on the level at which you are going to receive the data, you can call API in the following ways:

• At the account level
• At the business unit level

Calling the Business Documents API at the Account Level

To receive the documents via the Business Documents API at the account level:

1. Select the type of the documents you need.
1. Expand the /account-level-resources endpoint.
2. Click Try it out.
3. In the Parameters section > Document type identifier list, select the documentType and click Execute.
   The following document types can be selected:

• price-book-item
• categories
• departments
• price-groups
• promo-groups
• item-tags

  

  For more information about the XML documents exported depending on the selected Document type identifier, see Exported XML Files.

4. In the Responses section > Response body field, check the list of available resources.

   

   You will need to use a certain resource value without the quotes. For example, master-data/20211026/ from the first line in the image above.

2. Request the list of available documents.
1. Expand the /business-documents endpoint.
2. Click Try it out.
3. In the Parameters section > Resource identifier field, enter the resource value received at the Step 1.d. above and click Execute.

   

4. In the Responses section > Response body field, check the list of available documents.

   

   You will need to use the path value without the quotes. For example, master-data/20211026/price-book-item_20211026T044006-781024751.zip from the first line in the image above.

3. Receive a certain document.
1. Expand the /business-document endpoint.
2. Click Try it out.
3. In the Parameters section > Path to final document field, enter the path value received at the Step 2.d. above and click Execute.

   

4. In the Responses section, Curl and Request URL fields, receive the final destination from where the requested document can be downloaded.

   

Calling the Business Documents API at the Business Unit Level

You can receive the documents at the following business levels:

• At the station (location) level: Prepare the station (location) identifier as the input data.
• At the company level: Prepare the company identifier as the input data.

To learn how to retrieve the station (location) or company identifiers from CStoreOffice®, see Preparing the Input Parameters for API Request.

To receive the documents via the Business Documents API at the business unit level:

1. Select the type of the documents you need.
1. Expand the /business-unit-level-resources endpoint.
2. Click Try it out.
3. In the Parameters section:
1. In the Document type identifier list, select the documentType. The following document types can be selected:
   - cash-reconcilation
   - cost-of-goods-sold
   - general-journal-report
   - inventory-item
   - invoice
   - lottery-sale
   - lottery-purchase
   - pos-journal-report
   - report-exported
   - shift_fuel-grade-movement
   - shift_item-sales-movement
   - shift_merchandise-code-movement
   - shift_miscellaneous-summary-movement
   - store-purchase
   - fuel-products-cost-of-goods-sold
   - maintenance-report
   - fuel-invoice

2. In the Unique identifier of company or location field, enter the company or station (location) identifier value.
3. Click Execute.

   

   For more information about the XML documents exported depending on the selected Document type identifier, see Exported XML Files.

4. In the Responses section > Response body field, check the list of available resources.

   

   You will need to use a certain resource value without the quotes. For example, 2879/cost-of-goods-sold-data/20211023/ from the first line in the image above.

2. Request the list of available documents.
1. Expand the /business-documents endpoint.
2. Click Try it out.
3. In the Parameters section > Resource identifier field, enter the resource value received at the Step 1.d. above and click Execute.

   

4. In the Responses section > Response body field, check the list of available documents.

   

   You will need to use the path value without the quotes. For example, 2879/cost-of-goods-sold-data/20211023/cost-of-goods-sold_20211023T000000.zip from the first line in the image above.

3. Receive a certain document.
1. Expand the /business-document endpoint.
2. Click Try it out.
3. In the Parameters section > Path to final document field, enter the path value received at the Step 2.d. above and click Execute.

   

4. In the Responses section, Curl and Request URL fields, receive the final destination from where the requested document can be downloaded.

   

Result Pagination

Results returned at the business unit level are broken into pages. By default, the API returns 500 items per page, so it is possible that the single call may not contain the complete data. To check the number of items returned by the API and the total number of items, see the count and totalCount parameters of the response.

{
    "documents": [
        ...
    ],
    "count": 500,
    "totalCount": 700
}

To retrieve the missing data:

• Increase the number of items returned in the response by adjusting the limit API parameter.

curl --location 'https://business-documents-api.petrosoft.cloud/business-unit-level-resources?documentType=shift_fuel-grade-movement&businessUnitId=1&limit=800'

• Specify the starting item using the start parameter to continue from where the previous response ended.

curl --location 'https://business-documents-api.petrosoft.cloud/business-unit-level-resources?documentType=shift_fuel-grade-movement&businessUnitId=1&start=500'