Overview/Introduction
Our ARS Data API (Application Programming Interfaces) is used to read and write data back and forth between RMA and all web products. For more experienced users (and programmers) who want to tap into the RMA\Web data directly, You will be happy to hear that Advantage Route Systems has a tool that will let you do so. You will need to have some experience working with Rest APIs or similar tools to follow this process.
Our ARSDataAPI allows you to both read and write data. However, you must be careful when you do write data as this can greatly affect your system and must be done with prudence.
This tool kit will give you about 200 different functions that will let you:
- Read customer billing and route information
- Insert orders into our order table
- Make credit card payments
- Have access to customer equipment data
- Many other similar functions.
The balance of this article will help you download; set up and get started with the API. We will also provide you sample code and give you a few tips on using the interface.
Install and Setup
You must have RMA installed and a Web product prior to installing your ARSDataAPI. For directions on how to install RMA CLICK HERE.
You will also need to open a port within Windows Defender Firewall. The default port for ARSDataAPI is 55000. For directions on how to open a port CLICK HERE
1. Finding your correct ARSDataAPI version
2. Download and Install your ARSDataAPI
3. Configure your ARSDataAPI
3. Verify your ARSDataAPI service is running
4. How to call a key
These steps will be provided for you in the instructions below.
Process
To begin using the ARSDataAPI, you will first need to make sure the ARSDataAPI service has been installed and configured on the RMA server. Be sure the:
- Port
- User Name
- Password
are set in the ARSDataAPI configuration, as these will be needed for authentication.
You will also want to make sure your firewall(s) allow communications to that port from any web sites or servers that will be accessing the RMA data.
Once everything is set up and configured, you should review the API documentation in the ARSDataAPI.chm file, located in the ARSDataAPI folder within RMA on your server. This file contains definitions for all of the API methods and data objects available in the API. The methods can be found in the ARSDataAPICommon / IARSDataAPI Interface section of the help file.
When using the API, the first thing you will need to do is validate a token with the ARSDataAPI service. This token will be used for subsequent calls to the API. This is accomplished by calling the API’s Init method and passing the user name and password that were set during the ARSDataAPI service installation and configuration.
Please see the example PHP code below on how this is done. The API token expires on the hour, so it is important that your code check for an “invalid token” return and renew the token by calling Init.
You will also find some useful helper functions at the bottom of the example that can be used to simplify all of your API calls. With these steps completed, you can start to use the ARSDataAPI.
Sample PHP code
With everything installed, you are ready to begin writing PHP code to call or push data to RMA. The following code snippet will help you identify the way you will use the ARSDataAPI in a programming environment.
<?php
$url = "<<URL To ARSDataAPI>>"; # Example: http://ars247.com:50000/ARSDataAPI/ *** the URL to the ARSDataAPI includes the port # (55000 in this example) from the ARSDataAPI configuratoion
$user = "<<ARSDataAPI User>>";
$pass = "<<ARSDataAPI Password>>";
echo "Initialzing<br>";
# Create token based on user / password from the ARSDataAPI configuration
$token = '{"token":"' . GetToken($user, $pass) . '"}';
# Initialize our token
$result = Call("Init", $token);
if(!isset($result) || $result["Code"] != 0) {
echo "Error initializing token";
exit -1;
}
# Get Product Classifications (Categories) - This really should check for sub-classifications instead of assuming only 2 deep
$parameters = '{"token":"' . GetToken($user, $pass) . '"}';
$result = Call("GetProductClassifications", $parameters);
if(!isset($result) || $result["Code"] != 0) {
echo "Error getting data";
exit -2;
}
$classifications = json_decode($result["Data"]);
$filterClassifications = [];
foreach($classifications as $class) {
if($class->Parent === "WATER") {
$filterClassifications[] = $class->Code;
}
}
# Get product list
$parameters = '{"token":"' . GetToken($user, $pass) . '", "internetOnly":"true", "paginationSettings":{"Descending":false, "Offset":0, "OrderBy":null, "SearchText":null, "Take":50}, categories: ' . json_encode($filterClassifications) . '}';
$result = Call("GetProductListPaginated", $parameters);
if(!isset($result) || $result["Code"] != 0) {
echo "Error getting data";
exit -2;
}
$products = json_decode($result["Data"]);
foreach($products->records as $product) {
echo "Product:" . $product->Code . " - " . $product->WebDescription . " - " . $product->WebClassificationId . " - " . $product->WebClassificationParent . "<br>\n";
}
############################################################################
# HELPER FUNCTIONS
############################################################################
function Call($method, $data) {
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_URL, $GLOBALS["url"] . $method);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HEADER, 0);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
"Content-Type:application/json",
"Content-Length: " . strlen($data))
);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($curl);
curl_close($curl);
return IsEmpty($result) ? $result : json_decode($result, true);
}
function IsEmpty($data) {
return (!isset($data) || trim($data) === "");
}
function GetToken($user, $pass) {
return md5("$user:$pass:" . gmdate("YmdH"));
}
The chart below will give you an overview of all methods available to you:
Programming Tips
The following section will give you important and useful tips as you start coding your web application and wand to get data from your RMA application.
Partial List of Functions and Purpose
Here is a partial list of Functions and their purpose. You will use the Functions to move data back and forth. A complete list of the functions can be found in the documents ???????????????
| ACHCharge | Charges a customer's bank account and applies to oldest invoice |
| ACHChargeToDeliveryOrder | Charges a customer's bank account and creates a credit record with the delivery order amount |
| ACHChargeToInvoices | Charges a customer's bank account and applies to invoice(s) |
| AddProspectVisit | Adds a prospect visit as a contact message |
| AddVisit | Adds a visit as a contact message |
| AuthenticateMFS | Checks passed login info against database to determine if login is valid |
| AuthenticateMMS | Checks passed login info against database to determine if login is valid |
| AuthenticateMPOS | Checks passed login info against database to determine if login is valid |
| AuthenticateUser | Checks passed login info against database to determine if login is valid |
| CheckAccount | Search for customer to see if they exists |
| CheckCartMinimumOrderRequirements | Gets whether the passed list of cartProducts meet order requirements set in Mango Web Settings |
| CheckDeliveryStopAccess | Checks if the deliveryId is associated with the customerId either as a stop or sub-account stop |
| CheckExistingProspect | Checks new prospect id against existing ids |
| CheckForDuplicateEmail | Check if email address exists |
| CheckPostalCodeAvailibity | Checks if a postal code is included in a serviceable area |
| ClearPOSButton | Clears POS Buttons |
| CompleteOrder | Creates a delivery order while imposing customer hold service rules |
| CompletePurchase | Creates an invoice for the list of objects and applies payment against it |
| ConvertProspect | Convert Prospect |
| CreateContract | Creates a Contract using the passed contractData as the base |
| CreateCustomer | Creates a new customer |
| CreateDeliveryLocation | Creates a new delivery location for a customer |
| CreateDeliveryLocationWithOrder | Creates a customer delivery location with a delivery order using web rules |
| CreateGuestOrder | Creates an order using a preset Guest account. |
| CreateInvoice | Creates an invoice for a customer |
| CreateOrder | Creates a delivery order |
| CreatePayment | Makes payments to a customer's invoices or an unapplied payment by leaving the InvoiceKey empty |
| CreateProspect | Updates prospect information |
| CreateProspectCustomerWithOrder | Creates a customer with a delivery order using web rules |
| CreditCardNonVaultCharge | Charges a non-vaulted credit card and applies to oldest invoice |
| CreditCardNonVaultChargeToDeliveryOrder | Charges a non-vaulted credit card and creates a credit record with the delivery order amount |
| CreditCardNonVaultChargeToInvoices | Charges a non-vaulted credit card and applies to invoice(s) |
| CreditCardVaultAdd | Vaults a credit card for a customer |
| CreditCardVaultCharge | Charges a vaulted credit card and applies to oldest invoice |
| CreditCardVaultChargeToDeliveryOrder | Charges a vaulted credit card and creates a credit record with the delivery order amount |
| CreditCardVaultChargeToInvoices | Charges a vaulted credit card and applies to invoice(s) |
| CreditCardVaultDetail | Gets customers credit card information on file |
| CreditCardVaultRemove | Removes a vaulted credit card |
| DeleteDefaultProduct | Deletes default products |
| DeleteOrder | Deletes a delivery order |
| DeleteProspectDefaultProduct | Deletes default products from prospect |
| DoesDeliveryInformationExists | Checks if any of the delivery information entered exists |
| DoesSalesRepHaveOpenLeads | Checks if sales rep has any prospects that have not been contacted yet |
| EditProspectVisit | Edits a prospect visit as a contact message |
| EditVisit | Edits a visit as a contact message |
| EmailCustomerInvoice | Emails a pdf copy of the specified invoiec to the given email address |
| EmailCustomerYearlyCalendar | Emails yearly calendar to specified email address |
| EmployeeForgotPasswordEmail | Sends an email with the forgot password reset URL |
| ExchangeEquipment | Exchanges an equipment with another to a delivery location |
| GeSkipFeeCharge | Gets skip fee charge amount for deliveryId |
| GetActivationFee | Gets fee data for activatation fee during sign up |
| GetActiveEmployees | List of employees |
| GetAllContactViaData | Gets list of all Contact Via Data from database |
| GetAllDeliveryStops | Returns all delivery stop data for a customer, if it's the master account then all sub-accounts will be returned as well |
| GetAllOpenInvoices | Gets pdf of all open invoices |
| GetBillingAccount | Gets the customer's primary billing account # |
| GetBottleDepositeCodes | Gets list of bottle deposit codes for requested delivery location or web prospect |
| GetBranchCode | Get first available branch code |
| GetBranchContactData | Gets contact information for passed branch |
| GetBusinessName | Gets the business name |
| GetCartMinimumOrderQuantities | Get list of minimum order quantities |
| GetCartPricing | Get pricing information for all items in shopping cart |
| GetCartRent | Get rate information for all rental equipment in shopping cart |
| GetCartSalesTax | Get sales tax amount from list of shopping cart line items |
| GetCartWebCouponAmount | Get discount amount from list of shopping cart line items from a web coupon code |
| GetCICode | Internal use only |
| GetContractDocument | Gets document information to be used as a download |
| GetContractDocuments | Gets a list of documents for a specified contract type |
| GetContractTypeAuthorization | Generates document from contract workfrow |
| GetContractTypes | Gets a list of contract types |
| GetControlPanelSettings | Gets control panel settings from database |
| GetControlPanelSettingsMFS | Gets control panel settings from database for mango field sales employees |
| GetCreditCardFee | Gets fee data for credit card charges |
| GetCreditCardFeeCharge | Gets credit card fee charge amount based on provided parameters |
| GetCreditCardTerminals | Get Credit Card Terminals |
| GetCreditClasses | Get Credit Classes |
| GetCreditMessages | Get Credit Messages |
| GetCustomer | Gets customer information |
| GetCustomerAccountBillingType | Returns whether an account is consolidated billing, master, or neither |
| GetCustomerAccounts | Gets all the subaccounts for the primary account with the option to return the primary account as well |
| GetCustomerBalances | Gets Balance Details for customer |
| GetCustomerBank | Gets the customer's bank code |
| GetCustomerBankAccount | Gets the bank information for the specified customer |
| GetCustomerBranchId | Gets the customer's branch code |
| GetCustomerCreditCardCount | Gets the customer's credit card count |
| GetCustomerCreditCards | Gets a list of credit cards for the specified customer |
| GetCustomerCreditCardsCount | Gets a total of credit cards vaulted for the specified customer |
| GetCustomerCreditFlags | Checks if the provided customer is on hold service |
| GetCustomerInvoiceAndPaymentHistory | Gets the customer's invoice and payment history |
| GetCustomerOpenInvoices | Gets the customer's open invoices |
| GetCustomerOptions | Checks if the provided customer is on hold service |
| GetCustomerPendingPaymentAmount | Returns a sum of all payments a customer has in invoice payments |
| GetCustomerRoute | Gets the delviery stop's route code |
| GetCustomers | Get a list of customers |
| GetCustomersByName | Gets customer information. Use PaginationSettings.SearchText to search for name of customer. |
| GetCustomersPaginated | Get a list of customers |
| GetCutoffDateTime | Gets the current cutoff date/time |
| GetDefaultProducts | Gets a list of all default products for a passed delivery location |
| GetDeliveryDays | Gets a list of calendar dates that are scheduled for the passed route and between the passed dates |
| GetDeliveryFee | Gets fee data for delivery fee during order creation |
Common Issues and How to Troubleshoot
Getting started and using the ARSDataAPI can be a challenge. Here are some things we have found over the years that may help you as you get started and need to troubleshoot things that are not working the way you might expect.
Summary
The ARSDataAPI is a powerful tool that will let you enhance your Web site with copious amounts of RMA data. Once you get the knack of using it, you can quickly pull additional information into your Web Site. If you need assistance, reach out to our Tech Support Team and we will be happy to help you.
If you find that you need functions that are not currently available, let us know so we can address your needs. This starts with our support team and then your request will be passed on to our Engineering team to see if it is feasible and how long it would take.
Finally, thank you for using the ARSDataAPI. Please feel free to email us feedback on the tool to our Support group at Support@AdvantageRoute.com