Upload Bills API Documentation

Getting Started

This API for uploading bills requires a minimum of two steps for completion, and the detailed documentation for these steps is outlined below.

1. Authentication and Authorization

   OAuth2 API v1.10.8

   This API will generate JWT needed for the authorization of other API calls.

   URLs

   • Staging: https://authstage.nexitydev.com/oauth2/token/
   • Production: https://auth.blaggo.io/oauth2/token/

   Request Parameters:

   • client_id - API Client ID
   • client_secret - API Client Secret Key
   • grant_type - Grant type. For now it only accepts client_credentials grant type.

   Note:

   All parameters are required. The client_id and client_secret will be sent securely in a separate communication channel.

   Sample cURL request in Staging:

   curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}" \
     https://authstage.nexitydev.com/oauth2/token/
   

   Response Structure

   Success:

   {
     "access_token": "string",
     "expires_in": 0,
     "refresh_token": "string",
     "scope": "string",
     "token_type": "string"
   }
   

   The JWT is the value of access_token property. The token will expiry in 1 hour.

   Error:

   {
     "error": "string",
     "error_code": 0,
     "error_description": "string",
     "error_uri": "string"
   }
   

2. Bills Upload

   Partner Utility API v1.12.13

   The upload bills API requires authorization attached in the HTTP request. Use the JWT generated in step 1.

   URLs

   • Staging: https://utility-stage-e6jg27ou7a-as.a.run.app/bills
   • Production: https://utility-prod-nn67p6lyqq-as.a.run.app/bills

   Request Parameters:

   Array of objects with the following properties:

   • account_number - Account number of the customer.
   • amount - Bill net amount to be paid.
   • due_date - Bill due date. Example: 30-01-2024
   • period - Billing month period. Example: 01-2024

   Performance and Timeout Consideration:

   • 500 items - is the recommended total number of records in a single upload
   • 5 minutes - is the API maximum timeout

   It is recommended to divide large volume of billing information into batches to avoid performance and timeout issues. It is highly recommended to handle this 5 minute timeout in your code. Check the example cURL request for your guidance on how to construct the upload request.

   Notes:

   • All parameters are required.
   • Due date should be current/future date.
   • Period should be current/future month.

   Sample cURL request in Staging:

   curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${JWT}" \
     -d '[{"account_number": "AB123456","amount": 1500,"due_date": "25-05-2024","period": "06-2024"}, {"account_number": "AB123457","amount": 1700.78,"due_date": "26-05-2024","period": "06-2024"}, {"account_number": "AB123458","amount": 500.50,"due_date": "27-05-2024","period": "06-2024"}]' \
     https://utility-stage-e6jg27ou7a-as.a.run.app/bills
   

   Response Structure

   Success:

   {}
   

   Error:

   {
     "err": "string"
   }