Illinois Webservices Gateway Transmission Guide

1. Introduction
2. Setting Up a MyDevPortal Web Logon
3. Obtaining Your Certification
4. XML Transmission Services
5. SendSubmission
6. Get Acknowledgement
7. Get New Acknowledgements

This guide describes the interfaces used to communicate with the Illinois Department of Revenue for the transmission of returns via web service. Returns are formatted as eXstensible Markup Language (XML) documents and submitted by passing a streaming object into the body of the web service call. The actual transmission is handled with a Representational State Transfer (REST) POST request.

eXstensible Markup Language (XML)

XML is used to tag and define the data and its values. Descriptions of how to properly form this XML document are contained within the specific development guide for the return type being submitted and can be found on our website: Electronic Transmitters and Software Developers.

Representational State Transfer (REST)

REST is the messaging protocol being used for exchanging the information between your systems and our web service. To transmit information, an envelope is sent to the web service to be parsed. Upon processing, a response envelope is returned to verify the results of the transmission. This response does not inherently indicate the state of the return processing; it functions to either acknowledge a successful transmission or explain why a transmission failed. The address these calls are made against can be found on MyDevPortal for both real and certification-only calls.

MyDevPortal

Illinois’ MyDevPortal is the source for documentation, credential, and registration related requests for this type of transmission. To participate and use the web services in this guide, you must obtain a MyDevPortal web logon, credentials, and certification.

Registration

A MyDevPortal web logon is required to access the tools needed for development and testing of your transmission software. If you do not have a MyDevPortal web logon, reference the following steps to create one. MyDevPortal will be made available in late December 2024. Upon the Portal being available, registration will be required for all transmitters, software developers and taxpayers utilizing the XML schema for filing.

To participate in our testing opportunity prior to this availability, please contact us at rev.excisetaxefp@illinois.gov.

To register a MyDevPortal web logon and credential:

1. Open the MyDevPortal webpage.
2. Click the Register for electronic filing hyperlink. This begins the account registration process required for using the new XML transmission systems.
3. After the registration process is complete, follow the instructions in the email that you receive to finish setting up your web logon.
4. Once your web logon is created, log into MyDevPortal. An alert is displayed at the top of the screen with instructions for setting up your initial web service credential.
5. Follow the instructions to set up your credential. The username for your web service credential is the same as your web logon username but the password can be different.

Available Documentation

After logging into the MyDevPortal page, you can view your credential status and a few other account management tools. You can also see additional information about the APIs and services you have access to. This includes necessary URLs, available services for each API, example JSON response formats, and parameter documentation for each service call. To access this information, click the credential with access to the APIs you are interested in.

Figure 1: View the Status of Available Credentials

To use the production return services, you must connect and make test calls to each of the web services you intend to use against the URL labeled Test URL. For each service, there is a scenario with expected values to be input. You must make a successful call to the Test URL with the expected parameter values to pass the scenario. The scenarios, when passed, automatically update to reflect that you can now make calls to that service using the production URL.

Figure 2: Available Services and Certification Statuses

To see the parameter values expected to pass a scenario, click the service in the list for which you want to make a test call. For example, we can click the SendSubmission service in Figure 2. Clicking the service displays the tabs shown in Figure 3. The important tabs for initial development and certification are the Scenarios tab and the two documentation tabs.

Figure 3: Available Tabs in the SendSubmission Service

On the Scenarios tab, you will see any scenarios that need to be passed to gain or renew your credential. Clicking the scenario displays a description of the expected parameter values.

Figure 4: Expected Parameter Values for the Test Scenario

You can view more details on the parameters by returning to the Service page and viewing the Service Documentation tab. This tab displays detailed information about the URLs to be used when making your request. This includes the URL parameters, which are highlighted in red and described immediately below the URLs. A sample response format, as well as a list of all response parameters will also be presen

The XML submission itself will need to be transmitted as the request body for the Send Submission web service. For larger files, this should be a data stream as opposed to raw text. For passing the certification scenario, you will need to submit a valid XML return file for the category for which you are obtaining certification. This file does not need accurate or specific data as it will not be processed, but a submission ID must be able to be scanned from its contents.

To view information about the entire API, rather than a single service, view the API Documentation tab. From here you can download the API definition in YAML format by clicking the Open API Definition hyperlink.

Figure 5: The API’s Base URL and Links to Each Service Are Displayed on the API Documentation Tab

To use the production return services, you must connect and make test calls to each of the web services you intend to use against the URL labeled Test URL. For each service, there is a scenario with expected values to be input. You must make a successful call to the Test URL with the expected parameter values to pass the scenario. The scenarios, when passed, automatically update to reflect that you can now make calls to that service using the production URL.

Table 1.1: Return Statuses

The XML return, when acknowledged, has one of four statuses.

To use the production return services, you must connect and make test calls to each of the web services you intend to use against the URL labeled Test URL. For each service, there is a scenario with expected values to be input. You must make a succesful call to the Test URL with the expected parameter values to pass the scenario. The scenarios, when passed, automatically update to reflect that you can now make calls to that service using the production URL.

Table 2.1: URL Parameters

Table 2.2: Categories

The following is a list of currently accepted categories and schema version combinations. The filing period your return is being submitted for determines which schema version is applicable.

The Get Acknowledgement web service is used to check the status of a single submission using its submission ID as a reference key.

Table 3.1: URL Parameters

Any items in the RECEIVED status will not be marked as previously acknowledged. This will allow them to be picked up again using the Get New Acknowledgements request when they are fully processed. Any items that have been processed (ACCEPTED, ACCWARN, or REJECTED statuses) will be marked as acknowledged and will not appear again using this request.

Table 4.1: Parameters