API Specification
This section describes the distinct API requirements that must be met to enable data transfer from your utility billing storage solution to Digital Self Service - Transactions. The API used to request and retrieve bill information from your utility bill provisioning service is designed according to the industry-standard REST principals.
Bill Retrieval Operation
The bill retrieval operation is invoked to request the bill document from your utility bill provision service. The request is then sent from Oracle Utilities Opower Digital Self Service - Transactions over a TLS connection with no content. The response is returned with the bill document or no content.
Note: The API request can be made using either no authentication or the standard HTTP Basic Authentication. The credentials must be shared out-of-band and will be securely stored by Oracle Utilities.
Bill Retrieval Request
Method: GET
URL Pattern: https://[ip_addr]/dss/bill/download/[bill_id]
The URL pattern must meet the following criteria:
- The IP address must be provided out of band and be reachable form the Oracle Utilities or over HTTPS using basic auth. It must be reachable from the Oracle Utilities data center using the IPsec tunnel or reachable over a secure tunnel.
- It is recommended that your utility partner set up a High Availability configuration for the bill provision service implementation set to the IP address of the load balancer.
- The bill_id parameter is the Bill ID assigned by Oracle Utilities Customer to Meter or Customer Care and Billing system to the bill being retrieved.
Headers
The following header must be included with the request:
Note: The request may include additional information, but this information is treated as informative only and will not impact the semantics of the API described in this documentation.
| Header | Value | Description |
|---|---|---|
| Accept | application/pdf | Specifies the format of the processed bill document. PDF is the only supported format. |
Bill Retrieval Response
In order for Digital Self Service - Transactions to identify and appropriately escalate various problems and security errors, it is important that the bill retrieval service implemented by your utility return the supported response status codes.
200 OK: The bill retrieval is successful. The response body must include the following:
- The complete binary image of the bill document in PDF format.
- Header content-type is set to application / pdf.
- Header content-length is set to the size of the image in bytes.
Note: The maximum supported size for content-length is 5 MB.
404 Not Found: The bill document for the given bill_id was not found.
500 Server Error: Signals an internal error with the bill provisioning service implementation.
Note: Responses that fall outside of the supported response codes will be handled as a 500 Server Error.
Health Check Operation
The health check operation is used by Digital Self Service - Transactions to check the status of your utility's bill provision service to ensure that bill requests can be answered. The health check operation may be invoked as frequently as every ten seconds.
Health Check Request
Method: GET
URL pattern: https://[ip_addr]/dss/bill/healthcheck
Note: This request has no parameters.
Headers: The health check has no specific headers. Any headers that might be included with the request are expected to be informative and not affect the semantics of the API described in this guide.
Health Check Response
In order for Digital Self Service - Transactions to monitor its integration with the bill provisioning service implemented by your utility, it is important that only supported response status codes are returned following a health check. Response status codes not listed in this section indicate abnormal health of the bill provisioning service.
200 OK: Signals of normal health of the service and that the health check was a success. The header content-length of the 200 OK response must be set to zero.