{"id":20066288,"url":"https://github.com/ossobv/exactonline","last_synced_at":"2025-10-16T17:41:59.159Z","repository":{"id":28814956,"uuid":"32338157","full_name":"ossobv/exactonline","owner":"ossobv","description":"Exact Online (accounting software) REST API Library in Python","archived":false,"fork":false,"pushed_at":"2023-07-29T20:57:37.000Z","size":564,"stargazers_count":39,"open_issues_count":10,"forks_count":49,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-04-27T10:09:12.523Z","etag":null,"topics":["finance","library","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ossobv.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-16T16:29:57.000Z","updated_at":"2024-06-18T22:54:11.979Z","dependencies_parsed_at":"2024-06-18T22:54:06.753Z","dependency_job_id":null,"html_url":"https://github.com/ossobv/exactonline","commit_stats":{"total_commits":128,"total_committers":9,"mean_commits":"14.222222222222221","dds":0.0625,"last_synced_commit":"1311c7d70a959e78aa24b34b0379bf2b221c2c75"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossobv%2Fexactonline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossobv%2Fexactonline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossobv%2Fexactonline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossobv%2Fexactonline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ossobv","download_url":"https://codeload.github.com/ossobv/exactonline/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246916760,"owners_count":20854514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["finance","library","python"],"created_at":"2024-11-13T13:55:55.943Z","updated_at":"2025-10-16T17:41:54.105Z","avatar_url":"https://github.com/ossobv.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"|EXACTAPI|\n==========\n\n*Exact Online REST API Library in Python*\n\n.. image:: https://api.travis-ci.com/ossobv/exactonline.svg\n        :alt: Continuous Integration Status\n\n\nExact Online provides accounting software in a Software-as-a-Service\ndelivery model. It implements an API through a REST interface. This\nlibrary aims to ease its use.\n\n\n\nQuick jump\n----------\n\n* `Usage by example`_\n* `Using element adapters`_\n* `Setting up the link`_\n* `Implemented resources`_\n* `Other benefits`_\n* `License`_\n* `TODO`_\n* `Further reading`_\n\n\n\nUsage by example\n----------------\n\nSet up the basics:\n\n.. code-block:: python\n\n    from exactonline.api import ExactApi\n    from exactonline.exceptions import ObjectDoesNotExist\n    from exactonline.resource import GET, POST, PUT, DELETE\n    from exactonline.storage.ini import IniStorage\n\n    # Create a function to get the api with your own storage backend.\n    def get_api():\n        # NOTE: The IniStorage is really simple does not synchronize with\n        # other instances. You should create your own storage. See below.\n        storage = IniStorage('/path/to/config.ini')\n        return ExactApi(storage=storage)\n    api = get_api()\n\nGet an invoice:\n\n.. code-block:: python\n\n    # Get an invoice by your own invoice number (YourRef).\n    # Returns a dictionary, or raises ObjectDoesNotExist.\n    invoice = api.invoices.get(invoice_number='F0005555')\n\nIt looks somewhat like this:\n\n.. code-block:: python\n\n    invoice == {\n        u'AmountDC': 50.8,\n        u'AmountFC': 50.8,\n    # ...\n        u'SalesEntryLines': [\n            {u'AmountDC': 41.98,\n             u'AmountFC': 41.98,\n    # ...\n             u'Description': u'Omzet backups',\n             u'VATBaseAmountDC': 41.98,\n             u'VATBaseAmountFC': 41.98},\n        ],\n    # ...\n        u'VATAmountDC': 8.82,\n        u'VATAmountFC': 8.82,\n        u'YourRef': u'F0005555',\n        u'__metadata': {u'type': u'Exact.Web.Api.Models.SalesEntry',\n                        u'uri': u\"https://start.exactonline.nl/api/v1/...\"},\n    }\n\nGet relations:\n\n.. code-block:: python\n\n    relations_limit_2 = api.relations.filter(top=2)\n    # that was cheaper than: api.relations.all()[0:2]\n\n    relations_limit_2 == [\n        {u'Code': u'              1068',\n         u'ID': u'11111111-2222-3333-4444-555555555555',\n         u'Name': u'ACME Corporation',\n         u'__metadata': {u'type': u'Exact.Web.Api.Models.Account',\n                         u'uri': u\"https://start.exactonline.nl/api/v1/...')\"}},\n        {u'Code': u'               555',\n         u'ID': u'22222222-3333-4444-5555-666666666666',\n         u'Name': u'Daffy Duck Ltd.',\n         u'__metadata': {u'type': u'Exact.Web.Api.Models.Account',\n                         u'uri': u\"https://start.exactonline.nl/api/v1/...')\"}}\n    ]\n\nUpdate a relation:\n\n.. code-block:: python\n\n    daffy_duck = api.relations.get(relation_code='555')\n    api.relations.update(daffy_duck['ID'], {'Name': 'Daffy Duck and sons'})\n\nDelete a relation:\n\n.. code-block:: python\n\n    daffy_duck = api.relations.get(relation_code='555')\n    api.relations.delete(daffy_duck['ID'])\n\nCreate an invoice:\n\n.. code-block:: python\n\n    customer_data = api.relations.get(relation_code='123')  # local relation_code\n    customer_guid = customer_data['ID']\n    invoice_data = {\n        'AmountDC': str(amount_with_vat),  # DC = default currency\n        'AmountFC': str(amount_with_vat),  # FC = foreign currency\n        'EntryDate': invoice_date.strftime('%Y-%m-%dT%H:%M:%SZ'),  # pretend we're in UTC\n        'Customer': customer_guid,\n        'Description': u'Invoice description',\n        'Journal': remote_journal,  # 70 \"Verkoopboek\"\n        'ReportingPeriod': invoice_date.month,\n        'ReportingYear': invoice_date.year,\n        'SalesEntryLines': [],\n        'VATAmountDC': str(vat_amount),\n        'VATAmountFC': str(vat_amount),\n        'YourRef': local_invoice_number,\n        # must start uniquely at the start of a year, defaults to:\n        # YYJJ0001 where YY=invoice_date.year, and JJ=remote_journal\n        'InvoiceNumber': '%d%d%04d' % (invoice_date.year, remote_journal,\n                                       int(local_invoice_number)),\n    }\n    # The SalesEntryLines need to be filled with a bunch of dictionaries\n    # with these keys: AmountDC, AmountFC, Description, GLAccount,\n    # VATCode where GLAccount holds the Journal remote GUID, and the\n    # amounts are without VAT.\n\n    api.invoices.create(invoice_dict)\n\nYou may need to play around a bit to find out which fields are\nmandatory, and what kind of values the fields need.  The `Exact Online\nREST resources list`_ isn't always clear on that.\n\n\n\nUsing element adapters\n----------------------\n\nUsing the above works, but it's not really object oriented. If\navailable, you may be better off using one of the adaptable classes in\n``exactonline.elements`` and subclassing that.\n\nFor example, this is how you could create your own interface to an Exact\nOnline customer.\n\n.. code-block:: python\n\n    # Assuming you have a MyRelation that looks like this:\n    class MyRelation(object):\n        relcode = 12345\n        first_name = 'John'\n        last_name = 'Doe'\n        billing_address = None\n        # ...\n\n    # You could create an adapter subclass of ExactCustomer like this:\n    class MyExactCustomer(ExactCustomer):\n        def __init__(self, my_relation=None, **kwargs):\n            super(MyExactCustomer, self).__init__(**kwargs)\n            self._my_relation = my_relation\n\n        def get_code(self):\n            return str(self._my_relation.relcode)\n\n        def get_name(self):\n            return ' '.join([\n                self._my_relation.first_name,\n                self._my_relation.last_name])\n\n        def get_address(self):\n            address = self._my_relation.billing_address\n            if address:\n                return {\n                    'AddressLine1': address.street_and_number(),\n                    'Postcode': address.zipcode,\n                    'City': address.city.name,\n                }\n            return {}\n\nIf you have the above set up, and have unique customer codes, then\nwriting/updating an Exact Online relation is as convenient as this:\n\n.. code-block:: python\n\n    johndoe = MyRelation(...)\n    exactonline_relation = MyExactCustomer(my_relation=johndoe, api=api)\n    ret = exactonline_relation.commit()\n\nThese adaptable elements are currently implemented for writing customers\n(ExactCustomer) and invoices (ExactInvoice). See the files in\n``exactonline/elements/`` for more info.\n\n\n\nSetting up the link\n-------------------\n\nYou'll need a storage backend. The default ``IniStorage`` can be taken from\n``exactonline.storage``.\n\n.. code-block:: python\n\n    from exactonline.storage.ini import IniStorage\n\n    class MyIniStorage(IniStorage):\n        def get_response_url(self):\n            \"Configure your custom response URL.\"\n            return self.get_base_url() + '/oauth/success/'\n\n    storage = MyIniStorage('/path/to/config.ini')\n\n.. note:: *The IniStorage does not synchronize with other instances*\n\n    *This means that you cannot use multiple IniStorage instances at the same\n    time. If you want that, or thread-safe/multi-process-safe operations, or\n    better yet, integration with your project storage (database?), you should\n    create your custom storage backend. Look in ``exactonline/storage/base.py``\n    to see how. It's really easy.*\n\nYou need to set up access to your Exact Online SaaS instance, by creating an\nexport link. See `creating Exact Online credentials`_ for more info.\n\nTake that info, and configure it in your ``config.ini``.\n\n.. code-block:: ini\n\n    [server]\n    auth_url = https://start.exactonline.co.uk/api/oauth2/auth\n    rest_url = https://start.exactonline.co.uk/api\n    token_url = https://start.exactonline.co.uk/api/oauth2/token\n\n    [application]\n    base_url = https://example.com\n    client_id = {12345678-abcd-1234-abcd-0123456789ab}\n    client_secret = ZZZ999xxx000\n    ; optional config:\n    iteration_limit = 50\n\nCreate an initial URL:\n\n.. code-block:: python\n\n    api = ExactApi(storage=storage)\n    url = api.create_auth_request_url()\n\nThe URL will look like this; redirect the user there so he may\nauthenticate and allow your application access to Exact Online (this is\nOAuth)::\n\n    https://start.exactonline.nl/api/oauth2/auth?\n      client_id=%7B12345678-abcd-1234-abcd-0123456789ab%7D\u0026\n      redirect_uri=https%3A//example.com/oauth/success/\u0026\n      response_type=code\n\nAfter authentication he will get redirected back to::\n\n    https://example.com/oauth/success/?code=...\n\nYou should implement a view on that URL, that does basically this:\n\n.. code-block:: python\n\n    api.request_token(code)\n\nAt this point, you should configure your default division, if you\nhaven't already:\n\n.. code-block:: python\n\n    division_choices, current_division = api.get_divisions()\n    api.set_division(division_choices[0][0])  # select ID of first division\n\nNow you're all set!\n\n\n\nImplemented resources\n---------------------\n\nView ``exactonline/api/__init__.py`` to see which resource helpers are\nimplemented.\n\nCurrently, it looks like this:\n\n.. code-block:: python\n\n    contacts = Contacts.as_property()\n    invoices = Invoices.as_property()\n    ledgeraccounts = LedgerAccounts.as_property()\n    receivables = Receivables.as_property()\n    relations = Relations.as_property()\n    vatcodes = VatCodes.as_property()\n\nBut you can call resources which don't have a helper directly. The\nfollowing two three are equivalent:\n\n.. code-block:: python\n\n    api.relations.all()\n    api.restv1(GET('crm/Accounts'))\n    api.rest(GET('v1/%d/crm/Accounts' % selected_division))\n\nAs are the following three:\n\n.. code-block:: python\n\n    api.relations.filter(top=2)\n    api.restv1(GET('crm/Accounts?$top=2'))\n    api.rest(GET('v1/%d/crm/Accounts?$top=2' % selected_division))\n\nAnd these:\n\n.. code-block:: python\n\n    api.invoices.filter(filter=\"EntryDate gt datetime'2015-01-01'\")\n    api.restv1(GET('salesentry/SalesEntries?' +\n      '$filter=EntryDate%20gt%20datetime%272015-01-01%27'))\n    api.rest(GET('v1/%d/salesentry/SalesEntries?' +\n      '$filter=EntryDate%%20gt%%20datetime%%272015-01-01%%27' %\n      selected_division)\n    # convinced yet that the helpers are useful?\n\nSee the `Exact Online REST resources list`_ for all available resources.\n\n\n\nOther benefits\n--------------\n\nThe ExactApi class ensures that:\n\n* Tokens are refreshed as needed (see: ``exactonline/api/autorefresh.py``).\n* Paginated lists are automatically downloaded in full (see:\n  ``exactonline/api/unwrap.py``).\n\n\n\nCreating Exact Online credentials\n---------------------------------\n\nPreviously, one could create an API from the Exact Online interface directly.\nThis was removed at some point between 2014 and 2015.\n\nAccording to the `\"how can I create an application key?\" FAQ entry`_\nyou must now create one through the App Center.\n\n    *Why am I unable to see the Register an API link and how can I\n    create an application key?*\n\n    All registrations are now configured through the App Center.\n    Previously you were able to generate an Application Key and/or create an\n    OAuth registration within your Exact Online.\n\n    In Exact Online you can create an app registration for private use\n    (customer account) or an app registration for commercial use (partner\n    account). Go to Target groups and site maps for more information.\n\n    If the Register API Key link is not visible in the App Center\n    menu you do not have the correct rights to view it. To make the\n    link visible go to, Username \u003e My Exact Online \u003e Rights and\n    select Manage subscription.\n\nLog into the `Exact Online App Center`_, click MANAGE APPS (APPS BEHEREN);\nit should be a large link visible on the Top Right. Make sure the redirect\nURI has the same transport+domainname as the site that you wish to connect.\n\nFor sites with an internal URI only, you may need to alter the hostname\ntemporarily when registering. Generate the register URL with\n``api.create_auth_request_url`` and alter it as appropriate.\n\nAfter creating the App, you can go back and fetch the the *Client ID*\nand the *Client secret*.\n\n\n\nLicense\n-------\n\nExact Online REST API Library in Python is free software: you can\nredistribute it and/or modify it under the terms of the GNU Lesser\nGeneral Public License as published by the Free Software Foundation,\nversion 3 or any later version.\n\n\n\nTODO\n----\n\n* Fix so file Copyright headers are auto-populated (and date-updated).\n\n\n\nFurther reading\n---------------\n\n* `Exact Online REST API`_.\n* `Exact Online REST resources list`_.\n* `Tips by Bas van Beek`_.\n\n.. _`Exact Online App Center`: https://apps.exactonline.com/\n.. _`Exact Online REST API`: https://developers.exactonline.com/#RestIntro.html%3FTocPath%3DExact%2520Online%2520REST%2520API%7C_____0\n.. _`Exact Online REST resources list`: https://start.exactonline.co.uk/docs/HlpRestAPIResources.aspx?SourceAction=10\n.. _`Tips by Bas van Beek`: http://www.basvanbeek.nl/exact-online-tips/\n\n.. _`\"how can I create an application key?\" FAQ entry`: https://developers.exactonline.com/#FAQ_General.htm%3FTocPath%3DApp%2520Center%7C_____5\n\n\n.. |EXACTAPI| image:: assets/exactapi-head.png\n    :alt: ExactAPI\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fossobv%2Fexactonline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fossobv%2Fexactonline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fossobv%2Fexactonline/lists"}