API

AIOBilling has an external JSON API: one address, an action name, your credentials and the parameters, and an answer in JSON. Use it to connect a website, a mobile app, an accounting tool or your own scripts - create a client, place an order, read invoices, open a ticket, record a payment. This chapter covers how to sign in, how to limit a credential, the actions and a few examples.

Credentials and API roles

1. Open Setup → API Credentials, or the API link in the footer of the admin area (the API page, which has the documentation and your own credentials side by side).
2. Choose Generate New API Credential. Fill in a Note (what will use it), the Administrator it acts as, an API Role and the Allowed IP Addresses (one per line; empty means any address).
3. Press Generate. The page shows the identifier (it starts with ab_) and the secret (40 characters). Copy the secret now. It is stored as a hash and is shown only once. If you lose it, delete the credential and make a new one.

The credentials table shows each identifier, note, administrator, role, allowed IP addresses and when it was last used. Creating, editing and deleting need the Manage API Credentials permission. A credential stops working at once when you delete it or when its administrator is disabled.

API roles (the second tab) limit which actions a credential may call. Create a role with a name and tick the allowed actions - for example a role with only GetInvoices and GetClientsDetails for a reporting tool. A credential with no role may call every action. A role in use cannot be deleted.

Calling the API

Send a POST to https://your-billing.example.com/api/ (the address the API page shows as the endpoint) with:

Parameters may be sent as a form (-d), in the query string or as a JSON body. Arrays are written itemdescription[]=... (repeat it). Yes/no values accept 1, on, yes and true.

Every answer is JSON with a result of success or error:

{ "result": "success", "totalresults": 12, "startnumber": 0, "numreturned": 10, "invoices": { "invoice": [ ... ] } }
{ "result": "error", "message": "Authentication Failed" }

List actions take limitstart and limitnum (25 by default, 500 at most) and answer totalresults, startnumber and numreturned. Secrets - gateway keys, passwords and tokens - are never given out by the settings actions.

Switch on API Log under General Settings → Security to keep every call and its status in data/logs/api.log.

Examples

List unpaid invoices:

curl -s https://your-billing.example.com/api/ \
  -d "action=GetInvoices" -d "identifier=ab_xxxxxxxxxx" -d "secret=YOUR_SECRET" \
  -d "status=Unpaid" -d "limitnum=10"

Create a client:

curl -s https://your-billing.example.com/api/ \
  -d "action=AddClient" -d "identifier=ab_xxxxxxxxxx" -d "secret=YOUR_SECRET" \
  -d "firstname=Rahim" -d "lastname=Uddin" -d "email=rahim@example.com" \
  -d "password2=a-strong-password" -d "country=BD"

Create an invoice with two lines:

curl -s https://your-billing.example.com/api/ \
  -d "action=CreateInvoice" -d "identifier=ab_xxxxxxxxxx" -d "secret=YOUR_SECRET" -d "userid=1" \
  -d "itemdescription[]=Consulting" -d "itemamount[]=50.00" -d "itemtaxed[]=0" \
  -d "itemdescription[]=Setup" -d "itemamount[]=10.00" -d "sendinvoice=1"

Record a payment on an invoice (the amount defaults to the balance):

curl -s https://your-billing.example.com/api/ \
  -d "action=AddInvoicePayment" -d "identifier=ab_xxxxxxxxxx" -d "secret=YOUR_SECRET" \
  -d "invoiceid=25" -d "transid=BKASH-123" -d "gateway=bkash"

Place an order for a client and accept it:

curl -s https://your-billing.example.com/api/ \
  -d "action=AddOrder" -d "identifier=ab_xxxxxxxxxx" -d "secret=YOUR_SECRET" \
  -d "clientid=1" -d "paymentmethod=bkash" -d "pid[]=3" -d "billingcycle[]=monthly" -d "domain[]=example.com"
curl -s https://your-billing.example.com/api/ \
  -d "action=AcceptOrder" -d "identifier=ab_xxxxxxxxxx" -d "secret=YOUR_SECRET" -d "orderid=40"

The actions

The API page lists every action with its parameters and a filter box. There are 72 in the core; plugins can add more, which the page names under "Plugins add".

Clients and contacts

Products, services and domains

Orders

Billing

Support

System and mail

Good habits

• Make one credential per application, each with its own API role and, where the caller has a fixed address, Allowed IP Addresses.
• Always use https://. Never put the secret in a web page or a mobile app that others can read.
• Test with a role that can only read, then widen it.
• Delete credentials you no longer use. The last used time on the credentials page shows which ones are idle.