airtimeSearch method
Search airtime by phone number
Searches for a phone number's operator by carrier lookup and returns it with its offers (detected flow). Returns { items, pagination, details: { phoneLookup: { status, carrierName, countryCode } } }. items holds at most the detected operator with its offers. It is empty when status is not detected or no offer remains after the filters; then let the customer choose the operator with GET operators?countryCode=, using details.phoneLookup.countryCode. Each call makes exactly one carrier lookup and returns at most one item, so page must be 1. A phoneNumber that is not in international format gives 400 / 10001; a carrier lookup that fails gives 503 / 10007, retry later.
Parameters:
-
String phoneNumber (required): The recipient's number in international format, starting with + or 00; spaces, hyphens and parentheses are allowed.
-
String valueType: Keep only
fixedor onlyrangeoffers. -
String valueCurrency: Currency of
minValueandmaxValue, three letters; required with either of them. -
num minValue: Keep the offers whose value reaches at least this amount, in
valueCurrency. -
num maxValue: Keep the offers whose value starts at or below this amount, in
valueCurrency. -
num minPrice: Keep the offers whose indicative price reaches at least this amount, in the price currency.
-
num maxPrice: Keep the offers whose indicative price starts at or below this amount, in the price currency. A filter, not the
inputs.maxPricelimit of a purchase. -
String currency: Price currency, three letters in either case; the API key's currency when omitted. An unsupported code gives 404 / 10004.
-
int page: Must be 1: search returns at most one operator.
-
int limit: Page size, 1 to 100; default 10.
Implementation
Future<AirtimeSearchResult?> airtimeSearch(String phoneNumber, { String? valueType, String? valueCurrency, num? minValue, num? maxValue, num? minPrice, num? maxPrice, String? currency, int? page, int? limit, Future<void>? abortTrigger, }) async {
final response = await airtimeSearchWithHttpInfo(phoneNumber, valueType: valueType, valueCurrency: valueCurrency, minValue: minValue, maxValue: maxValue, minPrice: minPrice, maxPrice: maxPrice, currency: currency, page: page, limit: limit, abortTrigger: abortTrigger,);
if (response.statusCode >= HttpStatus.badRequest) {
throw ApiException(response.statusCode, await _decodeBodyBytes(response));
}
// When a remote server returns no body with a status of 204, we shall not decode it.
// At the time of writing this, `dart:convert` will throw an "Unexpected end of input"
// FormatException when trying to decode an empty string.
if (response.body.isNotEmpty && response.statusCode != HttpStatus.noContent) {
return await apiClient.deserializeAsync(await _decodeBodyBytes(response), 'AirtimeSearchResult',) as AirtimeSearchResult;
}
return null;
}