invoicefu heroku addon will let your application send invoices in a fast convenient way. In the simplest case, all you need is to make a single POST to our REST API to create and send an invoice to your client. The invoice will be available at the invoicefu backend where you will be able to check all your invoices, see how much you invoiced to each of your clients and share the invoices in read-only mode with your accountant.
Most advanced features like partial payments, proforma invoices, or client management are also available via our REST API.
Installing the addon
invoicefu addon will be associated to one of the apps you host in Heroku. You can see all your currently hosted apps at Heroku backend. First of all you'll need to login into your heroku account
The "My apps" option in the menu should display all your applications
Users in alpha phase, must now proceed to install the addon from the heroku console. Open a shell in your system and execute the following command:
heroku addons:add invoicefu --app appname
appname should be the exact name you see in the list. In our example the line would be
heroku addons:add invoicefu --app app-play
The command line interface should tell you the application was succesfully installed. At this moment, a user has been created for you in invoicefu, but you need to provide some information before you can start using the addon. To access invoicefu, go back to your browser, click on the name of your application, then open the "addons" dropdown and click on "invoicefu".
We need to know your business name, your contact e-mail and the country in which your business is operating to set the appropriate default values for your currency, taxes,date and number formats. You can modify these default values at anytime by accesing the "my account" option of invoicefu's backend. Default values can be overriden if needed when creating a single invoice using our API.
Please take into account until you finish the manual setup of the account (just providing the email and country) every call to the API will return a 404 not found error
After entering your data, you will see the account complete screen. You could already start using the application via the user interface or the API, but it's advisable to proceed first to the "My account" form and fill the data you want to use for your invoices. You can provide this information everytime you create an invoice, but for most users it's more convenient to enter the data only the first time and forget about it.
Congratulations! If you made it this far, you are ready to start using our REST API to manage your invoices. Keep reading to learn how to use it.
Using the API
invoicefu features a REST API available both as JSON and XML. All the communication with the API must be done via HTTPs. All you need to connect to invoicefu from your heroku application is the HTTPS client library of your choice.
A request to the API consists of a HTTP call to our endpoint with optional parameters. Since this is a REST API, the same URL will produce different results according to the HTTP verb used, so please make sure you are issuing your requests appropriately. For example:
GET https://invoicefu.com/api/v1/accounts/1-kovacek-nienow.json, would return the information about this account
PUT https://invoicefu.com/api/v1/accounts/1-kovacek-nienow.json, would update the information of this account with the supplied data
Our API support the verbs POST, GET, PUT, DESTROY. Note not all the resources/URL support all the verbs. For example, you can update an existing account via PUT, but you cannot DESTROY the current account.
If you want to use the JSON API use ".json" at the end of the URL. If you want to use XML, end your URLs with ".xml"
Authorization management. Signing in
Mosf of the operations require authentication. When using the heroku addon, no signin is necessary, and authentication is achieved by providing three parameters on each request: app_platform, app_id and api_key. These parameters uniquely identify your application in the system, so by providing them securely via SSL invoicefu will authorize your requests.
The values for these parameters will be available for your heroku application as the environment variables INVOICEFU_APP_PLATFORM, INVOICEFU_APP_ID and INVOICEFU_API_KEY.
Supossing your application has the INVOICEFU_APP_ID "app3681" and the INVOICEFU_API_KEY "bc3b8969e4eaa23aaf7c6973004675a05897c719", the following request would give you the information about your account
https://invoicefu.com/api/v1/accounts.xml?app_platform=heroku&app_id=app3681@kensa.heroku.com&api_key=bc3b8969e4eaa23aaf7c6973004675a05897c719
Trying invoicefu locally from your development environment
You'll probably want to try the addon from your development environment, before deploying to heroku. All you need to do is using the three
authentication parameters (app_platform, app_id and api_key) with the values registered in heroku. You can easily see the appropriate
values by using the heroku command line interface
heroku addons:add invoicefu --app appname
appname should be the exact name you see in the list. In our example the line would be
heroku config --app app-play
Creating invoices with the API
If you want to learn how to create invoices from your heroku application, visit our step-by-step example.
More information
You now have all the information you need to start using invoicefu. To know more about all the services available via our API, please check the api documentation.
