logo
Documentation Powered by ReDoc

Rainbow Invoicing portal (1.239.1)

Download OpenAPI specification:Download

Rainbow API Support: support@openrainbow.com URL: https://developers.openrainbow.com/support

Rainbow invoicing portal API guide

Preamble

Download Postman collection

Introduction

This guide describes list of API services that are provided by OT Rainbow Invoicing portal. This portal is dedicated to end user features.

Protocol

REST interface is used for sending/receiving OT rainbow API messages. HTTP requests GET, DELETE, POST, UPDATE are used. Standard HTTP responses are used to provide requested information or error status. There is no session notion in OT Rainbow system, so requests could be issued according stateless model, without transport conservation between them. Additional data could be provided in message body. JSON is used as a main format for data encoding in message body part. Each request is started with the following pattern /{module}/{version}/ where {module} is a portal module name to address and {version} is a version of used API, par example, “v1.0”.

Security considerations

Each request should contain some credential information to authenticate itself. Standard HTTP authentication with basic/bearer modes is used. JSON Web Token mechanism is used to provide authentication information. JWT has a expire timeout that is controlled by OT Rainbow portal to prevent very long token usage. Also authentication with application token is used. The token must be provided in the request HTTP header, using a custom header: APIKey. At server side, token is verified, and if it doesn’t match, 403 Not Allowed response is sent. TLS is used as a transport protocol to support message exchanges between OT Rainbow portal and an application.

Authentication

Bearer

For accessing the API, a valid JWT token or a valid OAuth access token can be passed in the 'Authorization' header.

Security Scheme Type API Key
Header parameter name: Authorization

Bearer-x-rainbow-api-key

For accessing the API, a valid API Key can be provided instead of 'Authorization' Bearer JWT header

This authentication method is useful for some applications needing a permanent authentication or not able to expose an interface allowing the user to authenticate (scripts, bots, IOT devices, ...).

A valid API Key is obtained from the API POST /api/rainbow/authentication/v1.0/apikeys.
When API Key authentication is used, the header x-rainbow-app-auth is mandatory to authenticate the application accessing the API.

Security Scheme Type API Key
Header parameter name: x-rainbow-api-key

Bearer-x-rainbow-challenge

Challenge for application authentication.

Should be randomly generated by the application (the challenge should be unique for each request for security reasons).

Mandatory only for authentication with x-rainbow-api-key (not used for authentication with JWT).

Security Scheme Type String

Bearer-x-rainbow-app-auth

Application authentication

Basic <base64encode(appId:sha256(appSecret challenge))> (Concatenation of appSecret and provided challenge, hashed with sha256).

The challenge used to compute the x-rainbow-app-auth value must be the same as the one provided in header x-rainbow-challenge.

Mandatory only for authentication with x-rainbow-api-key (not used for authentication with JWT).

Security Scheme Type String

Invoices

Download an available invoice

This API allows superadmin, bp_finance and admin to download a given invoice.
To download an invoice, admin should use filepath provided by GET /api/rainbow/invoicing/v1.0/invoices API.
Example of request to download an invoice : GET /api/rainbow/invoicing/v1.0/invoices/000000001111110001000010/2017-10/services/CDR_SERV_2017-10-10_DR_dr_bp_test.csv

Authorizations:
BearerBearer-x-rainbow-api-keyBearer-x-rainbow-challengeBearer-x-rainbow-app-auth
path Parameters
invoicePath
required
string

path of the file to download (e.g. 000000001111110001000010/2017-10/services/CDR_SERV_2017-10-10_DR_dr_bp_test.csv)

Responses

Response samples

Content type
application/json
application/json
text/csv
{
  • "Content-Type": "text/csv",
  • "Content-disposition": "string",
  • "csv": [
    ]
}

List all available invoices

This API allows superadmin, bp_finance and admin to list all available invoices.

Authorizations:
BearerBearer-x-rainbow-api-keyBearer-x-rainbow-challengeBearer-x-rainbow-app-auth
query Parameters
companyId
string

companyId for which invoices should be listed

billingPeriod
string

Period for which invoice should be listed (e.g. 2017-08)

invoiceType
string
Enum: "services" "conference" "voice"

Type of invoice that should be listed (services or conference)

fileType
string
Enum: "INV" "CDR"

Type of file that should be listed (INV or CDR)

invoiceCreationDate
string <date>

Allow to filter invoices on invoiceCreationDate. This is an exact match: API will return only invoices matching the given date. Expected format is : YYYY-MM-DD

fromInvoiceCreationDate
string <date>

Allow to filter invoices on invoiceCreationDate. API will return only invoices with invoiceCreationDate greater than the given date.

Expected format is : YYYY-MM-DD

Note: if invoiceCreationDate filter is provided, fromInvoiceCreationDate will be ignored.

toInvoiceCreationDate
string <date>

Allow to filter invoices on invoiceCreationDate. API will return only invoices with invoiceCreationDate lower than the given date.

Expected format is : YYYY-MM-DD

Note: if invoiceCreationDate filter is provided, toInvoiceCreationDate will be ignored.

bpType
string
Enum: "VAD" "DR" "IR"

bpType for which invoices should be listed.
Only usable by superadmin or business_admin.
Not taken into account if companyId query parameter is also provided.
Default value applied is VAD

Responses

Response samples

Content type
application/json
[
  • {
    }
]