This article covers the basic items that a developer needs to know to begin utilizing the IDI web services.
IP Origination
IP access to all web service endpoints is restricted to addresses registered on your company’s CostGuard Access List. Any hosts running software that will need access to IDI’s APIs for development, testing or production will therefore need to be added to your list via the IP Origination Form before they can access the end-points.
Web Service User
All web service endpoints require proper authentication in order to submit requests. The authentication process involves using a web service user account to obtain a authentication token from the Security service and then including the token on subsequent Web API calls.
More information on Security Tokens can be found in the article Understanding Authentication.
Web Service User Credentials
The User ID and Password for your web service user account can be provided to you by contacting your Account Manager or Project Manager.
Environments
Companies have a single production environment and typically at least one non-production environment.
Each non-production environment represents an individual copy of a company’s CostGuard data. The only exception to this is Security web app where there is a single set of users and permissions used to assign access across all of a company’s environments.
Environments for the same company may be running different versions of CostGuard. This is especially true in stage environments were testing of new releases often occurs. Information on how to determine what version of CostGuard is running in a given environment can be found in the article Versioning and WSDLs.
Promotion of your code from test environments to production is at your company’s discretion and is not controlled or gated by IDI. Developers should work with their company’s CostGuard administrator for any coordination that is needed.
Refreshing of data from the production environment is available on request and should be facilitated through your company’s CostGuard administrator.
List of Available Environments
The list of environments available for development can be confirmed by your CostGuard administrator.
URL
The web service endpoints all follow the following basic format:
https://api.idibilling.com/<web service name>/<version>/<environment>
You will need to know three things in order to construct your URL:
- Web Service Name – These are provided below.
- Major Version – Major version of the end-point you are connecting to (e.g. 1x, 2x, 3x). For example, if Customer 1.14 is deployed for your environment then you will connect to Customer\1X
- Environment name – These should be provided to you by your CostGuard administrator.
As an example, the following URL routes to the Customer web service, major version 1.0 for the YOD01_S_Stage environment:
https://api.idibilling.com/Customer/1x/Cust01_S_Stage
Endpoints
Address Verification
https://api.idibilling.com/addressvalidation
Product Catalog
https://api.idibilling.com/catalog
Customer Management
https://api.idibilling.com/customer
Data Web Service
https://api.idibilling.com/data
Journals & Tickets
https://api.idibilling.com/journal
Number Inventory
https://api.idibilling.com/numberinventory
Order Placement
https://api.idibilling.com/orderplacement
Security
https://api.idibilling.com/SecurityToken
Workflow
https://api.idibilling.com/workflowmanagement
Security Certificates
IDI provides two security certificates for web service development. These may need to be installed on any machine that are running applications that are call IDI’s Web APIs.
IDISaaSSecurityToken-NoPrivateKey.p7b – IDI’s Digital Signature.
All Web API responses from IDI are digitally signed to ensure their authenticity. This certificate may be used to verify that signature.
Some development libraries (e.g. Microsoft .NET) will automatically attempt to verify signed requests. For these libraries the digital signature certificate is not optional.
IDISaaSWebServices-Customer.pfx – Security Token Encryption Certificate.
Used to extract Simple Web Token from Security Token if you are not requesting the SWT from the Security endpoint directly.
The certificates, along with a README file with the password, can be downloaded here.
Web API Documentation
Documentation on available Web API functionality can be found in the Knowledge Center at:
https://help.idibilling.com/?ht_kb_category=web-api-documentation.
