Sage 300 API

1. Mange payroll companies.
2. Manage frequencies (Pay run rules).
3. Import Component Codes (Payroll codes)
4. Import or update payroll employees Information.
5. Import pay run period setup in Sage 300.
6. Generate payroll export hours.
7. Store history of the exported hours to payroll with result and identification codes.
8. API Logs
9. Application Service Options

Run the API application by clicking on the Eco Sage 300 API shortcut on the desktop or running the application called Sage300API32 or Sage300APIMs.

1. Select the Settings - Sage 300 Tab on the Eco Time Sage 300 API Client :

   

   1. Server: The API server URL or IP address and port number as supplied by the client. The current default is the current Sage 300 standard.
   2. Authentication Server: The API server URL or IP address and port number as supplied by Sage 300. The current default is the current Sage 300 standard.
   3. API Key: The API Key provided by Sage to access the API. Use this if "Authenticate Using Key Only" has been Enabled. Eco Time defaults to API Key authentication.
   4. Client Username: The client code supplied and generated in the customer's Sage 300 system. Note: The Username is only required if "Authenticate Using Key Only" has NOT been Enabled on the Sage API. Eco Time defaults to the API Key.
   5. Client Password: The client secret supplied and generated in the customer's Sage 300 system. Note: The Password is only required if "Authenticate Using Key Only" has NOT been Enabled on the Sage API. Eco Time defaults to the API Key.
   6. Authorization Token: The token is provided after successful authentication by Sage 300 using the client ID and client secret.
   7. API Scope: Leave the default as api.full_access.
   8. Receive Format: The receive format is json and for information purposes only.
   9. Working Company ID: The current selected company's employee payroll hours will be exported to Sage 300. This is a lookup field. Most customer have one in Sage 300. The companies table must be manually populated before the Authentication API is run.
   10. Payroll Period: The current selected payroll period for which employee payroll hours will be exported to Sage 300. This is a lookup field. The Pay Runs table is populated when the Pay Runs API is run.
   11. Stop timed events: This stops time based events. Typically, useful when doing fault finding or analysing data on the client response screen. The generate payroll hours and upload payroll hours is always a manual event, requiring user input via the web interface or desktop application.
   12. A web interface option is available. More information can be found here.
        
2. Select the Settings - API Tab on the Eco Time Sage 300 API Client

   

   1. Client API Type: This setting defaults to "Sage 300 People", and cannot be changed.
   2. Client API Mode: The Production option sets the api to interface with the customer's live Sage 300 data. The QAS option sets the api to interface with the customer's test Sage 300 data. Please note, each mode has its own settings.
   3. Client API Status: The two options are Enabled or Disabled. The setting has to be "Enabled" to make the Sage 300 options available in Eco Time's Web Browse menu.
   4. Version Number: This is the API version and cannot be changed,
   5. Log History Records: The log history will be truncated at this number of records (default 2000).
   6. Employee Identifier: Set to identify if the employees in Sage 300 are identified by Eco Time's employee number or payroll number.
       
3. Select the Settings - Syncronise Tab on the Eco Time Sage 300 API Client

   

   1. Last Sync Date: The last date all companies, frequencies, pay runs and employees were synced.
   2. Last Sync Time: The last time all companies, frequencies, pay runs and employees were synced.
   3. 1st Sync Time: The 1st time of day all companies, frequencies, pay runs and employees will be synced.
   4. 2nd Sync Time: The 2nd time of day all companies, frequencies, pay runs and employees will be synced.
   5. Purge Unverified Employees after (Days) : Employees in the list, which were not found in the Sage 300 system, will be removed after this number of days.

1. After the API Client has been configured, run the application and select the Authentication tab.

   

2. A web interface option is available. More information can be found here.

3. Please Note that the "Stop timed events" check box is enabled by default on a new API installation. There is no point running timed events until the configuration has been completed.

4. Select the API button on the bottom right. This will open the API Client window.

   

5. Now Press the Post (POST) button
6. The request window is now populated with text.

   

