2017-03-13 19:56:20 +01:00
API
===
Invoice Ninja provides a REST based API, `click here <https://app.invoiceninja.com/api-docs#/> `_ to see the full list of methods available.
To access the API you first need to create a token using the "Tokens” page under "Advanced Settings”.
2017-03-13 20:20:37 +01:00
- **Zapier** : https://zapier.com/zapbook/invoice-ninja/
- **PHP SDK** : https://github.com/invoiceninja/sdk-php
2017-03-13 19:56:20 +01:00
.. NOTE :: Replace ninja.dev with https://app.invoiceninja.com to access a hosted account.
Reading Data
""""""""""""
Here’ s an example of reading the list of clients using cURL from the command line.
2017-03-17 15:39:20 +01:00
.. code-block :: shell
curl -X GET ninja.dev/api/v1/clients -H "X-Ninja-Token: TOKEN"
2017-03-13 19:56:20 +01:00
2017-03-19 16:44:35 +01:00
For invoices, quotes, tasks and payments simply change the object type.
2017-03-13 19:56:20 +01:00
2017-03-17 15:39:20 +01:00
.. code-block :: shell
curl -X GET ninja.dev/api/v1/invoices -H "X-Ninja-Token: TOKEN"
2017-03-13 19:56:20 +01:00
To load a single record specify the Id in the URL. Note: you can add ?invoice_number=0001 to search invoices by invoice number.
2017-03-17 15:39:20 +01:00
.. code-block :: shell
curl -X GET ninja.dev/api/v1/invoices/1 -H "X-Ninja-Token: TOKEN"
2017-03-13 19:56:20 +01:00
2017-03-19 16:44:35 +01:00
You can specify additional relationships to load using the `` include `` parameter.
.. code-block :: shell
curl -X GET ninja.dev/api/v1/clients/1?include=invoices.invitations -H "X-Ninja-Token: TOKEN"
2017-03-13 19:56:20 +01:00
You can download a PDF using the following URL
2017-03-17 15:39:20 +01:00
.. code-block :: shell
curl -X GET ninja.dev/api/v1/download/1 -H "X-Ninja-Token: TOKEN"
2017-03-13 19:56:20 +01:00
Creating Data
"""""""""""""
Here’ s an example of creating a client. Note that email address is a property of the client’ s contact not the client itself.
2017-03-17 15:39:20 +01:00
.. code-block :: shell
curl -X POST ninja.dev/api/v1/clients -H "Content-Type:application/json"
-d '{"name":"Client","contact":{"email":"test@gmail.com"}}' -H "X-Ninja-Token: TOKEN"
2017-03-13 19:56:20 +01:00
You can also update a client by specifying a value for ‘ id’ . Next, here’ s an example of creating an invoice.
2017-03-17 15:39:20 +01:00
.. code-block :: shell
curl -X POST ninja.dev/api/v1/invoices -H "Content-Type:application/json"
-d '{"client_id":"1", "invoice_items":[{"product_key": "ITEM", "notes":"Test", "cost":10, "qty":1}]}'
-H "X-Ninja-Token: TOKEN"
2017-03-13 19:56:20 +01:00
If the product_key is set and matches an existing record the product fields will be auto-populated. If the email field is set then we’ ll search for a matching client. If no matches are found a new client will be created. To email the invoice set email_invoice to true.
To set the invoice date field you can either use the "invoice_date” field passing a date formatted the same way the company is configured or use "invoice_date_sql” to pass a SQL formatted date (ie, "YYYY-MM-DD”).
Emailing Invoices
"""""""""""""""""
To email an invoice use the email_invoice command passing the id of the invoice.
2017-03-17 15:32:11 +01:00
.. code-block :: shell
2017-03-17 15:39:20 +01:00
curl -X POST ninja.dev/api/v1/email_invoice -d '{"id":1}'
-H "Content-Type:application/json" -H "X-Ninja-Token: TOKEN"
2017-03-13 19:56:20 +01:00
Optional Settings
"""""""""""""""""
The following are optional query parameter settings:
2017-03-19 14:31:25 +01:00
- `` serializer `` : Either array (the default) or `JSON <http://jsonapi.org/> `_ .
2017-03-18 20:09:42 +01:00
- `` include `` : A comma-separated list of nested relationships to include.
- `` client_id `` : If set the results will be filtered by the client.
- `` page `` : The page number of results to return when the results are paginated.
- `` per_page `` : The number of results to return per page.
- `` updated_at `` : Timestamp used as a filter to only show recently updated records.
2017-03-13 19:56:20 +01:00
Subscriptions
"""""""""""""
You can use subscriptions to have Invoice Ninja POST newly created records to a third-party application. To enable this feature you need to manually add a record to the subscriptions table. To determine the event_id find the associated EVENT_CREATE_ value from app/Constants.php.