CloudBlue Commerce API (DRAFT)
Table Of Contents
ChargesImportManager¶
The type is used to implement Charge Import API
In this document:
Schema¶
The considered APS type (download)
extends the Resource APS type(s) and looks as follows:
{
"name": "ChargesImportManager",
"id": "http://com.odin.rating/charges-import-manager/1.0",
"apsVersion": "2.0",
"implements": [
"http://aps-standard.org/types/core/resource/1.0"
],
"operations": {
"openSession": {
"path": "importSessions",
"verb": "POST",
"response": {
"type": "ImportSessionInfo"
},
"errorResponse": {
"type": "object"
}
},
"getSessionByStatus": {
"path": "importSessions",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "ImportSessionInfo"
}
},
"errorResponse": {
"type": "object"
},
"parameters": {
"status": {
"kind": "query",
"type": "string"
},
"limit": {
"kind": "query",
"type": "integer"
}
}
},
"getSession": {
"path": "importSessions/{sessionId}",
"verb": "GET",
"response": {
"type": "ImportSessionInfo"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"sessionId": {
"kind": "path",
"type": "integer"
}
}
},
"closeSession": {
"path": "importSessions/{sessionId}",
"verb": "PUT",
"errorResponse": {
"type": "object"
},
"parameters": {
"sessionId": {
"kind": "path",
"type": "integer"
}
}
},
"importCharges": {
"path": "charges",
"verb": "POST",
"errorResponse": {
"type": "object"
},
"parameters": {
"charges": {
"kind": "body",
"type": "ChargesPacket"
}
}
}
},
"structures": {
"ImportSessionInfo": {
"type": "object",
"properties": {
"importSessionId": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"OPEN",
"NEW",
"PROCESSING",
"FAILED_PROCESSED",
"PROCESSED",
"REPORTED"
]
},
"errorDesc": {
"type": "string"
},
"lastUpdateTime": {
"type": "string",
"format": "date"
}
}
},
"Charge": {
"type": "object",
"properties": {
"type": {
"type": "string",
"required": true,
"enum": [
"COS",
"CHARGE",
"MSRP"
]
},
"subscriptionId": {
"type": "string",
"required": true
},
"accountId": {
"type": "string"
},
"resourceId": {
"type": "string",
"required": true
},
"unitPrice": {
"type": "number"
},
"totalPrice": {
"type": "number",
"required": true
},
"amount": {
"type": "number",
"required": true
},
"currencyCode": {
"type": "string",
"required": true
},
"uom": {
"type": "string"
},
"chargeStartDate": {
"type": "string",
"required": true,
"format": "date-time"
},
"chargeEndDate": {
"type": "string",
"required": true,
"format": "date-time"
},
"duration": {
"type": "number"
},
"durationUom": {
"type": "string"
},
"description": {
"type": "string"
},
"sku": {
"type": "string"
},
"mpn": {
"type": "string"
},
"poNumber": {
"type": "string"
},
"extChargeId": {
"type": "string"
},
"extHash": {
"type": "string"
},
"attributes": {
"type": "dictionary"
}
}
},
"ChargesPacket": {
"type": "object",
"properties": {
"importSessionId": {
"type": "integer",
"required": true
},
"charges": {
"type": "array",
"required": true,
"items": {
"type": "Charge"
}
}
}
}
}
}
Custom Operations¶
OPERATION |
VERB |
PATH |
RETURNS |
Description |
|---|---|---|---|---|
POST |
/importSessions |
Opens new charge import session |
||
GET |
/importSessions |
List of ImportSessionInfo |
Gets information about charge import sessions |
|
GET |
/importSessions/{sessionId} |
Gets information about particular charge import session |
||
PUT |
/importSessions/{sessionId} |
Closes charge import session and marks it as ready for processing |
||
POST |
/charges |
Imports list of charges for a particular import session |
openSession¶
HTTP Request
POST /aps/2/resources/{aps-id}/importSessions
Description
Opens new charge import session
Returns
getSessionByStatus¶
HTTP Request
GET /aps/2/resources/{aps-id}/importSessions
Description
Gets information about charge import sessions
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
status |
String |
Status of the sessions to be requested (all statuses by default) |
limit |
Integer |
Limit the result list by specified amount of sessions (100 by default) |
Returns
List of ImportSessionInfo
getSession¶
HTTP Request
GET /aps/2/resources/{aps-id}/importSessions/{sessionId}
Description
Gets information about particular charge import session
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
sessionId |
Integer |
Returns
closeSession¶
HTTP Request
PUT /aps/2/resources/{aps-id}/importSessions/{sessionId}
Description
Closes charge import session and marks it as ready for processing
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
sessionId |
Integer |
Returns
importCharges¶
HTTP Request
POST /aps/2/resources/{aps-id}/charges
Description
Imports list of charges for a particular import session
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
|---|---|---|
charges |
Data structure with list of charges and charge session id ChargesPacket |
Returns
Structures¶
ImportSessionInfo¶
Charge import session opened by Charge Import API.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
importSessionId |
Integer |
Not Required |
Charge import session ID (returned by ChargesImportOperations.openSession()). |
|
status |
Enum |
Not Required |
Status of the session. Values are:.
OPEN - session has been opened for new charges.NEW - session has been closed and ready to be processed by margin manager.PROCESSING - session is being rated by rating engine.FAILED_PROCESSED - session rating has failed.PROCESSED - session has been rated by rating engine.REPORTED - rated session has been reported to billing. |
|
errorDesc |
String |
Not Required |
Description of an error that could happen during session processing. |
|
lastUpdateTime |
String |
Not Required |
Timestamp of the last update of the session. |
Charge¶
Particular charge data to be imported.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
|---|---|---|---|---|
type |
Enum |
Required |
Type of charge. Values are:.
NEW - the charge is imported into database and ready to be rated.FAILED_PROCESSED - the charge rating has failed.PROCESSED - the charge has been rated successfully.FAILED_REPORTED - the charge reporting to billing subsystem has failed.REPORTED - the rated charge has been successfully reported to billing. |
|
subscriptionId |
String |
Required |
APS UUID of a customer or a reseller OSS subscription. |
|
accountId |
String |
Not Required |
APS UUID of customer’s or reseller’s account. |
|
resourceId |
String |
Required |
APS UUID of used BSS resource. |
|
unitPrice |
Number |
Not Required |
Price per unit of charged resource. |
|
totalPrice |
Number |
Required |
Total usage price. |
|
amount |
Number |
Required |
Total amount of the resource used. |
|
currencyCode |
String |
Required |
ISO currency code used in price fields. |
|
uom |
String |
Not Required |
Unit of measure for resource amount (“Gb”, “Kb”, “units”; “units” by default). |
|
chargeStartDate |
String |
Required |
Start of charging date. Format is “yyyy-MM-dd”. |
|
chargeEndDate |
String |
Required |
End of charging date. Format is “yyyy-MM-dd”. |
|
duration |
Number |
Not Required |
Resource usage duration. |
|
durationUom |
String |
Not Required |
Duration unit of measure { days, months, years }. |
|
description |
String |
Not Required |
Some description provided by vendor. |
|
sku |
String |
Not Required |
Stock Keeping Unit value in vendor system. |
|
mpn |
String |
Not Required |
Manufacturer Part Number. |
|
poNumber |
String |
Not Required |
Customer Purchase Order number. |
|
extChargeId |
String |
Not Required |
Charge ID in vendor system. |
|
extHash |
String |
Not Required |
Hash of all fields in the charge provided by vendor for uniqueness. |
|
attributes |
Dictionary |
Not Required |
Charge attributes |
Examples¶
Since the considered APS type contains custom operations, refer to Custom Operations for the general explanation of their structure and examples of operation calls.