7. To verify the connection, select the response tab.

   

8. If the response is very short, then there are the following possible errors:

   1. Server connection cannot be opened: The Sage 300 server connection details are incorrect, or a firewall is blocking the connection.
   2. 403 Unauthorized: The API operator does not have privilege to view the monitored items.
   3. 400 Bad Request: The response at the bottom will indicate {"error":"invalid_client"} which means clientid or client secret is wrong.
   4. 400 Bad Request: The response at the bottom will indicate {"error":"invalid_client"} which means clientid or client secret is wrong.
9. The features to the API methods which are available to the API operator are controlled by the Sage 300 user privileges. The specific access rights must be configure as described in the FAQ. The generic access categories include:
   1. Generic GET's
   2. General Ledgers to Access Payroll Runs
   3. Employee and Payyroll 
10. The "Do Not Process Reponse" disables any results processing. No tables will be populated. This is typically used for fault finding and in cases where you want to inspect the request packet and result packet.
11. Once you have established and tested that the Sage 300 API Client is successfully communicating with the Sage 300 API Server, the Sage 300 API Client must be loaded with the API information in the following sequence.
    1. Companies and Company Groups. Company groups are not supported. Company details must be manually entered.

       

    2. Inserting and or updating the company information displays the following update form:

       

       1. Status: Enables or disabled the company, which disabled all ap calls to the Sage server for the disabled company.
       2. Company Code: The company code is provided by the Sage consultant for the payroll company setup in sage fro example 001
       3. Site Code: Required for Sage Online hosted sites inly. The company code is provided by the Sage consultant in is in the format S99999. It can slo be deduced from the API url. It should be the page just after the base URL for example https://online.sage.co.za/S99999.
       4. Description: The company name or description.
       5. Employee group: The Eco Time employee group for this company. Only the employees' times in this group will be uploaded to payroll. 

          

       6. Override Export Settings: When enabled, the Export settings Tabs will override the payroll export codes and settings configured in Eco Time. This allows for different export settings for different payroll companies at one site. 
       7. A web interface option is available. More information can be found here.
    3. NB!! - The Working Company ID on the Settings - Sage 300 Tab must now be set.
    4. Frequencies are for reference purposes only, but they are required for the API upload of the payroll export and must be manually added. The sage consultant will provide the applicable company rules ledger setup ids and descriptions.

       

    5. Inserting and or updating the frequencies displays the following update form:

       

       1. Company ID: The company ID to which this GL code is is assigned to as provided by the Sage consultant.
       2. ID: The GL code as provided by the Sage consultant.
       3. Description: The GL code description as provided by the Sage consultant.
       4. Frequency: The frequency description as provided by the Sage consultant.
       5. Employee group: The Eco Time employee group for this frequence / payroll roll rule. Only the employees' times in this group will be uploaded to payroll, firstly filtered by the company employee group and then by this employee group.
    6. Component Codes are for reference purposes only. Although it is important that the frequency of the component codes being exported must be the same as the Pay Runs' frequency.

       

    7. NB!! - The Pay Runs must now be assigned and Eco Time payroll date. How to do this can be found here.
    8. NB!! - The Pay Periods on the Settings - Sage 300 Tab must now be set.
12. Audit and manage employee discrepancies.
    1. Updating a company's employee group:

       
       Select the change button on the companies browse opens the companies update form above.

    2. The user may assign an Eco Time employee group. This employee group will used to limit the employees in Eco Time when generating export payroll hours and uploading these to Sage 300. This is an optional field.
    3. Disabling the company will exclude all it and all its employees in Eco Time when generating export payroll hours and uploading these to Sage 300 if this company is selected as the working company.
    4. Update the employee groups for the entered frequencies / payroll rules. Only the employees' times in this group will be uploaded to payroll, firstly filtered by the company employee group and then by this employee group.
    5. Manually trigger the employee api button as per the details provided in the next section and then proceed to audit / verifiy the employees.
    6. A web interface option is available. More information can be found here.

