Prerequisite

You must have a fully functional 1099 Pro Corporate Suite installation working before setting up the API.

Step 1: Download software

  1. Download the latest 20xx ASP.Net installer from our host site: http://host.1099pro.com/ftp/product/
  2. Click on the appropriate year.
  3. Click on Corporate Suite.
  4. Click on API.
  5. Download the following file: Web-API-20XX.ZIP.

Step 2: Setup the API IIS website

Note: If you already have IIS set up, you can skip to step 9 (Add Web Site) in the Instructions below.


Requirements:

  • Net Framework 4.0
  • Windows Server 2008 Server or higher


Instructions:

  1. Go to Server Manager, expand Roles from the left pane, then select Add Roles.
    1. If you're using Windows Server 2012 R2, select IIS (left pane) > Manage (upper toolbar) > Add Roles and Features.
  2. Click Next.
  3. Check Web Server (IIS), then click Next.
  4. Click Next.
  5. Make sure the following boxes are checked:
    1. Application Development
      1. ASP.NET
      2. .NET Extensibility
      3. ASP
      4. CGI
      5. ISAPI Extensions
      6. ISAPI Filters
      7. Server Side Includes
    2. Common HTTP Features
      1. Static Content
    3. Security
      1. Basic Authentication
      2. Windows Authentication
      3. Request Filtering
  6. Click Next.
  7. Click Install, then click Close once the installation is finished.
    1. If you're using Windows Authentication, click on the Computer Name in the IIS Manager and make sure that Anonymous Authentication, ASP.NET Impersonation, Basic Authentication, and Forms Authentication are disabled, and that Windows Authentication is enabled.
    2. If required, go to Microsoft's site and download and install .Net Framework 4.0 (http://www.microsoft.com/en-us/download/details.aspx?id=17718) and reboot if it prompts you to.
  8. Expand the tree on the left until you see your default web site. Check the Site Bindings to not have conflicting ports.
    1. Note: The default port is 80. You can define them here.
  9. Right-click on Sites and select Add Web Site.
  10. Enter your desired site name. Click the Select button and choose ASP.NET v4.0 as the Application Pool. Then, click OK.
  11. Click the box to the right of physical path and make a new folder under the 1099 Pro installation folder named "1099ProAPI". Then, click OK.
  12. Uncheck the Start Web site immediately box, then click OK.

Step 3: Install and setup the API

  • Extract the API ZIP contents to the new 1099ProAPI folder.
  • Open Windows Explorer and navigate to the 1099ProAPI folder.
  • Edit the Web_new.config with your text editor. Change the following red highlighted values to the parameters you defined when setting up your corporate suite.

<add name="CSDb" connectionString="server=testserver\instance;Persist Security Info=True;user id=dbowner;password=dbownerpw;initial catalog=sqldbname;" providerName="System.Data.SqlClient" />

Note: the \instance is not always required, this is dependent on the database structure.

The 1099ProApiKey, 1099ProPrivateKey, and symmetricKey must be setup. SymmetricVector can be left empty.

<add key="symmetricKey" value="A base64 encoded 256-bit key" />
<add key="1099ProPrivateKey" value="A random 40 character string" />
<add key="1099ProApiKey" value="A random 40 character string" />


PowerShell Script: Generate 256-bit AES keyPowerShell Script: Generate 40-character string

PS C:\temp> $256AESKey = New-Object Byte[] 32
PS C:\temp> [Security.Cryptography.RNGCryptoServiceProvider]::Create().GetBytes($256AESKey)
PS C:\temp> Write-Host([Convert]::ToBase64String($256AESKey))
FJ1WZ3FnsP9pUIPRgTJ2Kw1E2Th4/9mGubZmobUuWoo=

PS C:\temp> -join (((48..57)+(65..90)+(97..122)) * 80 |Get-Random -Count 40 |%{[char]$_})
ZzVQEny0WlNARKb5DJ1CGJY59c4aDCxCrADfmRBh

