I320

DataRetrievalRESTAPIAdvanced

View:
2025R17 lessons 3 parts

I320: DataRetrievalRESTAPIAdvanced

Version: 2025R1
Category: Integration

How to Use This Course

External systems can use Acumatica ERP integration interfaces to access the business functionality and data of
Acumatica ERP. Acumatica ERP provides the following integration interfaces:
  • The Open Data (OData) protocol
  • The contract-based REST API
  • The screen-based SOAP API This course shows advanced techniques of the data retrieval with the contract-based REST API. This course does not cover the implementation of the integration scenarios with the other interfaces. The basic information about the data retrieval through the contract-based REST API is available in the I310 Data Retrieval with REST API Basics training course, which is a prerequisite for this course. The information about the screen-based SOAP API is available in Working with the SOAP API. The basic information about the data retrieval through the OData protocol is available in the I300 Data Retrieval with OData training course. The course is intended for developers who need to create applications that interact with Acumatica ERP. The course is based on a set of examples of web integration scenarios that demonstrate the processes involved in developing a client application that uses Acumatica ERP REST API. The course gives you ideas about how to develop your own applications by using the contract-based REST API. Aer you complete all the lessons of the course, you will be familiar with the advanced techniques of data retrieval through the Acumatica ERP contract-based REST API.

What the Course Prerequisites Are

To complete this course, you should be familiar with the basic principles of data retrieval with the Acumatica ERP
integration services. We recommend that you complete the I310 Data Retrieval with REST API Basics training course
before you begin this course.

What Is in a Part

The first part of the course explains how to authorize a third-party application to work with the Acumatica ERP
integration services.
The other parts of the course are dedicated to the implementation of particular web integration scenarios that you
may need to implement in a third-party application that integrates an external system with Acumatica ERP.
Each part of the course consists of lessons you should complete.

What Is in a Lesson

Each lesson is dedicated to a particular web integration scenario that you can implement by using the contract-
based REST API. Each lesson consists of a brief description of the web integration scenario and examples of the
implementation of this scenario.

Where the Source Code Is

You can find the Postman collection with the requests illustrated in this course in the
IntegrationDevelopment\I320 folder of the Help-and-Training-Examples repository in Acumatica GitHub.

What the Documentation Resources Are

The complete Acumatica ERP and Acumatica Framework documentation is available at https://help.acumatica.com/
and is included in the Acumatica ERP instance. While viewing any form used in the course, you can click the Open

How to Use This Course | 5

Help button in the top pane of the Acumatica ERP screen to bring up a form-specific Help menu; you can use the links on this menu to quickly access form-related information and activities and to open a reference topic with detailed descriptions of the form elements.

Which License You Should Use

For the educational purposes of this course, you use Acumatica ERP under the trial license, which does not require activation and provides all available features. For the production use of the Acumatica ERP functionality, an administrator has to activate the license the organization has purchased. Each particular feature may be subject to additional licensing; please consult the Acumatica ERP licensing policy for details. Company Story and MyStoreIntegration Application | 6

Company Story and MyStoreIntegration Application

In this course, you will simulate the integration of Acumatica ERP with the online store of a small retail company, MyStore. This company is a single business entity that has no branches or subsidiaries. MyStore uses Acumatica ERP for customer management, sales order processing, and payment collection. MyStore plans to extend its business and start selling goods online. MyStore needs to investigate the options available in Acumatica ERP for integration with eCommerce applications. In the first stage of implementation, the integration application, which MyStore is developing, should retrieve information about stock items, sales orders, and payments from Acumatica ERP. In the second stage of implementation, the integration application should submit information about customers, sales orders, and payments from the online store to Acumatica ERP. This course covers only the first stage of implementation. The second stage is covered in the I330 Data Manipulation with REST API training course. The MyStoreIntegration application will integrate Acumatica ERP with the online store of the MyStore company. For the implementation of the MyStoreIntegration application, the MyStore company can use the contract-based REST API. The OData protocol can be used only for the implementation of the data retrieval part of the MyStoreIntegration application, while the data submission should be performed by other integration interfaces because the data submission is not possible through OData. This implementation is outside of the scope of this course. The following diagram shows how the MyStoreIntegration integration application fits in the integration of the MyStore online store with Acumatica ERP.

Figure: Integration of the MyStore online store and Acumatica ERP

Integration Requirements

At the first stage of implementation, the MyStoreIntegration application should implement integration with Acumatica ERP to support the following usage scenarios in the online store:

  • A registered customer should be able to view all of this customer's purchases.
  • A registered customer should be able to view all of this customer's payments.
  • A potential customer should be able to view the image of any selected item. In this course, you do not implement the online store application itself; instead, you implement the integration part between the online store and Acumatica ERP. The integration part provides the support for the listed scenarios in the online store application. (The implementation of the online store application is outside of the scope of this course.) Initial Configuration | 7