1. Start by populating the following lists in order by pressing the API button on the respective tabs:
   1. Employees- Get Employees: The API button brings up the following popup menu:

      

      Select the "Get Employees" option by clicking on this item.

      
      The api employee table contains all the captured employees on the Sage 300 system
      The following api employees table fields will be populated

      1. ID: Internal Sage 300 Employee ID code
      2. Employee Number: Employee number captured in Sage 300.
         1. This field is used to match the Eco Time employee number and if a match is found, the Eco Time fields will be populated.
         2. If an Emp Number is not imported, no matching attempt will be made.
         3. If an Emp Number is imported, the corresponding Eco Time details will be populated in the api employee table:
            1. Eco Emp Number
            2. Eco Emp First Name
            3. Eco Emp Last Name
         4. If an Emp Number is imported, the API validates the employee surname and employee number.
            1. If employee name and surname do match, an image will appear next to the employee.
            2. If and Eco Time employee is not found in Sage 300, an error image will appear next to the employee.
            3. If employee surname does not match, an error image will appear next to the employee.
            4. The AP tries to match first names. If the first names do not match, the API tries to resolve initials or initials in combination with first names. But if this fails a warning image will appear next to theEmployee.
            5. You can mark the match indicator (see next paragraph). An exempted employee will display the exempted image .
            6. You can override the employee match indicator.
      3. firtName: Employee first name captured in Sage 300.
      4. lastName: Employee last name captured in Sage 300.
      5. Gender: Gender of employee captured in Sage 300.
      6. ID Number: Employee ID or Passport number.
      7. Eco Emp Number: Eco Time employee number matched with Sage 300.
      8. Eco First Name: Eco Time employee firstname matched with Sage 300.
      9. Eco Last Name: Eco Time employee last name matched with Sage 300.
      10. Verified Date: Date verified between API Employee's and Sage 300. If the verified date is older than today's date, then that employee does not exist in Sage 300 anymore.
      11. Import Date: Date added to the API Employee's table.
      12. A web interface option is available. More information can be found here.
           
   2. Updating an employee's matching status:

      
      Select the change button on the Employees browse opened the employe update form above.
      
      The user can override the employee's match status. Select Exempt if you will not export this employees' hours to payroll and do not require a match to be performed in the future for this employee. Select OK to save your changes.
      
      A web interface option is available. More information can be found here.

   3. Pay Runs

      
      The api Pay Runs table contains all the payroll periods setup in Sage 300.
      The following apipayrollruns table fields will be populated

      1. Description: Payroll Period Description.
      2. Is Main Run: For Eco Time reference, but Sage 300 internal use only.
      3. Pay Hours Date: This field must be updated by changing the record and entering Eco Time's corresponding payroll hours date for the payroll run. NB!!. This is a prerequisite in order to generate payroll hours and upload these to Sage 300.
      4. PayDate: For Eco Time reference, but Sage 300 internal use only.
      5. Period Start Date: For Eco Time reference, but Sage 300 internal use only.
      6. Period End Date: For Eco Time reference, but Sage 300 internal use only.
      7. RunStatus: For Eco Time reference, but Sage 300 internal use only.
      8. Run Type: For Eco Time reference, but Sage 300 internal use only.
      9. Value: For Eco Time reference, but Sage 300 internal use only.
      10. Frequency: For Eco Time reference, but Sage 300 internal use only.
      11. A web interface option is available. More information can be found here.
           
   4. Updating a payrun record with an Eco Time Payroll date:

      
      Select the change button on the companies browse opens the update companies form above.
      
      The user MUST assign an Eco Time payroll hours date to a PayRun record. The Sage 300 API uses this date to generate a payroll export hours and display history for the selected payroll run period. If this date is NOT SET, no hours will be generated or uploaded.
      
      A web interface option is available. More information can be found here.

