Fax¶
The Fax API can send and receive fax easily.
Send Fax¶
Send a PDF file to a fax number
res = Hoiio.fax.send('+6511111111', '/path/to/file.pdf')
print res.txn_ref
# 'TX-1234'
A more advanced use. The filename parameter is used to change the filename that resides at Hoiio.
res = Hoiio.fax.send('+6511111111', '/path/to/file.pdf',
filename = 'awesome-file.pdf',
caller_id = '+6500000000',
tag = 'myapp',
notify_url = 'http://my.server.com/myscript'
)
Receive Fax¶
To receive fax, you need to purchase a Hoiio number that supports receiving fax. Currently (as of Sep 2012), only Singapore numbers are capable of receiving fax.
To get a notification from Hoiio whenever you receive a fax at the number, you will need to go to Hoiio’s developer portal and configure the Notify URL, or use Number to configure.
Retrieve Fax status¶
Find out the status of a Fax (supports both sent or received) with its txn_ref.
res = Hoiio.fax.status('TX-1234')
print res.txn_ref
# 'TX-1234'
print res.fax_status
# 'answered'
print res.src
# '+6500000000'
print res.dest
# '+6511111111'
print res.date
# datetime.datetime(2012, 1, 31, 12, 6, 15)
print res.fax_pages
# 3
print res.fax_url
# 'http://some.server.com/file.pdf'
print res.tag
# 'my-tag'
print res.currency
# 'SGD'
print res.rate
# 0.032
print res.debit
# 0.064
Retrieve Fax history¶
Query for all fax transactions. Each of entry has similar fields as the response in Retrieve Fax status.
res = Hoiio.fax.history()
print res.total_entries_count
# 234
print res.entries_count
# 100
for entry in res.entries:
print entry.txn_ref
print entry.fax_status
# etc ..
You can also filter the fax history by date and type (incoming, outgoing or all).
res = Hoiio.fax.history(
from = '2010-01-01 00:00:00',
to = '2012-01-01 00:00:00',
page = 3,
type = 'incoming'
)
Retrieve Fax rate¶
Find out how much a fax will cost before you actually send it.
res = Hoiio.fax.rate('+6511111111')
print res.currency
# 'SGD'
print res.rate
# 0.032
You also check how much it cost to receive a fax.
res = Hoiio.fax.rate_in('+6500000000')
print res.currency
# 'SGD'
print res.rate
# 0.01