Rent
A rent keeps a number for days days. Its SMS come in RentItem.messages(), newest first.
get reserves the price (it shows in zbalance()): the rent starts with status() 0 and checked() false and waits up to 20 minutes for its first SMS. The first SMS that is not a notify notice confirms it (status() 1) and charges the price; without one the rent closes and the reservation is released. Some countries (confirm() in tariffs, e.g. US numbers) are confirmed and charged at once.
RentItem: tzid(), status(), number(), country(), sum(), days(), hours(), time(), timeSeconds(), extension(), extend(), messages(), startTime(), stopTime(), dayExtend(), … —
sum() is the cost in USD incl. extensions (a Double; the server sends a number or, in state, a decimal string), time() minutes left, timeSeconds() seconds left,
extension() 0 not extendable / 1 extendable / 2 auto-extension, extend() maps days to the extension price (empty when not extendable),
messages() is List<RentSms>: id(), service(), text(), code(), createdAt() — code() is "" when no code was found and "0" for a notify SMS (a prohibited sender; the server sends the number 0).
get
Rent a number. The price is reserved; the first SMS charges it.
suspend fun get(country: Int = 7, days: Int = 1, extension: Boolean = true): RentItem
| Param | Type | Default | Description |
|---|---|---|---|
country | Int | 7 | Country code. |
days | Int | 1 | One of the tariff's days() keys. |
extension | Boolean | true | false makes the rent non-extendable for good. |
val rent = client.rent.get(7, days = 7)
println("${rent.tzid()} ${rent.number()} ${rent.sum()}")
Errors: NoNumberException; ApiException UNDEFINED_DAYS, UNDEFINED_COUNTRY, WARNING_LOW_BALANCE, INTERVAL_CONCURRENT_REQUESTS_ERROR, TRY_AGAIN_LATER.
state
All rents of the account.
suspend fun state(): List<RentItem>
for (rent in client.rent.state()) {
println("${rent.number()} ${rent.messages().firstOrNull()?.code() ?: "-"}")
}
stateOne
One rent.
suspend fun stateOne(tzid: Long): RentItem
val messages = client.rent.stateOne(tzid).messages()
Errors: ApiException ERROR_NO_OPERATIONS for an unknown tzid.
extend
Extend a rent by days days and charge the balance at once. Only confirmed rents (status() 1 or 4) created with extension = true.
suspend fun extend(tzid: Long, days: Int = 1): RentItem
val rent = client.rent.extend(tzid, days = 3)
println(rent.stopTime())
Errors: ApiException TRY_AGAIN_LATER (unknown tzid, not confirmed yet or closed, not extendable, unknown period, a repeat within 10 s), WARNING_LOW_BALANCE.
close
Return the number before the period ends. A rent that is not confirmed yet (status() 0) and has no SMS can be closed only after 120 s; then, or with only notify SMS, the reservation is released. With a real SMS the rent is confirmed (charged) and closed. A confirmed rent closes without a refund. US numbers cannot be closed early.
suspend fun close(tzid: Long)
client.rent.close(tzid)
Errors: ApiException ERROR_NO_OPERATIONS, NO_COMPLETE_TZID, NO_CLOSE_RENT_US, TRY_AGAIN_LATER.
tariffs
Rent prices of every country, keyed by country code. No API key needed.
suspend fun tariffs(): Map<String, RentTariff>
RentTariff: code(), name(), enabled(), isNew(), position(), extend(), confirm(), days(), count(), extCounts() — days() maps rent days to the price in USD, count() to the numbers available.
val tariffs = client.rent.tariffs()
tariffsOne
Rent prices of one country.
suspend fun tariffsOne(country: Int = 7): RentTariff
val days = client.rent.tariffsOne(7).days()
println(days["7"]) // price of 7 days
Errors: ApiException NO_COUNTRY for a country without rent.