1. Payroll Export:

   
   The API Client will generate the payroll hours to be uploaded by selecting the Generate Export button.
   The export is generated form Eco Time's payroll hours for the selected pay run's payroll date.
   The Generate Export button can be used multiple times as it will clear the last generated export and recalculate the export from EcoTiem's current payroll hours.
   Select the API button to upload the Export Hours to Sage 300.

   1. Payroll Hours: This is Eco Time's payroll hours date as setup in the Payroll Period (Pay Run) current selected.
   2. Request ID: An internal incremental rerefernce ID created by Eco Time, which is used to upload the payroll hours to Sage 300 and match reponses from Sage 300 to the transaction.
   3. Payroll No: Eco Time's payroll number. Depending on the Identifier type selected in the settings tab, this can be Eco Time's payroll number or employee number.
   4. First Name: Eco Time's employee First Name.
   5. Surname: Eco Time's employee Surname.
   6. Component Code: Payrol code as configure in Eco Time's time category setup .
   7. Input Type: Currently only "Hours" is supported.
   8. Input Value: Totals payroll hours for the time category in decimal format.
   9. Cost Centre Code: Sage300 required field. Not supported by Eco Time.
   10. Activity Code: Sage300 required field. Not supported by Eco Time.
   11. A web interface option is available. More information can be found here.
        
2. Export History

   
   Once the payroll export has been uploaded to Sage 300, the Sage 300 will respond to each component uploaded.
   The hours uploaded and the Sage 300 response is stored in the API's Export History table.
   Note: You will on see the export history for the current selected payroll run period. To see previous payroll run's history, select the appropriate payroll run period from the settings tab.

   1. Payroll Date: This is Eco Time's payroll hours date as entered for the pay run currently selected in the settings tab .
   2. Request ID: An internal incremental reference ID created by Eco Time, which is used to upload the payroll hours to Sage 300 and match reponses from Sage 300 to the transaction. This wil match the component's ID uploaded to Sage 300.
   3. PaySlip ID: For Eco Time reference, but Sage 300 internal use only.
   4. Request ID: An inte
   5. Sucess: A Yes if the upload was successful or a No if not. This is a response from Sage 300.
   6. Error: If the upload was NOT successful, this reason field will be populated. This is a reason response from Sage 300.
   7. Employee No: Eco Time's employee number. Stored for history of the original upload.
   8. Payroll No: Eco Time's employee payroll number. Stored for history of the original upload.
   9. First Name: Eco Time's employee first name. Stored for history of the original upload.
   10. Surname: Eco Time's employee Surname. Stored for history of the original upload.
   11. Component Code: Payrol code as configure in Eco Time's time category setup . Stored for history of the orrginal upload.
   12. Input Type: Currently only "Hours" is supported. Stored for history of the original upload.
   13. Input Value: Totals payroll hours for the time category in decimal format. Stored for history of the original upload.
   14. Cost Centre Code: Sage 300 required field. Not supported by Eco Time. Stored for history of the original upload.
   15. Activity Code: Sage 300 required field. Not supported by Eco Time. Stored for history of the original upload.
   16. Date Added: The date the payroll export was uploaded and a Sage 300 response was received.
   17. Date Updated: If the Payroll Export was regenerated, and uploaded, this date will be updated when a Sage 300 response was received.
   18. A web interface option is available. More information can be found here.
        

Important: The Sage 300 Api client must be running at the same location as Eco's Web Server.
The webserver passes API requests to the API client, which in turn will process the request and send a response back to the webserver.

1. Payroll Options in the Web

   

   1. When the Sage 300 API is enabled in the Desktop Client settings tab, the Sage 300 menu will become available in the web's Browse Menu.
   2. Not all the API configuration settings is available in the web in an effort to keep the user experience streamlined. Use the desktop for to change advanced settings.
   3. All changes made in the web are reflected in the desktop API and the other way around.
   4. The settings tab allows the user to set the payroll run period and working company.
   5. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
2. Employees Check in the Web

   

   1. The employee check browse contains all the captured employees on the Sage 300 system.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
3. Updating Employees in the Web

   

   1. The user can override the employee's match status. Select Exempt if you will not export this employee's hours to payroll and do not require a match to be performed in the future for this employee. Select OK to save your changes..
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
4. Payroll Companies in the Web

   

   1. The payroll companies browse contains all the captured employees on the Sage 300 system.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
