Before you start with the development of an api integration, please contact your Run my Accounts online accountant or the support to create a booking concept ([email protected]). For api-integration to be executed correctly, it is absolutely necessary that a booking concept is available. If you have an online accountant, you can contact him directly, on the contrary please contact the support. They can help you with accounting related questions and provide you with a sandbox environment for your development. This documentation is intended for software developers who want to connect their applications to the accounting system of Run my Accounts.
API as RESTful resources
Run my Accounts’ API follows the design rules of “Representational State Transfer” as described in here.
API is based on HTTP(s)
HTTP-Methods are used to represent operations on the resources:
- GET return entities
- POST adds or changes entities
The basic api url is:
https://service.runmyaccounts.com/api/{version}/{resource}
Use version=latest to access the latest version of the api. If available, other versions would be named in the resource description details.
Content-Types and field/parameter formats
The Run my Accounts API understands XML and JSON. Make sure that…
- Requests must be UTF-8 encoded. Responses are UTF-8.
- Use header „Accept“ to set the content type of the GET responses: application/json or application/xml
- POST with header Content-Type application/json or application/xml
- Valid values for boolean parameters are: true or false
- Date parameters format is: yyyy-MM-dd. Relativ dates such as today, yesterday or tomorrow are supported.
- Datetime format is yyyy-MM-dd’T’HH:mm:ss.SSSZ (Ex: 2011-10-24T10:39:18.333+02:00)
- Some string fields might be limited in length. TEXT(32) is limited to 32 characters.
HTTP response codes
200: OK – All ok with response content
204: OK – With no response content (some POST resources do not reply with content)
400: Bad Request – Your request is invalid.
403: Forbidden – Access to the requested resource or action is forbidden.
404: Not Found – The requested resource could not be found.
500: Internal Server Error – We had a problem with our server. Try again later or contact Run my Accounts.
Authentication
Please get an api-key and the client name from your Run my Accounts contact. You will need this information to access the API.
For simple testing you can work with a query parameter ‘api_key’ in the URL. But for better security we advise you to pass the key via the RequestHeader ‘X-RMA-KEY’.
Tools
We recommend https://www.getpostman.com/ for testing.
Resources
The Run my Accounts API offers the following resources (end points):
Accounts receivables: customers, invoices, parts
- List of customers
- Create or deactivate customer
- Get customer by number
- List of invoices
- Create invoice
- Create project
- Get invoice
- PDF or HTML of invoice
- List of payments
- Payments of invoice
- Add payment to invoice
- List of parts
Account payables: vendors and vendor invoices
- List of vendors
- Create or deactivate vendor
- List of vendor invoices
- Create vendor invoice
- Get vendor invoice
- PDF of vendor invoice
- List payments of vendor invoice
- Add payment to vendor invoice
General ledger
- List charts
- Trial balance
- List cost and profit centers
- List projects
- Create general ledger booking
- Transactions in an account
- Get yearend bookings
Accounting Service
Entites
The following entities are available in the api:
- Chart
- Customer
- Department
- Project
- General ledger batch
- Invoice payment
- Invoice
- Part
- Vendor invoice
- Vendor invoice payment
- Vendor
Uses cases
On our API use case page you will find a variety of different use cases, documented with json and xml examples.
Use of bank accounts
Bank accounts are normally only booked by Run my Accounts. Incoming payments to bank accounts should therefore not be posted directly against a bank account through the API, but only through a current account. The corresponding current account will be opened upon request by Run my Accounts. Run my Accounts posts all customer-relevant bank account transactions against the current account, so that if the account is managed correctly, the current account is netted daily at zero.
Incoming payments must be booked with the correct amounts in the debtor system, otherwise the bookkeeping will not work. Any positions incorrectly booked by the customer must be cleared. If this is done through Run my Accounts, cleanup work is chargeable if it is due to incorrect customer handling. If incoming payments are not generally booked by the customer, Run my Accounts must be informed and be able to close the open positions independently.
Disclaimer
Due to malfunction of the APIs on the customer side resulting errors in the books, this needs to be cleared by Run my Accounts. This will have a cost impact on the client side. The customer ist fully responsible for all bookings performed through the API.