Examples:

<add key="symmetricKey" value="FJ1WZ3FnsP9pUIPRgTJ2Kw1E2Th4/9mGubZmobUuWoo=" />
<add key="1099ProPrivateKey" value="ZzVQEny0WlNARKb5DJ1CGJY59c4aDCxCrADfmRBh" />
<add key="1099ProApiKey" value="bQbHRGmhD/rlgVm8GGwrMc88d9ahDmHWZ9F7j6qM" />


Payer Code security by API key (optional)

With the API, you can enforce Payer Code security by API key. This means that an API key can be limited to only have access to one or more specified Payer Codes. You can configure this by adding a key equal to the value of the ApiKey, followed by a comma delimited list of allowed Payer Codes. Starting with the default "1099ProApiKey", you can configure up to 10 additional API keys, each with their own Payer Code limitations.


The following example gives the "WEX1OeV6tqa0SDO9i5dV0n9hrEZj6pXs5c46crRZ" API key access to PCODE1:

<add key="1099ProApiKey" value="WEX1OeV6tqa0SDO9i5dV0n9hrEZj6pXs5c46crRZ" />
<add key="WEX1OeV6tqa0SDO9i5dV0n9hrEZj6pXs5c46crRZ" value="PCODE1" />


The following example gives the "bQbHRGmhD/rlgVm8GGwrMc88d9ahDmHWZ9F7j6qM" API key access to PCODE1 and PCODE2:

<add key="1099ProApiKey1" value="bQbHRGmhD/rlgVm8GGwrMc88d9ahDmHWZ9F7j6qM" />
<add key="bQbHRGmhD/rlgVm8GGwrMc88d9ahDmHWZ9F7j6qM" value="PCODE1,PCODE2" />



HMAC-SHA256 security (optional)

With the API, you can require a valid HMAC-SHA256 signature of the API call parameters. To do this, set a base64 encoded 512-bit HMAC secret key value in the "1099ProHmacKey" key of the web.config. This is the secret HMAC key that will be used to validate the HMAC "Signature" value in the XML request.

(Optional) A "1099ProHmacExpiration" key and value are used to configure the amount of time a HMAC signature is valid for in seconds, from the time specified in the request's timestamp.

Example: If the request's timestamp is "10/28/2019 12:00:00 PM", and the 1099ProHmacExpiration is set to "60", the HMAC signature would be valid until 10/28/2019 12:01:00 PM.


(Optional) A "1099ProHmacReplay" key is used to tell the API to reject duplicate HMAC signatures. HMAC signatures replayed within the 1099ProHmacExpiration x 2 timeframe will be rejected as duplicate.

Example:

<add key="1099ProHmacKey" value="2bauSp2YvnzBQ7YIz3V/3s7Ggiiz8FboGpftAayRi/r+zYs5ILm/np2u142HSlzXjsJLOn9VfJ7KJrg7q0bEuw==" />

<add key="1099ProHmacExpiration" value="60" />

<add key="1099ProHmacReplay" value="Deny" />

PowerShell Script: Generate 512-bit HMAC secret key

PS C:\temp> $HMACkey = New-Object Byte[] 64
PS C:\temp> [Security.Cryptography.RNGCryptoServiceProvider]::Create().GetBytes($HMACkey)
PS C:\temp> Write-Host([Convert]::ToBase64String($HMACkey))
2bauSp2YvnzBQ7YIz3V/3s7Ggiiz8FboGpftAayRi/r+zYs5ILm/np2u142HSlzXjsJLOn9VfJ7KJrg7q0bEuw==


  • Once you completed the changes, click File > Save As and name the file "web.config". Then, click Save.
  • Copy the new "web.config" file to the 1099ProAPI directory.
    • Note: Copy and replace, when prompted.
  • Click the Start button under Browse Web Site, then click Browse under Browse Web Site.
  • You can test the API site by navigating to your site and going to the /api.asmx page.



  • No labels