Initial Configuration

You need to perform the prerequisite actions before you start to complete the course.

  1. Make sure that the environment that you are going to use conforms to the System Requirements for the Acumatica ERP Installation.
  2. Make sure that the Web Server (IIS) features that are listed in Configuration of IIS Web Server Features are turned on.
  3. Deploy an instance of Acumatica ERP 2025 R1 with the name MyStoreInstance and a tenant that contains the T100 data. If you have completed the I310 Data Retrieval with REST API Basics training course, you can use the instance that you have deployed for this course. For information on how to deploy the instance for the training course, see Deploying an Acumatica ERP Instance for the Training Course.
  4. Make sure the Postman application is installed on your computer. To download and install Postman, follow the instructions on https://www.postman.com/downloads/.
  5. Make sure that you have HTTP access to the Acumatica ERP instance from the computer where you work with the course.
  6. Because in the examples of this course you will use the OAuth 2.0 authorization, configure HTTPS on the Acumatica ERP website, as described in Configuring a Website for HTTPS. If you do not want to use OAuth 2.0 authorization, your application can use the API methods for the sign-in and sign-out (which were described in the I310 Data Retrieval with REST API Basics training course) and interact with Acumatica ERP via HTTP.

Deploying an Acumatica ERP Instance for the Training Course

         Instead of deploying a new instance, you can use the Acumatica ERP instance that you have deployed
         for the I310 Data Retrieval with REST API Basics training course.

You deploy an Acumatica ERP instance and configure it as follows:

  1. Open the Acumatica ERP Configuration wizard and deploy a new application instance as follows: a. On the Database Configuration page of the Acumatica ERP Configuration wizard, type the name of the database: MyStoreInstance. b. On the Tenant Setup page, set up one tenant with the T100 data inserted by specifying the following settings:
  • Tenant Name: MyStore
  • New: Selected
  • Insert Data: T100
  • Parent Tenant ID: 1
  • Visible: Selected The system creates a new Acumatica ERP instance, adds a new tenant, and loads the selected data.
  1. Sign in to the new tenant by using the following credentials:
  • Username: admin
  • Password: setup Change the password when the system prompts you to do so. Initial Configuration | 8
  1. Click the username in the top right corner of the Acumatica ERP screen and click My Profile. On the General Info tab of the User Profile (SM203010) form, which opens, select MYSTORE in the Default Branch box; then click Save on the form toolbar. In subsequent sign-ins to this account, you will be signed in to this branch.

Configuring a Website for HTTPS

In the examples of this guide, you will use the secure connection between the API client application and Acumatica ERP. A secure connection between the client application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is required for the authorization of the client application through OAuth 2.0. Therefore, you have to set up the Acumatica ERP website for HTTPS, as described in this topic.

Configuring a Website for HTTPS

As the Microso IIS documentation states, the general steps for configuring SSL for a site include the following:

  1. You obtain the needed certificate. (For the purposes of completing the course, you can create a self-signed server certificate.)
  2. You create an SSL binding on a site.
  3. You test the website by making a request to the site.
  4. Optional: You configure the SSL options.
    To complete the examples of this guide, you should create a self-signed certificate and configure SSL binding as follows:
  5. Create a self-signed certificate by doing the following: a. In the Control Panel, open Administrative Tools > Internet Information Services (IIS) Manager. b. In the Features View, double-click Server Certificates, as shown in the following screenshot.
          Figure: IIS Manager: The Server Certificates icon

   c. Click the Create Self-Signed Certificate link in the Actions pane (see the following screenshot).

Initial Configuration | 9

  Figure: IIS Manager: The Create Self-Signed Certificate link

d. Enter a name for the new certificate and click OK. 2. Do the following to create an SSL binding: a. Select a site in the tree view and click the Bindings link in the Actions pane (see the following screenshot).

  Figure: IIS Manager: Bindings link

b. In the Site Bindings dialog box, click Add to add your new SSL binding to the site. c. In the Type drop-down list, select https. d. Select the self-signed certificate you created and click OK to close the dialog box. 3. In the Actions pane, under Browse Website, click the link associated with the binding you just created (Browse *:443 (https)), as the following screenshot shows. Initial Configuration | 10

Figure: Opening the HTTPS website

The browser will display an error page because the self-signed certificate was issued by your computer rather than by a trusted certificate authority. 4. Click the link to proceed with this website and disregard the error. The HTTPS website opens. Part 1: Authorization of the Application to Work with the Web Service | 11

Course Structure

Part 1: Authorization of the Application to Work with the

Part 2: Performance Optimization

Part 3: Retrieval of Attachments