5. Updating Payroll Companies in the Web

   

   1. The user may assign an Eco Time employee group. This employee group will used to limit the employees in Eco Time when generating export payroll hours and uploading these to Sage 300. This is an optional field.
   2. Disabling the company will exclude all it and all its employees in Eco Time when generating export payroll hours and uploading these to Sage 300 if this company is selected as the working company.

      

   3. When enabled, the Export settings Tabs will override the payroll export codes and settings configured in Eco Time. This allows for different export settings for different payroll companies at one site.
   4. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
6. Frequencies / Payroll Rules in the web

   

   1. The Frequencies browse should contain all the captured frequencies / payroll ruls on the Sage 300 system and must be manually added.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
7. Updating Frequencies / Payroll Rules in the web

   

   1. The Frequencies update form allowed frequencies to be manually added.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
8. Pay Run Periods in the Web

   

   1. The Pay Run browse contains all the pay run periods setup in Sage 300.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
9. Updating Pay Run Periods in the Web

   

   1. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
10. Payroll Export in the Web

    

    1. The Payroll Export browse contains generated hours extract for the current selected pay run period which can be uploaded to Sage300.
    2. This mimics the behaviour and rules of the desktop interface which can be seen here.
    3. Note: The Generate and Upload button schedules that processes on a sperate thread for processing by the Sage300 API Desktop Client.
    4. Press the refresh button to update the progress and values in the Payroll Export Browse.
        
11. Payroll Export History in the Web

    

    1. The hours uploaded, and the Sage 300 response is stored in the API's Export History table and displayed in this browse.
    2. This mimics the behaviour and rules of the desktop interface which can be seen here.

1. An API call can be manually triggered at any time by pressing the API button at the bottom of each browse.
2. An API call triggered will depend on the current tab selected (eg Events).
3. All manually triggered API calls are not automated. This means the API Client Request Window will open and you would manually have to press the Res (Get) button. During this process you must wait for the response to arrive (the resposne window is updated). Afterwards press the close button to exit the API call.
   1. API Client Request Window Request:
      
   2. API Client Request Window Response:
      
4. The API Status message at the bottom left of the browse will be updated with the current action or process.
5. Manually triggering an API is used during the configuration and setting up phase of the API.
6. It is also very helpful when doing fault finding. See the FAQ for more details about this.

1. Timed events are automated events trigger either by time or an interval duration, in other words automated API calls.
2. During timed events the API Client Request Window is hidden but the API status message is updated.
3. There are three timed events:
   1. The API is authenticated with every timed event.
   2. The employees list is synced twice a day. Once at 1am and once at 1pm.
   3. The Frequencies list is synced twice a day. Once at 1am and once at 1pm.
   4. The Pay Run list is synced twice a day. Once at 1am and once at 1pm.
4. Timed events can be disabled be selecting the "Stop timed events" check box on the Sage 300 API Window.

1. The logs browse displays general information about the API requests, responses and processes.

   

2. The log display information about:
   1. Details about the API event.
   2. If the API event was processed or rejected. If rejected, it provides a reason.
   3. When manual or timed API events were triggered.

1. In which Eco Time version is this feature available?
   From version 2024.10.21 onwards.
    
