Allotments

Allotments Explanation

Each object have name (outbound_national) which build from direction (inbound or outbound) and classification from number manager configuration.

Properties

amount: time in seconds, which can be consumed
cycle: when we reset consumed allotments counter, must be one of minutely, hourly, daily, weekly, monthly.
increment: step (in seconds) of incrementing counter, minimum 1 second
minimum: minimum amount added to counter
no_consume_time: if call less or equal of this time (in seconds), then no allotment consumed.
group_consume: other allotments which will be summed, when calculating rest of allotments time on authorization. See examples below.

Examples

”increment”, “minimum” and “no_consume_time”

{
    "outbound_local": {
       "increment": 10,
       "minimum": 60,
       "no_consume_time": 5
    }
}

Call consumed time rounded before store it to DB. Call with duration 40 seconds will be count as 60 seconds.

69 seconds -> 70
75 seconds -> 80
5 seconds -> 0
6 seconds -> 60

”group_consume”

{
  "Class1": {
       "amount": 600,
       "group_consume": [
           "Class2"
       ]
   },
   "Class2": {
       "amount": 600,
       "group_consume": [
           "Class1"
       ]
   }
}

Here we have 2 classifiers which share same counter. If Class1 already consumed 400 seconds and Class2 consumed 150 seconds, next call with classifier Class2 (or Class1) will have 50 free seconds.

Little more complex example:

{
  "Class1": {
       "amount": 600,
       "group_consume": [
           "Class2",
           "Class3"
       ]
   },
   "Class2": {
       "amount": 120,
       "group_consume": [
           "Class1"
       ]
   },
   "Class3": {
       "amount": 300,
       "group_consume": [
            "Class2"
       ]
   }
}

So if we already have consumed calls:

Class1 - 300
Class2 - 60
Class3 - 180

As result next call will have this free seconds:

Class1 - 60 (300 Class1 + 60 Class2 + 180 Class3 = 540, 600-540 = 60)
Class2 - 0 (60 Class2 + 300 Class1 = 360, 360 > 120)
Class3 - 60 (180 Class3 + 60 Class2 = 240, 300-240 = 60)

Schema

Create buckets of minutes per time-period

Key	Description	Type	Required
`^\w+$.amount`	Time in seconds, which can be consumed	`integer(0..)`	`true`
`^\w+$.cycle`	On the basis to reset consumed allotments counter	`string('minutely', 'hourly', 'daily', 'weekly', 'monthly')`	`true`
`^\w+$.group_consume.[]`		`string()`	`false`
`^\w+$.group_consume`	Other allotments which will be summed, when calculating rest of allotments time on authorization	`array(string())`	`false`
`^\w+$.increment`	Step (in seconds) of incrementing counter	`integer(1..)`	`false`
`^\w+$.minimum`	Minimum amount added to counter	`integer(0..)`	`false`
`^\w+$.no_consume_time`	If call duration is less or equal of this time (in seconds), then no allotment consumed	`integer(0..)`	`false`
`^\w+$`		`object()`	`false`

Fetch

GET /v2/accounts/{ACCOUNT_ID}/allotments

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/allotments

{
    "data": {
        "outbound_national": {
            "amount": 600,
            "cycle": "hourly",
            "increment": 60,
            "minimum": 60,
            "no_consume_time": 2,
            "group_consume": [
                "outbound_local"
            ]
        },
        "outbound_local": {
            "amount": 600,
            "cycle": "hourly",
            "increment": 60,
            "minimum": 60,
            "no_consume_time": 2,
            "group_consume": [
                "outbound_national"
            ]
        }
    },
    "status": "success"
}

Update allotments configuration for a given account

POST /v2/accounts/{ACCOUNT_ID}/allotments

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/allotments

{
    "data": {
        "outbound_national": {
            "amount": 3600,
            "cycle": "monthly",
            "increment": 60,
            "minimum": 60,
            "no_consume_time": 2,
            "group_consume": [
                "outbound_local"
            ]
        },
        "outbound_local": {
            "amount": 3600,
            "cycle": "monthly",
            "increment": 60,
            "minimum": 60,
            "no_consume_time": 2,
            "group_consume": [
                "outbound_national"
            ]
        }
    }
}

Get consumed allotments for a given account

GET /v2/accounts/{ACCOUNT_ID}/allotments/consumed

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/allotments/consumed

{
    "data": {
        "outbound_local": {
            "consumed": 120,
            "consumed_to": 63608284800,
            "consumed_from": 63605606400,
            "cycle": "monthly"
        },
        "outbound_national": {
            "consumed": 120,
            "consumed_to": 63606384000,
            "consumed_from": 63605779200,
            "cycle": "weekly"
        }
    },
    "status": "success",
}

Get consumed allotments for a certain period of time

{TIMESTAMP} - Gregorian epoch seconds.

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/allotments/consumed?created_from={TIMESTAMP}&created_to={TIMESTAMP}`

{
    "data": {
        "outbound_local": {
            "consumed": 180,
            "consumed_to": 63607728001,
            "consumed_from": 63605046001,
            "cycle": "manual"
        },
        "outbound_national": {
            "consumed": 120,
            "consumed_to": 63607728001,
            "consumed_from": 63605046001,
            "cycle": "manual"
        }
    },
    "status": "success",
}

Get consumed allotments at certain time