1
0
mirror of https://github.com/invoiceninja/invoiceninja.git synced 2024-11-14 15:13:29 +01:00
invoiceninja/docs/api.rst
2019-01-30 22:00:26 +11:00

131 lines
4.6 KiB
ReStructuredText
Executable File
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

API
===
Invoice Ninja provides a RESTful 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 "API Tokens” page under "Advanced Settings”.
- **Zapier** [hosted or self-host]: https://zapier.com/zapbook/invoice-ninja/
- **Integromat**: https://www.integromat.com/en/integrations/invoiceninja
- **PHP SDK**: https://github.com/invoiceninja/sdk-php
- **Zend Framework**: https://github.com/alexz707/InvoiceNinjaModule
.. NOTE:: Replace ninja.test with https://app.invoiceninja.com to access a hosted account.
Reading Data
""""""""""""
Heres an example of reading the list of clients using cURL from the command line.
.. code-block:: shell
curl -X GET ninja.test/api/v1/clients -H "X-Ninja-Token: TOKEN"
For invoices, quotes, tasks and payments simply change the object type.
.. code-block:: shell
curl -X GET ninja.test/api/v1/invoices -H "X-Ninja-Token: TOKEN"
You can search clients by their email address or id number and invoices by their invoice number.
.. code-block:: shell
curl -X GET ninja.test/api/v1/clients?email=<value> -H "X-Ninja-Token: TOKEN"
curl -X GET ninja.test/api/v1/clients?id_number=<value> -H "X-Ninja-Token: TOKEN"
curl -X GET ninja.test/api/v1/invoices?invoice_number=<value> -H "X-Ninja-Token: TOKEN"
To load a single record specify the Id in the URL.
.. code-block:: shell
curl -X GET ninja.test/api/v1/invoices/1 -H "X-Ninja-Token: TOKEN"
You can specify additional relationships to load using the ``include`` parameter.
.. code-block:: shell
curl -X GET ninja.test/api/v1/clients/1?include=invoices.invitations -H "X-Ninja-Token: TOKEN"
You can download a PDF using the following URL
.. code-block:: shell
curl -X GET ninja.test/api/v1/download/1 -H "X-Ninja-Token: TOKEN"
Optional Settings
"""""""""""""""""
The following are optional query parameter settings:
- ``serializer``: Either array (the default) or `JSON <http://jsonapi.org/>`_.
- ``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.
Creating Data
"""""""""""""
.. TIP:: Add ``-H "X-Requested-With: XMLHttpRequest"`` to see validation errors in the response.
Heres an example of creating a client. Note that email address is a property of the clients contact not the client itself.
.. code-block:: shell
curl -X POST ninja.test/api/v1/clients -H "Content-Type:application/json" \
-d '{"name":"Client","contact":{"email":"test@example.com"}}' -H "X-Ninja-Token: TOKEN"
You can also update a client by specifying a value for id. Next, heres an example of creating an invoice.
.. code-block:: shell
curl -X POST ninja.test/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"
If the email field is set well search for a matching client, if no matches are found a new client will be created.
If the product_key is set and matches an existing record the product fields will be auto-populated. You can use a comma-separated value to create an invoice with multiple products.
Options
^^^^^^^
The following options are available when creating an invoice.
- ``email_invoice``: Email the invoice to the client.
- ``email_type``: Set to reminder1, reminder2 or reminder3 to use the reminder template.
- ``auto_bill``: Attempt to auto-bill the invoice using stored payment methods or credits.
- ``paid``: Create a payment for the defined amount.
Updating Data
"""""""""""""
.. NOTE:: When updating a client it's important to include the contact ids.
.. code-block:: shell
curl -X PUT ninja.test/api/v1/clients/1 -H "Content-Type:application/json" \
-d '{"name":"test", "contacts":[{"id": 1, "first_name": "test"}]}' \
-H "X-Ninja-Token: TOKEN"
You can archive, delete or restore an entity by setting ``action`` in the request
.. code-block:: shell
curl -X PUT ninja.test/api/v1/invoices/1?action=archive \
-H "X-Ninja-Token: TOKEN"
.. TIP:: For invoices use `mark_sent` to manually mark the invoice as sent
Emailing Invoices
"""""""""""""""""
To email an invoice use the email_invoice command passing the id of the invoice.
.. code-block:: shell
curl -X POST ninja.test/api/v1/email_invoice -d '{"id":1}' \
-H "Content-Type:application/json" -H "X-Ninja-Token: TOKEN"