2. What information must the customer provide to setup the API?
   1. Sage Online Customer URL (some like https://online.sage.co.za/U1234.). The URL can also be a local URL.
   2. API Key (Note: The user connected to the API key must first log in to Sage as a once off. The user must first have a successful login before the token can be issued.)
   3. Site Code (It looks something like S99999 or U1234). Local sites do not require a site code.
   4. Company Code (It looks something like 001) and Company Details as per the update company details form.
   5. The Eco Time employee group for who the payroll hours will be uploaded to Sage300.
   6. The sage consultant must provide the GLSetup Id's - otherwise known as payroll rules or frequencies.
   7. Sage must be configured by a Sage consultant as per Eco Time's Sage Integration Setup Access Requirements
       
3. What process must the customer follow on a regular basis before payroll?
   1. The match discrepancies in the employee browse must be resolved on a regular basis .
       
4. What process must the customer follow to upload payroll hours?
   1. Important: The match discrepancies in the employee browse must be resolved.
   2. Select the correct Pay Run Period.
   3. Generate Export.
   4. Upload Payroll Hours.
       
5. I want to supress some of Eco Time Time Categories being exported.
   You can supress the time category from being exported in the API by disabling the applicable time category's "Export to Payroll" setting in Eco Time.
    
6. Some of the component codes (payroll codes) are incorrect. Where can these be changed?
   You can change the component code exported by the API by changing the applicable time category's "Payroll Code" setting in Eco Time.
    
7. What is a Pay Run or Pay Run period.
   This is the terminology used by Pay Space indicating their pay period start and end date. Eco Time must update each pay run to indicate the payroll end date in Eco Time that matches each pay run.
    
8. My Pay Run API upload returns a large number of invalid component code errors.
   The component codes are linked to a frequency. Refer to the Component Codes' browse to verify that the Pay Run frequency matches that of the component code's frequency. It is most likely that the Pay Run frequency is set incorrectly in Sage 300 and now does not include the correct component code group.
    
9. I am trying to assign or select a pay run, but my pay run period is not in the lookup.
   Pay runs will only be available in the lookup if an Eco Time payroll date has been allocated. Select the Pay Runs browse and update the applicable pay run.
    
10. What is an unverified employee.
    This is an employee which was added to the employee browse from the Sage 300 system in the past, but in more recently compares between this list and the Sage 300 system, the employee was not found in the Sage 300 system anymore.
    This typically happens if an employee is removed from the Sage 300 system or allocated a new Sage 300 employee record.
     
11. I am manually trying to use the API to populate the Pay Runs table, but the API windows does not appear.
    The Frequencies table must be populated first. The Pay Runs API will not run if there are no entries in this browse.
     
12. What is an authentication token?
    An authentication token is a digital credential used to verify the identity of a user, application, or device trying to access a system, service, or resource. It is often generated after successful authentication and can be used to maintain a session or grant access to specific resources without needing to re-authenticate repeatedly.
    
    The token expires after 2 hours, requiring the authentication API to be run again to obtain a new token.  If the token has expired, any API call wil be retun an Invalid Token or Unauthorised Error.
     
13. Do I have to request an API Server URL and Authentication Server URL for customer?
    No. Sage 300's URLs are the same for all customers. The default URLs provided will be correct. NOTE: The Production and QAS URLs are different - but provided as defaults for each mode.
     
14. How can the API Client Request Window be used for fault finding?
    1. This window displays the request link in the server fields. You can use his value to determine if the correct link is being used during the call.
    2. Consider selecting the "Do Not Process Response" disables any results processing. No tables will be populated. This is typically used for faulty finding and is used in cases where you want to inspect the request packet and result packet.
    3. The Sage 300 API Server response is displayed in the response window's text field. This response is the raw unprocessed data from the Sage 300 API Server and represents the true data transmitted and received by the API Client.
    4. The response packet is json and is unformatted (one long string) and is in the body of the response. Copy this body to your clipboard and use an online formatter like https://jsonformatter.org/ to make the response easier to read.
    5. By inspecting the raw formatted json response, you can validate the values eventually stored in Eco Time and the Sage 300 API Client.
        
15. How do you configure the Sage 300 API Server for API Access?
    Sage must be configured by a Sage consultant as per Eco Time's Sage Integration Setup Access Requirements
     
16. The Desktop Server API Settings has an API Mode selection option for Production or QAS. What is the difference between the two modes?
    1. If Sage is able to create a duplicate of the customers live data for testing, the test server will be accessible via the test server (QAS) settings.
    2. The two modes allow the user to have two different settings for testing and live, and removes the requirement to change settings continuously if the user toggles between the testing and the live system.
    3. QAS is for Testing the Sage system and Production for the current live Sage system.